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" (CPAL) 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 (CPAL)

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

HTTP file cache

Rockbox caches remote audio files on disk so repeat plays are instant and require zero network traffic. Files are downloaded in the background in parallel range-request parts so the cache is populated without any interruption to the live stream.

# All fields are optional — shown with their defaults.
cache_enabled           = true
cache_dir               = "~/.config/rockbox.org/cache"
cache_max_size_mb       = 512    # total disk budget in MB
cache_min_free_space_mb = 100    # headroom to always preserve on disk
cache_parallel_parts    = 4      # concurrent HTTP Range requests per file

# Substrings that opt a URL out of caching entirely.
# Useful for live radio streams, HLS manifests, etc.
cache_no_cache_patterns = ["icecast", ".m3u8", "live", "stream"]

How it works

Step	What happens
1	stream_open checks the on-disk cache (SHA-256 of URL → .cache file).
2	Cache hit: the local file is opened instantly; seeks are O(1) file seeks — no network at all.
3	Cache miss: the live HTTP stream is opened normally (zero latency), AND a background thread downloads the full file in cache_parallel_parts simultaneous range requests.
4	Once the background download is complete (and verified), the file is atomically renamed to its final cache path. The next open is a hit.
5	When the cache exceeds cache_max_size_mb, the least-recently-used files are evicted to make room.

Stream / radio protection

The cache automatically skips URLs that have no Content-Length — infinite streams (ICY radio, HLS) never produce one, so they are never queued for caching. For URLs that do return a Content-Length but should still be skipped (e.g. a CDN-delivered live stream), add a matching substring to cache_no_cache_patterns.

Key derivation

Each cached URL is stored as SHA-256(url).cache in cache_dir. The hash is deterministic and URL-specific, so query-string variations produce distinct cache entries.

Parallel download

Files ≥ 2 MB are split into cache_parallel_parts equal byte ranges and fetched concurrently. Each thread writes directly to its allocated region of a pre-allocated file via pwrite (Unix) / seek_write (Windows), so threads never contend. Set cache_parallel_parts = 1 to fall back to single-connection downloads. If any range request fails (e.g. the server returns 200 instead of 206), the whole file is re-fetched sequentially as a fallback.

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.