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

<CardGroup cols={2}>
  <Card title="Built-in (CPAL)" icon="speaker" href="/audio-output/built-in">Default. No setup.</Card>
  <Card title="HLS + DASH (CMAF)" icon="globe" href="/audio-output/hls">Plays in any browser.</Card>
  <Card title="Snapcast" icon="network-wired" href="/audio-output/snapcast">FIFO or direct TCP.</Card>
  <Card title="AirPlay" icon="apple" href="/audio-output/airplay">Single or multi-room RAOP.</Card>
  <Card title="Squeezelite" icon="boxes-stacked" href="/audio-output/squeezelite">Slim Protocol multi-room.</Card>
  <Card title="Chromecast" icon="cast" href="/audio-output/chromecast">Google Cast over WAV/HTTP.</Card>
  <Card title="UPnP / DLNA" icon="tower-broadcast" href="/audio-output/upnp">Sink, server, renderer.</Card>
</CardGroup>

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

## 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).