: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` :Constructors: :: Clock(**properties) Methods ------- .. rst-class:: interim-class .. class:: Clock :no-index: .. method:: add_observation(slave: int, master: int) -> 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) -> 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:: get_calibration() -> 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. .. method:: id_compare_func(id1: None, id2: None) -> int Compares the two :obj:`~gi.repository.Gst.ClockID` instances. This function can be used as a GCompareFunc when sorting ids. :param id1: A :obj:`~gi.repository.Gst.ClockID` :param id2: A :obj:`~gi.repository.Gst.ClockID` to compare with .. method:: id_get_clock(id: None) -> ~gi.repository.Gst.Clock | None This function returns the underlying clock. .. versionadded:: 1.16 :param id: a :obj:`~gi.repository.Gst.ClockID` .. method:: id_get_time(id: None) -> int Gets the time of the clock ID :param id: The :obj:`~gi.repository.Gst.ClockID` to query .. method:: id_unschedule(id: None) -> 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`. :param id: The id to unschedule .. method:: id_uses_clock(id: None, 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 id: a :obj:`~gi.repository.Gst.ClockID` to check :param clock: a :obj:`~gi.repository.Gst.Clock` to compare against .. method:: id_wait(id: None) -> 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. :param id: The :obj:`~gi.repository.Gst.ClockID` to wait on .. method:: id_wait_async(id: None, func: ~typing.Callable[[...], bool], *user_data: ~typing.Any) -> ~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 id: a :obj:`~gi.repository.Gst.ClockID` to wait on :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) -> None 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) -> None 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: None, 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: None, 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 .. attribute:: props.window_size :type: int .. attribute:: props.window_threshold :type: int Signals ------- .. rst-class:: interim-class .. class:: Clock.signals :no-index: .. method:: synced(synced: bool) -> None Signaled on clocks with :const:`~gi.repository.Gst.ClockFlags.NEEDS_STARTUP_SYNC` set once the clock is synchronized, or when it completely lost synchronization. This signal will not be emitted on clocks without the flag. This signal will be emitted from an arbitrary thread, most likely not the application's main thread. .. 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 Change the resolution of the clock. Not all values might be acceptable. :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 Unblock a blocking or async wait operation. :param entry: the entry to unschedule .. method:: do_wait(entry: ~gi.repository.Gst.ClockEntry) -> tuple[~gi.repository.Gst.ClockReturn, int] Perform a blocking wait on the given :obj:`~gi.repository.Gst.ClockEntry` and return the jitter. :param entry: the entry to wait on .. method:: do_wait_async(entry: ~gi.repository.Gst.ClockEntry) -> ~gi.repository.Gst.ClockReturn Perform an asynchronous wait on the given :obj:`~gi.repository.Gst.ClockEntry`. :param entry: the entry to wait on Fields ------ .. rst-class:: interim-class .. class:: Clock :no-index: .. attribute:: object The parent structure .. attribute:: priv