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

check_uniqueness(list: list[Object], 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:

• list – a list of Object to check through

• name – the name to search for

default_deep_notify(object: Object, orig: Object, pspec: ParamSpec, excluded_props: Sequence[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:

• object – the Object that signalled the notify.

• 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

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: Sequence[Any]) → 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) → Any | 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

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

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 deep notify signal is used to be notified of property changes. It is typically attached to the toplevel bin to receive notifications from all the elements contained in that bin.

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

default signal handler

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