<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <HTML ><HEAD ><TITLE >Mixer Interface</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK REL="HOME" TITLE="GStreamer Plugin Writer's Guide" HREF="index.html"><LINK REL="UP" TITLE="Interfaces" HREF="chapter-advanced-interfaces.html"><LINK REL="PREVIOUS" TITLE="Interfaces" HREF="chapter-advanced-interfaces.html"><LINK REL="NEXT" TITLE="Tuner Interface" HREF="section-iface-tuner.html"></HEAD ><BODY CLASS="sect1" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#840084" ALINK="#0000FF" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" ><SPAN CLASS="application" >GStreamer</SPAN > Plugin Writer's Guide</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="chapter-advanced-interfaces.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" >Chapter 18. Interfaces</TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="section-iface-tuner.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><DIV CLASS="sect1" ><H1 CLASS="sect1" ><A NAME="section-iface-mixer" >18.2. Mixer Interface</A ></H1 ><P > 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 <SPAN CLASS="QUOTE" >"volume"</SPAN > 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. </P ><P > The mixer interface requires the <CODE CLASS="classname" >GstImplementsInterface</CODE > interface to be implemented by the element. The example below will feature both, so it serves as an example for the <CODE CLASS="classname" >GstImplementsInterface</CODE >, too. In the <CODE CLASS="classname" >GstImplementsInterface</CODE >, it is required to set a function pointer for the <CODE CLASS="function" >supported ()</CODE > 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 <CODE CLASS="function" >list_tracks ()</CODE >. All other function pointers in the mixer interface are optional, although it is strongly recommended to set function pointers for at least the <CODE CLASS="function" >get_volume ()</CODE > and <CODE CLASS="function" >set_volume ()</CODE > functions. The API reference for this interface documents the goal of each function, so we will limit ourselves to the implementation here. </P ><P > 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. </P ><PRE CLASS="programlisting" > #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; } </PRE ><P > 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 <SPAN CLASS="QUOTE" >"category"</SPAN > to indicate type of your element. In a software element that mixes random streams, you would not be required to implement the <CODE CLASS="function" >_get_volume ()</CODE > or <CODE CLASS="function" >_set_volume ()</CODE > functions. Rather, you would only implement the <CODE CLASS="function" >_set_record ()</CODE > 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. </P ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="chapter-advanced-interfaces.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="section-iface-tuner.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >Interfaces</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="chapter-advanced-interfaces.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >Tuner Interface</TD ></TR ></TABLE ></DIV ></BODY ></HTML >