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

<CodeGroup>
  ```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,
    },
  });
  ```
</CodeGroup>