> ## Documentation Index
> Fetch the complete documentation index at: https://rockboxzig.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`, `cmaf` (alias `hls`, `dash`), `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:

> [card] [Built-in (CPAL)](https://rockboxzig.mintlify.site/audio-output/built-in.md)
>
> Default. No setup.

> [card] [HLS + DASH (CMAF)](https://rockboxzig.mintlify.site/audio-output/hls.md)
>
> Plays in any browser.

> [card] [Snapcast](https://rockboxzig.mintlify.site/audio-output/snapcast.md)
>
> FIFO or direct TCP.

> [card] [AirPlay](https://rockboxzig.mintlify.site/audio-output/airplay.md)
>
> Single or multi-room RAOP.

> [card] [Squeezelite](https://rockboxzig.mintlify.site/audio-output/squeezelite.md)
>
> Slim Protocol multi-room.

> [card] [Chromecast](https://rockboxzig.mintlify.site/audio-output/chromecast.md)
>
> Google Cast over WAV/HTTP.

> [card] [UPnP / DLNA](https://rockboxzig.mintlify.site/audio-output/upnp.md)
>
> 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](https://rockboxzig.mintlify.site/audio-settings/equalizer.md).

## 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
```

## 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](https://rockboxzig.mintlify.site/reference/settings-toml.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.