rganalysis
This element analyzes raw audio sample data in accordance with the proposed ReplayGain standard for calculating the ideal replay gain for music tracks and albums. The element is designed as a pass-through filter that never modifies any data. As it receives an EOS event, it finalizes the ongoing analysis and generates a tag list containing the results. It is sent downstream with a tag event and posted on the message bus with a tag message. The EOS event is forwarded as normal afterwards. Result tag lists at least contain the tags GST_TAG_TRACK_GAIN, GST_TAG_TRACK_PEAK and GST_TAG_REFERENCE_LEVEL.
Because the generated metadata tags become available at the end of streams, downstream muxer and encoder elements are normally unable to save them in their output since they generally save metadata in the file header. Therefore, it is often necessary that applications read the results in a bus event handler for the tag message. Obtaining the values this way is always needed for album processing (see num-tracks property) since the album gain and peak values need to be associated with all tracks of an album, not just the last one.
Example launch lines
gst-launch-1.0 -t audiotestsrc wave=sine num-buffers=512 ! rganalysis ! fakesink
Analyze a simple test waveform
gst-launch-1.0 -t filesrc location=filename.ext ! decodebin \
! audioconvert ! audioresample ! rganalysis ! fakesink
Analyze a given file
gst-launch-1.0 -t gnomevfssrc location=http://replaygain.hydrogenaudio.org/ref_pink.wav \
! wavparse ! rganalysis ! fakesink
Analyze the pink noise reference file
The above launch line yields a result gain of +6 dB (instead of the expected +0 dB). This is not in error, refer to the reference-level property documentation for more information.
Acknowledgements
This element is based on code used in the vorbisgain program and many others. The relevant parts are copyrighted by David Robinson, Glen Sawyer and Frank Klemm.
Hierarchy
GObject ╰──GInitiallyUnowned ╰──GstObject ╰──GstElement ╰──GstBaseTransform ╰──rganalysis
Factory details
Authors: – René Stadler
Classification: – Filter/Analyzer/Audio
Rank – none
Plugin – replaygain
Package – GStreamer Good Plug-ins
Pad Templates
sink
audio/x-raw:
format: { F32LE, S16LE }
layout: interleaved
channels: 1
rate: { (int)8000, (int)11025, (int)12000, (int)16000, (int)22050, (int)24000, (int)32000, (int)44100, (int)48000 }
audio/x-raw:
format: { F32LE, S16LE }
layout: interleaved
channels: 2
channel-mask: 0x0000000000000003
rate: { (int)8000, (int)11025, (int)12000, (int)16000, (int)22050, (int)24000, (int)32000, (int)44100, (int)48000 }
src
audio/x-raw:
format: { F32LE, S16LE }
layout: interleaved
channels: 1
rate: { (int)8000, (int)11025, (int)12000, (int)16000, (int)22050, (int)24000, (int)32000, (int)44100, (int)48000 }
audio/x-raw:
format: { F32LE, S16LE }
layout: interleaved
channels: 2
channel-mask: 0x0000000000000003
rate: { (int)8000, (int)11025, (int)12000, (int)16000, (int)22050, (int)24000, (int)32000, (int)44100, (int)48000 }
Properties
forced
“forced” gboolean
Whether to analyze streams even when ReplayGain tags exist.
For assisting transcoder/converter applications, the element can silently skip the processing of streams that already contain the necessary tags. Data will flow as usual but the element will not consume CPU time and will not generate result tags. To enable possible skipping, set this property to FALSE.
If used in conjunction with album processing, the element will skip the number of remaining album tracks if a full set of tags is found for the first track. If a subsequent track of the album is missing tags, processing cannot start again. If this is undesired, the application has to scan all files beforehand and enable forcing of processing if needed.
Flags : Read / Write
Default value : true
message
“message” gboolean
Post statics messages
Flags : Read / Write / Construct
Default value : false
num-tracks
“num-tracks” gint
Number of remaining album tracks.
Analyzing several streams sequentially and assigning them a common result gain is known as "album processing". If this gain is used during playback (by switching to "album mode"), all tracks of an album receive the same amplification. This keeps the relative volume levels between the tracks intact. To enable this, set this property to the number of streams that will be processed as album tracks.
Every time an EOS event is received, the value of this property is decremented by one. As it reaches zero, it is assumed that the last track of the album finished. The tag list for the final stream will contain the additional tags GST_TAG_ALBUM_GAIN and GST_TAG_ALBUM_PEAK. All other streams just get the two track tags posted because the values for the album tags are not known before all tracks are analyzed. Applications need to ensure that the album gain and peak values are also associated with the other tracks when storing the results.
If the total number of album tracks is unknown beforehand, just ensure that the value is greater than 1 before each track starts. Then before the end of the last track, set it to the value 1.
To perform album processing, the element has to preserve data between streams. This cannot survive a state change to the NULL or READY state. If you change your pipeline's state to NULL or READY between tracks, lock the element's state using gst_element_set_locked_state when it is in PAUSED or PLAYING.
Flags : Read / Write
Default value : 0
reference-level
“reference-level” gdouble
Reference level [dB].
Analyzing the ReplayGain pink noise reference waveform computes a result of +6 dB instead of the expected 0 dB. This is because the default reference level is 89 dB. To obtain values as lined out in the original proposal of ReplayGain, set this property to 83.
Almost all software uses 89 dB as a reference however, and this value has become the new official value, and that change has been acclaimed by the original author of the ReplayGain proposal.
The value was changed because the original proposal recommends a default pre-amp value of +6 dB for playback. This seemed a bit odd, as it means that the algorithm has the general tendency to produce adjustment values that are 6 dB too low. Bumping the reference level by 6 dB compensated for this.
The problem of the reference level being ambiguous for lack of concise standardization is to be solved by adopting the GST_TAG_REFERENCE_LEVEL tag, which allows to store the used value alongside the gain values.
Flags : Read / Write
Default value : 89
The results of the search are