GstParse: GStreamer 1.0 Core Reference Manual

GstParse

GstParse — Get a pipeline from a text pipeline description

Functions

GQuark	gst_parse_error_quark ()
GstElement *	gst_parse_launch ()
GstElement *	gst_parse_launch_full ()
GstElement *	gst_parse_launchv ()
GstElement *	gst_parse_launchv_full ()
GstElement *	gst_parse_bin_from_description ()
GstElement *	gst_parse_bin_from_description_full ()
GstParseContext *	gst_parse_context_new ()
void	gst_parse_context_free ()
gchar **	gst_parse_context_get_missing_elements ()

Types and Values

#define	GST_PARSE_ERROR
enum	GstParseError
	GstParseContext
enum	GstParseFlags

Object Hierarchy

    GBoxed
    ╰── GstParseContext

Includes

#include <gst/gst.h>

Description

These function allow to create a pipeline based on the syntax used in the gst-launch-1.0 utility (see man-page for syntax documentation).

Please note that these functions take several measures to create somewhat dynamic pipelines. Due to that such pipelines are not always reusable (set the state to NULL and back to PLAYING).

Functions

gst_parse_error_quark ()

GQuark
gst_parse_error_quark (void);

Get the error quark used by the parsing subsystem.

Returns

the quark of the parse errors.

gst_parse_launch ()

GstElement *
gst_parse_launch (const gchar *pipeline_description,
                  GError **error);

Create a new pipeline based on command line syntax. Please note that you might get a return value that is not NULL even though the error is set. In this case there was a recoverable parsing error and you can try to play the pipeline.

Parameters

pipeline_description	the command line describing the pipeline
error	the error message in case of an erroneous pipeline.

Returns

a new element on success, NULL on failure. If more than one toplevel element is specified by the pipeline_description , all elements are put into a GstPipeline, which than is returned.

[transfer floating]

gst_parse_launch_full ()

GstElement *
gst_parse_launch_full (const gchar *pipeline_description,
                       GstParseContext *context,
                       GstParseFlags flags,
                       GError **error);

Parameters

pipeline_description	the command line describing the pipeline
context	a parse context allocated with `gst_parse_context_new()`, or `NULL`.	[allow-none]
flags	parsing options, or GST_PARSE_FLAG_NONE
error	the error message in case of an erroneous pipeline.

Returns

a new element on success, NULL on failure. If more than one toplevel element is specified by the pipeline_description , all elements are put into a GstPipeline, which then is returned.

[transfer floating]

gst_parse_launchv ()

GstElement *
gst_parse_launchv (const gchar **argv,
                   GError **error);

Create a new element based on command line syntax. error will contain an error message if an erroneous pipeline is specified. An error does not mean that the pipeline could not be constructed.

Parameters

argv	null-terminated array of arguments.	[in][array zero-terminated=1]
error	pointer to a GError

Returns

a new element on success and NULL on failure.

[transfer floating]

gst_parse_launchv_full ()

GstElement *
gst_parse_launchv_full (const gchar **argv,
                        GstParseContext *context,
                        GstParseFlags flags,
                        GError **error);

Create a new element based on command line syntax. error will contain an error message if an erroneous pipeline is specified. An error does not mean that the pipeline could not be constructed.

Parameters

argv	null-terminated array of arguments.	[in][array zero-terminated=1]
context	a parse context allocated with `gst_parse_context_new()`, or `NULL`.	[allow-none]
flags	parsing options, or GST_PARSE_FLAG_NONE
error	pointer to a GError (which must be initialised to `NULL`)

Returns

a new element on success; on failure, either NULL or a partially-constructed bin or element will be returned and error will be set (unless you passed GST_PARSE_FLAG_FATAL_ERRORS in flags , then NULL will always be returned on failure).

[transfer floating]

gst_parse_bin_from_description ()

GstElement *
gst_parse_bin_from_description (const gchar *bin_description,
                                gboolean ghost_unlinked_pads,
                                GError **err);

This is a convenience wrapper around gst_parse_launch() to create a GstBin from a gst-launch-style pipeline description. See gst_parse_launch() and the gst-launch man page for details about the syntax. Ghost pads on the bin for unlinked source or sink pads within the bin can automatically be created (but only a maximum of one ghost pad for each direction will be created; if you expect multiple unlinked source pads or multiple unlinked sink pads and want them all ghosted, you will have to create the ghost pads yourself).

Parameters

bin_description	command line describing the bin
ghost_unlinked_pads	whether to automatically create ghost pads for unlinked source or sink pads within the bin
err	where to store the error message in case of an error, or `NULL`

Returns

a newly-created bin, or NULL if an error occurred.

[transfer floating][type Gst.Bin][nullable]

gst_parse_bin_from_description_full ()

GstElement *
gst_parse_bin_from_description_full (const gchar *bin_description,
                                     gboolean ghost_unlinked_pads,
                                     GstParseContext *context,
                                     GstParseFlags flags,
                                     GError **err);

Parameters

bin_description	command line describing the bin
ghost_unlinked_pads	whether to automatically create ghost pads for unlinked source or sink pads within the bin
context	a parse context allocated with `gst_parse_context_new()`, or `NULL`.	[transfer none][allow-none]
flags	parsing options, or GST_PARSE_FLAG_NONE
err	where to store the error message in case of an error, or `NULL`

Returns

a newly-created element, which is guaranteed to be a bin unless GST_FLAG_NO_SINGLE_ELEMENT_BINS was passed, or NULL if an error occurred.

[transfer floating][type Gst.Element]

gst_parse_context_new ()

GstParseContext *
gst_parse_context_new (void);

Allocates a parse context for use with gst_parse_launch_full() or gst_parse_launchv_full().

Free-function: gst_parse_context_free

Returns

a newly-allocated parse context. Free with gst_parse_context_free() when no longer needed.

[transfer full]

gst_parse_context_free ()

void
gst_parse_context_free (GstParseContext *context);

Frees a parse context previously allocated with gst_parse_context_new().

Parameters

context

a GstParseContext.

[transfer full]

gst_parse_context_get_missing_elements ()

gchar **
gst_parse_context_get_missing_elements
                               (GstParseContext *context);

Retrieve missing elements from a previous run of gst_parse_launch_full() or gst_parse_launchv_full(). Will only return results if an error code of GST_PARSE_ERROR_NO_SUCH_ELEMENT was returned.

Parameters

context

a GstParseContext

Returns

a NULL-terminated array of element factory name strings of missing elements. Free with g_strfreev() when no longer needed.

[transfer full][array zero-terminated=1][element-type gchar*]

Types and Values

GST_PARSE_ERROR

#define GST_PARSE_ERROR gst_parse_error_quark ()

Get access to the error quark of the parse subsystem.

enum GstParseError

The different parsing errors that can occur.

Members

GST_PARSE_ERROR_SYNTAX	A syntax error occurred.
GST_PARSE_ERROR_NO_SUCH_ELEMENT	The description contained an unknown element
GST_PARSE_ERROR_NO_SUCH_PROPERTY	An element did not have a specified property
GST_PARSE_ERROR_LINK	There was an error linking two pads.
GST_PARSE_ERROR_COULD_NOT_SET_PROPERTY	There was an error setting a property
GST_PARSE_ERROR_EMPTY_BIN	An empty bin was specified.
GST_PARSE_ERROR_EMPTY	An empty description was specified
GST_PARSE_ERROR_DELAYED_LINK	A delayed link did not get resolved.

GstParseContext

typedef struct _GstParseContext GstParseContext;

Opaque structure.

enum GstParseFlags

Parsing options.

Members

GST_PARSE_FLAG_NONE	Do not use any special parsing options.
GST_PARSE_FLAG_FATAL_ERRORS	Always return `NULL` when an error occurs (default behaviour is to return partially constructed bins or elements in some cases)
GST_PARSE_FLAG_NO_SINGLE_ELEMENT_BINS	If a bin only has a single element, just return the element.