[API Request] Expose ReplayGain tags in song/track payload

[dweymouth]

Type of change

API extension

Proposal description

ReplayGain is an accepted standard for loudness normalization and many media files in users' collections will already have ReplayGain tags (and it's easy to scan for and add them). Currently some clients are able to use ReplayGain tags present in the files themselves, but this is not ideal since a) some transcoding setups may not preserve the file tags, and b) some clients, especially web-based ones, won't have access to reading the tags in the streamed audio file itself.

Implementing replaygain loudness normalization is very easy on the client side if you have access to the tags, since it can be done by setting the volume of the internal player based on a simple formula.

Backward compatibility impact

Additional properties on track struct. No break in backwards compatibility

Backward compatibility

• No backward compatibility impact.

API details

Add additional properties to the song structure: trackGain, trackPeak, albumGain, albumPeak. All 4 are float values, and the units for trackGain and albumGain are dB, and trackPeak and albumPeak are in the range [0.. 1]. The corresponding tags in the audio files to read from are REPLAYGAIN_TRACK_GAIN, etc

If a track is missing replay gain info, the server must omit the replaygain fields from the response rather than setting them to 0.

Security impacts

No response

Potential issues

No response

Alternative solutions

No response

[dweymouth]

And this is really niche, (but also really easy)..

We could also add a preEmphasis boolean property to tracks, indicating whether the track has CD pre-emphasis applied. This should be determined by reading the PRE_EMPHASIS tag in the audio file (or making it configurable on the server which tag it reads from). The server can safely set it to false, or omit it, if the track is missing a pre-emphasis tag or if the server just doesn't want to support it. (And any client that can't/doesn't want to support it can just ignore it)

Pre-emphasis was a technique used on some early CDs to mitigate poor linearity of early ADC/DACs by boosting the treble of the track before digitizing it, flagging it in the CD metadata, and having the player do the corresponding treble cut in the analog domain after the DAC. Even though it hasn't really been used since the 80s it's part of the Red Book CD-DA spec and all CD players should support it. CD rips won't automatically correct it though, and the standard thing to do is run the rip through SoX or a similar post-processor that can correct pre-emphasis. Or add a PRE_EMPHASIS=1 tag and use a player like Foobar2000 that can correct it in real-time. Any Subsonic client that uses libmpv for playback, or an audio backend that lets you add biquad filters to the signal chain, can correct pre-emphasis on the fly as well, provided they can know if it is present in the files.

[lachlan-00]

I've never heard of that once before. What kind of files would have this data? Is it from the cd or by analysis program?

[dweymouth]

The CD itself flags whether a track has pre-emphasis, and some CD rippers (e.g. EAC) can detect and save this info into the cue sheet.* iTunes will automatically correct pre-emphasis if it detects it when ripping, but is the only software that does so AFAIK.

• It's further complicated by the fact that there are two places a CD can flag whether pre-emphasis is present - the disc TOC and the track's subcode - and discs that only flag it in the subcode are generally not detected as having pre-emphasis at all by ripper software.

[lachlan-00]

That's a very simple one I think should definitely be added

[dweymouth]

Thinking more about this, if we pick this one up there needs to be a way to distinguish between a server not supporting replaygain metadata vs a specific file not containing it. So either make it mandatory under a certain OpenSubsonic API version that replaygain tags must be scanned and returned by the API, or adding a hasReplayGain property or similar. Some clients could fall back to tags that may be present in the files themselves if the server doesn't return replaygain info, but they would need a way to know if lack of replaygain info for a track means the track has not been replaygain processed (in which case they don't need to turn on the fallback handling) as opposed to the server not supporting it.

[Tolriq]

The way it should be done with the extensions, is that we create an extension named like 'replayGain' and any server that expose support at version 1 must returns the gains if present.
So no extension = no gain support, extension and no replay = no gain values present.

There's no "certain OpenSubsonic API version". If one day there's a v2 it will be a complete new proper API.

[Tolriq]

See proposal #52