gstreamer/docs/manual/appendix-integration.xml

<chapter id="chapter-intgration">
  <title>Integration</title>
  <para>
    &GStreamer; tries to integrate closely with operating systems (such
    as Linux and UNIX-like operating systems, OS X or Windows) and desktop
    environments (such as GNOME or KDE). In this chapter, we'll mention
    some specific techniques to integrate your application with your
    operating system or desktop environment of choice.
  </para>
 
  <sect1 id="section-integration-nix">
    <title>Linux and UNIX-like operating systems</title>
    <para>
      &GStreamer; provides a basic set of elements that are useful when
      integrating with Linux or a UNIX-like operating system.
    </para>
    <itemizedlist>
      <listitem>
        <para>
          For audio input and output, &GStreamer; provides input and
          output elements for several audio subsystems. Amongst others,
          &GStreamer; includes elements for ALSA (alsasrc, alsamixer,
          alsasink), OSS (osssrc, ossmixer, osssink) and Sun audio
          (sunaudiosrc, sunaudiomixer, sunaudiosink).
        </para>
      </listitem>
      <listitem>
        <para>
          For video input, &GStreamer; contains source elements for
          Video4linux (v4lsrc, v4lmjpegsrc, v4lelement and v4lmjpegisnk)
          and Video4linux2 (v4l2src, v4l2element).
        </para>
      </listitem>
      <listitem>
        <para>
          For video output, &GStreamer; provides elements for output
          to X-windows (ximagesink), Xv-windows (xvimagesink; for
          hardware-accelerated video), direct-framebuffer (dfbimagesink)
          and openGL image contexts (glsink).
        </para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="section-integration-gnome">
    <title>GNOME desktop</title>
    <para>
      &GStreamer; has been the media backend of the <ulink type="http"
      url="http://www.gnome.org/">GNOME</ulink> desktop since GNOME-2.2
      onwards. Nowadays, a whole bunch of GNOME applications make use of
      &GStreamer; for media-processing, including (but not limited to)
      <ulink type="http" url="http://www.rhythmbox.org/">Rhythmbox</ulink>,
      <ulink type="http" url="http://www.hadess.net/totem.php3">Totem</ulink>
      and <ulink type="http"
      url="http://www.burtonini.com/blog/computers/sound-juicer">Sound
      Juicer</ulink>.
    </para>
    <para>
      Most of these GNOME applications make use of some specific techniques
      to integrate as closely as possible with the GNOME desktop:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          GNOME applications call <function>gnome_program_init ()</function>
          to parse command-line options and initialize the necessary gnome
          modules. &GStreamer; applications would normally call
          <function>gst_init ()</function> to do the same for GStreamer.
          This would mean that only one of the two can parse command-line
          options. To work around this issue, &GStreamer; can provide a
          GLib <classname>GOptionGroup</classname> which can be passed to
          <function>gnome_program_init ()</function>. The following
          example requires Gnome-2.14 or newer (previous libgnome versions
          do not support command line parsing via GOption yet but use the
          now deprecated popt)
        </para>
        <programlisting><!-- example-begin gnome.c a -->
#include &lt;gnome.h&gt;
#include &lt;gst/gst.h&gt;

static gchar **cmd_filenames = NULL;

static GOptionEntries cmd_options[] = {
  /* here you can add command line options for your application. Check
   * the GOption section in the GLib API reference for a more elaborate
   * example of how to add your own command line options here */

  /* at the end we have a special option that collects all remaining 
   * command line arguments (like filenames) for us. If you don&apos;
   * need this, you can safely remove it */
  { G_OPTION_REMAINING, 0, 0, G_OPTION_ARG_FILENAME_ARRAY, &amp;cmd_filenames,
    "Special option that collects any remaining arguments for us" },

  /* mark the end of the options array with a NULL option */
  { NULL, }
};

/* this should usually be defined in your config.h */
#define VERSION "0.0.1"

gint
main (gint argc, gchar **argv)
{
  GOptionContext *context;
  GOptionGroup *gstreamer_group;
  GnomeProgram *program;

  /* we must initialise the threading system before using any
   * other GLib funtion, such as g_option_context_new() */
  if (!g_thread_supported ())
    g_thread_init (NULL);

  context = g_option_context_new ("gnome-demo-app");

  /* get command line options from GStreamer and add them to the group */
  gstreamer_group = gst_init_get_option_group ();
  g_option_context_add_group (context, gstreamer_group);

  /* add our own options. If you are using gettext for translation of your
   * strings, use GETTEXT_PACKAGE here instead of NULL */
  g_option_context_add_main_entries (context, cmd_options, NULL);

  program = gnome_program_init ("gnome-demo-app", VERSION
                                LIBGNOMEUI_MODULE, argc, argv,
                                GNOME_PARAM_HUMAN_READABLE_NAME, "Gnome Demo",
                                GNOME_PARAM_GOPTION_CONTEXT, context,
                                NULL);

  /* any filenames we got passed on the command line? parse them! */
  if (cmd_filenames != NULL) {
    guint i, num;

    num = g_strv_length (cmd_filenames);
    for (i = 0; i &lt; num; ++i) {
      /* do something with the filename ... */
      g_print ("Adding to play queue: %s\n", cmd_filenames[i]);
    }

    g_strfreev (cmd_filenames);
    cmd_filenames = NULL;
  }
<!-- example-end gnome.c a -->
[..]<!-- example-begin gnome.c b --><!--
  return 0;
--><!-- example-end gnome.c b -->
<!-- example-begin gnome.c c -->
}
        <!-- example-end gnome.c c --></programlisting>
      </listitem>
      <listitem>
        <para>
          GNOME stores the default video and audio sources and sinks in GConf.
          &GStreamer; provides a number of elements that create audio and
          video sources and sinks directly based on those GConf settings. 
          Those elements are: gconfaudiosink, gconfvideosink, gconfaudiosrc
          and gconfvideosrc. You can create them with
          <function>gst_element_factory_make ()</function> and use them
          directly just like you would use any other source or sink element.
          All GNOME applications are recommended to use those elements.
        </para>
      </listitem>
      <listitem>
        <para>
          &GStreamer; provides data input/output elements for use with the
          GNOME-VFS system. These elements are called <quote>gnomevfssrc</quote>
          and <quote>gnomevfssink</quote>.
        </para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="section-integration-kde">
    <title>KDE desktop</title>
    <para>
      &GStreamer; has been proposed for inclusion in KDE-4.0. Currently,
      &GStreamer; is included as an optional component, and it's used by
      several KDE applications, including <ulink type="http"
      url="http://amarok.kde.org/">AmaroK</ulink>, <ulink type="http"
      url="http://developer.kde.org/~wheeler/juk.html">JuK</ulink>,
      <ulink type="http"
      url="http://www.xs4all.nl/~jjvrieze/kmplayer.html">KMPlayer</ulink> and
      <ulink type="http"
      url="http://kaffeine.sourceforge.net/">Kaffeine</ulink>.
    </para>
    <para>
      Although not yet as complete as the GNOME integration bits, there
      are already some KDE integration specifics available. This list will
      probably grow as &GStreamer; starts to be used in KDE-4.0:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          AmaroK contains a kiosrc element, which is a source element that
          integrates with the KDE VFS subsystem KIO.
        </para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 id="section-integration-osx">
    <title>OS X</title>
    <para>
      &GStreamer; provides native video and audio output elements for OS X.
      It builds using the standard development tools for OS X.
    </para>
  </sect1>

  <sect1 id="section-integration-win32">
    <title>Windows</title>
    <para>
      &GStreamer; builds using Microsoft Visual C .NET 2003 and using Cygwin.
    </para>
  </sect1>
</chapter>