Configuration File

Overview

Aceplay uses a YAML configuration file to store persistent settings. The configuration file is automatically created when you run Aceplay for the first time or use the interactive configuration wizard.

Configuration File Location

The configuration file is located at:

~/.config/aceplay/config.yaml

Alternatively, if XDG_CONFIG_HOME is set:

$XDG_CONFIG_HOME/aceplay/config.yaml

Complete Configuration Example

player: mpv
timeout: 60s
connect_timeout: 5s
hls: false
verbose: false

engine:
  host: localhost
  port: 6878
  auto_start: false
  auto_start_command: ""

Configuration Fields

Top-Level Fields

player

string

default:"mpv"

The video player to use for playback. Supported players: mpv, vlc, ffplay.See Player Setup for more details on configuring players.

timeout

duration

default:"60s"

Maximum time to wait for a stream to become ready. Accepts duration strings like 60s, 2m, 1m30s.

connect_timeout

duration

default:"5s"

Maximum time to wait when connecting to the acestream-engine. Accepts duration strings.

hls

boolean

default:"false"

Enable HLS (HTTP Live Streaming) mode. When enabled, streams are delivered using HLS protocol.

verbose

boolean

default:"false"

Enable verbose logging mode for detailed output and debugging information.

Engine Configuration

The engine section configures the connection to acestream-engine:

Hide engine

engine.host

string

default:"localhost"

The hostname or IP address where acestream-engine is running.

engine.port

integer

default:"6878"

The port number for the acestream-engine HTTP API.

engine.auto_start

boolean

default:"false"

Automatically start the acestream-engine if it’s not already running.

engine.auto_start_command

string

default:""

Custom command to use when starting the engine. If empty, uses the default acestreamengine command.Example:

engine:
  auto_start: true
  auto_start_command: "docker start acestream-engine"

Managing Configuration

View Current Configuration

Display your current configuration settings:

aceplay config show

Interactive Configuration

Launch the interactive configuration wizard:

aceplay config edit
# or
aceplay interactive

The wizard provides a user-friendly interface to:

Select your preferred video player
Configure acestream-engine settings
Set timeout and playback options
Enable/disable HLS and verbose mode

Set Individual Values

Update specific configuration values from the command line:

# Set player
aceplay config set player vlc

# Configure engine
aceplay config set engine.host 192.168.1.100
aceplay config set engine.port 6878

# Set timeout
aceplay config set timeout 2m

# Enable HLS
aceplay config set hls true

# Enable verbose mode
aceplay config set verbose true

Manual Editing

You can also edit the configuration file directly with your preferred text editor:

$EDITOR ~/.config/aceplay/config.yaml

Configuration Priority

Configuration values are applied in the following order (later sources override earlier ones):

Default values - Built-in defaults from internal/config/config.go:14-22
Configuration file - Values from ~/.config/aceplay/config.yaml
Environment variables - See Environment Variables
Command-line flags - Flags passed directly to the aceplay command

Example Priority

# This uses default player (mpv)
aceplay play acestream://CONTENT_ID

# This uses player from config file
# (if player: vlc is set in config.yaml)
aceplay play acestream://CONTENT_ID

# This uses environment variable
export ACEPLAY_PLAYER=ffplay
aceplay play acestream://CONTENT_ID

# This uses command-line flag (highest priority)
aceplay --player vlc play acestream://CONTENT_ID

Default Values Reference

These defaults are defined in internal/config/config.go:

Field	Default Value
`player`	`mpv`
`timeout`	`60s`
`connect_timeout`	`5s`
`hls`	`false`
`verbose`	`false`
`engine.host`	`localhost`
`engine.port`	`6878`
`engine.auto_start`	`false`
`engine.auto_start_command`	`""` (empty)

First Run Setup

On first run, if no configuration file exists, Aceplay will automatically launch a setup wizard that:

Detects available video players on your system
Prompts you to select your preferred player
Asks if you want to enable HLS mode
Creates the configuration file with your selections

You can trigger the setup wizard again anytime with:

aceplay interactive

Get Started

Usage

Configuration

Advanced

Development

Configuration File

Overview