Skip to content

Configuration Guide

SnapDog is configured using a single snapdog.toml file. The server parses this file at startup (defaults to /etc/snapdog/snapdog.toml, or specified via the --config CLI argument).

1. Global Keys

  • name (String, default: "SnapDog") The display name of the audio controller server. Used as the default broadcast name for mDNS, the base MQTT topic node, and system status listings.

2. Table Reference

[system]

Handles server execution settings, logging outputs, and local state directories.

  • log_level (String, default: "info") Sets logging verbosity. Options: trace, debug, info, warn, error.
  • log_file (String, optional) Path to a local log file. If set, logs will rotate daily in addition to standard output.
  • state_dir (String, default: platform-dependent) Directory where SnapDog saves state files like EQ configurations, current volume levels, and dynamic client mappings.
    • Defaults to /var/lib/snapdog under systemd or platform data folders (~/.local/state/snapdog on Linux, ~/Library/Application Support/SnapDog on macOS).

[audio]

Controls formatting and preemption rules for audio streams.

  • sample_rate (Integer, default: 48000) Sets the target resampling frequency in Hz. All sources are resampled to this rate before encoding. Supported values: 44100, 48000, 88200, 96000, 176400, or 192000.
  • bit_depth (Integer, default: 16) PCM encoding bit depth. Options: 16, 24, or 32 bits.
  • channels (Integer, default: 2) Number of output channels (e.g. 2 for stereo, 1 for mono).
  • source_conflict (String, default: "last_wins") Preemption rules when multiple sources try to play on the same zone:
    • "last_wins": The newest request (e.g. starting a Spotify stream or manual radio click) overrides the active source.
    • "receiver_wins": AirPlay or Spotify Connect streams block any incoming Subsonic or radio play requests until the receiver stream stops.
  • zone_switch_fade_ms (Integer, default: 300, max: 1000) Fade duration in milliseconds when a SnapDog speaker switches between audio zones. Set to 0 to disable.
  • source_switch_fade_ms (Integer, default: 300, max: 1000) Fade duration when changing the audio source (e.g., Radio → Spotify) within a single zone.

[http]

Configures the REST API, WebSocket notifications, and static WebUI hosting.

  • port (Integer, default: 5555) The TCP port on which the web server listens.
  • bind (String, default: "::") Listen interface IP. The default :: listens on IPv6 and, on dual-stack systems, IPv4 as well. Set "0.0.0.0" for IPv4-only all-interface binding or a concrete IP address for one interface.
  • base_url (String, default: "http://localhost:5555") External base URL of the server (e.g., http://192.168.1.50:5555 or https://music.example.com). Used by integrations that need absolute URLs, such as MQTT discovery and some cover-art metadata.
  • tls_cert (String, optional) Path to a PEM-formatted TLS certificate chain. Required together with tls_key to activate HTTPS.
  • tls_key (String, optional) Path to an unencrypted PEM TLS private key.
  • api_keys (Array of Strings, optional) If configured, activates token authentication. REST requests use Authorization: Bearer <key>; WebSocket connections to /ws pass the same key as ?token=<key>.
  • api_docs (Boolean, default: true) Exposes the embedded Scalar API Reference UI dynamically at http://<host>:<port>/docs. Only applicable if the binary was compiled with the api-docs feature flag.

[snapcast]

Manages the embedded Snapcast synchronizer backend.

  • address (String, default: "127.0.0.1") The hostname or IP address of the Snapcast server.
  • jsonrpc_tcp_port (Integer, default: 1705) TCP port used to communicate JSON-RPC control events. jsonrpc_port is accepted as an alias.
  • streaming_port (Integer, default: 1704) TCP port where Snapcast client devices connect to pull the encoded PCM audio data.
  • codec (String, default: "flac") Streaming compression encoder. Options: "pcm", "flac", "f32lz4", "f32lz4e" (encrypted floats).
  • encryption_psk (String, optional) Pre-shared key (PSK) used to encrypt the stream when codec = "f32lz4e" is active.
  • group_volume_mode (String, default: "compressed") Defines how zone-level volume adjustments scale connected client speakers:
    • "absolute": Changes the volume of all clients to match the zone volume.
    • "relative": Scales each client proportionally (client_vol * zone_vol / 100).
    • "compressed": Soft relative scaling using a square-root curve, ensuring quiet clients do not drop too quickly.
  • managed (Boolean, default: true) If true, starts the built-in Rust snapcast server inside the daemon process.
  • verbose (Boolean, default: false) Enables verbose console logging for the underlying Snapcast protocol encoder.
  • unknown_clients (String, default: "accept") Action when an unconfigured MAC address connects:
    • "accept": Admits the speaker and assigns it to the default_zone.
    • "ignore": Accepts connection but excludes the client from WebUI controls.
    • "reject": Drops connection immediately.
  • default_zone (String, optional) Name of the fallback zone to place new clients into. Defaults to the first defined zone.

[mdns]

  • enabled (Boolean, default: true) Enables Bonjour/mDNS service advertisement.
  • advertise_snapcast (Boolean, default: false) Additionally advertises the _snapcast._tcp service type for discovery by generic Snapcast mobile apps.

[dbus]

  • enabled (Boolean, default: true) Exposes the MPRIS2 audio control interface on Linux D-Bus.

[airplay]

  • mode (String, default: "airplay2") AirPlay protocol compatibility: "airplay1" or "airplay2".
  • password (String, optional) If set, requires verification to stream to the AirPlay receiver.
  • bind (Array of Strings, optional) Restricts the AirPlay receiver to bind to specific network interfaces.

[spotify]

  • name (String) Device name advertised to Spotify Connect clients.
  • bitrate (Integer, default: 320) Streaming bitrate. Options: 96, 160, or 320 kbps.

[subsonic]

  • url (String) URL of the Subsonic API endpoint (e.g. Navidrome or Gonic).
  • username (String) Connection username.
  • password (String) Connection password.
  • format (String, default: "raw") Transcoding stream request format: "raw", "flac", "mp3", or "opus".
  • tls_skip_verify (Boolean, default: false) Skips certificate checks for self-signed certificates.

[subsonic.cache]

  • path (String) Local folder for pre-caching track streams. Defaults to the platform cache directory (~/Library/Caches/SnapDog/tracks on macOS, $XDG_CACHE_HOME/snapdog/tracks or ~/.cache/snapdog/tracks on Linux).
  • max_size_mb (Integer, default: 2048) Maximum size in MB before LRU track eviction occurs.

[mqtt]

  • broker (String) MQTT broker host and port (e.g. 192.168.1.10:1883).
  • client_id (String, default: "snapdog") Unique client ID.
  • username (String, optional) Broker username.
  • password (String, optional) Broker password.
  • base_topic (String, default: "snapdog/") Base namespace path under which states are published and commands are received. A trailing slash is added automatically if omitted.

[knx]

  • role (String, default: "client") KNX integration mode: "client" (connects to gateway tunnel) or "device" (registers as an ETS-programmable device). The older key name mode is accepted as an alias.
  • url (String, optional) Gateway connection URL (e.g. udp://192.168.1.50:3671).
  • individual_address (String, optional) KNX individual address (e.g. 1.1.100) for ETS programming.
  • persist_ets_config (Boolean, optional) Saves ETS parameter changes to local persistent memory across restarts.
  • start_prog_mode (Boolean, default: false) Starts with KNX physical programming mode enabled for ETS addressing.

3. Array Configuration Tables

[[zone]]

Multiple zones can be defined using array of tables.

  • name (String) Unique name for the room (e.g. "Living Room").
  • icon (String, default: "🎵") Icon or emoji used in the WebUI.
  • sink (String, optional) Manual override for the Snapcast audio sink path.
  • airplay_name (String, optional) Override for the AirPlay receiver name.
  • group_volume_mode (String, optional) Zone-specific override for [snapcast].group_volume_mode. Options: "absolute", "relative", or "compressed".
  • knx (Table, optional) Explicit group addresses for this zone. Supported keys include play, pause, stop, track_next, track_previous, control_status, volume, volume_status, volume_dim, mute, mute_status, mute_toggle, track metadata/status fields, playlist controls, shuffle/repeat controls, and presence controls. Unconfigured group addresses are ignored.
  • presence (Table, optional) Presence-activated playback and auto-off settings. auto_off_delay defaults to 900 seconds; default_source and schedule entry source values use none, radio:<index>, or playlist:<id>. Schedule entries use from and to in 24-hour HH:MM format, and overlapping or overnight ranges are rejected.

[[client]]

Defines output speaker hardware mapped to zones.

  • name (String) Friendly name for the speaker (e.g. "Living Room Left").
  • mac (String) Lowercase MAC address identifying the client device.
  • zone (String) Initial zone mapping. Must match a defined [[zone]].name.
  • icon (String, default: "🎵") Icon or emoji used in the WebUI.
  • max_volume (Integer, default: 100) Limits the maximum volume output (0-100) to protect speaker hardware.
  • knx (Table, optional) Explicit group addresses for this client. Supported keys: volume, volume_status, volume_dim, mute, mute_status, mute_toggle, latency, latency_status, zone, zone_status, and connected_status.

[[radio]]

Defines global internet radio streams.

  • name (String) Station name.
  • url (String) Streaming source stream URL (supports direct links, M3U/PLS, and HLS).
  • cover (String, optional) URL to a cover art image to display when this station is playing.

4. Environment Variable Overrides

The server applies these environment variables after loading snapdog.toml:

  • SNAPDOG_HTTP_PORT — Overrides [http].port.
  • SNAPDOG_HTTP_API_KEYS — Comma-separated API keys replacing [http].api_keys.
  • SNAPDOG_SUBSONIC_PASSWORD — Overrides [subsonic].password when Subsonic is configured.
  • SNAPDOG_MQTT_PASSWORD — Overrides [mqtt].password when MQTT is configured.
  • SNAPDOG_SNAPCAST_ENCRYPTION_PSK — Overrides [snapcast].encryption_psk.

Next Steps

CLI Reference Check server startup options, port overrides, and local soundcard driver setups.
REST API Reference Query system endpoints, trigger playback, adjust mixers, and configure DSP equalizer nodes.