Functions

buffer_get_max_memory() → int
caps_features_from_string(features: str) → CapsFeatures | None
Parameters:

features

caps_from_string(string: str) → Caps | None
Parameters:

string

core_error_quark() → int
debug_add_log_function(func: Callable[[...], None], *user_data: Any) → None

Adds the logging function to the list of logging functions. Be sure to use G_GNUC_NO_INSTRUMENT on that function, it is needed.

Parameters:

  • func – the function to use

  • user_data – user data

debug_add_ring_buffer_logger(max_size_per_thread: int, thread_timeout: int) → None

Adds a memory ringbuffer based debug logger that stores up to max_size_per_thread bytes of logs per thread and times out threads after thread_timeout seconds of inactivity.

Logs can be fetched with debug_ring_buffer_logger_get_logs() and the logger can be removed again with debug_remove_ring_buffer_logger(). Only one logger at a time is possible.

Added in version 1.14.

Parameters:

  • max_size_per_thread – Maximum size of log per thread in bytes

  • thread_timeout – Timeout for threads in seconds

debug_bin_to_dot_data(bin: Bin, details: DebugGraphDetails) → str

To aid debugging applications one can use this method to obtain the whole network of gstreamer elements that form the pipeline into a dot file. This data can be processed with graphviz to get an image.

Parameters:

  • bin – the top-level pipeline that should be analyzed

  • details – type of DebugGraphDetails to use

Returns:

a string containing the pipeline in graphviz dot format.

debug_bin_to_dot_file(bin: Bin, details: DebugGraphDetails, file_name: str) → None

To aid debugging applications one can use this method to write out the whole network of gstreamer elements that form the pipeline into a dot file. This file can be processed with graphviz to get an image.

dot -Tpng -oimage.png graph_lowlevel.dot
Parameters:

  • bin – the top-level pipeline that should be analyzed

  • details – type of DebugGraphDetails to use

  • file_name – output base filename (e.g. “myplayer”)

debug_bin_to_dot_file_with_ts(bin: Bin, details: DebugGraphDetails, file_name: str) → None

This works like debug_bin_to_dot_file(), but adds the current timestamp to the filename, so that it can be used to take multiple snapshots.

Parameters:

  • bin – the top-level pipeline that should be analyzed

  • details – type of DebugGraphDetails to use

  • file_name – output base filename (e.g. “myplayer”)

debug_construct_term_color(colorinfo: int) → str

Constructs a string that can be used for getting the desired color in color terminals. You need to free the string after use.

Parameters:

colorinfo – the color info

Returns:

a string containing the color definition

debug_construct_win_color(colorinfo: int) → int

Constructs an integer that can be used for getting the desired color in windows’ terminals (cmd.exe). As there is no mean to underline, we simply ignore this attribute.

This function returns 0 on non-windows machines.

Parameters:

colorinfo – the color info

Returns:

an integer containing the color definition

debug_get_all_categories() → list[DebugCategory]

Returns a snapshot of a all categories that are currently in use . This list may change anytime. The caller has to free the list after use.

Returns:

the list of debug categories

debug_get_color_mode() → DebugColorMode

Changes the coloring mode for debug output.

Added in version 1.2.

Returns:

see GstDebugColorMode for possible values.

debug_get_default_threshold() → DebugLevel

Returns the default threshold that is used for new categories.

Returns:

the default threshold level

debug_get_stack_trace(flags: StackTraceFlags) → str | None

Added in version 1.12.

Parameters:

flags – A set of StackTraceFlags to determine how the stack trace should look like. Pass GST_STACK_TRACE_SHOW_NONE to retrieve a minimal backtrace.

Returns:

a stack trace, if libunwind or glibc backtrace are present, else None.

debug_is_active() → bool

Checks if debugging output is activated.

Returns:

True, if debugging is activated

debug_is_colored() → bool

Checks if the debugging output should be colored.

Returns:

True, if the debug output should be colored.

debug_level_get_name(level: DebugLevel) → str
Parameters:

level

debug_log_default(category: DebugCategory, level: DebugLevel, file: str, function: str, line: int, object: Object | None, message: DebugMessage, user_data: None) → None

The default logging handler used by GStreamer. Logging functions get called whenever a macro like GST_DEBUG or similar is used. By default this function is setup to output the message and additional info to stderr (or the log file specified via the GST_DEBUG_FILE environment variable) as received via user_data.

You can add other handlers by using debug_add_log_function(). And you can remove this handler by calling gst_debug_remove_log_function(gst_debug_log_default);

Parameters:

  • category – category to log

  • level – level of the message

  • file – the file that emitted the message, usually the ``__FILE__`` identifier

  • function – the function that emitted the message

  • line – the line from that the message was emitted, usually ``__LINE__``

  • object – the object this message relates to, or None if none

  • message – the actual message

  • user_data – the FILE* to log to

debug_log_get_line(category: DebugCategory, level: DebugLevel, file: str, function: str, line: int, object: Object | None, message: DebugMessage) → str

Returns the string representation for the specified debug log message formatted in the same way as debug_log_default() (the default handler), without color. The purpose is to make it easy for custom log output handlers to get a log output that is identical to what the default handler would write out.

Added in version 1.18.

Parameters:

  • category – category to log

  • level – level of the message

  • file – the file that emitted the message, usually the ``__FILE__`` identifier

  • function – the function that emitted the message

  • line – the line from that the message was emitted, usually ``__LINE__``

  • object – the object this message relates to, or None if none

  • message – the actual message

debug_log_id_literal(category: DebugCategory, level: DebugLevel, file: str, function: str, line: int, id: str | None, message_string: str) → None

Logs the given message using the currently registered debugging handlers.

Added in version 1.22.

Parameters:

  • category – category to log

  • level – level of the message is in

  • file – the file that emitted the message, usually the ``__FILE__`` identifier

  • function – the function that emitted the message

  • line – the line from that the message was emitted, usually ``__LINE__``

  • id – the identifier of the object this message relates to or None if none

  • message_string – a message string

debug_log_literal(category: DebugCategory, level: DebugLevel, file: str, function: str, line: int, object: Object | None, message_string: str) → None

Logs the given message using the currently registered debugging handlers.

Added in version 1.20.

Parameters:

  • category – category to log

  • level – level of the message is in

  • file – the file that emitted the message, usually the ``__FILE__`` identifier

  • function – the function that emitted the message

  • line – the line from that the message was emitted, usually ``__LINE__``

  • object – the object this message relates to, or None if none

  • message_string – a message string

debug_print_stack_trace() → None

If libunwind, glibc backtrace or DbgHelp are present a stack trace is printed.

debug_remove_log_function(func: Callable[[...], None] | None = None) → int

Removes all registered instances of the given logging functions.

Parameters:

func – the log function to remove, or None to remove the default log function

Returns:

How many instances of the function were removed

debug_remove_log_function_by_data(data: None) → int

Removes all registered instances of log functions with the given user data.

Parameters:

data – user data of the log function to remove

Returns:

How many instances of the function were removed

debug_remove_ring_buffer_logger() → None

Removes any previously added ring buffer logger with debug_add_ring_buffer_logger().

Added in version 1.14.

debug_ring_buffer_logger_get_logs() → list[str]

Fetches the current logs per thread from the ring buffer logger. See debug_add_ring_buffer_logger() for details.

Added in version 1.14.

Returns:

NULL-terminated array of strings with the debug output per thread

debug_set_active(active: bool) → None

If activated, debugging messages are sent to the debugging handlers. It makes sense to deactivate it for speed issues. > This function is not threadsafe. It makes sense to only call it during initialization.

Parameters:

active – Whether to use debugging output or not

debug_set_color_mode(mode: DebugColorMode) → None

Changes the coloring mode for debug output.

This function may be called before init().

Added in version 1.2.

Parameters:

mode – The coloring mode for debug output. See GstDebugColorMode.

debug_set_color_mode_from_string(mode: str) → None

Changes the coloring mode for debug output.

This function may be called before init().

Added in version 1.2.

Parameters:

mode – The coloring mode for debug output. One of the following: “on”, “auto”, “off”, “disable”, “unix”.

debug_set_colored(colored: bool) → None

Sets or unsets the use of coloured debugging output. Same as gst_debug_set_color_mode () with the argument being being GST_DEBUG_COLOR_MODE_ON or GST_DEBUG_COLOR_MODE_OFF.

This function may be called before init().

Parameters:

colored – Whether to use colored output or not

debug_set_default_threshold(level: DebugLevel) → None

Sets the default threshold to the given level and updates all categories to use this threshold.

This function may be called before init().

Parameters:

level – level to set

debug_set_threshold_for_name(name: str, level: DebugLevel) → None

Sets all categories which match the given glob style pattern to the given level.

Parameters:

  • name – name of the categories to set

  • level – level to set them to

debug_set_threshold_from_string(list: str, reset: bool) → None

Sets the debug logging wanted in the same form as with the GST_DEBUG environment variable. You can use wildcards such as *, but note that the order matters when you use wild cards, e.g. foosrc:6,*src:3,*:2 sets everything to log level 2.

Added in version 1.2.

Parameters:

  • list – comma-separated list of “category:level” pairs to be used as debug logging levels

  • reset –

    True to clear all previously-set debug levels before setting

    new thresholds

    False if adding the threshold described by list to the one already set.

debug_unset_threshold_for_name(name: str) → None

Resets all categories with the given name back to the default level.

Parameters:

name – name of the categories to set

deinit() → None

Clean up any resources created by GStreamer in 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.

dynamic_type_register(plugin: Plugin, type: type) → bool

Registers a new GstDynamicTypeFactory in the registry

Added in version 1.12.

Parameters:

  • plugin – The Plugin to register dyn_type for

  • type – The Type to register dynamically

error_get_message(domain: int, code: int) → str

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:

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

event_type_get_flags(type: EventType) → EventTypeFlags
Parameters:

type

event_type_get_name(type: EventType) → str
Parameters:

type

event_type_to_quark(type: EventType) → int
Parameters:

type

event_type_to_sticky_ordering(type: EventType) → int
Parameters:

type

filename_to_uri(filename: str) → str | None

Similar to filename_to_uri(), but attempts to handle relative file paths as well. Before converting filename into an URI, it will be prefixed by the current working directory if it is a relative path, and then the path will be canonicalised so that it doesn’t contain any ‘./’ or ‘../’ segments.

On Windows filename should be in UTF-8 encoding.

Parameters:

filename – absolute or relative file name path

Returns:

newly-allocated URI string, or NULL on error. The caller must free the URI string with free() when no longer needed.

flow_get_name(ret: FlowReturn) → str

Gets a string representing the given flow return.

Parameters:

ret – a FlowReturn to get the name of.

Returns:

a static string with the name of the flow return.

flow_to_quark(ret: FlowReturn) → int

Get the unique quark for the given GstFlowReturn.

Parameters:

ret – a FlowReturn to get the quark of.

Returns:

the quark associated with the flow return or 0 if an invalid return was specified.

format_get_by_nick(nick: str) → Format
Parameters:

nick

format_get_details(format: Format) → FormatDefinition | None
Parameters:

format

format_get_name(format: Format) → str | None
Parameters:

format

format_iterate_definitions() → Iterator
format_register(nick: str, description: str) → Format
Parameters:

  • nick

  • description

format_to_quark(format: Format) → int
Parameters:

format

formats_contains(formats: Sequence[Format], format: Format) → bool

See if the given format is inside the format array.

Parameters:

  • formats – The format array to search

  • format – the format to find

Returns:

True if the format is found inside the array

get_main_executable_path() → str | None

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.

Added in version 1.14.

Returns:

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

init() → list[str]

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 update_registry() for details and section <link linkend=”gst-running”>Running GStreamer Applications</link> 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 init_check() instead.

init_check() → tuple[bool, list[str]]

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 init() instead.

Returns:

True if GStreamer could be initialized.

is_caps_features(obj: None) → bool

Checks if obj is a CapsFeatures

Parameters:

obj

Returns:

True if obj is a CapsFeatures False otherwise

is_initialized() → bool

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

Returns:

True if initialization has been done, False otherwise.

library_error_quark() → int
message_type_get_name(type: MessageType) → str
Parameters:

type

message_type_to_quark(type: MessageType) → int
Parameters:

type

meta_api_type_get_tags(api: type) → list[str]
Parameters:

api

meta_api_type_has_tag(api: type, tag: int) → bool
Parameters:

  • api

  • tag

meta_api_type_register(api: str, tags: Sequence[str]) → type
Parameters:

  • api

  • tags

meta_get_info(impl: str) → MetaInfo | None
Parameters:

impl

meta_register(api: type, impl: str, size: int, init_func: Callable[[Meta, None, Buffer], bool], free_func: Callable[[Meta, Buffer], None], transform_func: Callable[[Buffer, Meta, Buffer, int, None], bool]) → MetaInfo
Parameters:

  • api

  • impl

  • size

  • init_func

  • free_func

  • transform_func

meta_register_custom(name: str, tags: Sequence[str], transform_func: Callable[[...], bool] | None = None, *user_data: Any) → MetaInfo
Parameters:

  • name

  • tags

  • transform_func

  • user_data

mini_object_replace(newdata: MiniObject | None = None) → tuple[bool, MiniObject]
Parameters:

newdata

mini_object_take(newdata: MiniObject) → tuple[bool, MiniObject]
Parameters:

newdata

pad_mode_get_name(mode: PadMode) → str
Parameters:

mode

param_spec_array(name: str, nick: str, blurb: str, element_spec: ParamSpec, flags: ParamFlags) → ParamSpec

This function creates a GstArray GParamSpec for use by objects/elements that want to expose properties of GstArray type. This function is typically * used in connection with install_property() in a GObjects’s instance_init function.

Added in version 1.14.

Parameters:

  • name – canonical name of the property specified

  • nick – nick name for the property specified

  • blurb – description of the property specified

  • element_spec – GParamSpec of the array

  • flags – flags for the property specified

Returns:

a newly created parameter specification

param_spec_fraction(name: str, nick: str, blurb: str, min_num: int, min_denom: int, max_num: int, max_denom: int, default_num: int, default_denom: int, flags: ParamFlags) → ParamSpec | None

This function creates a fraction GParamSpec for use by objects/elements that want to expose properties of fraction type. This function is typically used in connection with install_property() in a GObjects’s instance_init function.

Parameters:

  • name – canonical name of the property specified

  • nick – nick name for the property specified

  • blurb – description of the property specified

  • min_num – minimum value (fraction numerator)

  • min_denom – minimum value (fraction denominator)

  • max_num – maximum value (fraction numerator)

  • max_denom – maximum value (fraction denominator)

  • default_num – default value (fraction numerator)

  • default_denom – default value (fraction denominator)

  • flags – flags for the property specified

Returns:

a newly created parameter specification

parent_buffer_meta_api_get_type() → type
parent_buffer_meta_get_info() → MetaInfo
parse_bin_from_description(bin_description: str, ghost_unlinked_pads: bool) → Bin

This is a convenience wrapper around parse_launch() to create a Bin from a gst-launch-style pipeline description. See 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

Returns:

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

parse_bin_from_description_full(bin_description: str, ghost_unlinked_pads: bool, context: ParseContext | None, flags: ParseFlags) → Element

This is a convenience wrapper around parse_launch() to create a Bin from a gst-launch-style pipeline description. See 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

  • context – a parse context allocated with new(), or None

  • flags – parsing options, or GST_PARSE_FLAG_NONE

Returns:

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

parse_error_quark() → int
parse_launch(pipeline_description: str) → Element

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

To create a sub-pipeline (bin) for embedding into an existing pipeline use parse_bin_from_description().

Parameters:

pipeline_description – the command line describing the pipeline

Returns:

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

parse_launch_full(pipeline_description: str, context: ParseContext | None, flags: ParseFlags) → Element

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

To create a sub-pipeline (bin) for embedding into an existing pipeline use parse_bin_from_description_full().

Parameters:

  • pipeline_description – the command line describing the pipeline

  • context – a parse context allocated with new(), or None

  • flags – parsing options, or GST_PARSE_FLAG_NONE

Returns:

a new element on success, None on failure. If more than one toplevel element is specified by the pipeline_description, all elements are put into a Pipeline, which then is returned (unless the GST_PARSE_FLAG_PLACE_IN_BIN flag is set, in which case they are put in a Bin instead).

parse_launchv(argv: Sequence[str]) → Element

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

Returns:

a new element on success and None on failure.

parse_launchv_full(argv: Sequence[str], context: ParseContext | None, flags: ParseFlags) → Element

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

  • context – a parse context allocated with new(), or None

  • flags – parsing options, or GST_PARSE_FLAG_NONE

Returns:

a new element on success; on failure, either None 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 None will always be returned on failure)

plugin_error_quark() → int
preset_get_app_dir() → str | None
preset_set_app_dir(app_dir: str) → bool
Parameters:

app_dir

protection_filter_systems_by_available_decryptors(system_identifiers: Sequence[str]) → list[str] | None

Iterates the supplied list of UUIDs and checks the GstRegistry for all the decryptors supporting one of the supplied UUIDs.

Added in version 1.14.

Parameters:

system_identifiers – A null terminated array of strings that contains the UUID values of each protection system that is to be checked.

Returns:

A null terminated array containing all the system_identifiers supported by the set of available decryptors, or None if no matches were found.

protection_meta_api_get_type() → type
protection_meta_get_info() → MetaInfo
protection_select_system(system_identifiers: Sequence[str]) → str | None

Iterates the supplied list of UUIDs and checks the GstRegistry for an element that supports one of the supplied UUIDs. If more than one element matches, the system ID of the highest ranked element is selected.

Added in version 1.6.

Parameters:

system_identifiers – A null terminated array of strings that contains the UUID values of each protection system that is to be checked.

Returns:

One of the strings from system_identifiers that indicates the highest ranked element that implements the protection system indicated by that system ID, or None if no element has been found.

query_type_get_flags(type: QueryType) → QueryTypeFlags
Parameters:

type

query_type_get_name(type: QueryType) → str
Parameters:

type

query_type_to_quark(type: QueryType) → int
Parameters:

type

reference_timestamp_meta_api_get_type() → type
reference_timestamp_meta_get_info() → MetaInfo
resource_error_quark() → int
segtrap_is_enabled() → bool

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

segtrap_set_enabled(enabled: bool) → None

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

Parameters:

enabled – whether a custom SIGSEGV handler should be installed.

state_change_get_name(transition: StateChange) → str
Parameters:

transition

static_caps_get_type() → type
static_pad_template_get_type() → type
stream_error_quark() → int
stream_type_get_name(stype: StreamType) → str
Parameters:

stype

structure_take(newstr: Structure | None = None) → tuple[bool, Structure]
Parameters:

newstr

tag_exists(tag: str) → bool

Checks if the given type is already registered.

Parameters:

tag – name of the tag

Returns:

True if the type is already registered

tag_get_description(tag: str) → str

Returns the human-readable description of this tag, You must not change or free this string.

Parameters:

tag – the tag

Returns:

the human-readable description of this tag

tag_get_flag(tag: str) → TagFlag

Gets the flag of tag.

Parameters:

tag – the tag

Returns:

the flag of this tag.

tag_get_nick(tag: str) → str

Returns the human-readable name of this tag, You must not change or free this string.

Parameters:

tag – the tag

Returns:

the human-readable name of this tag

tag_get_type(tag: str) → type

Gets the Type used for this tag.

Parameters:

tag – the tag

Returns:

the Type of this tag

tag_is_fixed(tag: str) → bool

Checks if the given tag is fixed. A fixed tag can only contain one value. Unfixed tags can contain lists of values.

Parameters:

tag – tag to check

Returns:

True, if the given tag is fixed.

tag_merge_strings_with_comma(src: Any) → Any

This is a convenience function for the func argument of tag_register(). It concatenates all given strings using a comma. The tag must be registered as a G_TYPE_STRING or this function will fail.

Parameters:

src – GValue to copy from

tag_merge_use_first(src: Any) → Any

This is a convenience function for the func argument of tag_register(). It creates a copy of the first value from the list.

Parameters:

src – GValue to copy from

toc_entry_type_get_nick(type: TocEntryType) → str
Parameters:

type

tracing_get_active_tracers() → list[Tracer]

Get a list of all active tracer objects owned by the tracing framework for the entirety of the run-time of the process or till deinit() is called.

Added in version 1.18.

Returns:

A GList of Tracer objects

tracing_register_hook(tracer: Tracer, detail: str, func: Callable[[], None]) → None

Register func to be called when the trace hook detail is getting invoked. Use None for detail to register to all hooks.

Added in version 1.8.

Parameters:

  • tracer – the tracer

  • detail – the detailed hook

  • func – the callback

type_find_get_type() → type
type_find_register(plugin: Plugin | None, name: str, rank: int, func: Callable[[...], None], extensions: str | None = None, possible_caps: Caps | None = None, *data: Any) → bool
Parameters:

  • plugin

  • name

  • rank

  • func

  • extensions

  • possible_caps

  • data

type_is_plugin_api(type: type) → tuple[bool, PluginAPIFlags]

Checks if type is plugin API. See type_mark_as_plugin_api() for details.

Added in version 1.18.

Parameters:

type – a GType

Returns:

True if type is plugin API or False otherwise.

type_mark_as_plugin_api(type: type, flags: PluginAPIFlags) → None

Marks type as plugin API. This should be called in class_init of elements that expose new types (i.e. enums, flags or internal GObjects) via properties, signals or pad templates.

Types exposed by plugins are not automatically added to the documentation as they might originate from another library and should in that case be documented via that library instead.

By marking a type as plugin API it will be included in the documentation of the plugin that defines it.

Added in version 1.18.

Parameters:

  • type – a GType

  • flags – a set of PluginAPIFlags to further inform cache generation.

update_registry() → bool

Forces GStreamer to re-scan its plugin paths and update the default plugin registry.

Applications will almost never need to call this function, it is only useful if the application knows new plugins have been installed (or old ones removed) since the start of the application (or, to be precise, the first call to init()) and the application wants to make use of any newly-installed plugins without restarting the application.

Applications should assume that the registry update is neither atomic nor thread-safe and should therefore not have any dynamic pipelines running (including the playbin and decodebin elements) and should also not create any elements or access the GStreamer registry while the update is in progress.

Note that this function may block for a significant amount of time.

Returns:

True if the registry has been updated successfully (does not imply that there were changes), otherwise False.

uri_construct(protocol: str, location: str) → str
Parameters:

  • protocol

  • location

uri_error_quark() → int
uri_from_string(uri: str) → Uri | None
Parameters:

uri

uri_from_string_escaped(uri: str) → Uri | None
Parameters:

uri

uri_get_location(uri: str) → str | None
Parameters:

uri

uri_get_protocol(uri: str) → str | None
Parameters:

uri

uri_has_protocol(uri: str, protocol: str) → bool
Parameters:

  • uri

  • protocol

uri_is_valid(uri: str) → bool
Parameters:

uri

uri_join_strings(base_uri: str, ref_uri: str) → str | None
Parameters:

  • base_uri

  • ref_uri

uri_protocol_is_supported(type: URIType, protocol: str) → bool
Parameters:

  • type

  • protocol

uri_protocol_is_valid(protocol: str) → bool
Parameters:

protocol

Searches inside array for search_data by using the comparison function search_func. array must be sorted ascending.

As search_data is always passed as second argument to search_func it’s not required that search_data has the same type as the array elements.

The complexity of this search function is O(log (num_elements)).

Parameters:

  • array – the sorted input array

  • num_elements – number of elements in the array

  • element_size – size of every element in bytes

  • search_func – function to compare two elements, search_data will always be passed as second argument

  • mode – search mode that should be used

  • search_data – element that should be found

  • user_data – data to pass to search_func

Returns:

The address of the found element or None if nothing was found

util_double_to_fraction(src: float) → tuple[int, int]

Transforms a float to a fraction and simplifies the result.

Parameters:

src – float to transform

util_dump_buffer(buf: Buffer) → None

Dumps the buffer memory into a hex representation. Useful for debugging.

Added in version 1.14.

Parameters:

buf – a Buffer whose memory to dump

util_dump_mem(mem: Sequence[int]) → None

Dumps the memory block into a hex representation. Useful for debugging.

Parameters:

mem – a pointer to the memory to dump

util_fraction_add(a_n: int, a_d: int, b_n: int, b_d: int) → tuple[bool, int, int]

Adds the fractions a_n/a_d and b_n/b_d and stores the result in res_n and res_d.

Parameters:

  • a_n – Numerator of first value

  • a_d – Denominator of first value

  • b_n – Numerator of second value

  • b_d – Denominator of second value

Returns:

False on overflow, True otherwise.

util_fraction_compare(a_n: int, a_d: int, b_n: int, b_d: int) → int

Compares the fractions a_n/a_d and b_n/b_d and returns

-1 if a < b, 0 if a = b and 1 if a > b.

Parameters:

  • a_n – Numerator of first value

  • a_d – Denominator of first value

  • b_n – Numerator of second value

  • b_d – Denominator of second value

Returns:

-1 if a < b; 0 if a = b; 1 if a > b.

util_fraction_multiply(a_n: int, a_d: int, b_n: int, b_d: int) → tuple[bool, int, int]

Multiplies the fractions a_n/a_d and b_n/b_d and stores the result in res_n and res_d.

Parameters:

  • a_n – Numerator of first value

  • a_d – Denominator of first value

  • b_n – Numerator of second value

  • b_d – Denominator of second value

Returns:

False on overflow, True otherwise.

util_fraction_to_double(src_n: int, src_d: int) → float

Transforms a fraction to a float.

Parameters:

  • src_n – Fraction numerator as int

  • src_d – Fraction denominator int

util_gdouble_to_guint64(value: float) → int
Parameters:

value – The float value to convert guint64 double

Returns:

value casted to guint64

util_get_object_array(object: Object, name: str) → tuple[bool, ValueArray]

Get a property of type %GST_TYPE_ARRAY and transform it into a ValueArray. This allow language bindings to get GST_TYPE_ARRAY properties which are otherwise not an accessible type.

Added in version 1.12.

Parameters:

  • object – the object to set the array to

  • name – the name of the property to set

util_get_timestamp() → int

Get a timestamp as GstClockTime to be used for interval measurements. The timestamp should not be interpreted in any other way.

Returns:

the timestamp

util_greatest_common_divisor(a: int, b: int) → int

Calculates the greatest common divisor of a and b.

Parameters:

  • a – First value as int

  • b – Second value as int

Returns:

Greatest common divisor of a and b

util_greatest_common_divisor_int64(a: int, b: int) → int

Calculates the greatest common divisor of a and b.

Parameters:

  • a – First value as int

  • b – Second value as int

Returns:

Greatest common divisor of a and b

util_group_id_next() → int

Return a constantly incrementing group id.

This function is used to generate a new group-id for the stream-start event.

This function never returns GROUP_ID_INVALID (which is 0)

Returns:

A constantly incrementing unsigned integer, which might overflow back to 0 at some point.

util_guint64_to_gdouble(value: int) → float
Parameters:

value – The guint64 value to convert to double

Returns:

value casted to float

util_seqnum_compare(s1: int, s2: int) → int

Compare two sequence numbers, handling wraparound.

The current implementation just returns (gint32)(s1 - s2).

Parameters:

  • s1 – A sequence number.

  • s2 – Another sequence number.

Returns:

A negative number if s1 is before s2, 0 if they are equal, or a positive number if s1 is after s2.

util_seqnum_next() → int

Return a constantly incrementing sequence number.

This function is used internally to GStreamer to be able to determine which events and messages are “the same”. For example, elements may set the seqnum on a segment-done message to be the same as that of the last seek event, to indicate that event and the message correspond to the same segment.

This function never returns SEQNUM_INVALID (which is 0).

Returns:

A constantly incrementing 32-bit unsigned integer, which might overflow at some point. Use util_seqnum_compare() to make sure you handle wraparound correctly.

util_set_object_arg(object: Object, name: str, value: str) → None

Converts the string value to the type of the objects argument and sets the argument with it.

Note that this function silently returns if object has no property named name or when value cannot be converted to the type of the property.

Parameters:

  • object – the object to set the argument of

  • name – the name of the argument to set

  • value – the string value to set

util_set_object_array(object: Object, name: str, array: ValueArray) → bool

Transfer a ValueArray to %GST_TYPE_ARRAY and set this value on the specified property name. This allow language bindings to set GST_TYPE_ARRAY properties which are otherwise not an accessible type.

Added in version 1.12.

Parameters:

  • object – the object to set the array to

  • name – the name of the property to set

  • array – a ValueArray containing the values

util_set_value_from_string(value_str: str) → Any

Converts the string to the type of the value and sets the value with it.

Note that this function is dangerous as it does not return any indication if the conversion worked or not.

Parameters:

value_str – the string to get the value from

util_uint64_scale(val: int, num: int, denom: int) → int

Scale val by the rational number num / denom, avoiding overflows and underflows and without loss of precision.

This function can potentially be very slow if val and num are both greater than G_MAXUINT32.

Parameters:

  • val – the number to scale

  • num – the numerator of the scale ratio

  • denom – the denominator of the scale ratio

Returns:

val * num / denom. In the case of an overflow, this function returns G_MAXUINT64. If the result is not exactly representable as an integer it is truncated. See also util_uint64_scale_round(), util_uint64_scale_ceil(), util_uint64_scale_int(), util_uint64_scale_int_round(), util_uint64_scale_int_ceil().

util_uint64_scale_ceil(val: int, num: int, denom: int) → int

Scale val by the rational number num / denom, avoiding overflows and underflows and without loss of precision.

This function can potentially be very slow if val and num are both greater than G_MAXUINT32.

Parameters:

  • val – the number to scale

  • num – the numerator of the scale ratio

  • denom – the denominator of the scale ratio

Returns:

val * num / denom. In the case of an overflow, this function returns G_MAXUINT64. If the result is not exactly representable as an integer, it is rounded up. See also util_uint64_scale(), util_uint64_scale_round(), util_uint64_scale_int(), util_uint64_scale_int_round(), util_uint64_scale_int_ceil().

util_uint64_scale_int(val: int, num: int, denom: int) → int

Scale val by the rational number num / denom, avoiding overflows and underflows and without loss of precision. num must be non-negative and denom must be positive.

Parameters:

  • val – guint64 (such as a ClockTime) to scale.

  • num – numerator of the scale factor.

  • denom – denominator of the scale factor.

Returns:

val * num / denom. In the case of an overflow, this function returns G_MAXUINT64. If the result is not exactly representable as an integer, it is truncated. See also util_uint64_scale_int_round(), util_uint64_scale_int_ceil(), util_uint64_scale(), util_uint64_scale_round(), util_uint64_scale_ceil().

util_uint64_scale_int_ceil(val: int, num: int, denom: int) → int

Scale val by the rational number num / denom, avoiding overflows and underflows and without loss of precision. num must be non-negative and denom must be positive.

Parameters:

  • val – guint64 (such as a ClockTime) to scale.

  • num – numerator of the scale factor.

  • denom – denominator of the scale factor.

Returns:

val * num / denom. In the case of an overflow, this function returns G_MAXUINT64. If the result is not exactly representable as an integer, it is rounded up. See also util_uint64_scale_int(), util_uint64_scale_int_round(), util_uint64_scale(), util_uint64_scale_round(), util_uint64_scale_ceil().

util_uint64_scale_int_round(val: int, num: int, denom: int) → int

Scale val by the rational number num / denom, avoiding overflows and underflows and without loss of precision. num must be non-negative and denom must be positive.

Parameters:

  • val – guint64 (such as a ClockTime) to scale.

  • num – numerator of the scale factor.

  • denom – denominator of the scale factor.

Returns:

val * num / denom. In the case of an overflow, this function returns G_MAXUINT64. If the result is not exactly representable as an integer, it is rounded to the nearest integer (half-way cases are rounded up). See also util_uint64_scale_int(), util_uint64_scale_int_ceil(), util_uint64_scale(), util_uint64_scale_round(), util_uint64_scale_ceil().

util_uint64_scale_round(val: int, num: int, denom: int) → int

Scale val by the rational number num / denom, avoiding overflows and underflows and without loss of precision.

This function can potentially be very slow if val and num are both greater than G_MAXUINT32.

Parameters:

  • val – the number to scale

  • num – the numerator of the scale ratio

  • denom – the denominator of the scale ratio

Returns:

val * num / denom. In the case of an overflow, this function returns G_MAXUINT64. If the result is not exactly representable as an integer, it is rounded to the nearest integer (half-way cases are rounded up). See also util_uint64_scale(), util_uint64_scale_ceil(), util_uint64_scale_int(), util_uint64_scale_int_round(), util_uint64_scale_int_ceil().

value_can_compare(value1: Any, value2: Any) → bool

Determines if value1 and value2 can be compared.

Parameters:

  • value1 – a value to compare

  • value2 – another value to compare

Returns:

True if the values can be compared

value_can_intersect(value1: Any, value2: Any) → bool

Determines if intersecting two values will produce a valid result. Two values will produce a valid intersection if they have the same type.

Parameters:

  • value1 – a value to intersect

  • value2 – another value to intersect

Returns:

True if the values can intersect

value_can_subtract(minuend: Any, subtrahend: Any) → bool

Checks if it’s possible to subtract subtrahend from minuend.

Parameters:

  • minuend – the value to subtract from

  • subtrahend – the value to subtract

Returns:

True if a subtraction is possible

value_can_union(value1: Any, value2: Any) → bool

Determines if value1 and value2 can be non-trivially unioned. Any two values can be trivially unioned by adding both of them to a GstValueList. However, certain types have the possibility to be unioned in a simpler way. For example, an integer range and an integer can be unioned if the integer is a subset of the integer range. If there is the possibility that two values can be unioned, this function returns True.

Parameters:

  • value1 – a value to union

  • value2 – another value to union

Returns:

True if there is a function allowing the two values to be unioned.

value_compare(value1: Any, value2: Any) → int

Compares value1 and value2. If value1 and value2 cannot be compared, the function returns GST_VALUE_UNORDERED. Otherwise, if value1 is greater than value2, GST_VALUE_GREATER_THAN is returned. If value1 is less than value2, GST_VALUE_LESS_THAN is returned. If the values are equal, GST_VALUE_EQUAL is returned.

Parameters:

  • value1 – a value to compare

  • value2 – another value to compare

Returns:

comparison result

value_deserialize(src: str) → tuple[bool, Any]

Tries to deserialize a string into the type specified by the given GValue. If the operation succeeds, True is returned, False otherwise.

Parameters:

src – string to deserialize

Returns:

True on success

value_deserialize_with_pspec(src: str, pspec: ParamSpec | None = None) → tuple[bool, Any]

Tries to deserialize a string into the type specified by the given GValue. pspec may be used to guide the deserializing of nested members. If the operation succeeds, True is returned, False otherwise.

Added in version 1.20.

Parameters:

  • src – string to deserialize

  • pspec – the ParamSpec describing the expected value

Returns:

True on success

value_fixate(dest: Any, src: Any) → bool

Fixate src into a new value dest. For ranges, the first element is taken. For lists and arrays, the first item is fixated and returned. If src is already fixed, this function returns False.

Parameters:

  • dest – the Value destination

  • src – the Value to fixate

Returns:

True if dest contains a fixated version of src.

value_fraction_multiply(product: Any, factor1: Any, factor2: Any) → bool

Multiplies the two Value items containing a GST_TYPE_FRACTION and sets product to the product of the two fractions.

Parameters:

  • product – a GValue initialized to GST_TYPE_FRACTION

  • factor1 – a GValue initialized to GST_TYPE_FRACTION

  • factor2 – a GValue initialized to GST_TYPE_FRACTION

Returns:

False in case of an error (like integer overflow), True otherwise.

value_fraction_subtract(dest: Any, minuend: Any, subtrahend: Any) → bool

Subtracts the subtrahend from the minuend and sets dest to the result.

Parameters:

  • dest – a GValue initialized to GST_TYPE_FRACTION

  • minuend – a GValue initialized to GST_TYPE_FRACTION

  • subtrahend – a GValue initialized to GST_TYPE_FRACTION

Returns:

False in case of an error (like integer overflow), True otherwise.

value_get_bitmask(value: Any) → int

Gets the bitmask specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_BITMASK

Returns:

the bitmask.

value_get_caps(value: Any) → Caps

Gets the contents of value. The reference count of the returned Caps will not be modified, therefore the caller must take one before getting rid of the value.

Parameters:

value – a GValue initialized to GST_TYPE_CAPS

Returns:

the contents of value

value_get_caps_features(value: Any) → CapsFeatures

Gets the contents of value.

Parameters:

value – a GValue initialized to GST_TYPE_CAPS_FEATURES

Returns:

the contents of value

value_get_double_range_max(value: Any) → float

Gets the maximum of the range specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_DOUBLE_RANGE

Returns:

the maximum of the range

value_get_double_range_min(value: Any) → float

Gets the minimum of the range specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_DOUBLE_RANGE

Returns:

the minimum of the range

value_get_flagset_flags(value: Any) → int

Retrieve the flags field of a GstFlagSet value.

Added in version 1.6.

Parameters:

value – a GValue initialized to GST_TYPE_FLAG_SET

Returns:

the flags field of the flagset instance.

value_get_flagset_mask(value: Any) → int

Retrieve the mask field of a GstFlagSet value.

Added in version 1.6.

Parameters:

value – a GValue initialized to GST_TYPE_FLAG_SET

Returns:

the mask field of the flagset instance.

value_get_fraction_denominator(value: Any) → int

Gets the denominator of the fraction specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_FRACTION

Returns:

the denominator of the fraction.

value_get_fraction_numerator(value: Any) → int

Gets the numerator of the fraction specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_FRACTION

Returns:

the numerator of the fraction.

value_get_fraction_range_max(value: Any) → Any | None

Gets the maximum of the range specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_FRACTION_RANGE

Returns:

the maximum of the range

value_get_fraction_range_min(value: Any) → Any | None

Gets the minimum of the range specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_FRACTION_RANGE

Returns:

the minimum of the range

value_get_int64_range_max(value: Any) → int

Gets the maximum of the range specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_INT64_RANGE

Returns:

the maximum of the range

value_get_int64_range_min(value: Any) → int

Gets the minimum of the range specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_INT64_RANGE

Returns:

the minimum of the range

value_get_int64_range_step(value: Any) → int

Gets the step of the range specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_INT64_RANGE

Returns:

the step of the range

value_get_int_range_max(value: Any) → int

Gets the maximum of the range specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_INT_RANGE

Returns:

the maximum of the range

value_get_int_range_min(value: Any) → int

Gets the minimum of the range specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_INT_RANGE

Returns:

the minimum of the range

value_get_int_range_step(value: Any) → int

Gets the step of the range specified by value.

Parameters:

value – a GValue initialized to GST_TYPE_INT_RANGE

Returns:

the step of the range

value_get_structure(value: Any) → Structure

Gets the contents of value.

Parameters:

value – a GValue initialized to GST_TYPE_STRUCTURE

Returns:

the contents of value

value_intersect(value1: Any, value2: Any) → tuple[bool, Any]

Calculates the intersection of two values. If the values have a non-empty intersection, the value representing the intersection is placed in dest, unless None. If the intersection is non-empty, dest is not modified.

Parameters:

  • value1 – a value to intersect

  • value2 – another value to intersect

Returns:

True if the intersection is non-empty

value_is_fixed(value: Any) → bool

Tests if the given GValue, if available in a GstStructure (or any other container) contains a “fixed” (which means: one value) or an “unfixed” (which means: multiple possible values, such as data lists or data ranges) value.

Parameters:

value – the Value to check

Returns:

true if the value is “fixed”.

value_is_subset(value1: Any, value2: Any) → bool

Check that value1 is a subset of value2.

Parameters:
Returns:

True is value1 is a subset of value2

value_register(table: ValueTable) → None

Registers functions to perform calculations on Value items of a given type. Each type can only be added once.

Parameters:

table – structure containing functions to register

value_serialize(value: Any) → str | None

tries to transform the given value into a string representation that allows getting back this string later on using value_deserialize().

Free-function: g_free

Parameters:

value – a Value to serialize

Returns:

the serialization for value or None if none exists

value_set_bitmask(value: Any, bitmask: int) → None

Sets value to the bitmask specified by bitmask.

Parameters:

  • value – a GValue initialized to GST_TYPE_BITMASK

  • bitmask – the bitmask

value_set_caps(value: Any, caps: Caps) → None

Sets the contents of value to caps. A reference to the provided caps will be taken by the value.

Parameters:

  • value – a GValue initialized to GST_TYPE_CAPS

  • caps – the caps to set the value to

value_set_caps_features(value: Any, features: CapsFeatures) → None

Sets the contents of value to features.

Parameters:

  • value – a GValue initialized to GST_TYPE_CAPS_FEATURES

  • features – the features to set the value to

value_set_double_range(value: Any, start: float, end: float) → None

Sets value to the range specified by start and end.

Parameters:

  • value – a GValue initialized to GST_TYPE_DOUBLE_RANGE

  • start – the start of the range

  • end – the end of the range

value_set_flagset(value: Any, flags: int, mask: int) → None

Sets value to the flags and mask values provided in flags and mask. The flags value indicates the values of flags, the mask represents which bits in the flag value have been set, and which are “don’t care”

Added in version 1.6.

Parameters:

  • value – a GValue initialized to ``%GST_TYPE_FLAG_SET``

  • flags – The value of the flags set or unset

  • mask – The mask indicate which flags bits must match for comparisons

value_set_fraction(value: Any, numerator: int, denominator: int) → None

Sets value to the fraction specified by numerator over denominator. The fraction gets reduced to the smallest numerator and denominator, and if necessary the sign is moved to the numerator.

Parameters:

  • value – a GValue initialized to GST_TYPE_FRACTION

  • numerator – the numerator of the fraction

  • denominator – the denominator of the fraction

value_set_fraction_range(value: Any, start: Any, end: Any) → None

Sets value to the range specified by start and end.

Parameters:

  • value – a GValue initialized to GST_TYPE_FRACTION_RANGE

  • start – the start of the range (a GST_TYPE_FRACTION GValue)

  • end – the end of the range (a GST_TYPE_FRACTION GValue)

value_set_fraction_range_full(value: Any, numerator_start: int, denominator_start: int, numerator_end: int, denominator_end: int) → None

Sets value to the range specified by numerator_start/denominator_start and numerator_end/denominator_end.

Parameters:

  • value – a GValue initialized to GST_TYPE_FRACTION_RANGE

  • numerator_start – the numerator start of the range

  • denominator_start – the denominator start of the range

  • numerator_end – the numerator end of the range

  • denominator_end – the denominator end of the range

value_set_int64_range(value: Any, start: int, end: int) → None

Sets value to the range specified by start and end.

Parameters:

  • value – a GValue initialized to GST_TYPE_INT64_RANGE

  • start – the start of the range

  • end – the end of the range

value_set_int64_range_step(value: Any, start: int, end: int, step: int) → None

Sets value to the range specified by start, end and step.

Parameters:

  • value – a GValue initialized to GST_TYPE_INT64_RANGE

  • start – the start of the range

  • end – the end of the range

  • step – the step of the range

value_set_int_range(value: Any, start: int, end: int) → None

Sets value to the range specified by start and end.

Parameters:

  • value – a GValue initialized to GST_TYPE_INT_RANGE

  • start – the start of the range

  • end – the end of the range

value_set_int_range_step(value: Any, start: int, end: int, step: int) → None

Sets value to the range specified by start, end and step.

Parameters:

  • value – a GValue initialized to GST_TYPE_INT_RANGE

  • start – the start of the range

  • end – the end of the range

  • step – the step of the range

value_set_structure(value: Any, structure: Structure) → None

Sets the contents of value to structure.

Parameters:

  • value – a GValue initialized to GST_TYPE_STRUCTURE

  • structure – the structure to set the value to

value_subtract(minuend: Any, subtrahend: Any) → tuple[bool, Any]

Subtracts subtrahend from minuend and stores the result in dest. Note that this means subtraction as in sets, not as in mathematics.

Parameters:

  • minuend – the value to subtract from

  • subtrahend – the value to subtract

Returns:

True if the subtraction is not empty

value_union(value1: Any, value2: Any) → tuple[bool, Any]

Creates a GValue corresponding to the union of value1 and value2.

Parameters:

  • value1 – a value to union

  • value2 – another value to union

Returns:

True if the union succeeded.

version() → tuple[int, int, int, int]

Gets the version number of the GStreamer library.

version_string() → str

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.