Configuration

Configure Rockbox via ~/.config/rockbox.org/settings.toml.

Rockbox reads ~/.config/rockbox.org/settings.toml once on startup. Edit the file, then rockbox restart. There is no live-reload; the API is the way to change things at runtime.

Minimal config

music_dir    = "/path/to/your/Music"
audio_output = "builtin"

music_dir is the only required field. audio_output defaults to "builtin" if omitted.

Top-level keys

Key	Type	Default	Description
music_dir	string	—	Absolute path to your music library
audio_output	string	"builtin"	One of: builtin, fifo, airplay, squeezelite, chromecast, snapcast_tcp, upnp
player_name	string	""	Name advertised to MPD clients and UI

Output sinks

Each sink has its own configuration block. See the dedicated pages:

Built-in (SDL)

Default. No setup.

Snapcast

FIFO or direct TCP.

AirPlay

Single or multi-room RAOP.

Squeezelite

Slim Protocol multi-room.

Chromecast

Google Cast over WAV/HTTP.

UPnP / DLNA

Sink, server, renderer.

Playback defaults

playlist_shuffle = false
repeat_mode      = 1   # 0=Off 1=All 2=One 3=Shuffle 4=A-B
party_mode       = true

Equalizer

eq_enabled = true

[[eq_band_settings]]   # band 0 — low shelf
cutoff = 0
q      = 64
gain   = 10

[[eq_band_settings]]   # bands 1–8 — peaking
cutoff = 3
q      = 125
gain   = 10

# ...repeat for the remaining bands

The full 10-band parametric EQ is documented in Audio settings › Equalizer.

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

Tone & stereo

bass             = 0
treble           = 0
bass_cutoff      = 0
treble_cutoff    = 0
balance          = 0
stereo_width     = 100
stereosw_mode    = 0
channel_config   = 0
surround_enabled = 0
surround_balance = 0
surround_fx1     = 0
surround_fx2     = 0

ReplayGain

[replaygain_settings]
noclip = true
type   = 0   # 0=Track 1=Album 2=Shuffle  (see Replaygain page)
preamp = 0

Compressor

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

Where settings come from

There are three layers, in order of precedence:

1. Runtime API calls — every setting is also exposed over GraphQL/gRPC and persists to disk on the next save cycle.
2. settings.toml — applied once at startup.
3. Compiled-in defaults — in apps/settings_list.c.

For the full settings catalogue with units, ranges and where each one is applied, see the Settings TOML reference.