gststreamvolume

gststreamvolume — Interface for elements that provide a stream volume

Synopsis

#include <gst/audio/streamvolume.h>

                    GstStreamVolume;
enum                GstStreamVolumeFormat;
gdouble             gst_stream_volume_get_volume        (GstStreamVolume *volume,
                                                         GstStreamVolumeFormat format);
void                gst_stream_volume_set_volume        (GstStreamVolume *volume,
                                                         GstStreamVolumeFormat format,
                                                         gdouble val);
gboolean            gst_stream_volume_get_mute          (GstStreamVolume *volume);
void                gst_stream_volume_set_mute          (GstStreamVolume *volume,
                                                         gboolean mute);
gdouble             gst_stream_volume_convert_volume    (GstStreamVolumeFormat from,
                                                         GstStreamVolumeFormat to,
                                                         gdouble val);

Object Hierarchy

  GInterface
   +----GstStreamVolume

Prerequisites

GstStreamVolume requires GObject.

Properties

  "mute"                     gboolean              : Read / Write
  "volume"                   gdouble               : Read / Write

Description

This interface is implemented by elements that provide a stream volume. Examples for such elements are volume and playbin.

Applications can use this interface to get or set the current stream volume. For this the "volume" GObject property can be used or the helper functions gst_stream_volume_set_volume() and gst_stream_volume_get_volume(). This volume is always a linear factor, i.e. 0.0 is muted 1.0 is 100%. For showing the volume in a GUI it might make sense to convert it to a different format by using gst_stream_volume_convert_volume(). Volume sliders should usually use a cubic volume.

Separate from the volume the stream can also be muted by the "mute" GObject property or gst_stream_volume_set_mute() and gst_stream_volume_get_mute().

Elements that provide some kind of stream volume should implement the "volume" and "mute" GObject properties and handle setting and getting of them properly. The volume property is defined to be a linear volume factor.

Details

GstStreamVolume

typedef struct _GstStreamVolume GstStreamVolume;

enum GstStreamVolumeFormat

typedef enum {
  GST_STREAM_VOLUME_FORMAT_LINEAR = 0,
  GST_STREAM_VOLUME_FORMAT_CUBIC,
  GST_STREAM_VOLUME_FORMAT_DB
} GstStreamVolumeFormat;

Different representations of a stream volume. gst_stream_volume_convert_volume() allows to convert between the different representations.

Formulas to convert from a linear to a cubic or dB volume are cbrt(val) and 20 * log10 (val).

GST_STREAM_VOLUME_FORMAT_LINEAR

Linear scale factor, 1.0 = 100%

GST_STREAM_VOLUME_FORMAT_CUBIC

Cubic volume scale

GST_STREAM_VOLUME_FORMAT_DB

Logarithmic volume scale (dB, amplitude not power)

gst_stream_volume_get_volume ()

gdouble             gst_stream_volume_get_volume        (GstStreamVolume *volume,
                                                         GstStreamVolumeFormat format);

volume :

GstStreamVolume that should be used

format :

GstStreamVolumeFormat which should be returned

Returns :

The current stream volume as linear factor

gst_stream_volume_set_volume ()

void                gst_stream_volume_set_volume        (GstStreamVolume *volume,
                                                         GstStreamVolumeFormat format,
                                                         gdouble val);

volume :

GstStreamVolume that should be used

format :

GstStreamVolumeFormat of val

val :

Linear volume factor that should be set

gst_stream_volume_get_mute ()

gboolean            gst_stream_volume_get_mute          (GstStreamVolume *volume);

volume :

GstStreamVolume that should be used

Returns :

Returns TRUE if the stream is muted

gst_stream_volume_set_mute ()

void                gst_stream_volume_set_mute          (GstStreamVolume *volume,
                                                         gboolean mute);

volume :

GstStreamVolume that should be used

mute :

Mute state that should be set

gst_stream_volume_convert_volume ()

gdouble             gst_stream_volume_convert_volume    (GstStreamVolumeFormat from,
                                                         GstStreamVolumeFormat to,
                                                         gdouble val);

from :

GstStreamVolumeFormat to convert from

to :

GstStreamVolumeFormat to convert to

val :

Volume in from format that should be converted

Returns :

the converted volume

Property Details

The "mute" property

  "mute"                     gboolean              : Read / Write

Mute the audio channel without changing the volume.

Default value: FALSE


The "volume" property

  "volume"                   gdouble               : Read / Write

Linear volume factor, 1.0=100%.

Allowed values: >= 0

Default value: 1