Environment Variables

Overview

Aceplay supports configuration through environment variables, which is useful for:

Containerized environments (Docker, Kubernetes)
CI/CD pipelines
Temporary configuration overrides
Scripts and automation

All environment variables use the ACEPLAY_ prefix.

Environment Variable Prefix

Aceplay automatically reads environment variables with the ACEPLAY_ prefix. The configuration system (Viper) is set up in internal/config/config.go:104 with:

v.SetEnvPrefix("ACEPLAY")
v.AutomaticEnv()

Supported Environment Variables

Player Configuration

ACEPLAY_PLAYER

string

default:"mpv"

Video player to use for playback.Valid values: mpv, vlc, ffplay

export ACEPLAY_PLAYER=vlc

Timeout Settings

ACEPLAY_TIMEOUT

duration

default:"60s"

Maximum time to wait for a stream to become ready.Format: Duration string (e.g., 60s, 2m, 1m30s)

export ACEPLAY_TIMEOUT=2m

ACEPLAY_CONNECT_TIMEOUT

duration

default:"5s"

Maximum time to wait when connecting to acestream-engine.

export ACEPLAY_CONNECT_TIMEOUT=10s

Stream Options

ACEPLAY_HLS

boolean

default:"false"

Enable HLS (HTTP Live Streaming) mode.Valid values: true, false

export ACEPLAY_HLS=true

ACEPLAY_VERBOSE

boolean

default:"false"

Enable verbose logging for detailed output.

export ACEPLAY_VERBOSE=true

Engine Configuration

ACEPLAY_ENGINE_HOST

string

default:"localhost"

Hostname or IP address of the acestream-engine.

export ACEPLAY_ENGINE_HOST=192.168.1.100

ACEPLAY_ENGINE_PORT

integer

default:"6878"

Port number for the acestream-engine HTTP API.

export ACEPLAY_ENGINE_PORT=6878

ACEPLAY_ENGINE_AUTO_START

boolean

default:"false"

Automatically start acestream-engine if not running.

export ACEPLAY_ENGINE_AUTO_START=true

ACEPLAY_ENGINE_AUTO_START_COMMAND

string

default:""

Custom command to start the acestream-engine.

export ACEPLAY_ENGINE_AUTO_START_COMMAND="docker start acestream"

Configuration Precedence

Configuration values are resolved in the following order (highest priority first):

Command-line flags - Direct flags passed to the command
Environment variables - ACEPLAY_* variables
Configuration file - ~/.config/aceplay/config.yaml
Default values - Built-in defaults

Precedence Example

Given this configuration file:

player: mpv
engine:
  host: localhost
  port: 6878

And these environment variables:

export ACEPLAY_PLAYER=vlc
export ACEPLAY_ENGINE_HOST=192.168.1.50

The effective configuration will be:

Player: vlc (from environment variable, overrides config file)
Engine host: 192.168.1.50 (from environment variable, overrides config file)
Engine port: 6878 (from config file)

If you then run:

aceplay --player ffplay play acestream://CONTENT_ID

The effective configuration becomes:

Player: ffplay (from CLI flag, highest priority)
Engine host: 192.168.1.50 (from environment variable)
Engine port: 6878 (from config file)

Usage Examples

Basic Usage

Set environment variables before running Aceplay:

export ACEPLAY_PLAYER=vlc
export ACEPLAY_ENGINE_HOST=localhost
export ACEPLAY_TIMEOUT=90s

aceplay play acestream://CONTENT_ID

One-Time Override

Set variables for a single command:

ACEPLAY_PLAYER=ffplay aceplay play acestream://CONTENT_ID

Docker Container

Pass environment variables to a Docker container:

docker run -e ACEPLAY_PLAYER=vlc \
           -e ACEPLAY_ENGINE_HOST=host.docker.internal \
           -e ACEPLAY_ENGINE_PORT=6878 \
           aceplay:latest play acestream://CONTENT_ID

Docker Compose

Define environment variables in docker-compose.yml:

version: '3'
services:
  aceplay:
    image: aceplay:latest
    environment:
      - ACEPLAY_PLAYER=mpv
      - ACEPLAY_ENGINE_HOST=acestream-engine
      - ACEPLAY_ENGINE_PORT=6878
      - ACEPLAY_TIMEOUT=120s
      - ACEPLAY_VERBOSE=true

Shell Script

Create a wrapper script with custom environment:

#!/bin/bash
# aceplay-wrapper.sh

export ACEPLAY_PLAYER=vlc
export ACEPLAY_ENGINE_HOST=192.168.1.100
export ACEPLAY_TIMEOUT=2m
export ACEPLAY_VERBOSE=true

aceplay "$@"

Usage:

chmod +x aceplay-wrapper.sh
./aceplay-wrapper.sh play acestream://CONTENT_ID

Environment File

Create a .env file:

# aceplay.env
ACEPLAY_PLAYER=mpv
ACEPLAY_ENGINE_HOST=localhost
ACEPLAY_ENGINE_PORT=6878
ACEPLAY_TIMEOUT=60s
ACEPLAY_HLS=false
ACEPLAY_VERBOSE=false

Load it before running:

source aceplay.env
aceplay play acestream://CONTENT_ID

Or with export:

export $(cat aceplay.env | xargs)
aceplay play acestream://CONTENT_ID