## GstStreamVolume

GstStreamVolume — Interface for elements that provide a stream volume

## Functions

gdouble | gst_stream_volume_get_volume ()
void | gst_stream_volume_set_volume ()
gboolean | gst_stream_volume_get_mute ()
void | gst_stream_volume_set_mute ()
gdouble | gst_stream_volume_convert_volume ()

## Properties

gboolean | mute | Read / Write
double | volume | Read / Write

## Types and Values

| GstStreamVolume
enum | GstStreamVolumeFormat

## Object Hierarchy

        GInterface
        ╰── GstStreamVolume

## Prerequisites

GstStreamVolume requires GObject.

## Includes

    #include <gst/audio/audio.h>

## 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.

## Functions

### gst_stream_volume_get_volume ()

    gdouble
    gst_stream_volume_get_volume (GstStreamVolume *volume,
                                  GstStreamVolumeFormat format);

#### Parameters

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);

#### Parameters

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);

#### Parameters

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);

#### Parameters

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);

#### Parameters

from | GstStreamVolumeFormat to convert from |
to | GstStreamVolumeFormat to convert to |
val | Volume in `from` format that should be converted |

#### Returns

the converted volume

## Types and Values

### GstStreamVolume

    typedef struct _GstStreamVolume GstStreamVolume;

### enum 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).

#### Members

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) |

## Property Details

### The `“mute”` property

      “mute”                     gboolean

Mute the audio channel without changing the volume.

Owner: GstStreamVolume

Flags: Read / Write

Default value: FALSE

### The `“volume”` property

      “volume”                   double

Linear volume factor, 1.0=100%.

Owner: GstStreamVolume

Flags: Read / Write

Allowed values: >= 0

Default value: 1