Object#

class Object(**properties: Any)#

Superclasses: InitiallyUnowned, Object

Subclasses: Allocator, BufferPool, Bus, Clock, ControlBinding, ControlSource, Device, DeviceMonitor, DeviceProvider, Element, Pad, PadTemplate, Plugin, PluginFeature, Registry, Stream, StreamCollection, Task, TaskPool, Tracer, TracerRecord

Object provides a root for the object hierarchy tree filed in by the GStreamer library. It is currently a thin wrapper on top of InitiallyUnowned. It is an abstract class that is not very usable on its own.

Object gives us basic refcounting, parenting functionality and locking. Most of the functions are just extended for special GStreamer needs and can be found under the same name in the base class of Object which is Object (e.g. ref() becomes ref()).

Since Object derives from InitiallyUnowned, it also inherits the floating reference. Be aware that functions such as add() and add_pad() take ownership of the floating reference.

In contrast to Object instances, Object adds a name property. The functions set_name() and get_name() are used to set/get the name of the object.

controlled properties#

Controlled properties offers a lightweight way to adjust gobject properties over stream-time. It works by using time-stamped value pairs that are queued for element-properties. At run-time the elements continuously pull value changes for the current stream-time.

What needs to be changed in a Element? Very little - it is just two steps to make a plugin controllable!

  • mark gobject-properties paramspecs that make sense to be controlled,

    by GST_PARAM_CONTROLLABLE.

  • when processing data (get, chain, loop function) at the beginning call

    gst_object_sync_values(element,timestamp). This will make the controller update all GObject properties that are under its control with the current values based on the timestamp.

What needs to be done in applications? Again it’s not a lot to change.

  • create a ControlSource.

    csource = gst_interpolation_control_source_new (); g_object_set (csource, “mode”, GST_INTERPOLATION_MODE_LINEAR, NULL);

  • Attach the ControlSource on the controller to a property.

    gst_object_add_control_binding (object, gst_direct_control_binding_new (object, “prop1”, csource));

  • Set the control values

    gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1); gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2);

  • start your pipeline

Methods#

class Object
add_control_binding(binding: ControlBinding) → bool#

Attach the ControlBinding to the object. If there already was a ControlBinding for this property it will be replaced.

The object’s reference count will be incremented, and any floating reference will be removed (see ref_sink())

Parameters:

binding – the ControlBinding that should be used

classmethod check_uniqueness(name: str) → bool#

Checks to see if there is any object named name in list. This function does not do any locking of any kind. You might want to protect the provided list with the lock of the owner of the list. This function will lock each Object in the list to compare the name, so be careful when passing a list with a locked object.

Parameters:

name – the name to search for

classmethod default_deep_notify(orig: Object, pspec: ParamSpec, excluded_props: list[str] | None = None) → None#

A default deep_notify signal callback for an object. The user data should contain a pointer to an array of strings that should be excluded from the notify. The default handler will print the new value of the property using g_print.

MT safe. This function grabs and releases object's LOCK for getting its

path string.

Parameters:

  • orig – a Object that initiated the notify.

  • pspec – a ParamSpec of the property.

  • excluded_props – a set of user-specified properties to exclude or None to show all changes.

default_error(error: GError, debug: str | None = None) → None#

A default error function that uses printerr() to display the error message and the optional debug string..

The default handler will simply print the error string using g_print.

Parameters:

  • error – the GError.

  • debug – an additional debug information string, or None

do_deep_notify(self, orig: Object, pspec: ParamSpec) → None#
Parameters:

  • orig

  • pspec

get_control_binding(property_name: str) → ControlBinding | None#

Gets the corresponding ControlBinding for the property. This should be unreferenced again after use.

Parameters:

property_name – name of the property

get_control_rate() → int#

Obtain the control-rate for this object. Audio processing Element objects will use this rate to sub-divide their processing loop and call sync_values() in between. The length of the processing segment should be up to control-rate nanoseconds.

If the object is not under property control, this will return CLOCK_TIME_NONE. This allows the element to avoid the sub-dividing.

The control-rate is not expected to change if the element is in PAUSED or PLAYING.

get_g_value_array(property_name: str, timestamp: int, interval: int, values: list[Value]) → bool#

Gets a number of Value for the given controlled property starting at the requested time. The array values need to hold enough space for n_values of Value.

This function is useful if one wants to e.g. draw a graph of the control curve or apply a control curve sample by sample.

Parameters:

  • property_name – the name of the property to get

  • timestamp – the time that should be processed

  • interval – the time spacing between subsequent values

  • values – array to put control-values in

get_name() → str | None#

Returns a copy of the name of object. Caller should free() the return value after usage. For a nameless object, this returns None, which you can safely free() as well.

Free-function: g_free

get_parent() → Object | None#

Returns the parent of object. This function increases the refcount of the parent object so you should unref() it after usage.

get_path_string() → str#

Generates a string describing the path of object in the object hierarchy. Only useful (or used) for debugging.

Free-function: g_free

get_value(property_name: str, timestamp: int) → Value | None#

Gets the value for the given controlled property at the requested time.

Parameters:

  • property_name – the name of the property to get

  • timestamp – the time the control-change should be read from

has_active_control_bindings() → bool#

Check if the object has active controlled properties.

has_ancestor(ancestor: Object) → bool#

Check if object has an ancestor ancestor somewhere up in the hierarchy. One can e.g. check if a Element is inside a Pipeline.

Deprecated since version Unknown: Use has_as_ancestor() instead.

MT safe. Grabs and releases object's locks.

Parameters:

ancestor – a Object to check as ancestor

has_as_ancestor(ancestor: Object) → bool#

Check if object has an ancestor ancestor somewhere up in the hierarchy. One can e.g. check if a Element is inside a Pipeline.

Parameters:

ancestor – a Object to check as ancestor

has_as_parent(parent: Object) → bool#

Check if parent is the parent of object. E.g. a Element can check if it owns a given Pad.

Added in version 1.6.

Parameters:

parent – a Object to check as parent

remove_control_binding(binding: ControlBinding) → bool#

Removes the corresponding ControlBinding. If it was the last ref of the binding, it will be disposed.

Parameters:

binding – the binding

classmethod replace(newobj: Object | None = None) → tuple[bool, Object | None]#

Atomically modifies a pointer to point to a new object. The reference count of oldobj is decreased and the reference count of newobj is increased.

Either newobj and the value pointed to by oldobj may be None.

Parameters:

newobj – a new Object

set_control_binding_disabled(property_name: str, disabled: bool) → None#

This function is used to disable the control bindings on a property for some time, i.e. sync_values() will do nothing for the property.

Parameters:

  • property_name – property to disable

  • disabled – boolean that specifies whether to disable the controller or not.

set_control_bindings_disabled(disabled: bool) → None#

This function is used to disable all controlled properties of the object for some time, i.e. sync_values() will do nothing.

Parameters:

disabled – boolean that specifies whether to disable the controller or not.

set_control_rate(control_rate: int) → None#

Change the control-rate for this object. Audio processing Element objects will use this rate to sub-divide their processing loop and call sync_values() in between. The length of the processing segment should be up to control-rate nanoseconds.

The control-rate should not change if the element is in PAUSED or PLAYING.

Parameters:

control_rate – the new control-rate in nanoseconds.

set_name(name: str | None = None) → bool#

Sets the name of object, or gives object a guaranteed unique name (if name is None). This function makes a copy of the provided name, so the caller retains ownership of the name it sent.

Parameters:

name – new name of object

set_parent(parent: Object) → bool#

Sets the parent of object to parent. The object’s reference count will be incremented, and any floating reference will be removed (see ref_sink()).

Parameters:

parent – new parent of object

suggest_next_sync() → int#

Returns a suggestion for timestamps where buffers should be split to get best controller results.

sync_values(timestamp: int) → bool#

Sets the properties of the object, according to the ControlSource that (maybe) handle them and for the given timestamp.

If this function fails, it is most likely the application developers fault. Most probably the control sources are not setup correctly.

Parameters:

timestamp – the time that should be processed

unparent() → None#

Clear the parent of object, removing the associated reference. This function decreases the refcount of object.

MT safe. Grabs and releases object's lock.

Properties#

class Object
props.name: str#
props.parent: Object#

The parent of the object. Please note, that when changing the ‘parent’ property, we don’t emit Object::notify and Object::deep-notify signals due to locking issues. In some cases one can use Bin::element-added or Bin::element-removed signals on the parent to achieve a similar effect.

Signals#

class Object.signals
deep_notify(prop_object: Object, prop: ParamSpec) → None#

The type of the None singleton.

Parameters:

  • prop_object – the object that originated the signal

  • prop – the property that changed

Virtual Methods#

class Object
do_deep_notify(orig: Object, pspec: ParamSpec) → None#

The type of the None singleton.

Parameters:

  • orig

  • pspec

Fields#

class Object
control_bindings#
control_rate#
flags#

Flags for this object

last_sync#
lock#

Object LOCK

name#

The name of the object

object#
parent#

This object’s parent, weak ref