GstGError

GStreamer elements can throw non-fatal warnings and fatal errors. Higher-level elements and applications can programmatically filter the ones they are interested in or can recover from, and have a default handler handle the rest of them.

The rest of this section will use the term "error" to mean both (non-fatal) warnings and (fatal) errors; they are treated similarly.

Errors from elements are the combination of a GError and a debug string. The GError contains:

a domain type: CORE, LIBRARY, RESOURCE or STREAM
a code: an enum value specific to the domain
a translated, human-readable message
a non-translated additional debug string, which also contains
file and line information

Elements do not have the context required to decide what to do with errors. As such, they should only inform about errors, and stop their processing. In short, an element doesn't know what it is being used for.

It is the application or compound element using the given element that has more context about the use of the element. Errors can be received by listening to the GstBus of the element/pipeline for GstMessage objects with the type GST_MESSAGE_ERROR or GST_MESSAGE_WARNING. The thrown errors should be inspected, and filtered if appropriate.

An application is expected to, by default, present the user with a dialog box (or an equivalent) showing the error message. The dialog should also allow a way to get at the additional debug information, so the user can provide bug reporting information.

A compound element is expected to forward errors by default higher up the hierarchy; this is done by default in the same way as for other types of GstMessage.

When applications or compound elements trigger errors that they can recover from, they can filter out these errors and take appropriate action. For example, an application that gets an error from xvimagesink that indicates all XVideo ports are taken, the application can attempt to use another sink instead.

Elements throw errors using the GST_ELEMENT_ERROR convenience macro:

Throwing an error

     GST_ELEMENT_ERROR (src, RESOURCE, NOT_FOUND,
       (_("No file name specified for reading.")), (NULL));

Things to keep in mind:

Don't go off inventing new error codes. The ones currently provided should be enough. If you find your type of error does not fit the current codes, you should use FAILED.
Don't provide a message if the default one suffices. this keeps messages more uniform. Use (%NULL) - not forgetting the parentheses.
If you do supply a custom message, it should be marked for translation. The message should start with a capital and end with a period. The message should describe the error in short, in a human-readable form, and without any complex technical terms. A user interface will present this message as the first thing a user sees. Details, technical info, ... should go in the debug string.
The debug string can be as you like. Again, use (%NULL) if there's nothing to add - file and line number will still be passed. GST_ERROR_SYSTEM can be used as a shortcut to give debug information on a system call error.

Functions

gst_error_get_message

gchar *
gst_error_get_message (GQuark domain,
                       gint code)

Get a string describing the error message in the current locale.

Parameters:

domain –

the GStreamer error domain this error belongs to.

code –

the error code belonging to the domain.

Returns ( [transfer: full]) –

a newly allocated string describing the error message (in UTF-8 encoding)

Gst.prototype.error_get_message

function Gst.prototype.error_get_message(domain: GLib.Quark, code: Number): {
    // javascript wrapper for 'gst_error_get_message'
}

Get a string describing the error message in the current locale.

Parameters:

domain (GLib.Quark) –

the GStreamer error domain this error belongs to.

code (Number) –

the error code belonging to the domain.

Returns (String) –

a newly allocated string describing the error message (in UTF-8 encoding)

Gst.error_get_message

def Gst.error_get_message (domain, code):
    #python wrapper for 'gst_error_get_message'

Get a string describing the error message in the current locale.

Parameters:

domain (GLib.Quark) –

the GStreamer error domain this error belongs to.

code (int) –

the error code belonging to the domain.

Returns (str) –

a newly allocated string describing the error message (in UTF-8 encoding)

Enumerations

GstCoreError

Core errors are errors inside the core GStreamer library.

Members

GST_CORE_ERROR_FAILED (1) –

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

GST_CORE_ERROR_TOO_LAZY (2) –

do not use this except as a placeholder for deciding where to go while developing code.

GST_CORE_ERROR_NOT_IMPLEMENTED (3) –

use this when you do not want to implement this functionality yet.

GST_CORE_ERROR_STATE_CHANGE (4) –

used for state change errors.

GST_CORE_ERROR_PAD (5) –

used for pad-related errors.

GST_CORE_ERROR_THREAD (6) –

used for thread-related errors.

GST_CORE_ERROR_NEGOTIATION (7) –

used for negotiation-related errors.

GST_CORE_ERROR_EVENT (8) –

used for event-related errors.

GST_CORE_ERROR_SEEK (9) –

used for seek-related errors.

GST_CORE_ERROR_CAPS (10) –

used for caps-related errors.

GST_CORE_ERROR_TAG (11) –

used for negotiation-related errors.

GST_CORE_ERROR_MISSING_PLUGIN (12) –

used if a plugin is missing.

GST_CORE_ERROR_CLOCK (13) –

used for clock related errors.

GST_CORE_ERROR_DISABLED (14) –

used if functionality has been disabled at compile time.

GST_CORE_ERROR_NUM_ERRORS (15) –

the number of core error types.

Gst.CoreError

Core errors are errors inside the core GStreamer library.

Members

Gst.CoreError.FAILED (1) –

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

Gst.CoreError.TOO_LAZY (2) –

do not use this except as a placeholder for deciding where to go while developing code.

Gst.CoreError.NOT_IMPLEMENTED (3) –

use this when you do not want to implement this functionality yet.

Gst.CoreError.STATE_CHANGE (4) –

used for state change errors.

Gst.CoreError.PAD (5) –

used for pad-related errors.

Gst.CoreError.THREAD (6) –

used for thread-related errors.

Gst.CoreError.NEGOTIATION (7) –

used for negotiation-related errors.

Gst.CoreError.EVENT (8) –

used for event-related errors.

Gst.CoreError.SEEK (9) –

used for seek-related errors.

Gst.CoreError.CAPS (10) –

used for caps-related errors.

Gst.CoreError.TAG (11) –

used for negotiation-related errors.

Gst.CoreError.MISSING_PLUGIN (12) –

used if a plugin is missing.

Gst.CoreError.CLOCK (13) –

used for clock related errors.

Gst.CoreError.DISABLED (14) –

used if functionality has been disabled at compile time.

Gst.CoreError.NUM_ERRORS (15) –

the number of core error types.

Gst.CoreError

Core errors are errors inside the core GStreamer library.

Members

Gst.CoreError.FAILED (1) –

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

Gst.CoreError.TOO_LAZY (2) –

do not use this except as a placeholder for deciding where to go while developing code.

Gst.CoreError.NOT_IMPLEMENTED (3) –

use this when you do not want to implement this functionality yet.

Gst.CoreError.STATE_CHANGE (4) –

used for state change errors.

Gst.CoreError.PAD (5) –

used for pad-related errors.

Gst.CoreError.THREAD (6) –

used for thread-related errors.

Gst.CoreError.NEGOTIATION (7) –

used for negotiation-related errors.

Gst.CoreError.EVENT (8) –

used for event-related errors.

Gst.CoreError.SEEK (9) –

used for seek-related errors.

Gst.CoreError.CAPS (10) –

used for caps-related errors.

Gst.CoreError.TAG (11) –

used for negotiation-related errors.

Gst.CoreError.MISSING_PLUGIN (12) –

used if a plugin is missing.

Gst.CoreError.CLOCK (13) –

used for clock related errors.

Gst.CoreError.DISABLED (14) –

used if functionality has been disabled at compile time.

Gst.CoreError.NUM_ERRORS (15) –

the number of core error types.

GstLibraryError

Library errors are for errors from the library being used by elements (initializing, finalizing, settings, ...)

Members

GST_LIBRARY_ERROR_FAILED (1) –

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

GST_LIBRARY_ERROR_TOO_LAZY (2) –

do not use this except as a placeholder for deciding where to go while developing code.

GST_LIBRARY_ERROR_INIT (3) –

used when the library could not be opened.

GST_LIBRARY_ERROR_SHUTDOWN (4) –

used when the library could not be closed.

GST_LIBRARY_ERROR_SETTINGS (5) –

used when the library doesn't accept settings.

GST_LIBRARY_ERROR_ENCODE (6) –

used when the library generated an encoding error.

GST_LIBRARY_ERROR_NUM_ERRORS (7) –

the number of library error types.

Gst.LibraryError

Library errors are for errors from the library being used by elements (initializing, finalizing, settings, ...)

Members

Gst.LibraryError.FAILED (1) –

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

Gst.LibraryError.TOO_LAZY (2) –

do not use this except as a placeholder for deciding where to go while developing code.

Gst.LibraryError.INIT (3) –

used when the library could not be opened.

Gst.LibraryError.SHUTDOWN (4) –

used when the library could not be closed.

Gst.LibraryError.SETTINGS (5) –

used when the library doesn't accept settings.

Gst.LibraryError.ENCODE (6) –

used when the library generated an encoding error.

Gst.LibraryError.NUM_ERRORS (7) –

the number of library error types.

Gst.LibraryError

Library errors are for errors from the library being used by elements (initializing, finalizing, settings, ...)

Members

Gst.LibraryError.FAILED (1) –

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

Gst.LibraryError.TOO_LAZY (2) –

do not use this except as a placeholder for deciding where to go while developing code.

Gst.LibraryError.INIT (3) –

used when the library could not be opened.

Gst.LibraryError.SHUTDOWN (4) –

used when the library could not be closed.

Gst.LibraryError.SETTINGS (5) –

used when the library doesn't accept settings.

Gst.LibraryError.ENCODE (6) –

used when the library generated an encoding error.

Gst.LibraryError.NUM_ERRORS (7) –

the number of library error types.

GstResourceError

Resource errors are for any resource used by an element: memory, files, network connections, process space, ... They're typically used by source and sink elements.

Members

GST_RESOURCE_ERROR_FAILED (1) –

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

GST_RESOURCE_ERROR_TOO_LAZY (2) –

do not use this except as a placeholder for deciding where to go while developing code.

GST_RESOURCE_ERROR_NOT_FOUND (3) –

used when the resource could not be found.

GST_RESOURCE_ERROR_BUSY (4) –

used when resource is busy.

GST_RESOURCE_ERROR_OPEN_READ (5) –

used when resource fails to open for reading.

GST_RESOURCE_ERROR_OPEN_WRITE (6) –

used when resource fails to open for writing.

GST_RESOURCE_ERROR_OPEN_READ_WRITE (7) –

used when resource cannot be opened for both reading and writing, or either (but unspecified which).

GST_RESOURCE_ERROR_CLOSE (8) –

used when the resource can't be closed.

GST_RESOURCE_ERROR_READ (9) –

used when the resource can't be read from.

GST_RESOURCE_ERROR_WRITE (10) –

used when the resource can't be written to.

GST_RESOURCE_ERROR_SEEK (11) –

used when a seek on the resource fails.

GST_RESOURCE_ERROR_SYNC (12) –

used when a synchronize on the resource fails.

GST_RESOURCE_ERROR_SETTINGS (13) –

used when settings can't be manipulated on.

GST_RESOURCE_ERROR_NO_SPACE_LEFT (14) –

used when the resource has no space left.

GST_RESOURCE_ERROR_NOT_AUTHORIZED (15) –

used when the resource can't be opened due to missing authorization. (Since: 1.2.4)

GST_RESOURCE_ERROR_NUM_ERRORS (16) –

the number of resource error types.

Gst.ResourceError

Resource errors are for any resource used by an element: memory, files, network connections, process space, ... They're typically used by source and sink elements.

Members

Gst.ResourceError.FAILED (1) –

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

Gst.ResourceError.TOO_LAZY (2) –

do not use this except as a placeholder for deciding where to go while developing code.

Gst.ResourceError.NOT_FOUND (3) –

used when the resource could not be found.

Gst.ResourceError.BUSY (4) –

used when resource is busy.

Gst.ResourceError.OPEN_READ (5) –

used when resource fails to open for reading.

Gst.ResourceError.OPEN_WRITE (6) –

used when resource fails to open for writing.

Gst.ResourceError.OPEN_READ_WRITE (7) –

used when resource cannot be opened for both reading and writing, or either (but unspecified which).

Gst.ResourceError.CLOSE (8) –

used when the resource can't be closed.

Gst.ResourceError.READ (9) –

used when the resource can't be read from.

Gst.ResourceError.WRITE (10) –

used when the resource can't be written to.

Gst.ResourceError.SEEK (11) –

used when a seek on the resource fails.

Gst.ResourceError.SYNC (12) –

used when a synchronize on the resource fails.

Gst.ResourceError.SETTINGS (13) –

used when settings can't be manipulated on.

Gst.ResourceError.NO_SPACE_LEFT (14) –

used when the resource has no space left.

Gst.ResourceError.NOT_AUTHORIZED (15) –

used when the resource can't be opened due to missing authorization. (Since: 1.2.4)

Gst.ResourceError.NUM_ERRORS (16) –

the number of resource error types.

Gst.ResourceError

Resource errors are for any resource used by an element: memory, files, network connections, process space, ... They're typically used by source and sink elements.

Members

Gst.ResourceError.FAILED (1) –

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

Gst.ResourceError.TOO_LAZY (2) –

do not use this except as a placeholder for deciding where to go while developing code.

Gst.ResourceError.NOT_FOUND (3) –

used when the resource could not be found.

Gst.ResourceError.BUSY (4) –

used when resource is busy.

Gst.ResourceError.OPEN_READ (5) –

used when resource fails to open for reading.

Gst.ResourceError.OPEN_WRITE (6) –

used when resource fails to open for writing.

Gst.ResourceError.OPEN_READ_WRITE (7) –

used when resource cannot be opened for both reading and writing, or either (but unspecified which).

Gst.ResourceError.CLOSE (8) –

used when the resource can't be closed.

Gst.ResourceError.READ (9) –

used when the resource can't be read from.

Gst.ResourceError.WRITE (10) –

used when the resource can't be written to.

Gst.ResourceError.SEEK (11) –

used when a seek on the resource fails.

Gst.ResourceError.SYNC (12) –

used when a synchronize on the resource fails.

Gst.ResourceError.SETTINGS (13) –

used when settings can't be manipulated on.

Gst.ResourceError.NO_SPACE_LEFT (14) –

used when the resource has no space left.

Gst.ResourceError.NOT_AUTHORIZED (15) –

used when the resource can't be opened due to missing authorization. (Since: 1.2.4)

Gst.ResourceError.NUM_ERRORS (16) –

the number of resource error types.

GstStreamError

Stream errors are for anything related to the stream being processed: format errors, media type errors, ... They're typically used by decoders, demuxers, converters, ...

Members

GST_STREAM_ERROR_FAILED (1) –

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

GST_STREAM_ERROR_TOO_LAZY (2) –

do not use this except as a placeholder for deciding where to go while developing code.

GST_STREAM_ERROR_NOT_IMPLEMENTED (3) –

use this when you do not want to implement this functionality yet.

GST_STREAM_ERROR_TYPE_NOT_FOUND (4) –

used when the element doesn't know the stream's type.

GST_STREAM_ERROR_WRONG_TYPE (5) –

used when the element doesn't handle this type of stream.

GST_STREAM_ERROR_CODEC_NOT_FOUND (6) –

used when there's no codec to handle the stream's type.

GST_STREAM_ERROR_DECODE (7) –

used when decoding fails.

GST_STREAM_ERROR_ENCODE (8) –

used when encoding fails.

GST_STREAM_ERROR_DEMUX (9) –

used when demuxing fails.

GST_STREAM_ERROR_MUX (10) –

used when muxing fails.

GST_STREAM_ERROR_FORMAT (11) –

used when the stream is of the wrong format (for example, wrong caps).

GST_STREAM_ERROR_DECRYPT (12) –

used when the stream is encrypted and can't be decrypted because this is not supported by the element.

GST_STREAM_ERROR_DECRYPT_NOKEY (13) –

used when the stream is encrypted and can't be decrypted because no suitable key is available.

GST_STREAM_ERROR_NUM_ERRORS (14) –

the number of stream error types.

Gst.StreamError

Stream errors are for anything related to the stream being processed: format errors, media type errors, ... They're typically used by decoders, demuxers, converters, ...

Members

Gst.StreamError.FAILED (1) –

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

Gst.StreamError.TOO_LAZY (2) –

do not use this except as a placeholder for deciding where to go while developing code.

Gst.StreamError.NOT_IMPLEMENTED (3) –

use this when you do not want to implement this functionality yet.

Gst.StreamError.TYPE_NOT_FOUND (4) –

used when the element doesn't know the stream's type.

Gst.StreamError.WRONG_TYPE (5) –

used when the element doesn't handle this type of stream.

Gst.StreamError.CODEC_NOT_FOUND (6) –

used when there's no codec to handle the stream's type.

Gst.StreamError.DECODE (7) –

used when decoding fails.

Gst.StreamError.ENCODE (8) –

used when encoding fails.

Gst.StreamError.DEMUX (9) –

used when demuxing fails.

Gst.StreamError.MUX (10) –

used when muxing fails.

Gst.StreamError.FORMAT (11) –

used when the stream is of the wrong format (for example, wrong caps).

Gst.StreamError.DECRYPT (12) –

used when the stream is encrypted and can't be decrypted because this is not supported by the element.

Gst.StreamError.DECRYPT_NOKEY (13) –

used when the stream is encrypted and can't be decrypted because no suitable key is available.

Gst.StreamError.NUM_ERRORS (14) –

the number of stream error types.

Gst.StreamError

Stream errors are for anything related to the stream being processed: format errors, media type errors, ... They're typically used by decoders, demuxers, converters, ...

Members

Gst.StreamError.FAILED (1) –

a general error which doesn't fit in any other category. Make sure you add a custom message to the error call.

Gst.StreamError.TOO_LAZY (2) –

do not use this except as a placeholder for deciding where to go while developing code.

Gst.StreamError.NOT_IMPLEMENTED (3) –

use this when you do not want to implement this functionality yet.

Gst.StreamError.TYPE_NOT_FOUND (4) –

used when the element doesn't know the stream's type.

Gst.StreamError.WRONG_TYPE (5) –

used when the element doesn't handle this type of stream.

Gst.StreamError.CODEC_NOT_FOUND (6) –

used when there's no codec to handle the stream's type.

Gst.StreamError.DECODE (7) –

used when decoding fails.

Gst.StreamError.ENCODE (8) –

used when encoding fails.

Gst.StreamError.DEMUX (9) –

used when demuxing fails.

Gst.StreamError.MUX (10) –

used when muxing fails.

Gst.StreamError.FORMAT (11) –

used when the stream is of the wrong format (for example, wrong caps).

Gst.StreamError.DECRYPT (12) –

used when the stream is encrypted and can't be decrypted because this is not supported by the element.

Gst.StreamError.DECRYPT_NOKEY (13) –

used when the stream is encrypted and can't be decrypted because no suitable key is available.

Gst.StreamError.NUM_ERRORS (14) –

the number of stream error types.

Constants

GST_CORE_ERROR

#define GST_CORE_ERROR      gst_core_error_quark ()

Error domain for core system. Errors in this domain will be from the GstCoreError enumeration. See GError for information on error domains.

GST_ERROR_SYSTEM

#define GST_ERROR_SYSTEM    ("system error: %s", g_strerror (errno))

Builds a string using errno describing the previously failed system call. To be used as the debug argument in GST_ELEMENT_ERROR.

GST_LIBRARY_ERROR

#define GST_LIBRARY_ERROR   gst_library_error_quark ()

Error domain for library loading. Errors in this domain will be from the GstLibraryError enumeration. See GError for information on error domains.

GST_RESOURCE_ERROR

#define GST_RESOURCE_ERROR  gst_resource_error_quark ()

Error domain for resource handling. Errors in this domain will be from the GstResourceError enumeration. See GError for information on error domains.

GST_STREAM_ERROR

#define GST_STREAM_ERROR    gst_stream_error_quark ()

Error domain for media stream processing. Errors in this domain will be from the GstStreamError enumeration. See GError for information on error domains.

The results of the search are