GStreamer Plugin Writer's Guide (0.10.12) | ||
---|---|---|
<<< Previous | Interfaces | Next >>> |
The goal of the mixer interface is to provide a simple yet powerful API to applications for audio hardware mixer/volume control. Most soundcards have hardware mixers, where volume can be changed, they can be muted, inputs can be modified to mix their content into what will be read from the device by applications (in our case: audio source plugins). The mixer interface is the way to control those. The mixer interface can also be used for volume control in software (e.g. the "volume" element). The end goal of this interface is to allow development of hardware volume control applications and for the control of audio volume and input/output settings.
The mixer interface requires the
GstImplementsInterface
interface to be implemented by the element. The example below will
feature both, so it serves as an example for the
GstImplementsInterface
, too. In this
interface, it is required to set a function pointer for the
supported () function.
If you don't, this function will always return FALSE (default
implementation) and the mixer interface implementation will not work. For
the mixer interface, the only required function is
list_tracks (). All other function pointers in the
mixer interface are optional, although it is strongly recommended to set
function pointers for at least the get_volume () and
set_volume () functions. The API reference for this
interface documents the goal of each function, so we will limit ourselves
to the implementation here.
The following example shows a mixer implementation for a software N-to-1 element. It does not show the actual process of stream mixing, that is far too complicated for this guide.
#include <gst/mixer/mixer.h> typedef struct _GstMyFilter { [..] gint volume; GList *tracks; } GstMyFilter; static void gst_my_filter_implements_interface_init (GstImplementsInterfaceClass *iface); static void gst_my_filter_mixer_interface_init (GstMixerClass *iface); GType gst_my_filter_get_type (void) { [..] static const GInterfaceInfo implements_interface_info = { (GInterfaceInitFunc) gst_my_filter_implements_interface_init, NULL, NULL }; static const GInterfaceInfo mixer_interface_info = { (GInterfaceInitFunc) gst_my_filter_mixer_interface_init, NULL, NULL }; [..] g_type_add_interface_static (my_filter_type, GST_TYPE_IMPLEMENTS_INTERFACE, &implements_interface_info); g_type_add_interface_static (my_filter_type, GST_TYPE_MIXER, &mixer_interface_info); [..] } static void gst_my_filter_init (GstMyFilter *filter) { GstMixerTrack *track = NULL; [..] filter->volume = 100; filter->tracks = NULL; track = g_object_new (GST_TYPE_MIXER_TRACK, NULL); track->label = g_strdup ("MyTrack"); track->num_channels = 1; track->min_volume = 0; track->max_volume = 100; track->flags = GST_MIXER_TRACK_SOFTWARE; filter->tracks = g_list_append (filter->tracks, track); } static gboolean gst_my_filter_interface_supported (GstImplementsInterface *iface, GType iface_type) { g_return_val_if_fail (iface_type == GST_TYPE_MIXER, FALSE); /* for the sake of this example, we'll always support it. However, normally, * you would check whether the device you've opened supports mixers. */ return TRUE; } static void gst_my_filter_implements_interface_init (GstImplementsInterfaceClass *iface) { iface->supported = gst_my_filter_interface_supported; } /* * This function returns the list of support tracks (inputs, outputs) * on this element instance. Elements usually build this list during * _init () or when going from NULL to READY. */ static const GList * gst_my_filter_mixer_list_tracks (GstMixer *mixer) { GstMyFilter *filter = GST_MY_FILTER (mixer); return filter->tracks; } /* * Set volume. volumes is an array of size track->num_channels, and * each value in the array gives the wanted volume for one channel * on the track. */ static void gst_my_filter_mixer_set_volume (GstMixer *mixer, GstMixerTrack *track, gint *volumes) { GstMyFilter *filter = GST_MY_FILTER (mixer); filter->volume = volumes[0]; g_print ("Volume set to %d\n", filter->volume); } static void gst_my_filter_mixer_get_volume (GstMixer *mixer, GstMixerTrack *track, gint *volumes) { GstMyFilter *filter = GST_MY_FILTER (mixer); volumes[0] = filter->volume; } static void gst_my_filter_mixer_interface_init (GstMixerClass *iface) { /* the mixer interface requires a definition of the mixer type: * hardware or software? */ GST_MIXER_TYPE (iface) = GST_MIXER_SOFTWARE; /* virtual function pointers */ iface->list_tracks = gst_my_filter_mixer_list_tracks; iface->set_volume = gst_my_filter_mixer_set_volume; iface->get_volume = gst_my_filter_mixer_get_volume; } |
The mixer interface is very audio-centric. However, with the software flag set, the mixer can be used to mix any kind of stream in a N-to-1 element to join (not aggregate!) streams together into one output stream. Conceptually, that's called mixing too. You can always use the element factory's "category" to indicate type of your element. In a software element that mixes random streams, you would not be required to implement the _get_volume () or _set_volume () functions. Rather, you would only implement the _set_record () to enable or disable tracks in the output stream. to make sure that a mixer-implementing element is of a certain type, check the element factory's category.
<<< Previous | Home | Next >>> |
URI interface | Up | Tuner Interface |