Gst

Gst — Media library supporting arbitrary formats and filter graphs.

Synopsis


#include <gst/gst.h>


void        gst_init                        (int *argc,
                                             char **argv[]);
gboolean    gst_init_check                  (int *argc,
                                             char **argv[],
                                             GError **err);
GOptionGroup* gst_init_get_option_group     (void);
void        gst_deinit                      (void);
void        gst_version                     (guint *major,
                                             guint *minor,
                                             guint *micro,
                                             guint *nano);
gchar*      gst_version_string              (void);

Description

GStreamer is a framework for constructing graphs of various filters (termed elements here) that will handle streaming media. Any discreet (packetizable) media type is supported, with provisions for automatically determining source type. Formatting/framing information is provided with a powerful negotiation framework. Plugins are heavily used to provide for all elements, allowing one to construct plugins outside of the GST library, even released binary-only if license require (please don't).

GStreamer borrows heavily from both the OGI media pipeline and Microsoft's DirectShow, hopefully taking the best of both and leaving the cruft behind. Its interface is still very fluid and thus can be changed to increase the sanity/noise ratio.

The GStreamer library should be initialized with gst_init() before it can be used. You should pass pointers to the main argc and argv variables so that GStreamer can process its own command line options, as shown in the following example.

Example 1. Initializing the gstreamer library

int
main (int argc, char *argv[])
{
  // initialize the GStreamer library
  gst_init (&argc, &argv);
  ...
}

It's allowed to pass two NULL pointers to gst_init() in case you don't want to pass the command line args to GStreamer.

You can also use GOption to initialize your own parameters as shown in the next code fragment:

Example 2. Initializing own parameters when initializing gstreamer

static gboolean stats = FALSE;
...
int
main (int argc, char *argv[])
{
 GOptionEntry options[] = {
  {"tags", 't', 0, G_OPTION_ARG_NONE, &tags,
      N_("Output tags (also known as metadata)"), NULL},
  {NULL}
 };
 ctx = g_option_context_new ("gst-launch");
 g_option_context_add_main_entries (ctx, options, GETTEXT_PACKAGE);
 g_option_context_add_group (ctx, gst_init_get_option_group());
 if (!g_option_context_parse (ctx, &argc, &argv, &err)) {
   g_print ("Error initializing: %s\n", GST_STR_NULL (err->message));
   exit (1);
 }
 g_option_context_free (ctx);
...
}

Use gst_version() to query the library version at runtime or use the GST_VERSION_* macros to find the version at compile time. Optionally gst_version_string() returns a printable string.

The gst_deinit() call is used to clean up all internal resources used by GStreamer. It is mostly used in unit tests to check for leaks.

Last reviewed on 2005-11-23 (0.9.5)

Details

gst_init ()

void        gst_init                        (int *argc,
                                             char **argv[]);

Initializes the GStreamer library, setting up internal path lists, registering built-in elements, and loading standard plugins.

Note

This function will terminate your program if it was unable to initialize GStreamer for some reason. If you want your program to fall back, use gst_init_check() instead.

WARNING: This function does not work in the same way as corresponding functions in other glib-style libraries, such as gtk_init(). In particular, unknown command line options cause this function to abort program execution.

argc : pointer to application's argc
argv : pointer to application's argv

gst_init_check ()

gboolean    gst_init_check                  (int *argc,
                                             char **argv[],
                                             GError **err);

Initializes the GStreamer library, setting up internal path lists, registering built-in elements, and loading standard plugins.

This function will return FALSE if GStreamer could not be initialized for some reason. If you want your program to fail fatally, use gst_init() instead.

argc : pointer to application's argc
argv : pointer to application's argv
err : pointer to a GError to which a message will be posted on error
Returns : TRUE if GStreamer could be initialized.

gst_init_get_option_group ()

GOptionGroup* gst_init_get_option_group     (void);

Returns a GOptionGroup with GStreamer's argument specifications. The group is set up to use standard GOption callbacks, so when using this group in combination with GOption parsing methods, all argument parsing and initialization is automated.

This function is useful if you want to integrate GStreamer with other libraries that use GOption (see g_option_context_add_group() ).

Returns : a pointer to GStreamer's option group. Should be dereferenced after use.

gst_deinit ()

void        gst_deinit                      (void);

Clean up. Call only once, before exiting. After this call GStreamer should not be used anymore.


gst_version ()

void        gst_version                     (guint *major,
                                             guint *minor,
                                             guint *micro,
                                             guint *nano);

Gets the version number of the GStreamer library.

major : pointer to a guint to store the major version number
minor : pointer to a guint to store the minor version number
micro : pointer to a guint to store the micro version number
nano : pointer to a guint to store the nano version number

gst_version_string ()

gchar*      gst_version_string              (void);

This function returns a string that is useful for describing this version of GStreamer to the outside world: user agent strings, logging, ...

Returns : a newly allocated string describing this version of GStreamer.

See Also

Check out both OGI's pipeline and Microsoft's DirectShow for some background.