Document how replaygain_limit interacts with REPLAYGAIN_ALBUM_PEAK/REPLAYGAIN_TRACK_PEAK tags

[dseomn]

Feature request

https://github.com/MusicPlayerDaemon/MPD/blob/c71e586c530e1d066efde7c2ca40c363f74100c7/doc/mpdconf.example#L395-L402 says "If replaygain_limit is disabled such amplification might occur" and I don't see anything about replaygain_limit at https://mpd.readthedocs.io/en/latest/user.html#replay-gain. From that description, I can't figure out if disabling replaygain_limit will use the REPLAYGAIN_ALBUM_PEAK/REPLAYGAIN_TRACK_PEAK tags to limit amplification to minimize clipping or not. Would it be possible to document that?

[dseomn]

Actually, I think I might have misunderstood a different part of the docs. This is the relevant code, right? I assume config.limit is from replaygain_limit, peak is from the appropriate REPLAYGAIN_*_PEAK tag, and scale is a number that each sample is multiplied by?

https://github.com/MusicPlayerDaemon/MPD/blob/c71e586c530e1d066efde7c2ca40c363f74100c7/src/tag/ReplayGainInfo.cxx#L20-L21

If I'm reading the code right, then I think the phrase "amplify audio signal above its original level" in the docs is confusing. I interpreted that as saying that replaygain_limit controls whether or not scale can ever be greater than 1 (to always prevent clipping no matter what). But from the code it looks like it controls whether scale * peak can be greater than 1 (to minimize clipping to cases where the peak tags are incorrect or there are rounding errors).

What do you think about changing:

If replaygain_limit is enabled MPD will never amplify audio signal above its original level. If replaygain_limit is disabled such amplification might occur.

to:

If replaygain_limit is enabled, MPD will use the peak from the ReplayGain tags to minimize clipping. If replaygain_limit is disabled, MPD will allow clipping of some quiet tracks.