:right-sidebar: True Clock =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Clock(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gst.Object`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Subclasses: :class:`~gi.repository.Gst.SystemClock` GStreamer uses a global clock to synchronize the plugins in a pipeline. Different clock implementations are possible by implementing this abstract base class or, more conveniently, by subclassing ``GstSystemClock``. The :obj:`~gi.repository.Gst.Clock` returns a monotonically increasing time with the method :func:`~gi.repository.Gst.Clock.get_time`. Its accuracy and base time depend on the specific clock implementation but time is always expressed in nanoseconds. Since the baseline of the clock is undefined, the clock time returned is not meaningful in itself, what matters are the deltas between two clock times. The time returned by a clock is called the absolute time. The pipeline uses the clock to calculate the running time. Usually all renderers synchronize to the global clock using the buffer timestamps, the ``GST_EVENT_SEGMENT`` events and the element's base time, see :obj:`~gi.repository.Gst.Pipeline`\. A clock implementation can support periodic and single shot clock notifications both synchronous and asynchronous. One first needs to create a :obj:`~gi.repository.Gst.ClockID` for the periodic or single shot notification using :func:`~gi.repository.Gst.Clock.new_single_shot_id` or :func:`~gi.repository.Gst.Clock.new_periodic_id`. To perform a blocking wait for the specific time of the :obj:`~gi.repository.Gst.ClockID` use :func:`~gi.repository.Gst.Clock.id_wait`. To receive a callback when the specific time is reached in the clock use :func:`~gi.repository.Gst.Clock.id_wait_async`. Both these calls can be interrupted with the :func:`~gi.repository.Gst.Clock.id_unschedule` call. If the blocking wait is unscheduled a return value of ``GST_CLOCK_UNSCHEDULED`` is returned. Periodic callbacks scheduled async will be repeatedly called automatically until they are unscheduled. To schedule a sync periodic callback, :func:`~gi.repository.Gst.Clock.id_wait` should be called repeatedly. The async callbacks can happen from any thread, either provided by the core or from a streaming thread. The application should be prepared for this. A :obj:`~gi.repository.Gst.ClockID` that has been unscheduled cannot be used again for any wait operation, a new :obj:`~gi.repository.Gst.ClockID` should be created and the old unscheduled one should be destroyed with :func:`~gi.repository.Gst.Clock.id_unref`. It is possible to perform a blocking wait on the same :obj:`~gi.repository.Gst.ClockID` from multiple threads. However, registering the same :obj:`~gi.repository.Gst.ClockID` for multiple async notifications is not possible, the callback will only be called for the thread registering the entry last. None of the wait operations unref the :obj:`~gi.repository.Gst.ClockID`\, the owner is responsible for unreffing the ids itself. This holds for both periodic and single shot notifications. The reason being that the owner of the :obj:`~gi.repository.Gst.ClockID` has to keep a handle to the :obj:`~gi.repository.Gst.ClockID` to unblock the wait on FLUSHING events or state changes and if the entry would be unreffed automatically, the handle might become invalid without any notification. These clock operations do not operate on the running time, so the callbacks will also occur when not in PLAYING state as if the clock just keeps on running. Some clocks however do not progress when the element that provided the clock is not PLAYING. When a clock has the ``GST_CLOCK_FLAG_CAN_SET_MASTER`` flag set, it can be slaved to another :obj:`~gi.repository.Gst.Clock` with :func:`~gi.repository.Gst.Clock.set_master`. The clock will then automatically be synchronized to this master clock by repeatedly sampling the master clock and the slave clock and recalibrating the slave clock with :func:`~gi.repository.Gst.Clock.set_calibration`. This feature is mostly useful for plugins that have an internal clock but must operate with another clock selected by the :obj:`~gi.repository.Gst.Pipeline`\. They can track the offset and rate difference of their internal clock relative to the master clock by using the :func:`~gi.repository.Gst.Clock.get_calibration` function. The master/slave synchronisation can be tuned with the :obj:`~gi.repository.Gst.Clock`\:timeout, :obj:`~gi.repository.Gst.Clock`\:window-size and :obj:`~gi.repository.Gst.Clock`\:window-threshold properties. The :obj:`~gi.repository.Gst.Clock`\:timeout property defines the interval to sample the master clock and run the calibration functions. :obj:`~gi.repository.Gst.Clock`\:window-size defines the number of samples to use when calibrating and :obj:`~gi.repository.Gst.Clock`\:window-threshold defines the minimum number of samples before the calibration is performed. Methods ------- .. rst-class:: interim-class .. class:: Clock :no-index: .. method:: add_observation(slave: int, master: int) -> ~typing.Tuple[bool, float] The time ``master`` of the master clock and the time ``slave`` of the slave clock are added to the list of observations. If enough observations are available, a linear regression algorithm is run on the observations and ``clock`` is recalibrated. If this functions returns :const:`True`, ``r_squared`` will contain the correlation coefficient of the interpolation. A value of 1.0 means a perfect regression was performed. This value can be used to control the sampling frequency of the master and slave clocks. :param slave: a time on the slave :param master: a time on the master .. method:: add_observation_unapplied(slave: int, master: int) -> ~typing.Tuple[bool, float, int, int, int, int] Add a clock observation to the internal slaving algorithm the same as :func:`~gi.repository.Gst.Clock.add_observation`, and return the result of the master clock estimation, without updating the internal calibration. The caller can then take the results and call :func:`~gi.repository.Gst.Clock.set_calibration` with the values, or some modified version of them. .. versionadded:: 1.6 :param slave: a time on the slave :param master: a time on the master .. method:: adjust_unlocked(internal: int) -> int Converts the given ``internal`` clock time to the external time, adjusting for the rate and reference time set with :func:`~gi.repository.Gst.Clock.set_calibration` and making sure that the returned time is increasing. This function should be called with the clock's OBJECT_LOCK held and is mainly used by clock subclasses. This function is the reverse of :func:`~gi.repository.Gst.Clock.unadjust_unlocked`. :param internal: a clock time .. method:: adjust_with_calibration(internal_target: int, cinternal: int, cexternal: int, cnum: int, cdenom: int) -> int Converts the given ``internal_target`` clock time to the external time, using the passed calibration parameters. This function performs the same calculation as :func:`~gi.repository.Gst.Clock.adjust_unlocked` when called using the current calibration parameters, but doesn't ensure a monotonically increasing result as :func:`~gi.repository.Gst.Clock.adjust_unlocked` does. Note: The ``clock`` parameter is unused and can be NULL .. versionadded:: 1.6 :param internal_target: a clock time :param cinternal: a reference internal time :param cexternal: a reference external time :param cnum: the numerator of the rate of the clock relative to its internal time :param cdenom: the denominator of the rate of the clock .. method:: do_change_resolution(self, old_resolution: int, new_resolution: int) -> int :param old_resolution: :param new_resolution: .. method:: do_get_internal_time(self) -> int .. method:: do_get_resolution(self) -> int .. method:: do_unschedule(self, entry: ~gi.repository.Gst.ClockEntry) -> None :param entry: .. method:: do_wait(self, entry: ~gi.repository.Gst.ClockEntry) -> ~typing.Tuple[~gi.repository.Gst.ClockReturn, int] :param entry: .. method:: do_wait_async(self, entry: ~gi.repository.Gst.ClockEntry) -> ~gi.repository.Gst.ClockReturn :param entry: .. method:: get_calibration() -> ~typing.Tuple[int, int, int, int] Gets the internal rate and reference time of ``clock``\. See :func:`~gi.repository.Gst.Clock.set_calibration` for more information. ``internal``\, ``external``\, ``rate_num``\, and ``rate_denom`` can be left :const:`None` if the caller is not interested in the values. .. method:: get_internal_time() -> int Gets the current internal time of the given clock. The time is returned unadjusted for the offset and the rate. .. method:: get_master() -> ~gi.repository.Gst.Clock | None Gets the master clock that ``clock`` is slaved to or :const:`None` when the clock is not slaved to any master clock. .. method:: get_resolution() -> int Gets the accuracy of the clock. The accuracy of the clock is the granularity of the values returned by :func:`~gi.repository.Gst.Clock.get_time`. .. method:: get_time() -> int Gets the current time of the given clock. The time is always monotonically increasing and adjusted according to the current offset and rate. .. method:: get_timeout() -> int Gets the amount of time that master and slave clocks are sampled. .. classmethod:: id_compare_func(id2: ~typing.Any = None) -> int Compares the two :obj:`~gi.repository.Gst.ClockID` instances. This function can be used as a GCompareFunc when sorting ids. :param id2: A :obj:`~gi.repository.Gst.ClockID` to compare with .. classmethod:: id_get_clock() -> ~gi.repository.Gst.Clock | None This function returns the underlying clock. .. versionadded:: 1.16 .. classmethod:: id_get_time() -> int Gets the time of the clock ID .. classmethod:: id_unschedule() -> None Cancels an outstanding request with ``id``\. This can either be an outstanding async notification or a pending sync notification. After this call, ``id`` cannot be used anymore to receive sync or async notifications, you need to create a new :obj:`~gi.repository.Gst.ClockID`\. .. classmethod:: id_uses_clock(clock: ~gi.repository.Gst.Clock) -> bool This function returns whether ``id`` uses ``clock`` as the underlying clock. ``clock`` can be NULL, in which case the return value indicates whether the underlying clock has been freed. If this is the case, the ``id`` is no longer usable and should be freed. .. versionadded:: 1.16 :param clock: a :obj:`~gi.repository.Gst.Clock` to compare against .. classmethod:: id_wait() -> ~typing.Tuple[~gi.repository.Gst.ClockReturn, int] Performs a blocking wait on ``id``\. ``id`` should have been created with :func:`~gi.repository.Gst.Clock.new_single_shot_id` or :func:`~gi.repository.Gst.Clock.new_periodic_id` and should not have been unscheduled with a call to :func:`~gi.repository.Gst.Clock.id_unschedule`. If the ``jitter`` argument is not :const:`None` and this function returns ``GST_CLOCK_OK`` or ``GST_CLOCK_EARLY``, it will contain the difference against the clock and the time of ``id`` when this method was called. Positive values indicate how late ``id`` was relative to the clock (in which case this function will return ``GST_CLOCK_EARLY``). Negative values indicate how much time was spent waiting on the clock before this function returned. .. classmethod:: id_wait_async(func: ~typing.Callable[[~gi.repository.Gst.Clock, int, ~typing.Any, ~typing.Any], bool], user_data: ~typing.Any = None) -> ~gi.repository.Gst.ClockReturn Registers a callback on the given :obj:`~gi.repository.Gst.ClockID` ``id`` with the given function and user_data. When passing a :obj:`~gi.repository.Gst.ClockID` with an invalid time to this function, the callback will be called immediately with a time set to :const:`~gi.repository.Gst.CLOCK_TIME_NONE`. The callback will be called when the time of ``id`` has been reached. The callback ``func`` can be invoked from any thread, either provided by the core or from a streaming thread. The application should be prepared for this. :param func: The callback function :param user_data: User data passed in the callback .. method:: is_synced() -> bool Checks if the clock is currently synced, by looking at whether :const:`~gi.repository.Gst.ClockFlags.NEEDS_STARTUP_SYNC` is set. .. versionadded:: 1.6 .. method:: new_periodic_id(start_time: int, interval: int) -> ~typing.Any Gets an ID from ``clock`` to trigger a periodic notification. The periodic notifications will start at time ``start_time`` and will then be fired with the given ``interval``\. :param start_time: the requested start time :param interval: the requested interval .. method:: new_single_shot_id(time: int) -> ~typing.Any Gets a :obj:`~gi.repository.Gst.ClockID` from ``clock`` to trigger a single shot notification at the requested time. :param time: the requested time .. method:: periodic_id_reinit(id: ~typing.Any, start_time: int, interval: int) -> bool Reinitializes the provided periodic ``id`` to the provided start time and interval. Does not modify the reference count. :param id: a :obj:`~gi.repository.Gst.ClockID` :param start_time: the requested start time :param interval: the requested interval .. method:: set_calibration(internal: int, external: int, rate_num: int, rate_denom: int) -> None Adjusts the rate and time of ``clock``\. A rate of 1/1 is the normal speed of the clock. Values bigger than 1/1 make the clock go faster. ``internal`` and ``external`` are calibration parameters that arrange that :func:`~gi.repository.Gst.Clock.get_time` should have been ``external`` at internal time ``internal``\. This internal time should not be in the future; that is, it should be less than the value of :func:`~gi.repository.Gst.Clock.get_internal_time` when this function is called. Subsequent calls to :func:`~gi.repository.Gst.Clock.get_time` will return clock times computed as follows: .. code-block:: C :dedent: time = (internal_time - internal) * rate_num / rate_denom + external This formula is implemented in :func:`~gi.repository.Gst.Clock.adjust_unlocked`. Of course, it tries to do the integer arithmetic as precisely as possible. Note that :func:`~gi.repository.Gst.Clock.get_time` always returns increasing values so when you move the clock backwards, :func:`~gi.repository.Gst.Clock.get_time` will report the previous value until the clock catches up. :param internal: a reference internal time :param external: a reference external time :param rate_num: the numerator of the rate of the clock relative to its internal time :param rate_denom: the denominator of the rate of the clock .. method:: set_master(master: ~gi.repository.Gst.Clock | None = None) -> bool Sets ``master`` as the master clock for ``clock``\. ``clock`` will be automatically calibrated so that :func:`~gi.repository.Gst.Clock.get_time` reports the same time as the master clock. A clock provider that slaves its clock to a master can get the current calibration values with :func:`~gi.repository.Gst.Clock.get_calibration`. ``master`` can be :const:`None` in which case ``clock`` will not be slaved anymore. It will however keep reporting its time adjusted with the last configured rate and time offsets. :param master: a master :obj:`~gi.repository.Gst.Clock` .. method:: set_resolution(resolution: int) -> int Sets the accuracy of the clock. Some clocks have the possibility to operate with different accuracy at the expense of more resource usage. There is normally no need to change the default resolution of a clock. The resolution of a clock can only be changed if the clock has the ``GST_CLOCK_FLAG_CAN_SET_RESOLUTION`` flag set. :param resolution: The resolution to set .. method:: set_synced(synced: bool) -> None Sets ``clock`` to synced and emits the :obj:`~gi.repository.Gst.Clock`\::synced signal, and wakes up any thread waiting in :func:`~gi.repository.Gst.Clock.wait_for_sync`. This function must only be called if :const:`~gi.repository.Gst.ClockFlags.NEEDS_STARTUP_SYNC` is set on the clock, and is intended to be called by subclasses only. .. versionadded:: 1.6 :param synced: if the clock is synced .. method:: set_timeout(timeout: int) -> None Sets the amount of time, in nanoseconds, to sample master and slave clocks :param timeout: a timeout .. method:: single_shot_id_reinit(id: ~typing.Any, time: int) -> bool Reinitializes the provided single shot ``id`` to the provided time. Does not modify the reference count. :param id: a :obj:`~gi.repository.Gst.ClockID` :param time: The requested time. .. method:: unadjust_unlocked(external: int) -> int Converts the given ``external`` clock time to the internal time of ``clock``\, using the rate and reference time set with :func:`~gi.repository.Gst.Clock.set_calibration`. This function should be called with the clock's OBJECT_LOCK held and is mainly used by clock subclasses. This function is the reverse of :func:`~gi.repository.Gst.Clock.adjust_unlocked`. :param external: an external clock time .. method:: unadjust_with_calibration(external_target: int, cinternal: int, cexternal: int, cnum: int, cdenom: int) -> int Converts the given ``external_target`` clock time to the internal time, using the passed calibration parameters. This function performs the same calculation as :func:`~gi.repository.Gst.Clock.unadjust_unlocked` when called using the current calibration parameters. Note: The ``clock`` parameter is unused and can be NULL .. versionadded:: 1.8 :param external_target: a clock time :param cinternal: a reference internal time :param cexternal: a reference external time :param cnum: the numerator of the rate of the clock relative to its internal time :param cdenom: the denominator of the rate of the clock .. method:: wait_for_sync(timeout: int) -> bool Waits until ``clock`` is synced for reporting the current time. If ``timeout`` is :const:`~gi.repository.Gst.CLOCK_TIME_NONE` it will wait forever, otherwise it will time out after ``timeout`` nanoseconds. For asynchronous waiting, the :obj:`~gi.repository.Gst.Clock`\::synced signal can be used. This returns immediately with :const:`True` if :const:`~gi.repository.Gst.ClockFlags.NEEDS_STARTUP_SYNC` is not set on the clock, or if the clock is already synced. .. versionadded:: 1.6 :param timeout: timeout for waiting or :const:`~gi.repository.Gst.CLOCK_TIME_NONE` Properties ---------- .. rst-class:: interim-class .. class:: Clock :no-index: .. attribute:: props.timeout :type: int The type of the None singleton. .. attribute:: props.window_size :type: int The type of the None singleton. .. attribute:: props.window_threshold :type: int The type of the None singleton. Signals ------- .. rst-class:: interim-class .. class:: Clock.signals :no-index: .. method:: synced(synced: bool) -> None The type of the None singleton. .. versionadded:: 1.6 :param synced: if the clock is synced now Virtual Methods --------------- .. rst-class:: interim-class .. class:: Clock :no-index: .. method:: do_change_resolution(old_resolution: int, new_resolution: int) -> int The type of the None singleton. :param old_resolution: the previous resolution :param new_resolution: the new resolution .. method:: do_get_internal_time() -> int Gets the current internal time of the given clock. The time is returned unadjusted for the offset and the rate. .. method:: do_get_resolution() -> int Gets the accuracy of the clock. The accuracy of the clock is the granularity of the values returned by :func:`~gi.repository.Gst.Clock.get_time`. .. method:: do_unschedule(entry: ~gi.repository.Gst.ClockEntry) -> None The type of the None singleton. :param entry: the entry to unschedule .. method:: do_wait(entry: ~gi.repository.Gst.ClockEntry) -> ~typing.Tuple[~gi.repository.Gst.ClockReturn, int] The type of the None singleton. :param entry: the entry to wait on .. method:: do_wait_async(entry: ~gi.repository.Gst.ClockEntry) -> ~gi.repository.Gst.ClockReturn The type of the None singleton. :param entry: the entry to wait on Fields ------ .. rst-class:: interim-class .. class:: Clock :no-index: .. attribute:: object The parent structure .. attribute:: priv