Skip to main content

​
Overview

Aceplay supports multiple video players for stream playback. Each player comes with optimized default arguments for the best streaming experience.

​
Supported Players

The following video players are officially supported (defined in internal/player/player.go:14-18):

mpv

Modern, lightweight media player

VLC

Popular cross-platform media player

ffplay

Simple player from FFmpeg suite

​
Default Player Arguments

Aceplay automatically configures each player with optimized arguments for streaming. These defaults are defined in internal/player/player.go:71-93.

​
mpv (Default)

mpv --force-window=immediate --cache=yes [stream-url]
​
--force-window=immediate
flag
Creates the player window immediately, before the stream starts loading.
​
--cache=yes
flag
Enables caching for smoother playback of network streams.

​
VLC

vlc --play-and-exit --network-caching=3000 [stream-url]
​
--play-and-exit
flag
Automatically closes VLC when playback finishes.
​
--network-caching=3000
integer
Sets network caching to 3000ms (3 seconds) for buffering.

​
ffplay

ffplay -window_title Aceplay -fflags nobuffer -flags low_delay -strict experimental [stream-url]
​
-window_title
string
Sets the window title to “Aceplay”.
​
-fflags nobuffer
flag
Disables buffering for lower latency.
​
-flags low_delay
flag
Enables low-delay mode for reduced latency.
​
-strict experimental
flag
Allows experimental codecs and features.

​
Selecting a Player

​
Using Configuration File

Set your preferred player in ~/.config/aceplay/config.yaml: 
player: mpv  # or vlc, ffplay

​
Using Environment Variable

export ACEPLAY_PLAYER=vlc
aceplay play acestream://CONTENT_ID

​
Using Command-Line Flag

aceplay --player ffplay play acestream://CONTENT_ID

​
Interactive Selection

Use the interactive configuration wizard: 
aceplay config edit
Or on first run, Aceplay will automatically prompt you to select a player from those available on your system.

​
Finding Available Players

Aceplay can detect which players are installed on your system.

​
Check Available Players

The player detection searches for executables in:
  1. System PATH
  2. Common installation directories:
    • /usr/bin/
    • /usr/local/bin/
    • /opt/[player]/bin/
    • ~/.local/bin/
This logic is implemented in internal/player/player.go:43-56.

​
Programmatic Check

During first run or when using aceplay config edit, Aceplay calls player.GetAvailablePlayers() (defined in internal/player/player.go:102-113) to detect installed players.

​
Installing Video Players

If you don’t have a supported player installed, here’s how to install them: 
sudo apt update
sudo apt install mpv

​
VLC

sudo apt update
sudo apt install vlc

​
ffplay (FFmpeg)

sudo apt update
sudo apt install ffmpeg

​
Custom Player Arguments

Custom player arguments are currently not configurable through the config file. The default arguments are hardcoded in internal/player/player.go:71-93.If you need custom arguments, you would need to modify the source code or use a wrapper script.

​
Wrapper Script Example

Create a custom wrapper script for advanced player customization: 
#!/bin/bash
# mpv-custom-wrapper

mpv --force-window=immediate \
    --cache=yes \
    --cache-secs=10 \
    --demuxer-max-bytes=50M \
    --demuxer-max-back-bytes=20M \
    "$@"
Make it executable and place it in your PATH: 
chmod +x mpv-custom-wrapper
sudo mv mpv-custom-wrapper /usr/local/bin/
Then configure Aceplay to use your wrapper: 
player: mpv-custom-wrapper

​
Player Configuration Examples

​
Minimal Configuration

player: mpv

​
With Remote Engine

player: vlc
engine:
  host: 192.168.1.100
  port: 6878

​
High-Performance Setup

player: mpv
timeout: 120s
connect_timeout: 10s
hls: false  # Direct streaming for better quality
engine:
  host: localhost
  port: 6878
  auto_start: true

​
HLS Mode

player: vlc
hls: true
engine:
  host: localhost
  port: 6878

​
Player Detection Process

When you select a player, Aceplay performs these steps (see internal/player/player.go:28-40):
  1. Create Player Instance: NewPlayer(name) is called
  2. Find Executable: Searches PATH and common directories
  3. Apply Default Args: Loads optimized arguments for the player
  4. Return Player: Returns configured player instance
If the player is not found, an error is returned: 
player 'vlc' not found: executable not found

​
Troubleshooting

​
Player Not Found

If Aceplay can’t find your player: 
# Check if player is in PATH
which mpv
which vlc
which ffplay

# Verify installation
mpv --version
vlc --version
ffplay -version

​
Player Doesn’t Start

Enable verbose mode to see detailed player startup logs: 
aceplay --verbose play acestream://CONTENT_ID

​
Check Available Players

During configuration, Aceplay will show you which players are available: 
aceplay config edit
The wizard will only display players that are actually installed and detected on your system.

​
Permission Issues

If you have permission issues with the player: 
# Check player permissions
ls -l $(which mpv)

# Ensure it's executable
chmod +x $(which mpv)

​
Player Comparison

FeaturempvVLCffplay
Default✓
Lightweight✓✓
Feature-rich✓✓
GUI Controls✓✓Basic
Keyboard ShortcutsExtensiveExtensiveLimited
Resource UsageLowMediumVery Low
Recommended ForGeneral useFeature needsMinimal setups

​
Best Practices

mpv is the default player and offers the best balance of features, performance, and streaming optimization.
VLC provides extensive GUI controls and is familiar to most users.
ffplay is the lightest option and works well in minimal environments.
Regularly update your video player to get the latest codec support and bug fixes.

Build docs developers (and LLMs) love

Get started for freeTalk to us