![]() |
![]() |
![]() |
GStreamer Bad Plugins 0.10 Plugins Reference Manual | ![]() |
---|---|---|---|---|
"forced" gboolean : Read / Write "num-tracks" gint : Read / Write "reference-level" gdouble : Read / Write
GstRgAnalysis 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 and GST_TAG_TRACK_PEAK.
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 receive the same amplification. This keeps the relative volume levels between the tracks intact. To enable this, set the num-tracks 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 will be 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 make sure that the album gain and peak values are also associated with the other tracks when storing the results. It is thus a bit more complex to implement, but should not be avoided since the album gain is generally more valuable for use during playback than the track gain.
For assisting transcoder/converter applications, the element can silently skip the processing of streams that already contain the necessary meta data 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 the forced 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, your application has to scan all files beforehand and enable forcing of processing if needed.
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 since the album gain and peak values need to be associated with all tracks of an album, not just the last one.
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 rganalysis element's state using
gst_element_set_locked_state()
when it is in PAUSED or PLAYING. As
with any other element, don't forget to unlock it again and set it
to the NULL state before dropping the last reference.
If the total number of album tracks is unknown beforehand, set the num-tracks property to some large value like G_MAXINT (or set it to >= 2 before each track starts). Before the last track ends, set the property value to 1.
Analyzing the ReplayGain pink noise reference waveform will compute a result of +6.00dB instead of the expected 0.00dB because the default reference level is 89dB. To obtain values as lined out in the original proposal of ReplayGain, set the reference-level property to 83. Almost all software uses 89dB as a reference however, which works against the tendency of the algorithm to advise to drastically lower the volume of music with a highly compressed dynamic range and high average output levels. This tendency is normally to be fought during playback (if wanted), by using a default pre-amp value of at least +6.00dB. At one point, the majority of analyzer implementations switched to 89dB which moved this adjustment to the analyzing/metadata writing process. This change has been acknowledged by the author of the ReplayGain proposal, however at the time of this writing, the webpage is still not updated.
Analyze a simple test waveform:
gst-launch -t audiotestsrc wave=sine num-buffers=512 ! rganalysis ! fakesink
Analyze a given file:
gst-launch -t filesrc location="Some file.ogg" ! decodebin ! audioconvert ! audioresample ! rganalysis ! fakesink
Analyze the pink noise reference file:
gst-launch -t gnomevfssrc location=http://replaygain.hydrogenaudio.org/ref_pink.wav ! wavparse ! rganalysis ! fakesink
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 |