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

# settings.toml reference

> Every key Rockbox reads from ~/.config/rockbox.org/settings.toml.

This is the canonical list of keys recognised by `rockbox_settings::load_settings()`.
Keys not listed here are ignored.

## Core

| Key | Type | Default | Description |
| - | - | - | - |
| `music_dir` | string | — | Absolute path to your music library |
| `audio_output` | string | `"builtin"` | `builtin` / `cmaf` (alias `hls`, `dash`) / `fifo` / `airplay` / `squeezelite` / `chromecast` / `snapcast_tcp` / `upnp` |
| `player_name` | string | `""` | Name advertised to MPD clients and the UI |

## Subsonic / Navidrome API server

| Key | Type | Default | Description |
| - | - | - | - |
| `subsonic_username` | string | `admin` | Username clients must authenticate with |
| `subsonic_password` | string | — | Password; server is **disabled** when this is empty |
| `subsonic_port` | int | `4533` | TCP port the Subsonic API listens on |

## Jellyfin-compatible API server

| Key | Type | Default | Description |
| - | - | - | - |
| `jellyfin_port` | int | — | TCP port the Jellyfin-compatible API listens on. **Omit to disable the server.** Conventional value: `8096`. |

The Jellyfin server activates only when `jellyfin_port` is set. It
reuses `subsonic_username` / `subsonic_password` as its credentials and
is additionally **disabled** when the password is empty. On startup it
also binds `udp/7359` for client auto-discovery (`"Who is JellyfinServer?"`)
and advertises `_jellyfin._tcp.local.` over mDNS. See
[API reference › Jellyfin](https://rockboxzig.mintlify.site/api-reference/jellyfin/overview.md) for the
endpoint surface and the list of tested native clients.

## S3-compatible API server

| Key | Type | Default | Description |
| - | - | - | - |
| `s3_enabled` | bool | `false` | Start the S3-compatible HTTP server |
| `s3_host` | string | `"0.0.0.0"` | Listen address |
| `s3_port` | int | `9000` | TCP port the S3 API listens on |
| `s3_access_key` | string | — | AWS access key ID for SigV4 auth; server **disabled** if empty |
| `s3_secret_key` | string | — | AWS secret access key for SigV4 auth; server **disabled** if empty |

The bucket name is fixed to `music` and the region is fixed to
`us-east-1`. The single bucket maps 1:1 to `music_dir`. Uploads are
accepted only for recognised audio extensions, and the library DB
stays in sync via the filesystem watcher — no rescan needed. See
[API reference › S3](https://rockboxzig.mintlify.site/api-reference/s3/overview.md) for the supported
operations and client recipes.

## CMAF (HLS + DASH) sink

| Key | Type | Default | Description |
| - | - | - | - |
| `cmaf_http_port` | int | `7882` | HTTP port the HLS playlist + DASH manifest + fMP4 segments are served on |
| `cmaf_bitrate` | int | `128000` | AAC-LC bitrate in bits/sec (clamped to 32 000 – 320 000) |
| `cmaf_segment_dir` | string | — | Optional directory to mirror `init.mp4`, `seg/N.m4s`, and the HLS/DASH manifests to (for serving from an external HTTP server / CDN) |

The aliases `audio_output = "hls"` and `audio_output = "dash"` are also accepted
and produce the same in-memory CMAF stream.

## FIFO / pipe sink

| Key | Type | Default | Description |
| - | - | - | - |
| `fifo_path` | string | `/tmp/rockbox.fifo` | Named FIFO path, or `"-"` for stdout |

## Snapcast TCP sink

| Key | Type | Default | Description |
| - | - | - | - |
| `snapcast_tcp_host` | string | — | snapserver host |
| `snapcast_tcp_port` | int | `4953` | snapserver TCP source port |

## AirPlay sink

| Key | Type | Default | Description |
| - | - | - | - |
| `airplay_host` | string | — | Single receiver IP |
| `airplay_port` | int | `5000` | Single receiver port |
| `airplay_receivers` | array of tables | — | Multi-room. Each entry: `host`, optional `port` |

```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
[[airplay_receivers]]
host = "192.168.1.50"

[[airplay_receivers]]
host = "192.168.1.51"
port = 5000
```

## Squeezelite sink

| Key | Type | Default | Description |
| - | - | - | - |
| `squeezelite_port` | int | `3483` | Slim Protocol TCP port |
| `squeezelite_http_port` | int | `9999` | HTTP PCM broadcast port |

## Chromecast sink

| Key | Type | Default | Description |
| - | - | - | - |
| `chromecast_host` | string | — | Target Chromecast IP |
| `chromecast_port` | int | `8009` | Cast control port |
| `chromecast_http_port` | int | `7881` | WAV HTTP stream port |

## UPnP

| Key | Type | Default | Description |
| - | - | - | - |
| `upnp_renderer_url` | string | — | AVTransport controlURL of the target renderer |
| `upnp_http_port` | int | `7879` | WAV broadcast HTTP port (sink mode) |
| `upnp_server_enabled` | bool | `false` | Start the ContentDirectory media server |
| `upnp_server_port` | int | `7878` | Media server HTTP port |
| `upnp_renderer_enabled` | bool | `false` | Start the MediaRenderer endpoint |
| `upnp_renderer_port` | int | `7880` | MediaRenderer HTTP port |
| `upnp_friendly_name` | string | `"Rockbox"` | Display name shown to control points |

## Playback defaults

| Key | Type | Default | Description |
| - | - | - | - |
| `playlist_shuffle` | bool | `false` | |
| `repeat_mode` | int | `1` | 0=Off 1=All 2=One 3=Shuffle 4=A-B |
| `party_mode` | bool | `true` | |

## Tone, stereo & channels

| Key | Type | Default | Description |
| - | - | - | - |
| `bass` | int | `0` | dB |
| `treble` | int | `0` | dB |
| `bass_cutoff` | int | `0` | Hz |
| `treble_cutoff` | int | `0` | Hz |
| `balance` | int | `0` | −100..+100 |
| `stereo_width` | int | `100` | 0..255 % (when `channel_config = Custom`) |
| `stereosw_mode` | int | `0` | |
| `channel_config` | int | `0` | 0=Stereo 1=Mono 2=Custom 3=ML 4=MR 5=Karaoke 6=Swap |

## Surround

| Key | Type | Default | Description |
| - | - | - | - |
| `surround_enabled` | int | `0` | 0/5/8/10/15/30 ms (0=off) |
| `surround_balance` | int | `0` | 0..99 % |
| `surround_fx1` | int | `0` | HF cutoff, Hz |
| `surround_fx2` | int | `0` | LF cutoff, Hz |
| `surround_method2` | bool | `false` | Side-only processing |
| `surround_mix` | int | `0` | 0..100 % |

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

## Equalizer

```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
eq_enabled = true
eq_precut  = 3            # dB headroom

[[eq_band_settings]]
cutoff = 0   # Hz (per-band)
q      = 64  # × 10 fixed-point
gain   = 10  # × 10 dB fixed-point

# repeat for each of the 10 bands
```

## ReplayGain

```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
[replaygain_settings]
type   = 0    # 0=Track 1=Album 2=Track shuffle 3=Off
noclip = true
preamp = 0    # × 10 dB fixed-point
```

## Compressor

```toml theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
[compressor_settings]
threshold    = -24   # dB
makeup_gain  = 0
ratio        = 4
knee         = 1
release_time = 300   # ms
attack_time  = 5     # ms
```

## Where it's parsed

The file is read by `rockbox_settings::load_settings()` in
`crates/settings/src/lib.rs`. Unknown keys are silently ignored, so
typos won't crash startup — but they also won't take effect.


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