mpv ReplayGain Not Working: How to Fix It

When mpv ReplayGain is not working, the player may appear to ignore loudness metadata completely: tagged songs play at noticeably different levels, album playback loses its intended volume balance, or enabling ReplayGain produces no audible change. The usual causes are straightforward. ReplayGain may be disabled, the selected mode may not match the available tags, the file may not contain usable gain metadata, or an mpv profile, script, filter, or later command-line option may be overriding your configuration. Streams and videos opened through yt-dlp add another complication because they often do not expose ReplayGain tags at all.

The safest approach is to test one known tagged local audio file with a clean mpv command. Once that works, restore your normal configuration one component at a time. This isolates the actual cause without deleting your config folder, replacing codecs, or changing unrelated video and hardware-decoding settings.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start with a local audio file that you know contains ReplayGain metadata. Avoid playlists, network paths, online URLs, scripts, and shell aliases during this first test. A simple local file removes several variables at once.

1.1 Run mpv Without Your Normal Configuration

Open a terminal in the file's directory and run:

mpv --no-config --replaygain=track "tagged-file.flac"

On Windows, use the executable name appropriate to your mpv package. A console-capable executable is useful because it lets you see diagnostic output. In PowerShell, Command Prompt, Bash, and Zsh, quote paths containing spaces.

The --no-config option temporarily prevents mpv from loading its usual configuration. It does not delete or modify any files. The --replaygain=track option asks mpv to apply track gain when suitable metadata is available.

Success means the test file's loudness changes by approximately the amount specified in its track-gain tag. Do not rely on mpv's displayed volume percentage alone. ReplayGain can alter decoded audio gain while the user-facing volume control remains at the same percentage.

1.2 Compare ReplayGain Off and On

Run the same file twice at the same system and mpv volume:

1. mpv --no-config --replaygain=no "tagged-file.flac"
2. mpv --no-config --replaygain=track "tagged-file.flac"

Choose a file with a meaningful gain adjustment, such as several decibels, because a tiny adjustment can be difficult to hear. Keep all other settings unchanged. If the difference matches the stored gain value, ReplayGain works in clean mpv and you can stop investigating operating-system audio components. The conflict is in your regular command, configuration, profile, or scripts.

If both commands sound identical, verify the tags before changing mpv options. A file that has never been analyzed for ReplayGain gives mpv nothing to apply.

2. Check ReplayGain Options and File Metadata

2.1 Choose the Correct replaygain Value

mpv's relevant mode is selected with --replaygain. The commonly used values are:

• no: disables ReplayGain processing
• track: uses each file's track gain, which is useful for mixed playlists
• album: uses album gain, preserving intentional differences among tracks from the same album

For a mixed playlist assembled from unrelated releases, track mode generally produces more consistent song-to-song loudness. For a complete album, album mode preserves relative dynamics between quiet and loud tracks. Album mode requires album-gain metadata. If a file contains only track gain, do not assume that album mode will produce the result you expect.

Add one explicit line to mpv.conf when you have confirmed the desired mode:

replaygain=track

mpv configuration files use option names without the leading --. Avoid writing both replaygain=track and replaygain=no in different sections unless a deliberate profile controls them.

2.2 Verify That the File Actually Has Tags

ReplayGain is metadata driven. mpv does not automatically scan an entire song and calculate persistent ReplayGain values during ordinary playback. The file must contain compatible gain metadata that its container and tag format can expose through mpv's demuxing stack.

Typical metadata includes track gain and track peak, with optional album gain and album peak. Vorbis-style metadata commonly uses fields such as REPLAYGAIN_TRACK_GAIN, REPLAYGAIN_TRACK_PEAK, REPLAYGAIN_ALBUM_GAIN, and REPLAYGAIN_ALBUM_PEAK. Other formats may store equivalent information differently.

Inspect the file with a trusted tag editor or an established media inspection tool already installed on your system. Check the actual file being opened, not another copy in a different folder. If no gain fields are present, analyze and write tags with a reputable ReplayGain-aware audio library or tagger. Preserve a backup before performing bulk tag changes.

Success means the inspector shows a numeric gain value and mpv's clean track-mode test produces a corresponding loudness change. Once that happens, stop retagging the file.

2.3 Account for Container and Tag Support

Having text that resembles a ReplayGain field somewhere in a file does not guarantee that mpv can use it. Metadata support depends on the audio format, container, tagging convention, and demuxer behavior. FLAC and formats using Vorbis comments commonly carry standard ReplayGain fields, while MP3 metadata may be represented through ID3 frames or other loudness schemes. Nonstandard custom fields may be visible in one tag editor but not interpreted as ReplayGain by the playback stack.

Test one conventionally tagged file in a well-supported format before concluding that mpv itself is broken. If that file works but another container does not, the problem is specific to the second file's metadata representation. Converting media should be a last resort. Correcting or rewriting its metadata with a trusted tool is usually less disruptive.

2.4 Configure Preamp and Clipping Prevention Carefully

The --replaygain-preamp option adds a preamplification adjustment to the ReplayGain result. A value of zero applies no additional preamp:

mpv --no-config --replaygain=track --replaygain-preamp=0 "tagged-file.flac"

If a large negative preamp is configured, playback may become much quieter than expected. A positive preamp can make the result louder, but it also increases clipping risk. Begin at zero while troubleshooting.

The --replaygain-clip setting controls whether mpv limits gain to reduce clipping based on available peak metadata. Clipping prevention can make the applied boost smaller than the raw gain tag suggests. That is expected behavior, not evidence that ReplayGain failed. Use:

mpv --no-config --replaygain=track --replaygain-preamp=0 --replaygain-clip=yes "tagged-file.flac"

If clipping prevention is enabled and peak metadata predicts an over, success may be a smaller safe increase rather than the full tagged increase. Do not disable protection merely to force a louder result unless you understand and accept the possibility of clipping.

3. Find Configuration, Profile, Binding, and Script Conflicts

3.1 Search Every Loaded Configuration Source

If the clean command works, inspect your normal mpv setup for every occurrence of replaygain, replaygain-preamp, and replaygain-clip. Check mpv.conf, included configuration files, command-line launchers, desktop shortcuts, file associations, shell aliases, and wrapper scripts.

A later option can override an earlier one. For example, a shortcut that appends --replaygain=no can defeat replaygain=track in mpv.conf. Likewise, a file-type or protocol profile may change behavior only for selected media.

3.2 Inspect Profiles Before Editing Them

Use mpv's profile inspection option for a named profile:

mpv --show-profile=profile-name

Review profiles that activate for audio files, playlists, protocols, or particular extensions. Look for ReplayGain settings and audio filters. If you find a conflict, temporarily comment out only the relevant line and repeat the same tagged-file test.

Success means normal mpv playback now matches the clean command. At that point, stop changing settings. The identified profile was the cause.

3.3 Check Input Bindings and Scripts

Custom input bindings and Lua or JavaScript scripts can change properties after playback begins. Search input.conf and script configuration files for ReplayGain, volume, mute, audio filters, and commands that load profiles. Temporarily disable one suspected script by moving that individual script out of the scripts directory, then test again. Do not delete the entire configuration directory.

The stats overlay and custom on-screen displays can help identify changing volume or filter state, but they may not present ReplayGain as a simple volume-number change. The strongest evidence remains an A/B test using a file with a known, substantial gain value.

3.4 Eliminate Audio Filter and Track Selection Confusion

A manually configured audio filter chain can normalize, compress, amplify, or otherwise change loudness after ReplayGain processing. Temporarily test without your custom af settings. Also verify that mpv selected the intended audio track. Video containers may contain multiple language tracks, commentary tracks, or codecs with different metadata.

Subtitle settings, video track selection, screenshot options, HDR tone mapping, shaders, GPU output, and hardware video decoding do not normally determine whether ReplayGain metadata is applied to decoded audio. Change them only if a script or profile connects those settings to audio behavior. Randomly changing hwdec, GPU drivers, or display-server options is unlikely to fix this specific symptom.

4. Check Media Source and Operating-System Limitations

4.1 Understand Why Online URLs Often Behave Differently

When mpv opens an online page through yt-dlp, it usually receives a selected media stream rather than the original local library file and its complete tag set. ReplayGain metadata may be absent from that stream. The same limitation can affect direct HTTP streams, internet radio, adaptive streaming formats, and media served by software that strips tags.

Confirm the difference by downloading or using a legally obtained local tagged test file, then run the clean command. If local ReplayGain works while the URL does not, mpv's ReplayGain implementation is functioning. The stream simply does not provide usable tags. Updating a trusted yt-dlp installation may solve extraction failures, but it cannot create ReplayGain metadata that the source never supplied.

4.2 Check Paths, Permissions, and Shell Quoting

A command can test the wrong file if its path is malformed or expanded unexpectedly by the shell. Always quote paths containing spaces, brackets, wildcard characters, or shell metacharacters. Confirm the filename printed by mpv is the tagged file you inspected.

Read permission is normally sufficient for playback because mpv does not need to rewrite ReplayGain tags. If the file plays, permissions are rarely the reason its gain metadata is ignored. However, sandboxed application packages may see a different file location or configuration directory than a terminal build. Compare the exact executable, config path, and media path used by each launch method.

4.3 Separate Audio Backend Problems From ReplayGain Problems

PulseAudio, PipeWire, ALSA, CoreAudio, and Windows audio backends can affect device selection and system-level volume. They generally do not decide whether mpv reads ReplayGain tags. Test another backend only when logs show output initialization errors, the wrong device is selected, or another application is applying automatic gain control.

Operating-system loudness enhancement, spatial audio, volume normalization, Bluetooth processing, or an external DAC's DSP can mask small ReplayGain differences. Disable such processing temporarily for the A/B test. If a large tagged adjustment becomes audible, restore enhancements individually and decide which normalization layer you want to keep.

5. Use mpv Logs and Runtime Information

5.1 Capture Detailed Terminal Output

Run the controlled test with verbose messages and a log file:

mpv --no-config --replaygain=track --msg-level=all=v --log-file=mpv-replaygain.log "tagged-file.flac"

Then search the log for terms such as replaygain, metadata, audio, demux, and the selected filename. Logs can establish which file, tracks, demuxer, and options were used. Avoid publishing an unedited log if it contains private paths, usernames, network addresses, or authentication tokens.

5.2 Verify the Track List

Use mpv's track list, console output, or stats overlay to confirm the selected audio stream. This matters most for video containers and multilingual files. If the tagged stream is track 1 but mpv selects an untagged commentary stream, ReplayGain cannot produce the expected result.

Select the intended audio track explicitly for the test, then repeat the off-versus-track comparison. Success means the correct track produces the expected loudness adjustment. Stop there rather than changing the video output or decoder.

5.3 Interpret a Lack of Log Evidence Carefully

Not every mpv build or log level presents ReplayGain processing with identical wording. The absence of an obvious human-readable ReplayGain line does not prove failure. Combine log evidence with verified metadata and a controlled listening comparison. The most convincing test uses one file with a clearly negative or positive track-gain value and no additional normalization filters.

6. Run a Clean Temporary Test Before Making Permanent Changes

Use this sequence to isolate the issue with minimal risk:

1. Choose one local file with verified track-gain and peak metadata.
2. Close other players and disable operating-system loudness normalization temporarily.
3. Run the file with --no-config --replaygain=no.
4. Run it again at the same volume with --no-config --replaygain=track --replaygain-preamp=0.
5. If it works, repeat without --no-config.
6. If it then fails, inspect mpv.conf, profiles, scripts, bindings, filters, and launcher arguments.
7. Restore components one at a time, repeating the same file and command after each change.

This method changes only one variable at each stage. Once ReplayGain works in your normal launch path, stop. Additional codec packs, driver replacement, video-output changes, or wholesale configuration resets are unnecessary and may introduce new problems.

7. Quick Fix Checklist

• Test one verified, tagged local audio file rather than an online URL.
• Run mpv --no-config --replaygain=track "file".
• Compare against --replaygain=no at the same volume.
• Confirm the file contains track gain, and album gain if album mode is used.
• Set replaygain=track or replaygain=album explicitly.
• Start with replaygain-preamp=0.
• Remember that clipping prevention may reduce a requested boost.
• Search configs, profiles, scripts, launchers, and aliases for overrides.
• Temporarily remove custom audio filters from the test.
• Confirm mpv selected the intended audio track.
• Use verbose output and a log file to verify the loaded file and options.
• Do not troubleshoot HDR, subtitles, screenshots, or hwdec unless automation links them to audio.

8. Frequently Asked Questions

8.1 Why Does mpv Show the Same Volume Percentage?

ReplayGain processing does not necessarily move mpv's ordinary volume control. The displayed percentage can remain unchanged while the decoded signal is adjusted according to the file's gain metadata. Compare playback with ReplayGain disabled and enabled instead of judging only by the on-screen volume number.

8.2 Should I Use Track Gain or Album Gain?

Use track gain for playlists containing unrelated songs when consistent per-track loudness is the priority. Use album gain for complete albums when you want to preserve the mastering's intentional differences between tracks. Album mode depends on valid album-gain tags.

8.3 Why Does ReplayGain Work for FLAC but Not Another File?

The other file may lack tags, use an unsupported or nonstandard metadata convention, or expose metadata differently through its container. Inspect both files with a trusted tag tool. If the FLAC test works, mpv's general ReplayGain function is operational, so focus on the failing file's metadata.

8.4 Can mpv Apply ReplayGain to YouTube or Network Streams?

Only when usable ReplayGain metadata reaches mpv with the media stream. Many online, adaptive, and live streams do not include it. yt-dlp can help mpv access supported media URLs, but it does not guarantee that ReplayGain tags exist. A successful local-file test distinguishes missing stream metadata from an mpv configuration problem.

8.5 Can Hardware Decoding or HDR Break ReplayGain?

Not under normal circumstances. Hardware decoding and HDR processing concern video, while ReplayGain concerns audio metadata and gain processing. Investigate those settings only if a custom profile or script changes audio options when HDR, a particular video output, or hardware decoding is active.

8.6 When Should I Stop Troubleshooting?

Stop when a verified tagged file produces the expected difference between replaygain=no and replaygain=track in your normal launch method. If local files work but a specific stream does not, the likely limitation is missing stream metadata. Continuing to alter drivers, codecs, subtitle settings, or unrelated video options will not add ReplayGain tags to the source.