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 ❌.
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:
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.ymlfile in the repo you can directly use to launch the whole block. This is the recommended setup starting fromv0.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 -dIf 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/acexyNOTE: For your convenience, a
docker-compose.ymlfile is given with all the possible adjustable parameters. It should be ready to run, and it's the recommended way starting fromv0.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_M3U8or-m3u8flag - is in a non-tested status. Using it is discoura 91D2 ged 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.
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/tcp8621/udp
NOTE: They can be adjusted through the
EXTRA_FLAGSvariable - within Docker - by using the--portflag.
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/acexyAceStream 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/acexyThat should enable AceStream to use UPnP freely.
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 -helpto 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 |
NOTE: The list of options is extensive but could be outdated. Always refer to the Acexy binary
-helpoutput when in doubt.