| Top | |
|
|
|
| gboolean | forced | Read / Write |
| gint | num-tracks | Read / Write |
| gdouble | reference-level | Read / Write |
| gboolean | message | Read / Write / Construct |
GObject
╰── GInitiallyUnowned
╰── GstObject
╰── GstElement
╰── GstBaseTransform
╰── GstRgAnalysis
This element analyzes raw audio sample data in accordance with the proposed
ReplayGain standard forcalculating 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.
1 |
gst-launch-1.0 -t audiotestsrc wave=sine num-buffers=512 ! rganalysis ! fakesink |
1 2 |
gst-launch-1.0 -t filesrc location=filename.ext ! decodebin \ ! audioconvert ! audioresample ! rganalysis ! fakesink |
1 2 |
gst-launch-1.0 -t gnomevfssrc location=http://replaygain.hydrogenaudio.org/ref_pink.wav \ ! wavparse ! rganalysis ! fakesink |
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.
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.
plugin |
replaygain |
author |
René Stadler <mail@renestadler.de> |
class |
Filter/Analyzer/Audio |
name |
sink |
direction |
sink |
presence |
always |
details |
audio/x-raw, format=(string){ F32LE, S16LE }, layout=(string)interleaved, channels=(int)1, rate=(int){ 8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000 } |
| audio/x-raw, format=(string){ F32LE, S16LE }, layout=(string)interleaved, channels=(int)2, channel-mask=(bitmask)0x0000000000000003, rate=(int){ 8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000 } |
name |
src |
direction |
source |
presence |
always |
details |
audio/x-raw, format=(string){ F32LE, S16LE }, layout=(string)interleaved, channels=(int)1, rate=(int){ 8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000 } |
| audio/x-raw, format=(string){ F32LE, S16LE }, layout=(string)interleaved, channels=(int)2, channel-mask=(bitmask)0x0000000000000003, rate=(int){ 8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000 } |
“forced” property “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
“num-tracks” property “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
Allowed values: >= 0
Default value: 0
“reference-level” property “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. That is to say, while the change has been acclaimed by the author of the ReplayGain proposal, the webpage is still outdated at the time of this writing.
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
Allowed values: [0,150]
Default value: 89