:right-sidebar: True Object =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Object(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Subclasses: :class:`~gi.repository.Gst.Allocator`, :class:`~gi.repository.Gst.BufferPool`, :class:`~gi.repository.Gst.Bus`, :class:`~gi.repository.Gst.Clock`, :class:`~gi.repository.Gst.ControlBinding`, :class:`~gi.repository.Gst.ControlSource`, :class:`~gi.repository.Gst.Device`, :class:`~gi.repository.Gst.DeviceMonitor`, :class:`~gi.repository.Gst.DeviceProvider`, :class:`~gi.repository.Gst.Element`, :class:`~gi.repository.Gst.Pad`, :class:`~gi.repository.Gst.PadTemplate`, :class:`~gi.repository.Gst.Plugin`, :class:`~gi.repository.Gst.PluginFeature`, :class:`~gi.repository.Gst.Registry`, :class:`~gi.repository.Gst.Stream`, :class:`~gi.repository.Gst.StreamCollection`, :class:`~gi.repository.Gst.Task`, :class:`~gi.repository.Gst.TaskPool`, :class:`~gi.repository.Gst.Tracer`, :class:`~gi.repository.Gst.TracerRecord` :obj:`~gi.repository.Gst.Object` provides a root for the object hierarchy tree filed in by the GStreamer library. It is currently a thin wrapper on top of :obj:`~gi.repository.GObject.InitiallyUnowned`\. It is an abstract class that is not very usable on its own. :obj:`~gi.repository.Gst.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 :obj:`~gi.repository.Gst.Object` which is :obj:`~gi.repository.GObject.Object` (e.g. :func:`~gi.repository.GObject.GObject.Object.ref` becomes :func:`~gi.repository.Gst.Object.ref`). Since :obj:`~gi.repository.Gst.Object` derives from :obj:`~gi.repository.GObject.InitiallyUnowned`\, it also inherits the floating reference. Be aware that functions such as :func:`~gi.repository.Gst.Bin.add` and :func:`~gi.repository.Gst.Element.add_pad` take ownership of the floating reference. In contrast to :obj:`~gi.repository.GObject.Object` instances, :obj:`~gi.repository.Gst.Object` adds a name property. The functions :func:`~gi.repository.Gst.Object.set_name` and :func:`~gi.repository.Gst.Object.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 :obj:`~gi.repository.Gst.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 :obj:`~gi.repository.Gst.ControlSource`\. csource = gst_interpolation_control_source_new (); g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL); - Attach the :obj:`~gi.repository.Gst.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 ------- .. rst-class:: interim-class .. class:: Object :no-index: .. method:: add_control_binding(binding: ~gi.repository.Gst.ControlBinding) -> bool Attach the :obj:`~gi.repository.Gst.ControlBinding` to the object. If there already was a :obj:`~gi.repository.Gst.ControlBinding` for this property it will be replaced. The object's reference count will be incremented, and any floating reference will be removed (see :func:`~gi.repository.Gst.Object.ref_sink`) :param binding: the :obj:`~gi.repository.Gst.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 :obj:`~gi.repository.Gst.Object` in the list to compare the name, so be careful when passing a list with a locked object. :param name: the name to search for .. classmethod:: default_deep_notify(orig: ~gi.repository.Gst.Object, pspec: ~gi.overrides.GObject.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. :param orig: a :obj:`~gi.repository.Gst.Object` that initiated the notify. :param pspec: a :obj:`~gi.repository.GObject.ParamSpec` of the property. :param excluded_props: a set of user-specified properties to exclude or :const:`None` to show all changes. .. method:: default_error(error: ~gi.repository.GLib.GError, debug: str | None = None) -> None A default error function that uses :func:`~gi.repository.GLib.printerr` to display the error message and the optional debug string.. The default handler will simply print the error string using g_print. :param error: the GError. :param debug: an additional debug information string, or :const:`None` .. method:: do_deep_notify(self, orig: ~gi.repository.Gst.Object, pspec: ~gi.overrides.GObject.ParamSpec) -> None :param orig: :param pspec: .. method:: get_control_binding(property_name: str) -> ~gi.repository.Gst.ControlBinding | None Gets the corresponding :obj:`~gi.repository.Gst.ControlBinding` for the property. This should be unreferenced again after use. :param property_name: name of the property .. method:: get_control_rate() -> int Obtain the control-rate for this ``object``\. Audio processing :obj:`~gi.repository.Gst.Element` objects will use this rate to sub-divide their processing loop and call :func:`~gi.repository.Gst.Object.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 :const:`~gi.repository.Gst.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 :const:`~gi.repository.Gst.State.PAUSED` or :const:`~gi.repository.Gst.State.PLAYING`. .. method:: get_g_value_array(property_name: str, timestamp: int, interval: int, values: list[~gi.repository.GObject.Value]) -> bool Gets a number of :obj:`~gi.repository.GObject.Value` for the given controlled property starting at the requested time. The array ``values`` need to hold enough space for ``n_values`` of :obj:`~gi.repository.GObject.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. :param property_name: the name of the property to get :param timestamp: the time that should be processed :param interval: the time spacing between subsequent values :param values: array to put control-values in .. method:: get_name() -> str | None Returns a copy of the name of ``object``\. Caller should :func:`~gi.repository.GLib.free` the return value after usage. For a nameless object, this returns :const:`None`, which you can safely :func:`~gi.repository.GLib.free` as well. Free-function: g_free .. method:: get_parent() -> ~gi.repository.Gst.Object | None Returns the parent of ``object``\. This function increases the refcount of the parent object so you should :func:`~gi.repository.Gst.Object.unref` it after usage. .. method:: 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 .. method:: get_value(property_name: str, timestamp: int) -> ~gi.repository.GObject.Value | None Gets the value for the given controlled property at the requested time. :param property_name: the name of the property to get :param timestamp: the time the control-change should be read from .. method:: has_active_control_bindings() -> bool Check if the ``object`` has active controlled properties. .. method:: has_ancestor(ancestor: ~gi.repository.Gst.Object) -> bool Check if ``object`` has an ancestor ``ancestor`` somewhere up in the hierarchy. One can e.g. check if a :obj:`~gi.repository.Gst.Element` is inside a :obj:`~gi.repository.Gst.Pipeline`\. .. deprecated:: Unknown Use :func:`~gi.repository.Gst.Object.has_as_ancestor` instead. MT safe. Grabs and releases ``object``\'s locks. :param ancestor: a :obj:`~gi.repository.Gst.Object` to check as ancestor .. method:: has_as_ancestor(ancestor: ~gi.repository.Gst.Object) -> bool Check if ``object`` has an ancestor ``ancestor`` somewhere up in the hierarchy. One can e.g. check if a :obj:`~gi.repository.Gst.Element` is inside a :obj:`~gi.repository.Gst.Pipeline`\. :param ancestor: a :obj:`~gi.repository.Gst.Object` to check as ancestor .. method:: has_as_parent(parent: ~gi.repository.Gst.Object) -> bool Check if ``parent`` is the parent of ``object``\. E.g. a :obj:`~gi.repository.Gst.Element` can check if it owns a given :obj:`~gi.repository.Gst.Pad`\. .. versionadded:: 1.6 :param parent: a :obj:`~gi.repository.Gst.Object` to check as parent .. method:: remove_control_binding(binding: ~gi.repository.Gst.ControlBinding) -> bool Removes the corresponding :obj:`~gi.repository.Gst.ControlBinding`\. If it was the last ref of the binding, it will be disposed. :param binding: the binding .. classmethod:: replace(newobj: ~gi.repository.Gst.Object | None = None) -> ~typing.Tuple[bool, ~gi.repository.Gst.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 :const:`None`. :param newobj: a new :obj:`~gi.repository.Gst.Object` .. method:: 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. :func:`~gi.repository.Gst.Object.sync_values` will do nothing for the property. :param property_name: property to disable :param disabled: boolean that specifies whether to disable the controller or not. .. method:: set_control_bindings_disabled(disabled: bool) -> None This function is used to disable all controlled properties of the ``object`` for some time, i.e. :func:`~gi.repository.Gst.Object.sync_values` will do nothing. :param disabled: boolean that specifies whether to disable the controller or not. .. method:: set_control_rate(control_rate: int) -> None Change the control-rate for this ``object``\. Audio processing :obj:`~gi.repository.Gst.Element` objects will use this rate to sub-divide their processing loop and call :func:`~gi.repository.Gst.Object.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 :const:`~gi.repository.Gst.State.PAUSED` or :const:`~gi.repository.Gst.State.PLAYING`. :param control_rate: the new control-rate in nanoseconds. .. method:: set_name(name: str | None = None) -> bool Sets the name of ``object``\, or gives ``object`` a guaranteed unique name (if ``name`` is :const:`None`). This function makes a copy of the provided name, so the caller retains ownership of the name it sent. :param name: new name of object .. method:: set_parent(parent: ~gi.repository.Gst.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 :func:`~gi.repository.Gst.Object.ref_sink`). :param parent: new parent of object .. method:: suggest_next_sync() -> int Returns a suggestion for timestamps where buffers should be split to get best controller results. .. method:: sync_values(timestamp: int) -> bool Sets the properties of the object, according to the :obj:`~gi.repository.Gst.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. :param timestamp: the time that should be processed .. method:: 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 ---------- .. rst-class:: interim-class .. class:: Object :no-index: .. attribute:: props.name :type: str .. attribute:: props.parent :type: ~gi.repository.Gst.Object The parent of the object. Please note, that when changing the 'parent' property, we don't emit :obj:`~gi.repository.GObject.Object`\::notify and :obj:`~gi.repository.Gst.Object`\::deep-notify signals due to locking issues. In some cases one can use :obj:`~gi.repository.Gst.Bin`\::element-added or :obj:`~gi.repository.Gst.Bin`\::element-removed signals on the parent to achieve a similar effect. Signals ------- .. rst-class:: interim-class .. class:: Object.signals :no-index: .. method:: deep_notify(prop_object: ~gi.repository.Gst.Object, prop: ~gi.overrides.GObject.ParamSpec) -> None The type of the None singleton. :param prop_object: the object that originated the signal :param prop: the property that changed Virtual Methods --------------- .. rst-class:: interim-class .. class:: Object :no-index: .. method:: do_deep_notify(orig: ~gi.repository.Gst.Object, pspec: ~gi.overrides.GObject.ParamSpec) -> None The type of the None singleton. :param orig: :param pspec: Fields ------ .. rst-class:: interim-class .. class:: Object :no-index: .. attribute:: control_bindings .. attribute:: control_rate .. attribute:: flags Flags for this object .. attribute:: last_sync .. attribute:: lock Object LOCK .. attribute:: name The name of the object .. attribute:: object .. attribute:: parent This object's parent, weak ref