settings.toml reference

Every key Rockbox reads from ~/.config/rockbox.org/settings.toml.

This is the canonical list of keys recognised by rockbox_settings::load_settings(). Keys not listed here are ignored.

Core

Key	Type	Default	Description
music_dir	string	—	Absolute path to your music library
audio_output	string	"builtin"	builtin / cmaf (alias hls, dash) / fifo / airplay / squeezelite / chromecast / snapcast_tcp / upnp
player_name	string	""	Name advertised to MPD clients and the UI

Subsonic / Navidrome API server

Key	Type	Default	Description
subsonic_username	string	admin	Username clients must authenticate with
subsonic_password	string	—	Password; server is disabled when this is empty
subsonic_port	int	4533	TCP port the Subsonic API listens on

Jellyfin-compatible API server

Key	Type	Default	Description
jellyfin_port	int	—	TCP port the Jellyfin-compatible API listens on. Omit to disable the server. Conventional value: 8096.

The Jellyfin server activates only when jellyfin_port is set. It reuses subsonic_username / subsonic_password as its credentials and is additionally disabled when the password is empty. On startup it also binds udp/7359 for client auto-discovery ("Who is JellyfinServer?") and advertises _jellyfin._tcp.local. over mDNS. See API reference › Jellyfin for the endpoint surface and the list of tested native clients.

S3-compatible API server

Key	Type	Default	Description
s3_enabled	bool	false	Start the S3-compatible HTTP server
s3_host	string	"0.0.0.0"	Listen address
s3_port	int	9000	TCP port the S3 API listens on
s3_access_key	string	—	AWS access key ID for SigV4 auth; server disabled if empty
s3_secret_key	string	—	AWS secret access key for SigV4 auth; server disabled if empty

The bucket name is fixed to music and the region is fixed to us-east-1. The single bucket maps 1:1 to music_dir. Uploads are accepted only for recognised audio extensions, and the library DB stays in sync via the filesystem watcher — no rescan needed. See API reference › S3 for the supported operations and client recipes.

CMAF (HLS + DASH) sink

Key	Type	Default	Description
cmaf_http_port	int	7882	HTTP port the HLS playlist + DASH manifest + fMP4 segments are served on
cmaf_bitrate	int	128000	AAC-LC bitrate in bits/sec (clamped to 32 000 – 320 000)
cmaf_segment_dir	string	—	Optional directory to mirror init.mp4, seg/N.m4s, and the HLS/DASH manifests to (for serving from an external HTTP server / CDN)

The aliases audio_output = "hls" and audio_output = "dash" are also accepted and produce the same in-memory CMAF stream.

FIFO / pipe sink

Key	Type	Default	Description
fifo_path	string	/tmp/rockbox.fifo	Named FIFO path, or "-" for stdout

Snapcast TCP sink

Key	Type	Default	Description
snapcast_tcp_host	string	—	snapserver host
snapcast_tcp_port	int	4953	snapserver TCP source port

AirPlay sink

Key	Type	Default	Description
airplay_host	string	—	Single receiver IP
airplay_port	int	5000	Single receiver port
airplay_receivers	array of tables	—	Multi-room. Each entry: host, optional port

[[airplay_receivers]]
host = "192.168.1.50"

[[airplay_receivers]]
host = "192.168.1.51"
port = 5000

Squeezelite sink

Key	Type	Default	Description
squeezelite_port	int	3483	Slim Protocol TCP port
squeezelite_http_port	int	9999	HTTP PCM broadcast port

Chromecast sink

Key	Type	Default	Description
chromecast_host	string	—	Target Chromecast IP
chromecast_port	int	8009	Cast control port
chromecast_http_port	int	7881	WAV HTTP stream port

UPnP

Key	Type	Default	Description
upnp_renderer_url	string	—	AVTransport controlURL of the target renderer
upnp_http_port	int	7879	WAV broadcast HTTP port (sink mode)
upnp_server_enabled	bool	false	Start the ContentDirectory media server
upnp_server_port	int	7878	Media server HTTP port
upnp_renderer_enabled	bool	false	Start the MediaRenderer endpoint
upnp_renderer_port	int	7880	MediaRenderer HTTP port
upnp_friendly_name	string	"Rockbox"	Display name shown to control points

Playback defaults

Key	Type	Default	Description
playlist_shuffle	bool	false
repeat_mode	int	1	0=Off 1=All 2=One 3=Shuffle 4=A-B
party_mode	bool	true

Tone, stereo & channels

Key	Type	Default	Description
bass	int	0	dB
treble	int	0	dB
bass_cutoff	int	0	Hz
treble_cutoff	int	0	Hz
balance	int	0	−100..+100
stereo_width	int	100	0..255 % (when channel_config = Custom)
stereosw_mode	int	0
channel_config	int	0	0=Stereo 1=Mono 2=Custom 3=ML 4=MR 5=Karaoke 6=Swap

Surround

Key	Type	Default	Description
surround_enabled	int	0	0/5/8/10/15/30 ms (0=off)
surround_balance	int	0	0..99 %
surround_fx1	int	0	HF cutoff, Hz
surround_fx2	int	0	LF cutoff, Hz
surround_method2	bool	false	Side-only processing
surround_mix	int	0	0..100 %

Crossfade

crossfade           = 5
fade_on_stop        = false
fade_in_delay       = 2
fade_in_duration    = 7
fade_out_delay      = 4
fade_out_duration   = 0
fade_out_mixmode    = 2

Equalizer

eq_enabled = true
eq_precut  = 3            # dB headroom

[[eq_band_settings]]
cutoff = 0   # Hz (per-band)
q      = 64  # × 10 fixed-point
gain   = 10  # × 10 dB fixed-point

# repeat for each of the 10 bands

ReplayGain

[replaygain_settings]
type   = 0    # 0=Track 1=Album 2=Track shuffle 3=Off
noclip = true
preamp = 0    # × 10 dB fixed-point

Compressor

[compressor_settings]
threshold    = -24   # dB
makeup_gain  = 0
ratio        = 4
knee         = 1
release_time = 300   # ms
attack_time  = 5     # ms

Where it’s parsed

The file is read by rockbox_settings::load_settings() in crates/settings/src/lib.rs. Unknown keys are silently ignored, so typos won’t crash startup — but they also won’t take effect.