# GStreamer

GStreamer is a framework for constructing graphs of various filters (termed elements here) that will handle streaming media.

Any discrete (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 covers a wide range of use cases including: playback, recording, editing, serving streams, voice over ip and video calls.

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.

## 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 GOptionContext to initialize your own parameters as shown in the next code fragment:

## 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 ("[ADDITIONAL ARGUMENTS]");
     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.

## Functions

### gst_check_version

    gboolean
    gst_check_version (guint major,
                       guint minor,
                       guint micro)

Applications might want to check if the runtime GStreamer version is greater or equal to the version specified using major, minor and micro.

Parameters:

`major` –

Major version number

`minor` –

Minor version number

`micro` –

Micro version number

Returns –

TRUE if the GStreamer version is greater or equal to major.@minor.@micro, FALSE otherwise. Also this function returns FALSE when checking for a different major version to the current one, as major version bumps are ABI breaks anyway.

Since : 1.28

### Gst.prototype.check_version

    function Gst.prototype.check_version(major: Number, minor: Number, micro: Number): {
        // javascript wrapper for 'gst_check_version'
    }

Applications might want to check if the runtime GStreamer version is greater or equal to the version specified using major, minor and micro.

Parameters:

`major` (Number) –

Major version number

`minor` (Number) –

Minor version number

`micro` (Number) –

Micro version number

Returns (Number) –

true if the GStreamer version is greater or equal to major.@minor.@micro, false otherwise. Also this function returns false when checking for a different major version to the current one, as major version bumps are ABI breaks anyway.

Since : 1.28

### Gst.check_version

    def Gst.check_version (major, minor, micro):
        #python wrapper for 'gst_check_version'

Applications might want to check if the runtime GStreamer version is greater or equal to the version specified using major, minor and micro.

Parameters:

`major` (int) –

Major version number

`minor` (int) –

Minor version number

`micro` (int) –

Micro version number

Returns (bool) –

True if the GStreamer version is greater or equal to major.@minor.@micro, False otherwise. Also this function returns False when checking for a different major version to the current one, as major version bumps are ABI breaks anyway.

Since : 1.28

### gst_deinit

    gst_deinit ()

Clean up any resources created by GStreamer in gst_init.

It is normally not needed to call this function in a normal application as the resources will automatically be freed when the program terminates. This function is therefore mostly used by testsuites and other memory profiling tools.

After this call GStreamer (including this method) should not be used anymore.

### Gst.prototype.deinit

    function Gst.prototype.deinit(): {
        // javascript wrapper for 'gst_deinit'
    }

Clean up any resources created by GStreamer in Gst.prototype.init.

It is normally not needed to call this function in a normal application as the resources will automatically be freed when the program terminates. This function is therefore mostly used by testsuites and other memory profiling tools.

After this call GStreamer (including this method) should not be used anymore.

### Gst.deinit

    def Gst.deinit ():
        #python wrapper for 'gst_deinit'

Clean up any resources created by GStreamer in Gst.init.

It is normally not needed to call this function in a normal application as the resources will automatically be freed when the program terminates. This function is therefore mostly used by testsuites and other memory profiling tools.

After this call GStreamer (including this method) should not be used anymore.

### gst_get_main_executable_path

    const gchar *
    gst_get_main_executable_path ()

This helper is mostly helpful for plugins that need to inspect the folder of the main executable to determine their set of features.

When a plugin is initialized from the gst-plugin-scanner external process, the returned path will be the same as from the parent process.

Returns ( [transfer: none][nullable]) –

The path of the executable that initialized GStreamer, or NULL if it could not be determined.

Since : 1.14

### Gst.prototype.get_main_executable_path

    function Gst.prototype.get_main_executable_path(): {
        // javascript wrapper for 'gst_get_main_executable_path'
    }

This helper is mostly helpful for plugins that need to inspect the folder of the main executable to determine their set of features.

When a plugin is initialized from the gst-plugin-scanner external process, the returned path will be the same as from the parent process.

Returns (String) –

The path of the executable that initialized GStreamer, or null if it could not be determined.

Since : 1.14

### Gst.get_main_executable_path

    def Gst.get_main_executable_path ():
        #python wrapper for 'gst_get_main_executable_path'

This helper is mostly helpful for plugins that need to inspect the folder of the main executable to determine their set of features.

When a plugin is initialized from the gst-plugin-scanner external process, the returned path will be the same as from the parent process.

Returns (str) –

The path of the executable that initialized GStreamer, or None if it could not be determined.

Since : 1.14

### gst_init

    gst_init (int* argc,
              char*** argv)

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

Unless the plugin registry is disabled at compile time, the registry will be loaded. By default this will also check if the registry cache needs to be updated and rescan all plugins if needed. See gst_update_registry for details and section

Running GStreamer Applications for how to disable automatic registry updates.

WARNING: 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.

Parameters:

`argc` ( [inout][optional]) –

pointer to application's argc

`argv` ( [inout][array length=argc][optional]) –

pointer to application's argv

### Gst.prototype.init

    function Gst.prototype.init(argc: Number, argv: [ String ]): {
        // javascript wrapper for 'gst_init'
    }

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

Unless the plugin registry is disabled at compile time, the registry will be loaded. By default this will also check if the registry cache needs to be updated and rescan all plugins if needed. See Gst.prototype.update_registry for details and section

Running GStreamer Applications for how to disable automatic registry updates.

WARNING: 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.prototype.init_check instead.

Parameters:

`argc` (Number) –

pointer to application's argc

`argv` ([ String ]) –

pointer to application's argv

### Gst.init

    def Gst.init (argc, argv):
        #python wrapper for 'gst_init'

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

Unless the plugin registry is disabled at compile time, the registry will be loaded. By default this will also check if the registry cache needs to be updated and rescan all plugins if needed. See Gst.update_registry for details and section

Running GStreamer Applications for how to disable automatic registry updates.

WARNING: 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.

Parameters:

`argc` (int) –

pointer to application's argc

`argv` ([ str ]) –

pointer to application's argv

### gst_init_check

    gboolean
    gst_init_check (int* argc,
                    char*** argv,
                    GError ** error)

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.

Parameters:

`argc` ( [inout][optional]) –

pointer to application's argc

`argv` ( [inout][array length=argc][optional]) –

pointer to application's argv

`error` –

pointer to a GError to which a message will be posted on error

Returns –

TRUE if GStreamer could be initialized.

### Gst.prototype.init_check

    function Gst.prototype.init_check(argc: Number, argv: [ String ]): {
        // javascript wrapper for 'gst_init_check'
    }

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.prototype.init instead.

Parameters:

`argc` (Number) –

pointer to application's argc

`argv` ([ String ]) –

pointer to application's argv

Returns a tuple made of:

(Number ) –

true if GStreamer could be initialized.

`argc` (Number ) –

true if GStreamer could be initialized.

`argv` ([ String ] ) –

true if GStreamer could be initialized.

### Gst.init_check

    @raises(GLib.GError)
    def Gst.init_check (argc, argv):
        #python wrapper for 'gst_init_check'

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.

Parameters:

`argc` (int) –

pointer to application's argc

`argv` ([ str ]) –

pointer to application's argv

Returns a tuple made of:

(bool ) –

True if GStreamer could be initialized.

`argc` (int ) –

True if GStreamer could be initialized.

`argv` ([ str ] ) –

True if GStreamer could be initialized.

### gst_init_get_option_group

    GOptionGroup *
    gst_init_get_option_group ()

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 ).

If you use this function, you should make sure you initialise the GLib threading system as one of the very first things in your program (see the example at the beginning of this section).

Returns ( [transfer: full][nullable]) –

a pointer to GStreamer's option group.

### gst_is_initialized

    gboolean
    gst_is_initialized ()

Use this function to check if GStreamer has been initialized with gst_init or gst_init_check.

Returns –

TRUE if initialization has been done, FALSE otherwise.

### Gst.prototype.is_initialized

    function Gst.prototype.is_initialized(): {
        // javascript wrapper for 'gst_is_initialized'
    }

Use this function to check if GStreamer has been initialized with Gst.prototype.init or Gst.prototype.init_check.

Returns (Number) –

true if initialization has been done, false otherwise.

### Gst.is_initialized

    def Gst.is_initialized ():
        #python wrapper for 'gst_is_initialized'

Use this function to check if GStreamer has been initialized with Gst.init or Gst.init_check.

Returns (bool) –

True if initialization has been done, False otherwise.

### gst_segtrap_is_enabled

    gboolean
    gst_segtrap_is_enabled ()

Some functions in the GStreamer core might install a custom SIGSEGV handler to better catch and report errors to the application. Currently this feature is enabled by default when loading plugins.

Applications might want to disable this behaviour with the gst_segtrap_set_enabled function. This is typically done if the application wants to install its own handler without GStreamer interfering.

Returns –

TRUE if GStreamer is allowed to install a custom SIGSEGV handler.

### Gst.prototype.segtrap_is_enabled

    function Gst.prototype.segtrap_is_enabled(): {
        // javascript wrapper for 'gst_segtrap_is_enabled'
    }

Some functions in the GStreamer core might install a custom SIGSEGV handler to better catch and report errors to the application. Currently this feature is enabled by default when loading plugins.

Applications might want to disable this behaviour with the Gst.prototype.segtrap_set_enabled function. This is typically done if the application wants to install its own handler without GStreamer interfering.

Returns (Number) –

true if GStreamer is allowed to install a custom SIGSEGV handler.

### Gst.segtrap_is_enabled

    def Gst.segtrap_is_enabled ():
        #python wrapper for 'gst_segtrap_is_enabled'

Some functions in the GStreamer core might install a custom SIGSEGV handler to better catch and report errors to the application. Currently this feature is enabled by default when loading plugins.

Applications might want to disable this behaviour with the Gst.segtrap_set_enabled function. This is typically done if the application wants to install its own handler without GStreamer interfering.

Returns (bool) –

True if GStreamer is allowed to install a custom SIGSEGV handler.

### gst_segtrap_set_enabled

    gst_segtrap_set_enabled (gboolean enabled)

Applications might want to disable/enable the SIGSEGV handling of the GStreamer core. See gst_segtrap_is_enabled for more information.

Parameters:

`enabled` –

whether a custom SIGSEGV handler should be installed.

### Gst.prototype.segtrap_set_enabled

    function Gst.prototype.segtrap_set_enabled(enabled: Number): {
        // javascript wrapper for 'gst_segtrap_set_enabled'
    }

Applications might want to disable/enable the SIGSEGV handling of the GStreamer core. See Gst.prototype.segtrap_is_enabled for more information.

Parameters:

`enabled` (Number) –

whether a custom SIGSEGV handler should be installed.

### Gst.segtrap_set_enabled

    def Gst.segtrap_set_enabled (enabled):
        #python wrapper for 'gst_segtrap_set_enabled'

Applications might want to disable/enable the SIGSEGV handling of the GStreamer core. See Gst.segtrap_is_enabled for more information.

Parameters:

`enabled` (bool) –

whether a custom SIGSEGV handler should be installed.

### gst_version

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

Gets the version number of the GStreamer library.

Parameters:

`major` ( [out]) –

pointer to a guint to store the major version number

`minor` ( [out]) –

pointer to a guint to store the minor version number

`micro` ( [out]) –

pointer to a guint to store the micro version number

`nano` ( [out]) –

pointer to a guint to store the nano version number

### Gst.prototype.version

    function Gst.prototype.version(): {
        // javascript wrapper for 'gst_version'
    }

Gets the version number of the GStreamer library.

### Gst.version

    def Gst.version ():
        #python wrapper for 'gst_version'

Gets the version number of the GStreamer library.

### gst_version_string

    gchar *
    gst_version_string ()

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

Returns ( [transfer: full]) –

a newly allocated string describing this version of GStreamer.

### Gst.prototype.version_string

    function Gst.prototype.version_string(): {
        // javascript wrapper for 'gst_version_string'
    }

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

Returns (String) –

a newly allocated string describing this version of GStreamer.

### Gst.version_string

    def Gst.version_string ():
        #python wrapper for 'gst_version_string'

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

Returns (str) –

a newly allocated string describing this version of GStreamer.

The results of the search are