gstreamer/gst/replaygain/gstrgvolume.c

/* GStreamer ReplayGain volume adjustment
 *
 * Copyright (C) 2007 Rene Stadler <mail@renestadler.de>
 * 
 * gstrgvolume.c: Element to apply ReplayGain volume adjustment
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301 USA
 */

/**
 * SECTION:element-rgvolume
 * @see_also: #GstRgLimiter, #GstRgAnalysis
 *
 * This element applies volume changes to streams as lined out in the proposed
 * <ulink url="http://replaygain.org">ReplayGain standard</ulink>.  It
 * interprets the ReplayGain meta data tags and carries out the adjustment (by
 * using a volume element internally).  The relevant tags are:
 * <itemizedlist>
 * <listitem>#GST_TAG_TRACK_GAIN</listitem>
 * <listitem>#GST_TAG_TRACK_PEAK</listitem>
 * <listitem>#GST_TAG_ALBUM_GAIN</listitem>
 * <listitem>#GST_TAG_ALBUM_PEAK</listitem>
 * <listitem>#GST_TAG_REFERENCE_LEVEL</listitem>
 * </itemizedlist>
 * The information carried by these tags must have been calculated beforehand by
 * performing the ReplayGain analysis.  This is implemented by the <link
 * linkend="GstRgAnalysis">rganalysis</link> element.
 * 
 * The signal compression/limiting recommendations outlined in the proposed
 * standard are not implemented by this element.  This has to be handled by
 * separate elements because applications might want to have additional filters
 * between the volume adjustment and the limiting stage.  A basic limiter is
 * included with this plugin: The <link linkend="GstRgLimiter">rglimiter</link>
 * element applies -6 dB hard limiting as mentioned in the ReplayGain standard.
 * 
 * <refsect2>
 * <title>Example launch line</title>
 * |[
 * gst-launch filesrc location=filename.ext ! decodebin ! audioconvert \
 *     ! rgvolume ! audioconvert ! audioresample ! alsasink
 * ]| Playback of a file
 * </refsect2>
 */

#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include <gst/gst.h>
#include <gst/pbutils/pbutils.h>
#include <math.h>

#include "gstrgvolume.h"
#include "replaygain.h"

GST_DEBUG_CATEGORY_STATIC (gst_rg_volume_debug);
#define GST_CAT_DEFAULT gst_rg_volume_debug

enum
{
  PROP_0,
  PROP_ALBUM_MODE,
  PROP_HEADROOM,
  PROP_PRE_AMP,
  PROP_FALLBACK_GAIN,
  PROP_TARGET_GAIN,
  PROP_RESULT_GAIN
};

#define DEFAULT_ALBUM_MODE TRUE
#define DEFAULT_HEADROOM 0.0
#define DEFAULT_PRE_AMP 0.0
#define DEFAULT_FALLBACK_GAIN 0.0

#define DB_TO_LINEAR(x) pow (10., (x) / 20.)
#define LINEAR_TO_DB(x) (20. * log10 (x))

#define GAIN_FORMAT "+.02f dB"
#define PEAK_FORMAT ".06f"

#define VALID_GAIN(x) ((x) > -60.00 && (x) < 60.00)
#define VALID_PEAK(x) ((x) > 0.)

/* Same template caps as GstVolume, for I don't like having just ANY caps. */

static GstStaticPadTemplate sink_template = GST_STATIC_PAD_TEMPLATE ("sink",
    GST_PAD_SINK, GST_PAD_ALWAYS, GST_STATIC_CAPS ("audio/x-raw-float, "
        "rate = (int) [ 1, MAX ], "
        "channels = (int) [ 1, MAX ], "
        "endianness = (int) BYTE_ORDER, "
        "width = (int) 32; "
        "audio/x-raw-int, "
        "channels = (int) [ 1, MAX ], "
        "rate = (int) [ 1,  MAX ], "
        "endianness = (int) BYTE_ORDER, "
        "width = (int) 16, " "depth = (int) 16, " "signed = (bool) TRUE"));

static GstStaticPadTemplate src_template = GST_STATIC_PAD_TEMPLATE ("src",
    GST_PAD_SRC, GST_PAD_ALWAYS, GST_STATIC_CAPS ("audio/x-raw-float, "
        "rate = (int) [ 1, MAX ], "
        "channels = (int) [ 1, MAX ], "
        "endianness = (int) BYTE_ORDER, "
        "width = (int) 32; "
        "audio/x-raw-int, "
        "channels = (int) [ 1, MAX ], "
        "rate = (int) [ 1,  MAX ], "
        "endianness = (int) BYTE_ORDER, "
        "width = (int) 16, " "depth = (int) 16, " "signed = (bool) TRUE"));

GST_BOILERPLATE (GstRgVolume, gst_rg_volume, GstBin, GST_TYPE_BIN);

static void gst_rg_volume_set_property (GObject * object, guint prop_id,
    const GValue * value, GParamSpec * pspec);
static void gst_rg_volume_get_property (GObject * object, guint prop_id,
    GValue * value, GParamSpec * pspec);
static void gst_rg_volume_dispose (GObject * object);

static GstStateChangeReturn gst_rg_volume_change_state (GstElement * element,
    GstStateChange transition);
static gboolean gst_rg_volume_sink_event (GstPad * pad, GstEvent * event);

static GstEvent *gst_rg_volume_tag_event (GstRgVolume * self, GstEvent * event);
static void gst_rg_volume_reset (GstRgVolume * self);
static void gst_rg_volume_update_gain (GstRgVolume * self);
static inline void gst_rg_volume_determine_gain (GstRgVolume * self,
    gdouble * target_gain, gdouble * result_gain);

static void
gst_rg_volume_base_init (gpointer g_class)
{
  GstElementClass *element_class = g_class;

  gst_element_class_add_pad_template (element_class,
      gst_static_pad_template_get (&src_template));
  gst_element_class_add_pad_template (element_class,
      gst_static_pad_template_get (&sink_template));
  gst_element_class_set_details_simple (element_class, "ReplayGain volume",
      "Filter/Effect/Audio",
      "Apply ReplayGain volume adjustment",
      "Ren\xc3\xa9 Stadler <mail@renestadler.de>");

  GST_DEBUG_CATEGORY_INIT (gst_rg_volume_debug, "rgvolume", 0,
      "ReplayGain volume element");
}

static void
gst_rg_volume_class_init (GstRgVolumeClass * klass)
{
  GObjectClass *gobject_class;
  GstElementClass *element_class;
  GstBinClass *bin_class;

  gobject_class = (GObjectClass *) klass;

  gobject_class->set_property = gst_rg_volume_set_property;
  gobject_class->get_property = gst_rg_volume_get_property;
  gobject_class->dispose = gst_rg_volume_dispose;

  /**
   * GstRgVolume:album-mode:
   *
   * Whether to prefer album gain over track gain.
   *
   * If set to %TRUE, use album gain instead of track gain if both are
   * available.  This keeps the relative loudness levels of tracks from the same
   * album intact.
   *
   * If set to %FALSE, track mode is used instead.  This effectively leads to
   * more extensive normalization.
   *
   * If album mode is enabled but the album gain tag is absent in the stream,
   * the track gain is used instead.  If both gain tags are missing, the value
   * of the <link linkend="GstRgVolume--fallback-gain">fallback-gain</link>
   * property is used instead.
   */
  g_object_class_install_property (gobject_class, PROP_ALBUM_MODE,
      g_param_spec_boolean ("album-mode", "Album mode",
          "Prefer album over track gain", DEFAULT_ALBUM_MODE,
          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
  /**
   * GstRgVolume:headroom:
   *
   * Extra headroom [dB].  This controls the amount by which the output can
   * exceed digital full scale.
   *
   * Only set this to a value greater than 0.0 if signal compression/limiting of
   * a suitable form is applied to the output (or output is brought into the
   * correct range by some other transformation).
   *
   * This element internally uses a volume element, which also supports
   * operating on integer audio formats.  These formats do not allow exceeding
   * digital full scale.  If extra headroom is used, make sure that the raw
   * audio data format is floating point (audio/x-raw-float).  Otherwise,
   * clipping distortion might be introduced as part of the volume adjustment
   * itself.
   */
  g_object_class_install_property (gobject_class, PROP_HEADROOM,
      g_param_spec_double ("headroom", "Headroom", "Extra headroom [dB]",
          0., 60., DEFAULT_HEADROOM,
          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
  /**
   * GstRgVolume:pre-amp:
   *
   * Additional gain to apply globally [dB].  This controls the trade-off
   * between uniformity of normalization and utilization of available dynamic
   * range.
   *
   * Note that the default value is 0 dB because the ReplayGain reference value
   * was adjusted by +6 dB (from 83 to 89 dB).  At the time of this writing, the
   * <ulink url="http://replaygain.org">webpage</ulink> is still outdated and
   * does not reflect this change however.  Where the original proposal states
   * that a proper default pre-amp value is +6 dB, this translates to the used 0
   * dB.
   */
  g_object_class_install_property (gobject_class, PROP_PRE_AMP,
      g_param_spec_double ("pre-amp", "Pre-amp", "Extra gain [dB]",
          -60., 60., DEFAULT_PRE_AMP,
          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
  /**
   * GstRgVolume:fallback-gain:
   *
   * Fallback gain [dB] for streams missing ReplayGain tags.
   */
  g_object_class_install_property (gobject_class, PROP_FALLBACK_GAIN,
      g_param_spec_double ("fallback-gain", "Fallback gain",
          "Gain for streams missing tags [dB]",
          -60., 60., DEFAULT_FALLBACK_GAIN,
          G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
  /**
   * GstRgVolume:result-gain:
   *
   * Applied gain [dB].  This gain is applied to processed buffer data.
   *
   * This is set to the <link linkend="GstRgVolume--target-gain">target
   * gain</link> if amplification by that amount can be applied safely.
   * "Safely" means that the volume adjustment does not inflict clipping
   * distortion.  Should this not be the case, the result gain is set to an
   * appropriately reduced value (by applying peak normalization).  The proposed
   * standard calls this "clipping prevention".
   *
   * The difference between target and result gain reflects the necessary amount
   * of reduction.  Applications can make use of this information to temporarily
   * reduce the <link linkend="GstRgVolume--pre-amp">pre-amp</link> for
   * subsequent streams, as recommended by the ReplayGain standard.
   *
   * Note that target and result gain differing for a great majority of streams
   * indicates a problem: What happens in this case is that most streams receive
   * peak normalization instead of amplification by the ideal replay gain.  To
   * prevent this, the <link linkend="GstRgVolume--pre-amp">pre-amp</link> has
   * to be lowered and/or a limiter has to be used which facilitates the use of
   * <link linkend="GstRgVolume--headroom">headroom</link>.
   */
  g_object_class_install_property (gobject_class, PROP_RESULT_GAIN,
      g_param_spec_double ("result-gain", "Result-gain", "Applied gain [dB]",
          -120., 120., 0., G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
  /**
   * GstRgVolume:target-gain:
   *
   * Applicable gain [dB].  This gain is supposed to be applied.
   *
   * Depending on the value of the <link
   * linkend="GstRgVolume--album-mode">album-mode</link> property and the
   * presence of ReplayGain tags in the stream, this is set according to one of
   * these simple formulas:
   *
   * <itemizedlist>
   * <listitem><link linkend="GstRgVolume--pre-amp">pre-amp</link> + album gain
   * of the stream</listitem>
   * <listitem><link linkend="GstRgVolume--pre-amp">pre-amp</link> + track gain
   * of the stream</listitem>
   * <listitem><link linkend="GstRgVolume--pre-amp">pre-amp</link> + <link
   * linkend="GstRgVolume--fallback-gain">fallback gain</link></listitem>
   * </itemizedlist>
   */
  g_object_class_install_property (gobject_class, PROP_TARGET_GAIN,
      g_param_spec_double ("target-gain", "Target-gain",
          "Applicable gain [dB]", -120., 120., 0.,
          G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));

  element_class = (GstElementClass *) klass;
  element_class->change_state = GST_DEBUG_FUNCPTR (gst_rg_volume_change_state);

  bin_class = (GstBinClass *) klass;
  /* Setting these to NULL makes gst_bin_add and _remove refuse to let anyone
   * mess with our internals. */
  bin_class->add_element = NULL;
  bin_class->remove_element = NULL;
}

static void
gst_rg_volume_init (GstRgVolume * self, GstRgVolumeClass * gclass)
{
  GObjectClass *volume_class;
  GstPad *volume_pad, *ghost_pad;

  self->album_mode = DEFAULT_ALBUM_MODE;
  self->headroom = DEFAULT_HEADROOM;
  self->pre_amp = DEFAULT_PRE_AMP;
  self->fallback_gain = DEFAULT_FALLBACK_GAIN;
  self->target_gain = 0.0;
  self->result_gain = 0.0;

  self->volume_element = gst_element_factory_make ("volume", "rgvolume-volume");
  if (G_UNLIKELY (self->volume_element == NULL)) {
    GstMessage *msg;

    GST_WARNING_OBJECT (self, "could not create volume element");
    msg = gst_missing_element_message_new (GST_ELEMENT_CAST (self), "volume");
    gst_element_post_message (GST_ELEMENT_CAST (self), msg);

    /* Nothing else to do, we will refuse the state change from NULL to READY to
     * indicate that something went very wrong.  It is doubtful that someone
     * attempts changing our state though, since we end up having no pads! */
    return;
  }

  volume_class = G_OBJECT_GET_CLASS (G_OBJECT (self->volume_element));
  self->max_volume = G_PARAM_SPEC_DOUBLE
      (g_object_class_find_property (volume_class, "volume"))->maximum;

  GST_BIN_CLASS (parent_class)->add_element (GST_BIN_CAST (self),
      self->volume_element);

  volume_pad = gst_element_get_static_pad (self->volume_element, "sink");
  ghost_pad = gst_ghost_pad_new_from_template ("sink", volume_pad,
      gst_pad_get_pad_template (volume_pad));
  gst_object_unref (volume_pad);
  gst_pad_set_event_function (ghost_pad, gst_rg_volume_sink_event);
  gst_element_add_pad (GST_ELEMENT_CAST (self), ghost_pad);

  volume_pad = gst_element_get_static_pad (self->volume_element, "src");
  ghost_pad = gst_ghost_pad_new_from_template ("src", volume_pad,
      gst_pad_get_pad_template (volume_pad));
  gst_object_unref (volume_pad);
  gst_element_add_pad (GST_ELEMENT_CAST (self), ghost_pad);
}

static void
gst_rg_volume_set_property (GObject * object, guint prop_id,
    const GValue * value, GParamSpec * pspec)
{
  GstRgVolume *self = GST_RG_VOLUME (object);

  switch (prop_id) {
    case PROP_ALBUM_MODE:
      self->album_mode = g_value_get_boolean (value);
      break;
    case PROP_HEADROOM:
      self->headroom = g_value_get_double (value);
      break;
    case PROP_PRE_AMP:
      self->pre_amp = g_value_get_double (value);
      break;
    case PROP_FALLBACK_GAIN:
      self->fallback_gain = g_value_get_double (value);
      break;
    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
      break;
  }

  gst_rg_volume_update_gain (self);
}

static void
gst_rg_volume_get_property (GObject * object, guint prop_id,
    GValue * value, GParamSpec * pspec)
{
  GstRgVolume *self = GST_RG_VOLUME (object);

  switch (prop_id) {
    case PROP_ALBUM_MODE:
      g_value_set_boolean (value, self->album_mode);
      break;
    case PROP_HEADROOM:
      g_value_set_double (value, self->headroom);
      break;
    case PROP_PRE_AMP:
      g_value_set_double (value, self->pre_amp);
      break;
    case PROP_FALLBACK_GAIN:
      g_value_set_double (value, self->fallback_gain);
      break;
    case PROP_TARGET_GAIN:
      g_value_set_double (value, self->target_gain);
      break;
    case PROP_RESULT_GAIN:
      g_value_set_double (value, self->result_gain);
      break;
    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
      break;
  }
}

static void
gst_rg_volume_dispose (GObject * object)
{
  GstRgVolume *self = GST_RG_VOLUME (object);

  if (self->volume_element != NULL) {
    /* Manually remove our child using the bin implementation of remove_element.
     * This is needed because we prevent gst_bin_remove from working, which the
     * parent dispose handler would use if we had any children left. */
    GST_BIN_CLASS (parent_class)->remove_element (GST_BIN_CAST (self),
        self->volume_element);
    self->volume_element = NULL;
  }

  G_OBJECT_CLASS (parent_class)->dispose (object);
}

static GstStateChangeReturn
gst_rg_volume_change_state (GstElement * element, GstStateChange transition)
{
  GstRgVolume *self = GST_RG_VOLUME (element);
  GstStateChangeReturn res;

  switch (transition) {
    case GST_STATE_CHANGE_NULL_TO_READY:

      if (G_UNLIKELY (self->volume_element == NULL)) {
        /* Creating our child volume element in _init failed. */
        return GST_STATE_CHANGE_FAILURE;
      }
      break;

    case GST_STATE_CHANGE_READY_TO_PAUSED:

      gst_rg_volume_reset (self);
      break;

    default:
      break;
  }

  res = GST_ELEMENT_CLASS (parent_class)->change_state (element, transition);

  return res;
}

/* Event function for the ghost sink pad. */
static gboolean
gst_rg_volume_sink_event (GstPad * pad, GstEvent * event)
{
  GstRgVolume *self;
  GstPad *volume_sink_pad;
  GstEvent *send_event = event;
  gboolean res;

  self = GST_RG_VOLUME (gst_pad_get_parent_element (pad));
  volume_sink_pad = gst_ghost_pad_get_target (GST_GHOST_PAD (pad));

  switch (GST_EVENT_TYPE (event)) {
    case GST_EVENT_TAG:

      GST_LOG_OBJECT (self, "received tag event");

      send_event = gst_rg_volume_tag_event (self, event);

      if (send_event == NULL)
        GST_LOG_OBJECT (self, "all tags handled, dropping event");

      break;

    case GST_EVENT_EOS:

      gst_rg_volume_reset (self);
      break;

    default:
      break;
  }

  if (G_LIKELY (send_event != NULL))
    res = gst_pad_send_event (volume_sink_pad, send_event);
  else
    res = TRUE;

  gst_object_unref (volume_sink_pad);
  gst_object_unref (self);
  return res;
}

static GstEvent *
gst_rg_volume_tag_event (GstRgVolume * self, GstEvent * event)
{
  GstTagList *tag_list;
  gboolean has_track_gain, has_track_peak, has_album_gain, has_album_peak;
  gboolean has_ref_level;

  g_return_val_if_fail (event != NULL, NULL);
  g_return_val_if_fail (GST_EVENT_TYPE (event) == GST_EVENT_TAG, event);

  gst_event_parse_tag (event, &tag_list);

  if (gst_tag_list_is_empty (tag_list))
    return event;

  has_track_gain = gst_tag_list_get_double (tag_list, GST_TAG_TRACK_GAIN,
      &self->track_gain);
  has_track_peak = gst_tag_list_get_double (tag_list, GST_TAG_TRACK_PEAK,
      &self->track_peak);
  has_album_gain = gst_tag_list_get_double (tag_list, GST_TAG_ALBUM_GAIN,
      &self->album_gain);
  has_album_peak = gst_tag_list_get_double (tag_list, GST_TAG_ALBUM_PEAK,
      &self->album_peak);
  has_ref_level = gst_tag_list_get_double (tag_list, GST_TAG_REFERENCE_LEVEL,
      &self->reference_level);

  if (!has_track_gain && !has_track_peak && !has_album_gain && !has_album_peak)
    return event;

  if (has_ref_level && (has_track_gain || has_album_gain)
      && (ABS (self->reference_level - RG_REFERENCE_LEVEL) > 1.e-6)) {
    /* Log a message stating the amount of adjustment that is applied below. */
    GST_DEBUG_OBJECT (self,
        "compensating for reference level difference by %" GAIN_FORMAT,
        RG_REFERENCE_LEVEL - self->reference_level);
  }
  if (has_track_gain) {
    self->track_gain += RG_REFERENCE_LEVEL - self->reference_level;
  }
  if (has_album_gain) {
    self->album_gain += RG_REFERENCE_LEVEL - self->reference_level;
  }

  /* Ignore values that are obviously invalid. */
  if (G_UNLIKELY (has_track_gain && !VALID_GAIN (self->track_gain))) {
    GST_DEBUG_OBJECT (self,
        "ignoring bogus track gain value %" GAIN_FORMAT, self->track_gain);
    has_track_gain = FALSE;
  }
  if (G_UNLIKELY (has_track_peak && !VALID_PEAK (self->track_peak))) {
    GST_DEBUG_OBJECT (self,
        "ignoring bogus track peak value %" PEAK_FORMAT, self->track_peak);
    has_track_peak = FALSE;
  }
  if (G_UNLIKELY (has_album_gain && !VALID_GAIN (self->album_gain))) {
    GST_DEBUG_OBJECT (self,
        "ignoring bogus album gain value %" GAIN_FORMAT, self->album_gain);
    has_album_gain = FALSE;
  }
  if (G_UNLIKELY (has_album_peak && !VALID_PEAK (self->album_peak))) {
    GST_DEBUG_OBJECT (self,
        "ignoring bogus album peak value %" PEAK_FORMAT, self->album_peak);
    has_album_peak = FALSE;
  }

  /* Clamp peaks >1.0.  Float based decoders can produce spurious samples >1.0,
   * cutting these files back to 1.0 should not cause any audible distortion.
   * This is most often seen with Vorbis files. */
  if (has_track_peak && self->track_peak > 1.) {
    GST_DEBUG_OBJECT (self,
        "clamping track peak %" PEAK_FORMAT " to 1.0", self->track_peak);
    self->track_peak = 1.0;
  }
  if (has_album_peak && self->album_peak > 1.) {
    GST_DEBUG_OBJECT (self,
        "clamping album peak %" PEAK_FORMAT " to 1.0", self->album_peak);
    self->album_peak = 1.0;
  }

  self->has_track_gain |= has_track_gain;
  self->has_track_peak |= has_track_peak;
  self->has_album_gain |= has_album_gain;
  self->has_album_peak |= has_album_peak;

  event = (GstEvent *) gst_mini_object_make_writable (GST_MINI_OBJECT (event));
  gst_event_parse_tag (event, &tag_list);

  gst_tag_list_remove_tag (tag_list, GST_TAG_TRACK_GAIN);
  gst_tag_list_remove_tag (tag_list, GST_TAG_TRACK_PEAK);
  gst_tag_list_remove_tag (tag_list, GST_TAG_ALBUM_GAIN);
  gst_tag_list_remove_tag (tag_list, GST_TAG_ALBUM_PEAK);
  gst_tag_list_remove_tag (tag_list, GST_TAG_REFERENCE_LEVEL);

  gst_rg_volume_update_gain (self);

  if (gst_tag_list_is_empty (tag_list)) {
    gst_event_unref (event);
    event = NULL;
  }

  return event;
}

static void
gst_rg_volume_reset (GstRgVolume * self)
{
  self->has_track_gain = FALSE;
  self->has_track_peak = FALSE;
  self->has_album_gain = FALSE;
  self->has_album_peak = FALSE;

  self->reference_level = RG_REFERENCE_LEVEL;

  gst_rg_volume_update_gain (self);
}

static void
gst_rg_volume_update_gain (GstRgVolume * self)
{
  gdouble target_gain, result_gain, result_volume;
  gboolean target_gain_changed, result_gain_changed;

  gst_rg_volume_determine_gain (self, &target_gain, &result_gain);

  result_volume = DB_TO_LINEAR (result_gain);

  /* Ensure that the result volume is within the range that the volume element
   * can handle.  Currently, the limit is 10. (+20 dB), which should not be
   * restrictive. */
  if (G_UNLIKELY (result_volume > self->max_volume)) {
    GST_INFO_OBJECT (self,
        "cannot handle result gain of %" GAIN_FORMAT " (%0.6f), adjusting",
        result_gain, result_volume);

    result_volume = self->max_volume;
    result_gain = LINEAR_TO_DB (result_volume);
  }

  /* Direct comparison is OK in this case. */
  if (target_gain == result_gain) {
    GST_INFO_OBJECT (self,
        "result gain is %" GAIN_FORMAT " (%0.6f), matching target",
        result_gain, result_volume);
  } else {
    GST_INFO_OBJECT (self,
        "result gain is %" GAIN_FORMAT " (%0.6f), target is %" GAIN_FORMAT,
        result_gain, result_volume, target_gain);
  }

  target_gain_changed = (self->target_gain != target_gain);
  result_gain_changed = (self->result_gain != result_gain);

  self->target_gain = target_gain;
  self->result_gain = result_gain;

  g_object_set (self->volume_element, "volume", result_volume, NULL);

  if (target_gain_changed)
    g_object_notify ((GObject *) self, "target-gain");
  if (result_gain_changed)
    g_object_notify ((GObject *) self, "result-gain");
}

static inline void
gst_rg_volume_determine_gain (GstRgVolume * self, gdouble * target_gain,
    gdouble * result_gain)
{
  gdouble gain, peak;

  if (!self->has_track_gain && !self->has_album_gain) {

    GST_DEBUG_OBJECT (self, "using fallback gain");
    gain = self->fallback_gain;
    peak = 1.0;

  } else if ((self->album_mode && self->has_album_gain)
      || (!self->album_mode && !self->has_track_gain)) {

    gain = self->album_gain;
    if (G_LIKELY (self->has_album_peak)) {
      peak = self->album_peak;
    } else {
      GST_DEBUG_OBJECT (self, "album peak missing, assuming 1.0");
      peak = 1.0;
    }
    /* Falling back from track to album gain shouldn't really happen. */
    if (G_UNLIKELY (!self->album_mode))
      GST_INFO_OBJECT (self, "falling back to album gain");

  } else {
    /* !album_mode && !has_album_gain || album_mode && has_track_gain */

    gain = self->track_gain;
    if (G_LIKELY (self->has_track_peak)) {
      peak = self->track_peak;
    } else {
      GST_DEBUG_OBJECT (self, "track peak missing, assuming 1.0");
      peak = 1.0;
    }
    if (self->album_mode)
      GST_INFO_OBJECT (self, "falling back to track gain");
  }

  gain += self->pre_amp;

  *target_gain = gain;
  *result_gain = gain;

  if (LINEAR_TO_DB (peak) + gain > self->headroom) {
    *result_gain = LINEAR_TO_DB (1. / peak) + self->headroom;
  }
}