acexy - An AceStream Proxy Written In Go! ⚡

Table of Contents

• How It Works? 🛠
• Key Features 🔗
• Usage 📐
• Optimizing 🚀
• Alternative 🧃
• Configuration Options ⚙

How It Works? 🛠

This project is a wrapper around the AceStream middleware HTTP API, allowing both HLS and MPEG-TS playback of a stream.

I was tired of the limitations of AceStream and some of the problems that exist when playing a stream 📽. For example, it is only possible to play the same channel for 1 single client. For having multiple clients playing different streams, you must manually add a unique pid per client. If there was an error during the transmission, the whole stream goes down, etc.

I found quite frustrating the experience of using AceStream in a home network with a single server and multiple clients, to try to optimize resources. This is the topology for which I am using AceStream:

There are some problems:

• Only one client can play the same stream at a time 🚫.
• Having each client to run AceStream on their own is a waste of resources and saturates the network 📉.
• Multiple clients can play different streams if they have a unique pid (Player ID) associated 🔓.
• The standard AceStream HTTP API is not resilient enough against errors, if the transmission stops it stops for every client ❌.

Key Features 🔗

When using acexy, you automatically have:

• A single, centralized server running all your AceStream streams ⛓.
• Automatic assignation of a unique pid (Player ID) per client per stream 🪪.
• Stream Multiplexing 🕎: The same stream can be reproduced at the same time in multiple clients.
• Resilient, error-proof streaming thanks to the HTTP Middleware 🛡.
• Blazing fast, minimal proxy ☄ written in Go!

With this proxy, the following architecture is now possible:

Usage 📐

acexy is available and published as a Docker image. Make sure you have the latest Docker image installed and available.

The Acexy container will connect against an AceStream server. You need to deploy either a Docker image, and link Acexy within the same network; Or have a running AceStream version on your host and run Acexy in host-networked mode.

INFO: There is a docker-compose.yml file in the repo you can directly use to launch the whole block. This is the recommended setup starting from v0.2.0.

To run the services block, first grab the docker-compose.yml file, and run:

wget https://raw.githubusercontent.com/Javinator9889/acexy/refs/heads/main/docker-compose.yml
docker compose run -d

If you don't want to use Docker Compose, assuming you already have an AceStream server, another way could be:

docker run --network host ghcr.io/javinator9889/acexy

NOTE: For your convenience, a docker-compose.yml file is given with all the possible adjustable parameters. It should be ready to run, and it's the recommended way starting from v0.2.0.

By default, the proxy will work in MPEG-TS mode. For switching between them, you must add the -m3u8 flag or set ACEXY_M3U8=true environment variable.

NOTE: The HLS mode - ACEXY_M3U8 or -m3u8 flag - is in a non-tested status. Using it is discouraged and not guaranteed to work.

There is a single available endpoint: /ace/getstream which takes the same parameters as the standard AceStream Middleware/HTTP API. Therefore, for running a stream, just open the following link in your preferred application - such as VLC:

http://127.0.0.1:8080/ace/getstream?id=dd1e67078381739d14beca697356ab76d49d1a2

where dd1e67078381739d14beca697356ab76d49d1a2 is the ID of the AceStream channel.

Optimizing 🚀

The AceStream Engine running behind of the proxy has a number of ports that can be exposed to optimize the performance. Those are, by default:

• 8621/tcp
• 8621/udp

NOTE: They can be adjusted through the EXTRA_FLAGS variable - within Docker - by using the --port flag.

Exposing those ports should help getting a more stable streaming experience. Notice that you will need to open up those ports on your gateway too.

For reference, this is how you should run the Docker command:

docker run -t -p 8080:8080 -p 8621:8621 ghcr.io/javinator9889/acexy

Alternative 🧃

AceStream underneath attempts to use UPnP IGD to connect against a remote machine. The problem is that this is not working because of the bridging layer added by Docker (see: https://docs.docker.com/engine/network/drivers/bridge/).

If you are running a single instance of Acexy - and a single instance of AceStream - it should be safe for you to run the container with host networking. This means:

• The container can access any other application bridged to your main network.
• You don't need to expose any ports.
• Performance is optimized a little bit.

NOTE: This only works on Linux environments. See https://docs.docker.com/engine/network/drivers/host/ for more information.

The command is quite straightforward:

docker run -t --network host ghcr.io/javinator9889/acexy

That should enable AceStream to use UPnP freely.

Configuration Options ⚙

Acexy has tons of configuration options that allow you to customize the behavior. All of them have default values that were tested for the optimal experience, but you may need to adjust them to fit your needs.

PRO-TIP: You can issue acexy -help to have a complete view of all the available options.

As Acexy was thought to be run inside a Docker container, all the variables and settings are adjustable by using environment variables.

Flag	Environment Variable	Description	Default
-license	-	Prints the program license and exits	-
-help	-	Prints the help message and exits	-
-addr	ACEXY_LISTEN_ADDR	Address where Acexy is listening to. Useful when running in host mode.	:8080
-scheme	ACEXY_SCHEME	The scheme of the AceStream middleware. If you have configured AceStream to work in HTTPS, you will have to tweak this value.	http
-acestream-host	ACEXY_HOST	Where the AceStream middleware is located. Change it if you need Acexy to connect to a different AceStream Engine.	localhost
-acestream-port	ACEXY_PORT	The port to connect to the AceStream middleware. Change it if you need Acexy to connect to a different AceStream Engine.	6878
-m3u8-stream-timeout	ACEXY_M3U8_STREAM_TIMEOUT	When running Acexy in M3U8 mode, the timeout to consider a stream is done.	60s
-m3u8	ACEXY_M3U8	Enable M3U8 mode in Acexy. WARNING: This mode is experimental and may not work as expected.	Disabled
-empty-timeout	ACEXY_EMPTY_TIMEOUT	Timeout to consider a stream is finished once empty information is received from the middleware. Useless when in M3U8 mode.	1m
-buffer-size	ACEXY_BUFFER_SIZE	Buffers up-to buffer-size bytes of a stream before copying the data to the player. Useful to have better stability during plays.	4.2MiB
-no-response-timeout	ACEXY_NO_RESPONSE_TIMEOUT	Time to wait for the AceStream middleware to return a response for a newly opened stream. This must be as low as possible unless your Internet connection is really bad (ie: You have very big latencies).	1s
-client-eviction-timeout	ACEXY_CLIENT_EVICTION_TIMEOUT	Time with no response from a client before kicking it out of the pool of players. This helps prevent the other players from lagging behind because of an unresponsive player. If the player's connection is expected to be unstable, increasing this value might prevent the server from evicting slow clients.	5s

NOTE: The list of options is extensive but could be outdated. Always refer to the Acexy binary -help output when in doubt.