Skip to main content

Interface: ReplayGainOptions

Defined in: packages/player/src/player.ts:120

Loudness normalisation from the ReplayGain tags embedded in a file.

Maps onto mpv's four replaygain* options. All four are runtime-settable: each carries mpv's UPDATE_VOL flag (options/options.c, verified in mpv 0.41.0), which makes an option write re-run audio_update_volume() — so Player.setReplayGain takes effect on the currently playing track, without a reload.

Remarks​

ReplayGain needs tags in the file (REPLAYGAIN_TRACK_GAIN and friends). Files without them get fallback, and nothing else — mpv's compute_replaygain() takes the fallback branch instead of the tag branch, which is what the manual means by "If this is applied, no other replaygain options are applied."

The fallback branch is broader than "untagged file": it is the else of if (opts->rgain_mode && rg) (player/audio.c, mpv 0.41.0), so a non-zero fallback also applies when mode is 'no' — the manual's "always applied if the replaygain logic is somehow inactive". Turning ReplayGain off for real means { mode: 'no', fallback: 0 }.

Pick this or Player.setLoudnessNormalization, not both. They level loudness by different means — ReplayGain is a per-track volume-domain gain read from tags (zero DSP, dynamics untouched); loudness normalization is a live loudnorm filter (dynamic gain ride, 192 kHz resample, 3 s lookahead). Run together their gains stack: a track ReplayGain already leveled gets re-leveled — and re-compressed — by loudnorm. When files carry tags, ReplayGain is the better tool; loudness normalization exists for the files that don't. (See that method's TSDoc for the full cost sheet.)

Properties​

clip?​

readonly optional clip?: boolean;

Defined in: packages/player/src/player.ts:149

Whether the gain is allowed to clip (mpv replaygain-clip, default false).

Remarks​

The polarity is the opposite of what mpv 0.35.1's options.rst says. That manual reads "Prevent clipping caused by replaygain by automatically lowering the gain (default). Use --replaygain-clip=no to disable this", but the code does if (!opts->rgain_clip) { rgain = MPMIN(rgain, 1.0 / peak); } (player/audio.c, compute_replaygain) and the option's default is 0 — i.e. clipping prevention is what you get by default, and setting the option to yes turns the prevention off. mpv fixed the wording in 0.38.0: "Allow the volume gain to clip (default: no). If this option is not enabled, mpv automatically will prevent clipping by lowering the gain." This field follows the behaviour, not the stale prose: leave it alone (or pass false) to keep peak-limiting on.

fallback?​

readonly optional fallback?: number;

Defined in: packages/player/src/player.ts:163

Gain in dB applied whenever the tag branch is inactive (mpv replaygain-fallback, default 0) — the file carries no ReplayGain tags, or mode is 'no'. mpv 0.41.0 options.rst: "This option is always applied if the replaygain logic is somehow inactive."

Because of that second case, mode: 'no' does not silence a fallback written earlier: a non-zero value keeps attenuating (or boosting) every track until you write fallback: 0 yourself.

Must be within mpv's own range, -200 … 60 (options/options.c, M_RANGE(-200, 60)).

mode​

readonly mode: ReplayGainMode;

Defined in: packages/player/src/player.ts:122

Which tag set to use. 'no' disables tag-based adjustment entirely.

preamp?​

readonly optional preamp?: number;

Defined in: packages/player/src/player.ts:131

Extra gain in dB applied on top of the tag value (mpv replaygain-preamp, default 0).

Must be within mpv's own range, -150 … 150 (options/options.c, M_RANGE(-150, 150)); anything else throws an invalid-state PlayerError rather than being silently clamped.