Configuration reference¶

Kite uses strict, versioned YAML. Unknown fields and invalid fallback graphs prevent startup or reload.

Server¶

server.http_address enables plaintext HTTP/1.1 and the legacy ICE request-line adapter. It is empty by default. server.https_address serves HTTP/1.1 and HTTP/2. server.http3_address serves QUIC on UDP, normally using the same port number. public_https_port controls the advertised Alt-Svc port.

server.hls_enabled controls live HLS output (.m3u8 playlists and MPEG-TS segments) for mounts with the mp3 or aac-adts profile. It is enabled by default and can be toggled live.

server.status_page_enabled controls the built-in HTML status and player page served at /, /index.html, and /status.xsl. It is enabled by default and can be toggled live.

Changing any listener address at runtime requires a restart.

TLS¶

development: creates an ephemeral self-signed certificate on each start.
files: loads certificate_file and private_key_file; changes are picked up for new TLS handshakes.
acme: obtains certificates for the explicit hosts allowlist using the configured email and cache directory. Set http_challenge_address: ":80" when HTTP-01 is required.

An alternative ACME directory can be configured with acme_directory_url, which is useful for Pebble testing.

For a public ACME deployment, point every hostname in tls.hosts at the server, allow inbound TCP 80 and TCP/UDP 443, and keep tls.cache_directory on persistent storage. The HTTP challenge listener owns its configured internal port while ACME is active; do not also configure server.http_address on that port. The production Compose example maps host ports 80/443 to unprivileged container ports and publishes the admin API only on host loopback (127.0.0.1:9090).

Source credentials¶

Each mount requires exactly one credential source (unless configured as a relay without direct source ingest):

source:
  username: source
  password_bcrypt: "$2a$12$..."

or password_env, or password_file. Environment and file values may be plaintext or bcrypt hashes. Files and environment variables are resolved at authentication time, allowing secret rotation without a config reload.

Relay (Master/Slave pull replication)¶

Mounts can pull an upstream stream from an external Icecast or Kite server:

mounts:
  - path: /relayed
    profile: mp3
    relay:
      url: "https://upstream.example.com/live"
      username: relay_user        # optional
      password_env: RELAY_PASS    # or password, or password_file
      retry_delay: 3s             # default: 3s

Kite requests ICY metadata (Icy-MetaData: 1) from the upstream server, extracts StreamTitle metadata updates on the fly without audio artifacts, and distributes the clean audio frames to local listeners.

If source credentials are also defined on a relay mount, a live source (e.g. DJ) connecting via PUT or SOURCE will temporarily preempt the relay stream. When the direct source disconnects, the relay automatically reconnects and resumes.

Profiles¶

mp3 → audio/mpeg
aac-adts → audio/aac
ogg-opus → audio/ogg; codecs=opus
opaque → an explicitly configured content_type; fallback is disabled

Kite parses MP3 frames, ADTS frames, and Ogg pages before fan-out. Every mount in a fallback chain must use the same profile.

Fallback (AutoDJ)¶

Fallback candidates are evaluated in order of priority:

fallback:
  - mount: /backup
  - folder: /var/lib/kite/music   # directory of audio files (recursive)
    shuffle: true                 # randomize playback order
  - playlist: /var/lib/kite/playlists/hits.m3u  # M3U playlist file
    shuffle: false
  - file: ./emergency.mp3         # single fallback audio file
    title: Emergency programming  # optional title override

Kite switches after source_timeout without valid input. It returns to a stable primary after failback_delay. Listener connections remain open. The switch occurs at a media frame/page boundary; Kite does not decode, crossfade, or normalize audio.

Extended Fallback & AutoDJ Features¶

Folder & Playlist Support: Configure folder: path/to/dir or playlist: path/to/playlist.m3u.
Automatic ID3 Metadata Extraction: When moving between tracks in a folder or playlist, Kite automatically extracts Artist and Title from ID3v2 (v2.2, v2.3, v2.4) and ID3v1 tags (or formats the filename) without external dependencies. Metadata updates are broadcast to web status listeners via SSE and inserted into ICY streaming clients at icy_meta_interval boundaries.
Shuffle & Continuous Loop: When shuffle: true is enabled, the track rotation is randomized and continuously looped with automatic reshuffle at loop boundaries.
Immediate Preemption: When a live DJ or Relay connects, fallback playback immediately stops. When the live source disconnects, fallback immediately resumes.

Kite validates every configured fallback file, folder, and playlist during startup and before a dynamic configuration commit. A missing file or invalid directory rejects the configuration without changing runtime state.

Fallback audio is looped and paced using metadata.bitrate, or 128 kbit/s if omitted.

Buffering¶

buffer_duration determines the bounded per-listener queue. A client that falls beyond the live window is disconnected instead of increasing latency and memory indefinitely. Tune metadata.bitrate accurately to make this bound representative.

CORS¶

List allowed browser origins per mount. "*" is suitable only for public streams. WebSocket requests are rejected when their Origin is not allowed.