docs/plugins/html/gst-plugins-good-plugins-rgvolume.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>rgvolume</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="GStreamer Good Plugins 0.10 Plugins Reference Manual">
   8 <link rel="up" href="ch01.html" title="gst-plugins-good Elements">
   9 <link rel="prev" href="gst-plugins-good-plugins-rglimiter.html" title="rglimiter">
  10 <link rel="next" href="gst-plugins-good-plugins-rippletv.html" title="rippletv">
  11 <meta name="generator" content="GTK-Doc V1.17 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="gst-plugins-good-plugins-rglimiter.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="ch01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GStreamer Good Plugins 0.10 Plugins Reference Manual</th>
  21 <td><a accesskey="n" href="gst-plugins-good-plugins-rippletv.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#gst-plugins-good-plugins-rgvolume.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#gst-plugins-good-plugins-rgvolume.description" class="shortcut">Description</a>
  27                    |
  28                   <a href="#gst-plugins-good-plugins-rgvolume.object-hierarchy" class="shortcut">Object Hierarchy</a>
  29                    |
  30                   <a href="#gst-plugins-good-plugins-rgvolume.implemented-interfaces" class="shortcut">Implemented Interfaces</a>
  31                    |
  32                   <a href="#gst-plugins-good-plugins-rgvolume.properties" class="shortcut">Properties</a>
  33 </td></tr>
  34 </table>
  35 <div class="refentry">
  36 <a name="gst-plugins-good-plugins-rgvolume"></a><div class="titlepage"></div>
  37 <div class="refnamediv"><table width="100%"><tr>
  38 <td valign="top">
  39 <h2><span class="refentrytitle"><a name="gst-plugins-good-plugins-rgvolume.top_of_page"></a>rgvolume</span></h2>
  40 <p>rgvolume — Apply ReplayGain volume adjustment</p>
  41 </td>
  42 <td valign="top" align="right"></td>
  43 </tr></table></div>
  44 <div class="refsynopsisdiv">
  45 <a name="gst-plugins-good-plugins-rgvolume.synopsis"></a><h2>Synopsis</h2>
  46 <a name="GstRgVolume"></a><pre class="synopsis">struct              <a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume-struct" title="struct GstRgVolume">GstRgVolume</a>;
  47 </pre>
  48 </div>
  49 <div class="refsect1">
  50 <a name="gst-plugins-good-plugins-rgvolume.object-hierarchy"></a><h2>Object Hierarchy</h2>
  51 <pre class="synopsis">
  52   <a href="http://library.gnome.org/devel/gobject/unstable/gobject-The-Base-Object-Type.html#GObject">GObject</a>
  53    +----<a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstObject.html">GstObject</a>
  54          +----<a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstElement.html">GstElement</a>
  55                +----<a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstBin.html">GstBin</a>
  56                      +----GstRgVolume
  57 </pre>
  58 </div>
  59 <div class="refsect1">
  60 <a name="gst-plugins-good-plugins-rgvolume.implemented-interfaces"></a><h2>Implemented Interfaces</h2>
  61 <p>
  62 GstRgVolume implements
  63  <a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstChildProxy.html">GstChildProxy</a>.</p>
  64 </div>
  65 <div class="refsect1">
  66 <a name="gst-plugins-good-plugins-rgvolume.properties"></a><h2>Properties</h2>
  67 <pre class="synopsis">
  68   "<a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--album-mode" title='The "album-mode" property'>album-mode</a>"               <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a>              : Read / Write
  69   "<a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--fallback-gain" title='The "fallback-gain" property'>fallback-gain</a>"            <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>               : Read / Write
  70   "<a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--headroom" title='The "headroom" property'>headroom</a>"                 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>               : Read / Write
  71   "<a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--pre-amp" title='The "pre-amp" property'>pre-amp</a>"                  <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>               : Read / Write
  72   "<a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--result-gain" title='The "result-gain" property'>result-gain</a>"              <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>               : Read
  73   "<a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--target-gain" title='The "target-gain" property'>target-gain</a>"              <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>               : Read
  74 </pre>
  75 </div>
  76 <div class="refsect1">
  77 <a name="gst-plugins-good-plugins-rgvolume.description"></a><h2>Description</h2>
  78 <p>
  79 This element applies volume changes to streams as lined out in the proposed
  80 <a class="ulink" href="http://replaygain.org" target="_top">ReplayGain standard</a>.  It
  81 interprets the ReplayGain meta data tags and carries out the adjustment (by
  82 using a volume element internally).  The relevant tags are:
  83 </p>
  84 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
  85 <li class="listitem"><a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstTagList.html#GST-TAG-TRACK-GAIN:CAPS"><span class="type">GST_TAG_TRACK_GAIN</span></a></li>
  86 <li class="listitem"><a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstTagList.html#GST-TAG-TRACK-PEAK:CAPS"><span class="type">GST_TAG_TRACK_PEAK</span></a></li>
  87 <li class="listitem"><a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstTagList.html#GST-TAG-ALBUM-GAIN:CAPS"><span class="type">GST_TAG_ALBUM_GAIN</span></a></li>
  88 <li class="listitem"><a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstTagList.html#GST-TAG-ALBUM-PEAK:CAPS"><span class="type">GST_TAG_ALBUM_PEAK</span></a></li>
  89 <li class="listitem"><a href="http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstTagList.html#GST-TAG-REFERENCE-LEVEL:CAPS"><span class="type">GST_TAG_REFERENCE_LEVEL</span></a></li>
  90 </ul></div>
  91 <p>
  92 The information carried by these tags must have been calculated beforehand by
  93 performing the ReplayGain analysis.  This is implemented by the <a class="link" href="gst-plugins-good-plugins-rganalysis.html#GstRgAnalysis">rganalysis</a> element.
  94 </p>
  95 <p>
  96 The signal compression/limiting recommendations outlined in the proposed
  97 standard are not implemented by this element.  This has to be handled by
  98 separate elements because applications might want to have additional filters
  99 between the volume adjustment and the limiting stage.  A basic limiter is
 100 included with this plugin: The <a class="link" href="gst-plugins-good-plugins-rglimiter.html#GstRgLimiter">rglimiter</a>
 101 element applies -6 dB hard limiting as mentioned in the ReplayGain standard.
 102 </p>
 103 <p>
 104 </p>
 105 <div class="refsect2">
 106 <a name="idp19607840"></a><h3>Example launch line</h3>
 107 <div class="informalexample">
 108   <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 109     <tbody>
 110       <tr>
 111         <td class="listing_lines" align="right"><pre>1
 112 2</pre></td>
 113         <td class="listing_code"><pre class="programlisting">gst<span class="gtkdoc opt">-</span>launch filesrc location<span class="gtkdoc opt">=</span>filename<span class="gtkdoc opt">.</span>ext <span class="gtkdoc opt">!</span> decodebin <span class="gtkdoc opt">!</span> audioconvert \
 114     <span class="gtkdoc opt">!</span> rgvolume <span class="gtkdoc opt">!</span> audioconvert <span class="gtkdoc opt">!</span> audioresample <span class="gtkdoc opt">!</span> alsasink</pre></td>
 115       </tr>
 116     </tbody>
 117   </table>
 118 </div>
 119  Playback of a file
 120 </div>
 121 <p>
 122 </p>
 123 <div class="refsynopsisdiv">
 124 <h2>Synopsis</h2>
 125 <div class="refsect2">
 126 <a name="idp19682864"></a><h3>Element Information</h3>
 127 <div class="variablelist"><table border="0">
 128 <col align="left" valign="top">
 129 <tbody>
 130 <tr>
 131 <td><p><span class="term">plugin</span></p></td>
 132 <td>
 133             <a class="link" href="gst-plugins-good-plugins-plugin-replaygain.html#plugin-replaygain">replaygain</a>
 134           </td>
 135 </tr>
 136 <tr>
 137 <td><p><span class="term">author</span></p></td>
 138 <td>René Stadler &lt;mail@renestadler.de&gt;</td>
 139 </tr>
 140 <tr>
 141 <td><p><span class="term">class</span></p></td>
 142 <td>Filter/Effect/Audio</td>
 143 </tr>
 144 </tbody>
 145 </table></div>
 146 </div>
 147 <hr>
 148 <div class="refsect2">
 149 <a name="idp12314896"></a><h3>Element Pads</h3>
 150 <div class="variablelist"><table border="0">
 151 <col align="left" valign="top">
 152 <tbody>
 153 <tr>
 154 <td><p><span class="term">name</span></p></td>
 155 <td>sink</td>
 156 </tr>
 157 <tr>
 158 <td><p><span class="term">direction</span></p></td>
 159 <td>sink</td>
 160 </tr>
 161 <tr>
 162 <td><p><span class="term">presence</span></p></td>
 163 <td>always</td>
 164 </tr>
 165 <tr>
 166 <td><p><span class="term">details</span></p></td>
 167 <td>audio/x-raw-float, rate=(int)[ 1, 2147483647 ], channels=(int)[ 1, 2147483647 ], endianness=(int)1234, width=(int)32</td>
 168 </tr>
 169 <tr>
 170 <td><p><span class="term"></span></p></td>
 171 <td> audio/x-raw-int, channels=(int)[ 1, 2147483647 ], rate=(int)[ 1, 2147483647 ], endianness=(int)1234, width=(int)16, depth=(int)16, signed=(boolean)true</td>
 172 </tr>
 173 </tbody>
 174 </table></div>
 175 <div class="variablelist"><table border="0">
 176 <col align="left" valign="top">
 177 <tbody>
 178 <tr>
 179 <td><p><span class="term">name</span></p></td>
 180 <td>src</td>
 181 </tr>
 182 <tr>
 183 <td><p><span class="term">direction</span></p></td>
 184 <td>source</td>
 185 </tr>
 186 <tr>
 187 <td><p><span class="term">presence</span></p></td>
 188 <td>always</td>
 189 </tr>
 190 <tr>
 191 <td><p><span class="term">details</span></p></td>
 192 <td>audio/x-raw-float, rate=(int)[ 1, 2147483647 ], channels=(int)[ 1, 2147483647 ], endianness=(int)1234, width=(int)32</td>
 193 </tr>
 194 <tr>
 195 <td><p><span class="term"></span></p></td>
 196 <td> audio/x-raw-int, channels=(int)[ 1, 2147483647 ], rate=(int)[ 1, 2147483647 ], endianness=(int)1234, width=(int)16, depth=(int)16, signed=(boolean)true</td>
 197 </tr>
 198 </tbody>
 199 </table></div>
 200 </div>
 201 </div>
 202 <p>
 203 </p>
 204 </div>
 205 <div class="refsect1">
 206 <a name="gst-plugins-good-plugins-rgvolume.details"></a><h2>Details</h2>
 207 <div class="refsect2">
 208 <a name="GstRgVolume-struct"></a><h3>struct GstRgVolume</h3>
 209 <pre class="programlisting">struct GstRgVolume;</pre>
 210 <p>
 211 Opaque data structure.
 212 </p>
 213 </div>
 214 </div>
 215 <div class="refsect1">
 216 <a name="gst-plugins-good-plugins-rgvolume.property-details"></a><h2>Property Details</h2>
 217 <div class="refsect2">
 218 <a name="GstRgVolume--album-mode"></a><h3>The <code class="literal">"album-mode"</code> property</h3>
 219 <pre class="programlisting">  "album-mode"               <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gboolean"><span class="type">gboolean</span></a>              : Read / Write</pre>
 220 <p>
 221 Whether to prefer album gain over track gain.
 222 </p>
 223 <p>
 224 If set to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#TRUE:CAPS"><code class="literal">TRUE</code></a>, use album gain instead of track gain if both are
 225 available.  This keeps the relative loudness levels of tracks from the same
 226 album intact.
 227 </p>
 228 <p>
 229 If set to <a href="http://library.gnome.org/devel/glib/unstable/glib-Standard-Macros.html#FALSE:CAPS"><code class="literal">FALSE</code></a>, track mode is used instead.  This effectively leads to
 230 more extensive normalization.
 231 </p>
 232 <p>
 233 If album mode is enabled but the album gain tag is absent in the stream,
 234 the track gain is used instead.  If both gain tags are missing, the value
 235 of the <a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--fallback-gain" title='The "fallback-gain" property'>fallback-gain</a>
 236 property is used instead.
 237 </p>
 238 <p>Default value: TRUE</p>
 239 </div>
 240 <hr>
 241 <div class="refsect2">
 242 <a name="GstRgVolume--fallback-gain"></a><h3>The <code class="literal">"fallback-gain"</code> property</h3>
 243 <pre class="programlisting">  "fallback-gain"            <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>               : Read / Write</pre>
 244 <p>
 245 Fallback gain [dB] for streams missing ReplayGain tags.
 246 </p>
 247 <p>Allowed values: [-60,60]</p>
 248 <p>Default value: 0</p>
 249 </div>
 250 <hr>
 251 <div class="refsect2">
 252 <a name="GstRgVolume--headroom"></a><h3>The <code class="literal">"headroom"</code> property</h3>
 253 <pre class="programlisting">  "headroom"                 <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>               : Read / Write</pre>
 254 <p>
 255 Extra headroom [dB].  This controls the amount by which the output can
 256 exceed digital full scale.
 257 </p>
 258 <p>
 259 Only set this to a value greater than 0.0 if signal compression/limiting of
 260 a suitable form is applied to the output (or output is brought into the
 261 correct range by some other transformation).
 262 </p>
 263 <p>
 264 This element internally uses a volume element, which also supports
 265 operating on integer audio formats.  These formats do not allow exceeding
 266 digital full scale.  If extra headroom is used, make sure that the raw
 267 audio data format is floating point (audio/x-raw-float).  Otherwise,
 268 clipping distortion might be introduced as part of the volume adjustment
 269 itself.
 270 </p>
 271 <p>Allowed values: [0,60]</p>
 272 <p>Default value: 0</p>
 273 </div>
 274 <hr>
 275 <div class="refsect2">
 276 <a name="GstRgVolume--pre-amp"></a><h3>The <code class="literal">"pre-amp"</code> property</h3>
 277 <pre class="programlisting">  "pre-amp"                  <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>               : Read / Write</pre>
 278 <p>
 279 Additional gain to apply globally [dB].  This controls the trade-off
 280 between uniformity of normalization and utilization of available dynamic
 281 range.
 282 </p>
 283 <p>
 284 Note that the default value is 0 dB because the ReplayGain reference value
 285 was adjusted by +6 dB (from 83 to 89 dB).  At the time of this writing, the
 286 <a class="ulink" href="http://replaygain.org" target="_top">webpage</a> is still outdated and
 287 does not reflect this change however.  Where the original proposal states
 288 that a proper default pre-amp value is +6 dB, this translates to the used 0
 289 dB.
 290 </p>
 291 <p>Allowed values: [-60,60]</p>
 292 <p>Default value: 0</p>
 293 </div>
 294 <hr>
 295 <div class="refsect2">
 296 <a name="GstRgVolume--result-gain"></a><h3>The <code class="literal">"result-gain"</code> property</h3>
 297 <pre class="programlisting">  "result-gain"              <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>               : Read</pre>
 298 <p>
 299 Applied gain [dB].  This gain is applied to processed buffer data.
 300 </p>
 301 <p>
 302 This is set to the <a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--target-gain" title='The "target-gain" property'>target
 303 gain</a> if amplification by that amount can be applied safely.
 304 "Safely" means that the volume adjustment does not inflict clipping
 305 distortion.  Should this not be the case, the result gain is set to an
 306 appropriately reduced value (by applying peak normalization).  The proposed
 307 standard calls this "clipping prevention".
 308 </p>
 309 <p>
 310 The difference between target and result gain reflects the necessary amount
 311 of reduction.  Applications can make use of this information to temporarily
 312 reduce the <a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--pre-amp" title='The "pre-amp" property'>pre-amp</a> for
 313 subsequent streams, as recommended by the ReplayGain standard.
 314 </p>
 315 <p>
 316 Note that target and result gain differing for a great majority of streams
 317 indicates a problem: What happens in this case is that most streams receive
 318 peak normalization instead of amplification by the ideal replay gain.  To
 319 prevent this, the <a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--pre-amp" title='The "pre-amp" property'>pre-amp</a> has
 320 to be lowered and/or a limiter has to be used which facilitates the use of
 321 <a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--headroom" title='The "headroom" property'>headroom</a>.
 322 </p>
 323 <p>Allowed values: [-120,120]</p>
 324 <p>Default value: 0</p>
 325 </div>
 326 <hr>
 327 <div class="refsect2">
 328 <a name="GstRgVolume--target-gain"></a><h3>The <code class="literal">"target-gain"</code> property</h3>
 329 <pre class="programlisting">  "target-gain"              <a href="http://library.gnome.org/devel/glib/unstable/glib-Basic-Types.html#gdouble"><span class="type">gdouble</span></a>               : Read</pre>
 330 <p>
 331 Applicable gain [dB].  This gain is supposed to be applied.
 332 </p>
 333 <p>
 334 Depending on the value of the <a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--album-mode" title='The "album-mode" property'>album-mode</a> property and the
 335 presence of ReplayGain tags in the stream, this is set according to one of
 336 these simple formulas:
 337 </p>
 338 <p>
 339 </p>
 340 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
 341 <li class="listitem">
 342 <a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--pre-amp" title='The "pre-amp" property'>pre-amp</a> + album gain
 343 of the stream</li>
 344 <li class="listitem">
 345 <a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--pre-amp" title='The "pre-amp" property'>pre-amp</a> + track gain
 346 of the stream</li>
 347 <li class="listitem">
 348 <a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--pre-amp" title='The "pre-amp" property'>pre-amp</a> + <a class="link" href="gst-plugins-good-plugins-rgvolume.html#GstRgVolume--fallback-gain" title='The "fallback-gain" property'>fallback gain</a>
 349 </li>
 350 </ul></div>
 351 <p>
 352 </p>
 353 <p>Allowed values: [-120,120]</p>
 354 <p>Default value: 0</p>
 355 </div>
 356 </div>
 357 <div class="refsect1">
 358 <a name="gst-plugins-good-plugins-rgvolume.see-also"></a><h2>See Also</h2>
 359 <a class="link" href="gst-plugins-good-plugins-rglimiter.html#GstRgLimiter"><span class="type">GstRgLimiter</span></a>, <a class="link" href="gst-plugins-good-plugins-rganalysis.html#GstRgAnalysis"><span class="type">GstRgAnalysis</span></a>
 360 </div>
 361 </div>
 362 <div class="footer">
 363 <hr>
 364           Generated by GTK-Doc V1.17</div>
 365 </body>
 366 </html>