> ## Documentation Index > Fetch the complete documentation index at: https://rockboxzig-feat-caching.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}} 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: Default. No setup. FIFO or direct TCP. Single or multi-room RAOP. Slim Protocol multi-room. Google Cast over WAV/HTTP. Sink, server, renderer. ## Playback defaults ```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}} playlist_shuffle = false repeat_mode = 1 # 0=Off 1=All 2=One 3=Shuffle 4=A-B party_mode = true ``` ## Equalizer ```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}} 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](/audio-settings/equalizer). ## Crossfade ```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}} 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 ```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}} 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 ```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}} [replaygain_settings] noclip = true type = 0 # 0=Track 1=Album 2=Shuffle (see Replaygain page) preamp = 0 ``` ## Compressor ```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}} [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. ```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}} # 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](/reference/settings-toml).