Skip to main content
This guide will get you streaming with Aceplay in just a few steps. Make sure you’ve already installed Aceplay before continuing.

​
Play your first stream

1

Ensure you have a video player

Aceplay works with mpv, vlc, or ffplay. Check if you have one installed:
which mpv vlc ffplay
If none are installed, install mpv (recommended):
sudo apt install mpv
2

Run the setup wizard (first time only)

On first run, Aceplay will launch an interactive setup wizard to configure your preferences:
aceplay
The wizard will ask you to:
  • Select your preferred video player
  • Choose whether to use HLS mode
Your configuration will be saved to ~/.config/aceplay/config.yaml.
3

Play a stream

Now you’re ready to play an Ace Stream! Use the play command or pass the URL directly:
aceplay acestream://94c2fd8fb9bc8f2fc71a2cbe9d4b866f227a0209
Or explicitly use the play subcommand:
aceplay play acestream://94c2fd8fb9bc8f2fc71a2cbe9d4b866f227a0209
Aceplay will:
  1. Parse the content ID from the URL
  2. Check if acestream-engine is running (and start it if needed)
  3. Request the stream from the engine
  4. Wait for the stream to be ready
  5. Launch your configured video player
4

Watch stream statistics

While streaming, Aceplay displays real-time statistics in your terminal:
✓ Stream ready! Playing...
  URL: http://localhost:6878/ace/manifest.m3u8?...

Status: dl | ⬇ 2.4 MB/s | ⬆ 156 KB/s | Peers: 47
The status line shows:
  • Status - Current stream state (dl = downloading, prebuf = prebuffering)
  • Download speed - Incoming data rate
  • Upload speed - Outgoing data rate (P2P sharing)
  • Peers - Number of connected peers

​
Basic usage examples

​
Play with a specific player

Override your configured player for a single stream: 
aceplay acestream://94c2fd8fb9bc8f2fc71a2cbe9d4b866f227a0209 --player vlc

​
Use HLS mode

Enable HLS streaming (recommended for better compatibility): 
aceplay acestream://94c2fd8fb9bc8f2fc71a2cbe9d4b866f227a0209 --hls

​
Verbose output

See detailed logging information: 
aceplay acestream://94c2fd8fb9bc8f2fc71a2cbe9d4b866f227a0209 --verbose

​
Just the content ID

You can also pass just the content ID without the acestream:// prefix: 
aceplay 94c2fd8fb9bc8f2fc71a2cbe9d4b866f227a0209

​
Configure your preferences

After the initial setup, you can change settings using the interactive configuration menu: 
aceplay config
Or edit settings directly: 
# Set default player
aceplay config set player mpv

# Set engine host (if running remotely)
aceplay config set engine.host 192.168.1.100

# Set timeout
aceplay config set timeout 90s

# Enable HLS by default
aceplay config set hls true

​
View current configuration

See your current settings: 
aceplay config show
Output: 
Aceplay Configuration

Player:     mpv
Engine:     localhost:6878
Timeout:    60s
HLS:        false
Verbose:    false

​
Configuration file location

Your configuration is stored at: 
~/.config/aceplay/config.yaml
You can edit this file directly if preferred: 
player: mpv
engine:
  host: localhost
  port: 6878
timeout: 60s
hls: false
verbose: false

​
Browser integration

To open acestream:// links directly from your browser: 
aceplay register-protocol
After running this command, clicking an acestream:// link in your browser will automatically open Aceplay and start playback. The protocol handler is registered at ~/.local/share/applications/aceplay.desktop.

​
Understanding stream states

During playback, you’ll see different stream states:
StatusDescription
prebufPrebuffering - building up initial buffer
dlDownloading - actively streaming content
checkChecking - verifying stream availability
waitWaiting - waiting for peers or data
idleIdle - stream is ready but not active
loadingLoading - initializing stream
errorError - stream encountered a problem

​
Troubleshooting

​
acestream-engine not starting

If the engine fails to start automatically:
  1. Check if acestream-engine is installed: 
    which acestreamengine
  2. Try starting it manually: 
    acestreamengine --client-console
  3. Check if it’s running: 
    curl http://localhost:6878/

​
Stream timeout

If streams timeout frequently, increase the timeout value: 
aceplay config set timeout 120s

​
Player doesn’t start

Verify your player is properly installed and in your PATH: 
which mpv
mpv --version
If using a different player, make sure it’s configured: 
aceplay config set player vlc

​
Next steps

Configuration guide

Learn about all configuration options

CLI reference

Complete command-line reference

Player settings

Customize player arguments and behavior

Troubleshooting

Common issues and solutions

Build docs developers (and LLMs) love

Get started for freeTalk to us