manual-intgration.md

   1 ---
   2 title: Integration
   3 ...
   4
   5 # Integration
   6
   7 GStreamer tries to integrate closely with operating systems (such as
   8 Linux and UNIX-like operating systems, OS X or Windows) and desktop
   9 environments (such as GNOME or KDE). In this chapter, we'll mention some
  10 specific techniques to integrate your application with your operating
  11 system or desktop environment of choice.
  12
  13 ## Linux and UNIX-like operating systems
  14
  15 GStreamer provides a basic set of elements that are useful when
  16 integrating with Linux or a UNIX-like operating system.
  17
  18   - For audio input and output, GStreamer provides input and output
  19     elements for several audio subsystems. Amongst others, GStreamer
  20     includes elements for ALSA (alsasrc, alsasink), OSS (osssrc,
  21     osssink) Pulesaudio (pulsesrc, pulsesink) and Sun audio
  22     (sunaudiosrc, sunaudiomixer, sunaudiosink).
  23
  24   - For video input, GStreamer contains source elements for Video4linux2
  25     (v4l2src, v4l2element, v4l2sink).
  26
  27   - For video output, GStreamer provides elements for output to
  28     X-windows (ximagesink), Xv-windows (xvimagesink; for
  29     hardware-accelerated video), direct-framebuffer (dfbimagesink) and
  30     openGL image contexts (glsink).
  31
  32 ## GNOME desktop
  33
  34 GStreamer has been the media backend of the
  35 [GNOME](http://www.gnome.org/) desktop since GNOME-2.2 onwards.
  36 Nowadays, a whole bunch of GNOME applications make use of GStreamer for
  37 media-processing, including (but not limited to)
  38 [Rhythmbox](http://www.rhythmbox.org/),
  39 [Videos](https://wiki.gnome.org/Apps/Videos) and [Sound
  40 Juicer](https://wiki.gnome.org/Apps/SoundJuicer).
  41
  42 Most of these GNOME applications make use of some specific techniques to
  43 integrate as closely as possible with the GNOME desktop:
  44
  45   - GNOME applications usually call `gtk_init ()` to parse command-line
  46     options and initialize GTK. GStreamer applications would normally
  47     call `gst_init ()` to do the same for GStreamer. This would mean
  48     that only one of the two can parse command-line options. To work
  49     around this issue, GStreamer can provide a GLib `GOptionGroup` which
  50     can be passed to `gnome_program_init ()`. The following example
  51     requires GTK 2.6 or newer (previous GTK versions do not support
  52     command line parsing via GOption yet)
  53
  54     ``` c
  55     #include <gtk/gtk.h>
  56     #include <gst/gst.h>
  57
  58     static gchar **cmd_filenames = NULL;
  59
  60     static GOptionEntries cmd_options[] = {
  61       /* here you can add command line options for your application. Check
  62        * the GOption section in the GLib API reference for a more elaborate
  63        * example of how to add your own command line options here */
  64
  65       /* at the end we have a special option that collects all remaining
  66        * command line arguments (like filenames) for us. If you don't
  67        * need this, you can safely remove it */
  68       { G_OPTION_REMAINING, 0, 0, G_OPTION_ARG_FILENAME_ARRAY, &cmd_filenames,
  69         "Special option that collects any remaining arguments for us" },
  70
  71       /* mark the end of the options array with a NULL option */
  72       { NULL, }
  73     };
  74
  75     /* this should usually be defined in your config.h */
  76     #define VERSION "0.0.1"
  77
  78     gint
  79     main (gint argc, gchar **argv)
  80     {
  81       GOptionContext *context;
  82       GOptionGroup *gstreamer_group, *gtk_group;
  83       GError *err = NULL;
  84
  85       context = g_option_context_new ("gtk-demo-app");
  86
  87       /* get command line options from GStreamer and add them to the group */
  88       gstreamer_group = gst_init_get_option_group ();
  89       g_option_context_add_group (context, gstreamer_group);
  90       gtk_group = gtk_get_option_group (TRUE);
  91       g_option_context_add_group (context, gtk_group);
  92
  93       /* add our own options. If you are using gettext for translation of your
  94        * strings, use GETTEXT_PACKAGE here instead of NULL */
  95       g_option_context_add_main_entries (context, cmd_options, NULL);
  96
  97       /* now parse the commandline options, note that this already
  98        * calls gtk_init() and gst_init() */
  99       if (!g_option_context_parse (ctx, &argc, &argv, &err)) {
 100         g_print ("Error initializing: %s\n", err->message);
 101         g_clear_error (&err);
 102         g_option_context_free (ctx);
 103         exit (1);
 104       }
 105       g_option_context_free (ctx);
 106
 107       /* any filenames we got passed on the command line? parse them! */
 108       if (cmd_filenames != NULL) {
 109         guint i, num;
 110
 111         num = g_strv_length (cmd_filenames);
 112         for (i = 0; i < num; ++i) {
 113           /* do something with the filename ... */
 114           g_print ("Adding to play queue: %s\n", cmd_filenames[i]);
 115         }
 116
 117         g_strfreev (cmd_filenames);
 118         cmd_filenames = NULL;
 119       }
 120
 121     [..]
 122
 123     }
 124     ```
 125
 126   - GNOME uses Pulseaudio for audio, use the pulsesrc and pulsesink
 127     elements to have access to all the features.
 128
 129   - GStreamer provides data input/output elements for use with the GIO
 130     VFS system. These elements are called “giosrc” and “giosink”. The
 131     deprecated GNOME-VFS system is supported too but shouldn't be used
 132     for any new applications.
 133
 134 ## KDE desktop
 135
 136 GStreamer has been proposed for inclusion in KDE-4.0. Currently,
 137 GStreamer is included as an optional component, and it's used by several
 138 KDE applications, including [AmaroK](http://amarok.kde.org/),
 139 [KMPlayer](http://www.xs4all.nl/~jjvrieze/kmplayer.html) and
 140 [Kaffeine](http://kaffeine.sourceforge.net/).
 141
 142 Although not yet as complete as the GNOME integration bits, there are
 143 already some KDE integration specifics available. This list will
 144 probably grow as GStreamer starts to be used in KDE-4.0:
 145
 146   - AmaroK contains a kiosrc element, which is a source element that
 147     integrates with the KDE VFS subsystem KIO.
 148
 149 ## OS X
 150
 151 GStreamer provides native video and audio output elements for OS X. It
 152 builds using the standard development tools for OS X.
 153
 154 ## Windows
 155
 156 > **Warning**
 157 >
 158 > Note: this section is out of date. GStreamer-1.0 has much better
 159 > support for win32 than previous versions though and should usually
 160 > compile and work out-of-the-box both using MSYS/MinGW or Microsoft
 161 > compilers. The [GStreamer web site](http://gstreamer.freedesktop.org)
 162 > and the [mailing list
 163 > archives](http://news.gmane.org/gmane.comp.video.gstreamer.devel) are
 164 > a good place to check the latest win32-related news.
 165
 166 GStreamer builds using Microsoft Visual C .NET 2003 and using Cygwin.
 167
 168 ### Building GStreamer under Win32
 169
 170 There are different makefiles that can be used to build GStreamer with
 171 the usual Microsoft compiling tools.
 172
 173 The Makefile is meant to be used with the GNU make program and the free
 174 version of the Microsoft compiler
 175 (<http://msdn.microsoft.com/visualc/vctoolkit2003/>). You also have to
 176 modify your system environment variables to use it from the
 177 command-line. You will also need a working Platform SDK for Windows that
 178 is available for free from Microsoft.
 179
 180 The projects/makefiles will generate automatically some source files
 181 needed to compile GStreamer. That requires that you have installed on
 182 your system some GNU tools and that they are available in your system
 183 PATH.
 184
 185 The GStreamer project depends on other libraries, namely :
 186
 187   - GLib
 188
 189   - libxml2
 190
 191   - libintl
 192
 193   - libiconv
 194
 195 Work is being done to provide pre-compiled GStreamer-1.0 libraries as a
 196 packages for win32. Check the [GStreamer web
 197 site](http://gstreamer.freedesktop.org) and check our [mailing
 198 list](http://news.gmane.org/gmane.comp.video.gstreamer.devel) for the
 199 latest developments in this respect.
 200
 201 > **Note**
 202 >
 203 > GNU tools needed that you can find on
 204 > <http://gnuwin32.sourceforge.net/>
 205 >
 206 >   - GNU flex (tested with 2.5.4)
 207 >
 208 >   - GNU bison (tested with 1.35)
 209 >
 210 > and <http://www.mingw.org/>
 211 >
 212 >   - GNU make (tested with 3.80)
 213 >
 214 > the generated files from the -auto makefiles will be available soon
 215 > separately on the net for convenience (people who don't want to
 216 > install GNU tools).
 217
 218 ### Installation on the system
 219
 220 FIXME: This section needs be updated for GStreamer-1.0.
 221