gstmixer

## gstmixer gstmixer — Interface for elements that provide mixer operations |

## Functions

const GList * | gst_mixer_list_tracks ()
void | gst_mixer_get_volume ()
void | gst_mixer_set_volume ()
void | gst_mixer_set_mute ()
void | gst_mixer_set_record ()
void | gst_mixer_set_option ()
void | gst_mixer_mute_toggled ()
void | gst_mixer_record_toggled ()
void | gst_mixer_volume_changed ()
void | gst_mixer_option_changed ()
void | gst_mixer_options_list_changed ()
const gchar * | gst_mixer_get_option ()
void | gst_mixer_mixer_changed ()
GstMixerFlags | gst_mixer_get_mixer_flags ()
GstMixerType | gst_mixer_get_mixer_type ()
GstMixerMessageType | gst_mixer_message_get_type ()
void | gst_mixer_message_parse_mute_toggled ()
void | gst_mixer_message_parse_option_changed ()
void | gst_mixer_message_parse_record_toggled ()
void | gst_mixer_message_parse_volume_changed ()
void | gst_mixer_message_parse_options_list_changed ()

## Signals

void | mute-toggled | Run Last
void | option-changed | Run Last
void | record-toggled | Run Last
void | volume-changed | Run Last

## Types and Values

| GstMixer
enum | GstMixerType
enum | GstMixerFlags
enum | GstMixerMessageType

## Object Hierarchy

        GInterface
        ╰── GstMixer

## Prerequisites

GstMixer requires GstImplementsInterface and GstElement.

## Includes

    #include <gst/interfaces/mixer.h>

## Description

Basic interface for hardware mixer controls.

Applications rarely need to use this interface, it is provided mainly for system-level mixer applets and the like. Volume control in playback applications should be done using a `volume` element or, if available, using the “volume” property of the audio sink element used (as provided by `pulsesink` for example), or even better: just use the `playbin2` element's “volume” property.

Usage: In order to use the `GstMixer` interface, the element needs to be at least in READY state (so that the element has opened the mixer device). Once the element has been set to READY state or higher, it can be cast to a `GstMixer` using the GST_MIXER macro (in C) and the mixer API can be used.

## Functions

### gst_mixer_list_tracks ()

    const GList *
    gst_mixer_list_tracks (GstMixer *mixer);

Returns a list of available tracks for this mixer/element. Note that it is allowed for sink (output) elements to only provide the output tracks in this list. Likewise, for sources (inputs), it is allowed to only provide input elements in this list.

#### Parameters

mixer | the GstMixer (a GstElement) to get the tracks from. |

#### Returns

A GList consisting of zero or more GstMixerTracks. The list is owned by the GstMixer instance and must not be freed or modified.

### gst_mixer_get_volume ()

    void
    gst_mixer_get_volume (GstMixer *mixer,
                          GstMixerTrack *track,
                          gint *volumes);

Get the current volume(s) on the given track.

#### Parameters

mixer | the GstMixer (a GstElement) that owns the track |
track | the GstMixerTrack to get the volume from. |
volumes | a pre-allocated array of integers (of size track->num_channels) to store the current volume of each channel in the given track in. |

### gst_mixer_set_volume ()

    void
    gst_mixer_set_volume (GstMixer *mixer,
                          GstMixerTrack *track,
                          gint *volumes);

Sets the volume on each channel in a track. Short note about naming: a track is defined as one separate stream owned by the mixer/element, such as 'Line-in' or 'Microphone'. A channel is said to be a mono-stream inside this track. A stereo track thus contains two channels.

#### Parameters

mixer | The GstMixer (a GstElement) that owns the track. |
track | The GstMixerTrack to set the volume on. |
volumes | an array of integers (of size track->num_channels) that gives the wanted volume for each channel in this track. |

### gst_mixer_set_mute ()

    void
    gst_mixer_set_mute (GstMixer *mixer,
                        GstMixerTrack *track,
                        gboolean mute);

Mutes or unmutes the given channel. To find out whether a track is currently muted, use `GST_MIXER_TRACK_HAS_FLAG()`.

#### Parameters

mixer | the GstMixer (a GstElement) that owns the track. |
track | the GstMixerTrack to operate on. |
mute | a boolean value indicating whether to turn on or off muting. |

### gst_mixer_set_record ()

    void
    gst_mixer_set_record (GstMixer *mixer,
                          GstMixerTrack *track,
                          gboolean record);

Enables or disables recording on the given track. Note that this is only possible on input tracks, not on output tracks (see `GST_MIXER_TRACK_HAS_FLAG()` and the GST_MIXER_TRACK_INPUT flag).

#### Parameters

mixer | The GstMixer (a GstElement) that owns the track. |
track | the GstMixerTrack to operate on. |
record | a boolean value that indicates whether to turn on or off recording. |

### gst_mixer_set_option ()

    void
    gst_mixer_set_option (GstMixer *mixer,
                          GstMixerOptions *opts,
                          gchar *value);

Sets a name/value option in the mixer to the requested value.

#### Parameters

mixer | The GstMixer (a GstElement) that owns the optionlist. |
opts | The GstMixerOptions that we operate on. |
value | The requested new option value. |

### gst_mixer_mute_toggled ()

    void
    gst_mixer_mute_toggled (GstMixer *mixer,
                            GstMixerTrack *track,
                            gboolean mute);

This function is called by the mixer implementation to produce a notification message on the bus indicating that the given track has changed mute state.

This function only works for GstElements that are implementing the GstMixer interface, and the element needs to have been provided a bus.

#### Parameters

mixer | the GstMixer (a GstElement) that owns the track |
track | the GstMixerTrack that has change mute state. |
mute | the new state of the mute flag on the track |

### gst_mixer_record_toggled ()

    void
    gst_mixer_record_toggled (GstMixer *mixer,
                              GstMixerTrack *track,
                              gboolean record);

This function is called by the mixer implementation to produce a notification message on the bus indicating that the given track has changed recording state.

This function only works for GstElements that are implementing the GstMixer interface, and the element needs to have been provided a bus.

#### Parameters

mixer | the GstMixer (a GstElement) that owns the track |
track | the GstMixerTrack that has changed recording state. |
record | the new state of the record flag on the track |

### gst_mixer_volume_changed ()

    void
    gst_mixer_volume_changed (GstMixer *mixer,
                              GstMixerTrack *track,
                              gint *volumes);

This function is called by the mixer implementation to produce a notification message on the bus indicating that the volume(s) for the given track have changed.

This function only works for GstElements that are implementing the GstMixer interface, and the element needs to have been provided a bus.

#### Parameters

mixer | the GstMixer (a GstElement) that owns the track |
track | the GstMixerTrack that has changed. |
volumes | Array of volume values, one per channel on the mixer track. |

### gst_mixer_option_changed ()

    void
    gst_mixer_option_changed (GstMixer *mixer,
                              GstMixerOptions *opts,
                              const gchar *value);

This function is called by the mixer implementation to produce a notification message on the bus indicating that the given options object has changed state.

This function only works for GstElements that are implementing the GstMixer interface, and the element needs to have been provided a bus.

#### Parameters

mixer | the GstMixer (a GstElement) that owns the options |
opts | the GstMixerOptions that has changed value. |
value | the new value of the GstMixerOptions. |

### gst_mixer_options_list_changed ()

    void
    gst_mixer_options_list_changed (GstMixer *mixer,
                                    GstMixerOptions *opts);

This function is called by the mixer implementation to produce a notification message on the bus indicating that the list of possible options of a given options object has changed.

The new options are not contained in the message on purpose. Applications should call `gst_mixer_options_get_values()` on `opts` to make `opts` update its internal state and obtain the new list of values.

This function only works for GstElements that are implementing the GstMixer interface, and the element needs to have been provided a bus for this to work.

#### Parameters

mixer | the GstMixer (a GstElement) that owns the options |
opts | the GstMixerOptions whose list of values has changed |

Since: 0.10.18

### gst_mixer_get_option ()

    const gchar *
    gst_mixer_get_option (GstMixer *mixer,
                          GstMixerOptions *opts);

Get the current value of a name/value option in the mixer.

#### Parameters

mixer | The GstMixer (a GstElement) that owns the optionlist. |
opts | The GstMixerOptions that we operate on. |

#### Returns

current value of the name/value option.

### gst_mixer_mixer_changed ()

    void
    gst_mixer_mixer_changed (GstMixer *mixer);

This function is called by the mixer implementation to produce a notification message on the bus indicating that the list of available mixer tracks for a given mixer object has changed. Applications should rebuild their interface when they receive this message.

This function only works for GstElements that are implementing the GstMixer interface, and the element needs to have been provided a bus.

#### Parameters

mixer | the GstMixer (a GstElement) which has changed |

Since: 0.10.18

### gst_mixer_get_mixer_flags ()

    GstMixerFlags
    gst_mixer_get_mixer_flags (GstMixer *mixer);

Get the set of supported flags for this mixer implementation.

#### Parameters

mixer | The GstMixer implementation |

#### Returns

A set of or-ed GstMixerFlags for supported features.

### gst_mixer_get_mixer_type ()

    GstMixerType
    gst_mixer_get_mixer_type (GstMixer *mixer);

Get the GstMixerType of this mixer implementation.

#### Parameters

mixer | The GstMixer implementation |

#### Returns

A the GstMixerType.

Since: 0.10.24

### gst_mixer_message_get_type ()

    GstMixerMessageType
    gst_mixer_message_get_type (GstMessage *message);

Check a bus message to see if it is a GstMixer notification message and return the GstMixerMessageType identifying which type of notification it is.

#### Parameters

message | A GstMessage to inspect. |

#### Returns

The type of the GstMixerMessage, or GST_MIXER_MESSAGE_INVALID if the message is not a GstMixer notification.

Since: 0.10.14

### gst_mixer_message_parse_mute_toggled ()

    void
    gst_mixer_message_parse_mute_toggled (GstMessage *message,
                                          GstMixerTrack **track,
                                          gboolean *mute);

Extracts the contents of a mute-toggled bus message. Reads the GstMixerTrack that has changed, and the new value of the mute flag.

The GstMixerTrack remains valid until the message is freed.

#### Parameters

message | A mute-toggled change notification message. |
track | Pointer to hold a GstMixerTrack object, or NULL. |
mute | A pointer to a gboolean variable, or NULL. |

Since: 0.10.14

### gst_mixer_message_parse_option_changed ()

    void
    gst_mixer_message_parse_option_changed
                                   (GstMessage *message,
                                    GstMixerOptions **options,
                                    const gchar **value);

Extracts the GstMixerOptions and new value from a option-changed bus notification message.

The options and value returned remain valid until the message is freed.

#### Parameters

message | A volume-changed change notification message. |
options | Pointer to hold a GstMixerOptions object, or NULL. |
value | Result location to receive the new options value, or NULL. |

Since: 0.10.14

### gst_mixer_message_parse_record_toggled ()

    void
    gst_mixer_message_parse_record_toggled
                                   (GstMessage *message,
                                    GstMixerTrack **track,
                                    gboolean *record);

Extracts the contents of a record-toggled bus message. Reads the GstMixerTrack that has changed, and the new value of the recording flag.

The GstMixerTrack remains valid until the message is freed.

#### Parameters

message | A record-toggled change notification message. |
track | Pointer to hold a GstMixerTrack object, or NULL. |
record | A pointer to a gboolean variable, or NULL. |

Since: 0.10.14

### gst_mixer_message_parse_volume_changed ()

    void
    gst_mixer_message_parse_volume_changed
                                   (GstMessage *message,
                                    GstMixerTrack **track,
                                    gint **volumes,
                                    gint *num_channels);

Parses a volume-changed notification message and extracts the track object it refers to, as well as an array of volumes and the size of the volumes array.

The track object remains valid until the message is freed.

The caller must free the array returned in the volumes parameter using g_free when they are done with it.

#### Parameters

message | A volume-changed change notification message. |
track | Pointer to hold a GstMixerTrack object, or NULL. |
volumes | A pointer to receive an array of gint values, or NULL. |
num_channels | Result location to receive the number of channels, or NULL. |

Since: 0.10.14

### gst_mixer_message_parse_options_list_changed ()

    void
    gst_mixer_message_parse_options_list_changed
                                   (GstMessage *message,
                                    GstMixerOptions **options);

Extracts the GstMixerOptions whose value list has changed from an options-list-changed bus notification message.

The options object returned remains valid until the message is freed. You do not need to unref it.

#### Parameters

message | A volume-changed change notification message. |
options | Pointer to hold a GstMixerOptions object, or NULL. |

Since: 0.10.18

## Types and Values

### GstMixer

    typedef struct _GstMixer GstMixer;

### enum GstMixerType

Mixer classification.

#### Members

GST_MIXER_HARDWARE | mixing is implemented with dedicated hardware. |
GST_MIXER_SOFTWARE | mixing is implemented via software processing. |

### enum GstMixerFlags

Flags indicating which optional features are supported by a mixer implementation.

#### Members

GST_MIXER_FLAG_NONE | No flags |
GST_MIXER_FLAG_AUTO_NOTIFICATIONS | The mixer implementation automatically sends notification messages. |
GST_MIXER_FLAG_HAS_WHITELIST | The mixer implementation flags tracks that should be displayed by default (whitelisted). Since: 0.10.23 |
GST_MIXER_FLAG_GROUPING | The mixer implementation will leave some controls marked without either input or output. Controls marked as input or output should be grouped with input & output sliders, even if they are options or bare switches. Since: 0.10.23 |

Since: 0.10.14

### enum GstMixerMessageType

An enumeration for the type of a GstMixer message received on the bus

#### Members

GST_MIXER_MESSAGE_INVALID | Not a GstMixer message |
GST_MIXER_MESSAGE_MUTE_TOGGLED | A mute-toggled GstMixer message |
GST_MIXER_MESSAGE_RECORD_TOGGLED | A record-toggled GstMixer message |
GST_MIXER_MESSAGE_VOLUME_CHANGED | A volume-changed GstMixer message |
GST_MIXER_MESSAGE_OPTION_CHANGED | An option-changed GstMixer message |
GST_MIXER_MESSAGE_OPTIONS_LIST_CHANGED | An options-list-changed GstMixer message, posted when the list of available options for a GstMixerOptions object has changed (Since: 0.10.18) |
GST_MIXER_MESSAGE_MIXER_CHANGED | A mixer-changed GstMixer message, posted when the list of available mixer tracks has changed. The application should re-build its interface in this case (Since: 0.10.18) |

Since: 0.10.14

## Signal Details

### The `“mute-toggled”` signal

    void
    user_function (GstMixer      *gstmixer,
                   GstMixerTrack *arg1,
                   gboolean       arg2,
                   gpointer       user_data)

Flags: Run Last

### The `“option-changed”` signal

    void
    user_function (GstMixer        *gstmixer,
                   GstMixerOptions *arg1,
                   gchar           *arg2,
                   gpointer         user_data)

Flags: Run Last

### The `“record-toggled”` signal

    void
    user_function (GstMixer      *gstmixer,
                   GstMixerTrack *arg1,
                   gboolean       arg2,
                   gpointer       user_data)

Flags: Run Last

### The `“volume-changed”` signal

    void
    user_function (GstMixer      *gstmixer,
                   GstMixerTrack *arg1,
                   gpointer       arg2,
                   gpointer       user_data)

Flags: Run Last

## See Also

alsamixer, oss4mixer, sunaudiomixer