Access ReplayGain metadata through the Emby API for audio playback

[MarvinB 5]

I am the developer of Ear Wax, an Alexa music client that streams tracks from Emby Server 4.9.3.0.

Emby’s FFmpeg transcode log confirms that it detects embedded ReplayGain tags. For example:

REPLAYGAIN_TRACK_GAIN: -2.85 dB
REPLAYGAIN_TRACK_PEAK: 0.861816
REPLAYGAIN_ALBUM_GAIN: -2.16 dB
REPLAYGAIN_ALBUM_PEAK: 1.000000

The corresponding item is available through /emby/Audio/{Id}/stream.mp3, but requesting the complete item through /emby/Users/{UserId}/Items/{Id} does not return any gain, peak, ReplayGain, loudness, or normalization fields.

Is there a supported API endpoint or optional field that returns these embedded ReplayGain values before playback?

If not, is there a supported audio-streaming parameter that tells Emby’s transcoder to apply track ReplayGain during progressive MP3 transcoding?

The goal is track-to-track volume consistency. I would prefer to use Emby’s existing metadata and transcoder without requiring users to install a custom plugin or modify their media files.

I am specifically looking for:

• An API-accessible track gain and peak.
• A documented way to apply that gain during audio transcoding.
• Confirmation whether these capabilities are unavailable in Emby 4.9.3.0.

Thank you

[softworkz 5365]

@MarvinB

Thanks for your request.

The way Emby works is that we are ffprobe-ing all new media files and are storing a subset of that data with the items in the library in the form of  Emby SDK Reference: MediaSourceInfo and MediaStream.

 At the moment, replay gain information is not included with the media information data that is being stored. We might be able to add that, though.

With regards to transcoding, the question is how it should be handled: applied and removed, not applied but preserved/carried over, not applied and dropped. I think the latter is happening at the moment - at least when a volume filter is included.

[MarvinB 5]

@softworkz;

Thank you and that explains why the tags appear in the FFmpeg log but not in the item response.

Would you consider adding the following optional fields to MediaSourceInfo or the audio MediaStream?

ReplayGainTrackGain
ReplayGainTrackPeak
ReplayGainAlbumGain
ReplayGainAlbumPeak
ReplayGainReferenceLoudness

The values would only need to be stored and returned through the API; existing playback behavior would not need to change.

Separately, is there currently a supported audio-streaming request parameter, device-profile option, or API mechanism that allows a client to request a specific constant gain—such as -2.85 dB—during progressive MP3 transcoding?

My intended client behavior is:

• Use track gain for mixed-track playback.
• Apply the gain during transcoding.
• Do not depend on the receiving player to interpret ReplayGain tags.
• Preserve existing behavior when no gain is requested.

If no such transcoding control currently exists, would Emby consider exposing one?

I am trying to avoid requiring users to install a custom plugin or modify their audio files.

 

Thank you

[Luke 42979]

Hi, yes it’s likely to be added in the future. Thanks.

[MarvinB 5]

@Luke@softworkz,

 

Understood. Is there an existing feature-request or issue number I can follow, and would this likely be considered for the 4.9 release series or a later major release?

[Luke 42979]

Yes there’s a topic in the feature requests section for replay gain .

[MarvinB 5]

@Luke 

Would a plugin using the documented IFfmpegConfiguration and media-encoding interfaces to expose ReplayGain metadata and a gain-adjusted audio stream be acceptable for the Emby plugin catalog?

Are those interfaces considered stable for third-party plugins?

[softworkz 5365]

Emby SDK Reference: IFfmpegConfiguration only tells you the location of the FFmpeg binaries.

[MarvinB 5]

@softworkz  

Thank you for clarifying.

Is there a supported public plugin API—such as IFfmpegRunner, IMediaEncoder, or another service—that allows a plugin to create an audio transcoding job with a custom constant-volume filter and stream the result?

I am trying to avoid launching and managing FFmpeg directly from the plugin.

If no supported extension point exists for adding an audio filter to Emby’s transcoding pipeline, that answers the question.

[softworkz 5365]

On the subject in general, this cannot be reduced to a single feature request like  "Replay Gain Feature" yes/no.

There are really multiple parts and the first one is obviously media information data.
Stream side data in FFmpeg has substantially grown in variety in recent years, so one consideration might be to always record the full side data for all streams as Json string to catch everything, even when we don't have our own data structures for it.

I'm saying this, because the value of replay gain data specifically is questionable - because  it also depends on what we are doing with it:

As you might know, we have different ways for playback: There's "direct play", where the client retrieves the original bytes of the media files and plays them directly - and we have transcoded playback. When we would apply the gain adjustments in case of transcoding, but still return the replay gain information as part off the media info, a client might assume that it still needs to apply that gain correction - or the other way round, it would need to know that it needs to apply gain adjustment only in case of direct play but not in case of transcoded playback.

My immediate intuition on the whole topic would be to:

• Leave it up to the client to handle replay gain  adjustment - according to what's baked into the media metadata
• When transcoding at the server-side, don't apply any gain correction - just make sure that any replay gain metadata information does not get lost when transcoding

 

Edited 2 hours ago by softworkz

[softworkz 5365]

In other words: with regards to our own ecosystem, I think this is a client-side feature and should be handled by client players rather than by the server.

Having a transcoding parameter to cause server transcoding to apply such gain adjustments nonetheless is still possible.

But these are two very different things - which is why I said that we're not talking about...

22 minutes ago, softworkz said:

a single feature request like  "The Replay Gain Feature"

[MarvinB 5]

@softworkz

 

Thank you.

I agree that Emby should not apply ReplayGain automatically and that clients normally should decide how to use it.

My client has an additional constraint: it uses Alexa AudioPlayer, which accepts a stream URL but provides no DSP or ReplayGain controls. The client cannot modify audio samples, and the Echo cannot be assumed to honor preserved ReplayGain tags.

Emby also has its own Alexa integration, so this limitation may apply beyond Ear Wax.

Alexa AudioPlayer clients are not full media players with local DSP. They generally provide Alexa with a stream URL and cannot apply ReplayGain themselves.

Therefore, exposing and preserving ReplayGain metadata solves discovery but not playback leveling for Alexa integrations. An explicit, opt-in server-side gain parameter would allow both Emby’s Alexa integration and third-party Alexa clients to request normalized output without changing Emby’s default behavior for ordinary clients.

Would an explicit opt-in transcoding parameter be feasible—for example:

ApplyReplayGain=Track

or:

AudioGain=-2.85

When requested, Emby would force transcoding and apply that constant gain. Without the parameter, current direct-play and transcoding behavior would remain unchanged.

To prevent double application, the playback/media-source response could indicate:

ReplayGainApplied=true
AppliedGainDb=-2.85

Exposing the original ReplayGain fields or complete stream side-data JSON would allow my client to make one provider-neutral gain decision. The explicit stream parameter would allow Emby to perform that decision only when requested by a client that cannot process audio itself.

Does the current transcoding API or plugin API have an extension point for this kind of explicit client-requested audio filter?

[Luke 42979]

For example a client based on the mpv player doesn’t need to wait for any server features. You can just enable the options in libmpv

[MarvinB 5]

1 hour ago, Luke said:

For example a client based on the mpv player doesn’t need to wait for any server features. You can just enable the options in libmpv

Thank you.

I understand that an MPV-based client can enable replaygain=track and allow libmpv to apply the adjustment locally.

Ear Wax is an Alexa AudioPlayer skill, however, so it does not own the decoder or playback engine. It can only provide Alexa with an HTTPS audio URL.

Does Emby’s existing audio-transcoding endpoint accept a parameter that instructs the server to apply a specified gain or ReplayGain adjustment to the transcoded output?

For example, something equivalent to ReplayGain=track, AudioGain=-3.7, or an FFmpeg volume-filter parameter.

If not, would exposing such a parameter through the existing transcoding endpoint be feasible?

That would support clients such as Alexa that cannot perform client-side DSP.

 

thank you,

 

Marvin