Callbacks

  BufferForeachMetaFunc (buffer, *user_data)
  BufferListFunc (idx, *user_data)
  BusFunc (bus, message, *user_data)
  BusSyncHandler (bus, message, *user_data)
  CapsFilterMapFunc (features, structure, *user_data)
  CapsForeachFunc (features, structure, *user_data)
  CapsMapFunc (features, structure, *user_data)
  ClockCallback (clock, time, id, *user_data)
  ControlBindingConvert (binding, src_value, dest_value)
  ControlSourceGetValue (self, timestamp, value)
  ControlSourceGetValueArray (self, timestamp, interval, n_values, values)
  DebugFuncPtr ()
  ElementCallAsyncFunc (element, *user_data)
  ElementForeachPadFunc (element, pad, *user_data)
  IteratorCopyFunction (it, copy)
  IteratorFoldFunction (item, ret, *user_data)
  IteratorForeachFunction (item, *user_data)
  IteratorFreeFunction (it)
  IteratorItemFunction (it, item)
  IteratorNextFunction (it, result)
  IteratorResyncFunction (it)
  LogFunction (category, level, file, function, line, object, message, *user_data)
  MemoryCopyFunction (mem, offset, size)
  MemoryIsSpanFunction (mem1, mem2, offset)
  MemoryMapFullFunction (mem, info, maxsize)
  MemoryMapFunction (mem, maxsize, flags)
  MemoryShareFunction (mem, offset, size)
  MemoryUnmapFullFunction (mem, info)
  MemoryUnmapFunction (mem)
  MetaFreeFunction (meta, buffer)
  MetaInitFunction (meta, params, buffer)
  MetaTransformFunction (transbuf, meta, buffer, type, data)
  MiniObjectDisposeFunction (obj)
  MiniObjectFreeFunction (obj)
  MiniObjectNotify (user_data, obj)
  PadActivateFunction (pad, parent)
  PadActivateModeFunction (pad, parent, mode, active)
  PadChainFunction (pad, parent, buffer)
  PadChainListFunction (pad, parent, list)
  PadEventFullFunction (pad, parent, event)
  PadEventFunction (pad, parent, event)
  PadForwardFunction (pad, *user_data)
  PadGetRangeFunction (pad, parent, offset, length, buffer)
  PadIterIntLinkFunction (pad, parent)
  PadLinkFunction (pad, parent, peer)
  PadProbeCallback (pad, info, *user_data)
  PadQueryFunction (pad, parent, query)
  PadStickyEventsForeachFunction (pad, event, *user_data)
  PadUnlinkFunction (pad, parent)
  PluginFeatureFilter (feature, *user_data)
  PluginFilter (plugin, *user_data)
  PluginInitFullFunc (plugin, *user_data)
  PluginInitFunc (plugin)
  PromiseChangeFunc (promise, *user_data)
  StructureFilterMapFunc (field_id, value, *user_data)
  StructureForeachFunc (field_id, value, *user_data)
  StructureMapFunc (field_id, value, *user_data)
  TagForeachFunc (list, tag, *user_data)
  TagMergeFunc (dest, src)
  TaskFunction (*user_data)
  TaskPoolFunction (*user_data)
  TaskThreadFunc (task, thread, *user_data)
  TypeFindFunction (find, *user_data)
  ValueCompareFunc (value1, value2)
  ValueDeserializeFunc (dest, s)
  ValueSerializeFunc (value1)

Details

Gst.BufferForeachMetaFunc(buffer, *user_data)
Parameters:
Returns:

False when Gst.Buffer.foreach_meta() should stop

meta:a pointer to a Gst.Meta

Return type:

(bool, meta: Gst.Meta or None)

A function that will be called from Gst.Buffer.foreach_meta(). The meta field will point to a the reference of the meta.

buffer should not be modified from this callback.

When this function returns True, the next meta will be returned. When False is returned, Gst.Buffer.foreach_meta() will return.

When meta is set to None, the item will be removed from the buffer.

Gst.BufferListFunc(idx, *user_data)
Parameters:
Returns:

False when Gst.BufferList.foreach() should stop

buffer:pointer the buffer

Return type:

(bool, buffer: Gst.Buffer or None)

A function that will be called from Gst.BufferList.foreach(). The buffer field will point to a the reference of the buffer at idx.

When this function returns True, the next buffer will be returned. When False is returned, Gst.BufferList.foreach() will return.

When buffer is set to None, the item will be removed from the bufferlist. When buffer has been made writable, the new buffer reference can be assigned to buffer. This function is responsible for unreffing the old buffer when removing or modifying.

Gst.BusFunc(bus, message, *user_data)
Parameters:
Returns:

False if the event source should be removed.
Return type:

bool

Specifies the type of function passed to Gst.Bus.add_watch() or Gst.Bus.add_watch(), which is called from the mainloop when a message is available on the bus.

The message passed to the function will be unreffed after execution of this function so it should not be freed in the function.

Note that this function is used as a GLib.SourceFunc which means that returning False will remove the GLib.Source from the mainloop.

Gst.BusSyncHandler(bus, message, *user_data)
Parameters:
Returns:

Gst.BusSyncReply stating what to do with the message
Return type:

Gst.BusSyncReply

Handler will be invoked synchronously, when a new message has been injected into the bus. This function is mostly used internally. Only one sync handler can be attached to a given bus.

If the handler returns Gst.BusSyncReply.DROP, it should unref the message, else the message should not be unreffed by the sync handler.

Gst.CapsFilterMapFunc(features, structure, *user_data)
Parameters:
Returns:

True if the features and structure should be preserved, False if it should be removed.
Return type:

bool

A function that will be called in Gst.Caps.filter_and_map_in_place(). The function may modify features and structure, and both will be removed from the caps if False is returned.

Gst.CapsForeachFunc(features, structure, *user_data)
Parameters:
Returns:

True if the foreach operation should continue, False if the foreach operation should stop with False.
Return type:

bool

A function that will be called in Gst.Caps.foreach(). The function may not modify features or structure.

New in version 1.6.

Gst.CapsMapFunc(features, structure, *user_data)
Parameters:
Returns:

True if the map operation should continue, False if the map operation should stop with False.
Return type:

bool

A function that will be called in Gst.Caps.map_in_place(). The function may modify features and structure.

Gst.ClockCallback(clock, time, id, *user_data)
Parameters:
Returns:

True or False (currently unused)
Return type:

bool

The function prototype of the callback.

Gst.ControlBindingConvert(binding, src_value, dest_value)
Parameters:

FIXME(2.0): remove, this is unused

Gst.ControlSourceGetValue(self, timestamp, value)
Parameters:
Returns:

True if the value was successfully calculated.
Return type:

bool

Function for returning a value for a given timestamp.

Gst.ControlSourceGetValueArray(self, timestamp, interval, n_values, values)
Parameters:
  • self (Gst.ControlSource) – the Gst.ControlSource instance
  • timestamp (int) – timestamp for which a value should be calculated
  • interval (int) – the time spacing between subsequent values
  • n_values (int) – the number of values
  • values (float) – array to put control-values in
Returns:

True if the values were successfully calculated.
Return type:

bool

Function for returning an array of values for starting at a given timestamp.

Gst.DebugFuncPtr()

we define this to avoid a compiler warning regarding a cast from a function pointer to a void pointer (see https://bugzilla.gnome.org/show_bug.cgi?id=309253)

Gst.ElementCallAsyncFunc(element, *user_data)
Parameters:
  • element (Gst.Element) – The Gst.Element this function has been called against
  • user_data (object or None) – Data passed in the function where that callback has been passed

Callback prototype used in Gst.Element.call_async

Gst.ElementForeachPadFunc(element, pad, *user_data)
Parameters:
Returns:

False to stop iterating pads, True to continue
Return type:

bool

Function called for each pad when using Gst.Element.foreach_sink_pad(), Gst.Element.foreach_src_pad(), or Gst.Element.foreach_pad().

New in version 1.14.

Gst.IteratorCopyFunction(it, copy)
Parameters:

This function will be called when creating a copy of it and should create a copy of all custom iterator fields or increase their reference counts.

Gst.IteratorFoldFunction(item, ret, *user_data)
Parameters:
Returns:

True if the fold should continue, False if it should stop.
Return type:

bool

A function to be passed to Gst.Iterator.fold().

Gst.IteratorForeachFunction(item, *user_data)
Parameters:

A function that is called by Gst.Iterator.foreach() for every element.

Gst.IteratorFreeFunction(it)
Parameters:it (Gst.Iterator) – the iterator

This function will be called when the iterator is freed.

Implementors of a Gst.Iterator should implement this function and pass it to the constructor of the custom iterator. The function will be called with the iterator lock held.

Gst.IteratorItemFunction(it, item)
Parameters:
Returns:

the result of the operation.
Return type:

Gst.IteratorItem

The function that will be called after the next item of the iterator has been retrieved. This function can be used to skip items or stop the iterator.

The function will be called with the iterator lock held.

Gst.IteratorNextFunction(it, result)
Parameters:
Returns:

the result of the operation.
Return type:

Gst.IteratorResult

The function that will be called when the next element of the iterator should be retrieved.

Implementors of a Gst.Iterator should implement this function and pass it to the constructor of the custom iterator. The function will be called with the iterator lock held.

Gst.IteratorResyncFunction(it)
Parameters:it (Gst.Iterator) – the iterator

This function will be called whenever a concurrent update happened to the iterated datastructure. The implementor of the iterator should restart the iterator from the beginning and clean up any state it might have.

Implementors of a Gst.Iterator should implement this function and pass it to the constructor of the custom iterator. The function will be called with the iterator lock held.

Gst.LogFunction(category, level, file, function, line, object, message, *user_data)
Parameters:

Function prototype for a logging function that can be registered with Gst.debug_add_log_function(). Use G_GNUC_NO_INSTRUMENT on that function.

Gst.MemoryCopyFunction(mem, offset, size)
Parameters:
Returns:

a new Gst.Memory object wrapping a copy of the requested region in mem.
Return type:

Gst.Memory

Copy size bytes from mem starting at offset and return them wrapped in a new Gst.Memory object. If size is set to -1, all bytes starting at offset are copied.

Gst.MemoryIsSpanFunction(mem1, mem2, offset)
Parameters:
Returns:

True if mem1 and mem2 are in contiguous memory.
Return type:

bool

Check if mem1 and mem2 occupy contiguous memory and return the offset of mem1 in the parent buffer in offset.

Gst.MemoryMapFullFunction(mem, info, maxsize)
Parameters:
Returns:

a pointer to memory of which at least maxsize bytes can be accessed according to the access pattern in info’s flags.
Return type:

object or None

Get the memory of mem that can be accessed according to the mode specified in info’s flags. The function should return a pointer that contains at least maxsize bytes.

Gst.MemoryMapFunction(mem, maxsize, flags)
Parameters:
Returns:

a pointer to memory of which at least maxsize bytes can be accessed according to the access pattern in flags.
Return type:

object or None

Get the memory of mem that can be accessed according to the mode specified in flags. The function should return a pointer that contains at least maxsize bytes.

Gst.MemoryShareFunction(mem, offset, size)
Parameters:
Returns:

a new Gst.Memory object sharing the requested region in mem.
Return type:

Gst.Memory

Share size bytes from mem starting at offset and return them wrapped in a new Gst.Memory object. If size is set to -1, all bytes starting at offset are shared. This function does not make a copy of the bytes in mem.

Gst.MemoryUnmapFullFunction(mem, info)
Parameters:

Release the pointer previously retrieved with Gst.Memory.map() with info.

Gst.MemoryUnmapFunction(mem)
Parameters:mem (Gst.Memory) – a Gst.Memory

Release the pointer previously retrieved with Gst.Memory.map().

Gst.MetaFreeFunction(meta, buffer)
Parameters:

Function called when meta is freed in buffer.

Gst.MetaInitFunction(meta, params, buffer)
Parameters:
Return type:

bool

Function called when meta is initialized in buffer.

Gst.MetaTransformFunction(transbuf, meta, buffer, type, data)
Parameters:
Returns:

True if the transform could be performed
Return type:

bool

Function called for each meta in buffer as a result of performing a transformation on transbuf. Additional type specific transform data is passed to the function as data.

Implementations should check the type of the transform and parse additional type specific fields in data that should be used to update the metadata on transbuf.

Gst.MiniObjectDisposeFunction(obj)
Parameters:obj (Gst.MiniObject) – MiniObject to dispose
Returns:True if the object should be cleaned up.
Return type:bool

Function prototype for when a miniobject has lost its last refcount. Implementation of the mini object are allowed to revive the passed object by doing a gst_mini_object_ref(). If the object is not revived after the dispose function, the function should return True and the memory associated with the object is freed.

Gst.MiniObjectFreeFunction(obj)
Parameters:obj (Gst.MiniObject) – MiniObject to free

Virtual function prototype for methods to free resources used by mini-objects.

Gst.MiniObjectNotify(user_data, obj)
Parameters:
  • user_data (object or None) – data that was provided when the notify was added
  • obj (Gst.MiniObject) – the mini object

A Gst.MiniObjectNotify function can be added to a mini object as a callback that gets triggered when gst_mini_object_unref() drops the last ref and obj is about to be freed.

Gst.PadActivateFunction(pad, parent)
Parameters:
Returns:

True if the pad could be activated.
Return type:

bool

This function is called when the pad is activated during the element READY to PAUSED state change. By default this function will call the activate function that puts the pad in push mode but elements can override this function to activate the pad in pull mode if they wish.

Gst.PadActivateModeFunction(pad, parent, mode, active)
Parameters:
Returns:

True if the pad could be activated or deactivated.
Return type:

bool

The prototype of the push and pull activate functions.

Gst.PadChainFunction(pad, parent, buffer)
Parameters:
Returns:

Gst.FlowReturn.OK for success
Return type:

Gst.FlowReturn

A function that will be called on sinkpads when chaining buffers. The function typically processes the data contained in the buffer and either consumes the data or passes it on to the internally linked pad(s).

The implementer of this function receives a refcount to buffer and should gst_buffer_unref() when the buffer is no longer needed.

When a chain function detects an error in the data stream, it must post an error on the bus and return an appropriate Gst.FlowReturn value.

Gst.PadChainListFunction(pad, parent, list)
Parameters:
Returns:

Gst.FlowReturn.OK for success
Return type:

Gst.FlowReturn

A function that will be called on sinkpads when chaining buffer lists. The function typically processes the data contained in the buffer list and either consumes the data or passes it on to the internally linked pad(s).

The implementer of this function receives a refcount to list and should gst_buffer_list_unref() when the list is no longer needed.

When a chainlist function detects an error in the data stream, it must post an error on the bus and return an appropriate Gst.FlowReturn value.

Gst.PadEventFullFunction(pad, parent, event)
Parameters:
Returns:

Gst.FlowReturn.OK if the event was handled properly, or any other Gst.FlowReturn dependent on downstream state.
Return type:

Gst.FlowReturn

Function signature to handle an event for the pad.

This variant is for specific elements that will take into account the last downstream flow return (from a pad push), in which case they can return it.

New in version 1.8.

Gst.PadEventFunction(pad, parent, event)
Parameters:
Returns:

True if the pad could handle the event.
Return type:

bool

Function signature to handle an event for the pad.

Gst.PadForwardFunction(pad, *user_data)
Parameters:
Returns:

True if the dispatching procedure has to be stopped.
Return type:

bool

A forward function is called for all internally linked pads, see Gst.Pad.forward().

Gst.PadGetRangeFunction(pad, parent, offset, length, buffer)
Parameters:
  • pad (Gst.Pad) – the src Gst.Pad to perform the getrange on.
  • parent (Gst.Object or None) – the parent of pad. If the Gst.PadFlags.NEED_PARENT flag is set, parent is guaranteed to be not-None and remain valid during the execution of this function.
  • offset (int) – the offset of the range
  • length (int) – the length of the range
  • buffer (Gst.Buffer) – a memory location to hold the result buffer, cannot be None.
Returns:

Gst.FlowReturn.OK for success and a valid buffer in buffer. Any other return value leaves buffer undefined.
Return type:

Gst.FlowReturn

This function will be called on source pads when a peer element request a buffer at the specified offset and length. If this function returns Gst.FlowReturn.OK, the result buffer will be stored in buffer. The contents of buffer is invalid for any other return value.

This function is installed on a source pad with gst_pad_set_getrange_function() and can only be called on source pads after they are successfully activated with Gst.Pad.activate_mode() with the Gst.PadMode.PULL.

offset and length are always given in byte units. offset must normally be a value between 0 and the length in bytes of the data available on pad. The length (duration in bytes) can be retrieved with a Gst.QueryType.DURATION or with a Gst.QueryType.SEEKING.

Any offset larger or equal than the length will make the function return Gst.FlowReturn.EOS, which corresponds to EOS. In this case buffer does not contain a valid buffer.

The buffer size of buffer will only be smaller than length when offset is near the end of the stream. In all other cases, the size of buffer must be exactly the requested size.

It is allowed to call this function with a 0 length and valid offset, in which case buffer will contain a 0-sized buffer and the function returns Gst.FlowReturn.OK.

When this function is called with a -1 offset, the sequentially next buffer of length length in the stream is returned.

When this function is called with a -1 length, a buffer with a default optimal length is returned in buffer. The length might depend on the value of offset.

Gst.PadIterIntLinkFunction(pad, parent)
Parameters:
Returns:

a new Gst.Iterator that will iterate over all pads that are linked to the given pad on the inside of the parent element.

the caller must call Gst.Iterator.free() after usage.
Return type:

Gst.Iterator

The signature of the internal pad link iterator function.

Gst.PadLinkFunction(pad, parent, peer)
Parameters:
Returns:

the result of the link with the specified peer.
Return type:

Gst.PadLinkReturn

Function signature to handle a new link on the pad.

Gst.PadProbeCallback(pad, info, *user_data)
Parameters:
Returns:

a Gst.PadProbeReturn
Return type:

Gst.PadProbeReturn

Callback used by Gst.Pad.add_probe(). Gets called to notify about the current blocking type.

The callback is allowed to modify the data pointer in info.

Gst.PadQueryFunction(pad, parent, query)
Parameters:
Returns:

True if the query could be performed.
Return type:

bool

The signature of the query function.

Gst.PadStickyEventsForeachFunction(pad, event, *user_data)
Parameters:
Returns:

True if the iteration should continue
Return type:

bool

Callback used by Gst.Pad.sticky_events_foreach().

When this function returns True, the next event will be returned. When False is returned, Gst.Pad.sticky_events_foreach() will return.

When event is set to None, the item will be removed from the list of sticky events. event can be replaced by assigning a new reference to it. This function is responsible for unreffing the old event when removing or modifying.

Gst.PadUnlinkFunction(pad, parent)
Parameters:

Function signature to handle a unlinking the pad prom its peer.

The pad’s lock is already held when the unlink function is called, so most pad functions cannot be called from within the callback.

Gst.PluginFeatureFilter(feature, *user_data)
Parameters:
Returns:

True for a positive match, False otherwise
Return type:

bool

A function that can be used with e.g. Gst.Registry.feature_filter() to get a list of pluginfeature that match certain criteria.

Gst.PluginFilter(plugin, *user_data)
Parameters:
Returns:

True for a positive match, False otherwise
Return type:

bool

A function that can be used with e.g. Gst.Registry.plugin_filter() to get a list of plugins that match certain criteria.

Gst.PluginInitFullFunc(plugin, *user_data)
Parameters:
Returns:

True if plugin initialised successfully
Return type:

bool

A plugin should provide a pointer to a function of either Gst.PluginInitFunc or this type in the plugin_desc struct. The function will be called by the loader at startup. One would then register each Gst.PluginFeature. This version allows user data to be passed to init function (useful for bindings).

Gst.PluginInitFunc(plugin)
Parameters:plugin (Gst.Plugin) – The plugin object
Returns:True if plugin initialised successfully
Return type:bool

A plugin should provide a pointer to a function of this type in the plugin_desc struct. This function will be called by the loader at startup. One would then register each Gst.PluginFeature.

Gst.PromiseChangeFunc(promise, *user_data)
Parameters:

New in version 1.14.

Gst.StructureFilterMapFunc(field_id, value, *user_data)
Parameters:
Returns:

True if the field should be preserved, False if it should be removed.
Return type:

bool

A function that will be called in Gst.Structure.filter_and_map_in_place(). The function may modify value, and the value will be removed from the structure if False is returned.

Gst.StructureForeachFunc(field_id, value, *user_data)
Parameters:
Returns:

True if the foreach operation should continue, False if the foreach operation should stop with False.
Return type:

bool

A function that will be called in Gst.Structure.foreach(). The function may not modify value.

Gst.StructureMapFunc(field_id, value, *user_data)
Parameters:
Returns:

True if the map operation should continue, False if the map operation should stop with False.
Return type:

bool

A function that will be called in Gst.Structure.map_in_place(). The function may modify value.

Gst.TagForeachFunc(list, tag, *user_data)
Parameters:

A function that will be called in Gst.TagList.foreach(). The function may not modify the tag list.

Gst.TagMergeFunc(dest, src)
Parameters:

A function for merging multiple values of a tag used when registering tags.

Gst.TaskFunction(*user_data)
Parameters:user_data (object or None) – user data passed to the function

A function that will repeatedly be called in the thread created by a Gst.Task.

Gst.TaskPoolFunction(*user_data)
Parameters:user_data (object or None) – user data for the task function

Task function, see Gst.TaskPool.push().

Gst.TaskThreadFunc(task, thread, *user_data)
Parameters:

Custom Gst.Task thread callback functions that can be installed.

Gst.TypeFindFunction(find, *user_data)
Parameters:

A function that will be called by typefinding.

Gst.ValueCompareFunc(value1, value2)
Parameters:
Returns:

one of Gst.VALUE_LESS_THAN, Gst.VALUE_EQUAL, Gst.VALUE_GREATER_THAN or Gst.VALUE_UNORDERED
Return type:

int

Used together with Gst.value_compare() to compare GObject.Value items.

Gst.ValueDeserializeFunc(dest, s)
Parameters:
Returns:

True for success
Return type:

bool

Used by Gst.value_deserialize() to parse a non-binary form into the GObject.Value.

Gst.ValueSerializeFunc(value1)
Parameters:value1 (GObject.Value) – a GObject.Value
Returns:the string representation of the value
Return type:str

Used by Gst.value_serialize() to obtain a non-binary form of the GObject.Value.

Free-function: GLib.free