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

# ReplayGain

> Loudness normalisation using ReplayGain tags embedded in your files.

ReplayGain reads the `REPLAYGAIN_*` tags written by tools like
`loudgain` / `mp3gain` / `metaflac` and applies the recommended gain at
playback time. Albums are kept at consistent loudness without re-encoding
the files.

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

## Settings

| Setting | Storage | Values / range | Default | Description |
| - | - | - | - | - |
| Type | `.type` | track / album / track shuffle / off | shuffle | Which RG tag to apply for normalisation |
| No-Clip | `.noclip` | bool | false | If the RG adjustment would cause clipping, scale down to avoid it |
| Preamp | `.preamp` | −120..+120 dB (step 5) | 0 dB | Extra gain on top of the RG value (use with No-Clip to avoid surprises) |

Applied via `dsp_replaygain_set_settings()` in `lib/rbcodec/dsp/dsp_misc.h`.

## Modes explained

* **Track** — every track plays at its own RG-normalised level.
* **Album** — all tracks within an album share the same gain; preserves
  intended quiet/loud relationships within the album.
* **Track shuffle** — Track gain when shuffling, Album gain otherwise. The
  default; behaves naturally regardless of how you're listening.
* **Off** — RG tags ignored.

## Tagging your files

Rockbox does not write ReplayGain tags. Use one of:

* **`loudgain`** — modern multi-format CLI (FLAC, MP3, Opus, OGG, M4A).
* **`mp3gain`** — MP3 only, but lossless.
* **`metaflac --add-replay-gain`** — FLAC, ships with `flac`.

Example:

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
loudgain -a -k -s e *.flac    # tag album-mode, prevent clipping
```

After re-tagging, trigger a library rescan:

```graphql theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
mutation { scanLibrary }
```

## Configuring at runtime

```graphql GraphQL theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
mutation {
  saveSettings(input: {
    replaygainSettings: {
      type: 1
      noclip: true
      preamp: 0
    }
  }) { replaygainSettings { type } }
}
```

```ts TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
import { ReplaygainType } from '@rockbox-zig/sdk';

await client.settings.save({
  replaygainSettings: {
    type: ReplaygainType.Album,
    noclip: true,
    preamp: 0,
  },
});
```


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