Gst.Clock¶

Subclasses:	`Gst.SystemClock`

Methods¶

Inherited:	Gst.Object (27), GObject.Object (37)
Structs:	GObject.ObjectClass (5)

class	`id_compare_func` (id1, id2)
class	`id_get_clock` (id)
class	`id_get_time` (id)
class	`id_ref` (id)
class	`id_unref` (id)
class	`id_unschedule` (id)
class	`id_uses_clock` (id, clock)
class	`id_wait` (id)
class	`id_wait_async` (id, func, *user_data)
	`add_observation` (slave, master)
	`add_observation_unapplied` (slave, master)
	`adjust_unlocked` (internal)
	`adjust_with_calibration` (internal_target, cinternal, cexternal, cnum, cdenom)
	`get_calibration` ()
	`get_internal_time` ()
	`get_master` ()
	`get_resolution` ()
	`get_time` ()
	`get_timeout` ()
	`is_synced` ()
	`new_periodic_id` (start_time, interval)
	`new_single_shot_id` (time)
	`periodic_id_reinit` (id, start_time, interval)
	`set_calibration` (internal, external, rate_num, rate_denom)
	`set_master` (master)
	`set_resolution` (resolution)
	`set_synced` (synced)
	`set_timeout` (timeout)
	`single_shot_id_reinit` (id, time)
	`unadjust_unlocked` (external)
	`unadjust_with_calibration` (external_target, cinternal, cexternal, cnum, cdenom)
	`wait_for_sync` (timeout)

Virtual Methods¶

Inherited:	Gst.Object (1), GObject.Object (7)

	`do_change_resolution` (old_resolution, new_resolution)
	`do_get_internal_time` ()
	`do_get_resolution` ()
	`do_unschedule` (entry)
	`do_wait` (entry, jitter)
	`do_wait_async` (entry)

Properties¶

Inherited:	Gst.Object (2)

Name	Type	Flags	Short Description
`timeout`	`int`	r/w	The amount of time, in nanoseconds, to sample master and slave clocks
`window-size`	`int`	r/w	The size of the window used to calculate rate and offset
`window-threshold`	`int`	r/w	The threshold to start calculating rate and offset

Signals¶

Inherited:	Gst.Object (1), GObject.Object (1)

Name	Short Description
`synced`	Signaled on clocks with `Gst.ClockFlags.NEEDS_STARTUP_SYNC` set once the clock is synchronized, or when it completely lost synchronization.

Fields¶

Inherited:	Gst.Object (1), GObject.Object (1)

Name	Type	Access	Description
object	`Gst.Object`	r

Class Details¶

class Gst.Clock(**kwargs)¶

Bases:	`Gst.Object`
Abstract:	Yes
Structure:	`Gst.ClockClass`

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 Gst.SystemClock.

The Gst.Clock returns a monotonically increasing time with the method Gst.Clock.get_time(). Its accuracy and base time depend on the specific clock implementation but time is always expressed in nanoseconds.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 newsegment events and the element’s base time, see Gst.Pipeline.

A clock implementation can support periodic and single shot clock notifications both synchronous and asynchronous.

One first needs to create a #GstClockID for the periodic or single shot notification using Gst.Clock.new_single_shot_id() or Gst.Clock.new_periodic_id().

To perform a blocking wait for the specific time of the #GstClockID use the Gst.Clock.id_wait(). To receive a callback when the specific time is reached in the clock use Gst.Clock.id_wait_async(). Both these calls can be interrupted with the Gst.Clock.id_unschedule() call. If the blocking wait is unscheduled a return value of Gst.ClockReturn.UNSCHEDULED is returned.

Periodic callbacks scheduled async will be repeatedly called automatically until it is unscheduled. To schedule a sync periodic callback, 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 #GstClockID that has been unscheduled cannot be used again for any wait operation, a new #GstClockID should be created and the old unscheduled one should be destroyed with Gst.Clock.id_unref().

It is possible to perform a blocking wait on the same #GstClockID from multiple threads. However, registering the same #GstClockID 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 #GstClockID, 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 #GstClockID has to keep a handle to the #GstClockID 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.ClockFlags.CAN_SET_MASTER flag set, it can be slaved to another Gst.Clock with the 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 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 Gst.Pipeline. They can track the offset and rate difference of their internal clock relative to the master clock by using the Gst.Clock.get_calibration() function.

The master/slave synchronisation can be tuned with the Gst.Clock :timeout, Gst.Clock :window-size and Gst.Clock :window-threshold properties. The Gst.Clock :timeout property defines the interval to sample the master clock and run the calibration functions. Gst.Clock :window-size defines the number of samples to use when calibrating and Gst.Clock :window-threshold defines the minimum number of samples before the calibration is performed.

New in version the.

classmethod id_compare_func(id1, id2)[source]¶

Parameters:

id1 (object or None) – A #GstClockID
id2 (object or None) – A #GstClockID to compare with

Returns:

negative value if a < b; zero if a = b; positive value if a > b

MT safe.

Return type:

int

Compares the two #GstClockID instances. This function can be used as a GLib.CompareFunc when sorting ids.

classmethod id_get_clock(id)[source]¶

Parameters:	id (`object`) – a #GstClockID
Returns:	a `Gst.Clock` or `None` when the underlying clock has been freed. Unref after usage. MT safe.
Return type:	`Gst.Clock` or `None`

This function returns the underlying clock.

New in version 1.16.

classmethod id_get_time(id)[source]¶

Parameters:	id (`object`) – The #GstClockID to query
Returns:	the time of the given clock id. MT safe.
Return type:	`int`

Get the time of the clock ID

classmethod id_ref(id)[source]¶

Parameters:	id (`object`) – The #GstClockID to ref
Returns:	The same #GstClockID with increased refcount. MT safe.
Return type:	`object`

Increase the refcount of given id.

classmethod id_unref(id)[source]¶

Parameters:	id (`object`) – The #GstClockID to unref

Unref given id. When the refcount reaches 0 the #GstClockID will be freed.

MT safe.

classmethod id_unschedule(id)[source]¶

Parameters:	id (`object`) – The id to unschedule

Cancel 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 #GstClockID.

MT safe.

classmethod id_uses_clock(id, clock)[source]¶

Parameters:

id (object) – a #GstClockID to check
clock (Gst.Clock) – a Gst.Clock to compare against

Returns:

whether the clock id uses the same underlying Gst.Clock clock.

MT safe.

Return type:

bool

This function returns whether id uses clock as the underlying clock. clock can be None, 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.

New in version 1.16.

classmethod id_wait(id)[source]¶

Parameters: id (object) – The #GstClockID to wait on

Returns:

the result of the blocking wait. Gst.ClockReturn.EARLY will be returned if the current clock time is past the time of id, Gst.ClockReturn.OK if id was scheduled in time. Gst.ClockReturn.UNSCHEDULED if id was unscheduled with Gst.Clock.id_unschedule().

MT safe.

jitter:	a pointer that will contain the jitter, can be `None`.

Return type: (Gst.ClockReturn, jitter: int)

Perform a blocking wait on id. id should have been created with Gst.Clock.new_single_shot_id() or Gst.Clock.new_periodic_id() and should not have been unscheduled with a call to Gst.Clock.id_unschedule().

If the jitter argument is not None and this function returns Gst.ClockReturn.OK or Gst.ClockReturn.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.ClockReturn.EARLY). Negative values indicate how much time was spent waiting on the clock before this function returned.

classmethod id_wait_async(id, func, *user_data)[source]¶

Parameters:

id (object) – a #GstClockID to wait on
func (Gst.ClockCallback) – The callback function
user_data (object or None) – User data passed in the callback

Returns:

the result of the non blocking wait.

MT safe.

Return type:

Gst.ClockReturn

Register a callback on the given #GstClockID id with the given function and user_data. When passing a #GstClockID with an invalid time to this function, the callback will be called immediately with a time set to 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.

add_observation(slave, master)[source]¶

Parameters:

slave (int) – a time on the slave
master (int) – a time on the master

Returns:

True if enough observations were added to run the regression algorithm.

MT safe.

r_squared:	a pointer to hold the result

Return type:

(bool, r_squared: 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 self is recalibrated.

If this functions returns 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.

add_observation_unapplied(slave, master)[source]¶

Parameters:

slave (int) – a time on the slave
master (int) – a time on the master

Returns:

r_squared:	a pointer to hold the result
internal:	a location to store the internal time
external:	a location to store the external time
rate_num:	a location to store the rate numerator
rate_denom:	a location to store the rate denominator

Return type:

(bool, r_squared: float, internal: int, external: int, rate_num: int, rate_denom: int)

Add a clock observation to the internal slaving algorithm the same as 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 Gst.Clock.set_calibration() with the values, or some modified version of them.

New in version 1.6.

adjust_unlocked(internal)[source]¶

Parameters:	internal (`int`) – a clock time
Returns:	the converted time of the clock.
Return type:	`int`

Converts the given internal clock time to the external time, adjusting for the rate and reference time set with 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 Gst.Clock.unadjust_unlocked().

adjust_with_calibration(internal_target, cinternal, cexternal, cnum, cdenom)[source]¶

Parameters:	internal_target (`int`) – a clock time cinternal (`int`) – a reference internal time cexternal (`int`) – a reference external time cnum (`int`) – the numerator of the rate of the clock relative to its internal time cdenom (`int`) – the denominator of the rate of the clock
Returns:	the converted time of the clock.
Return type:	`int`

Converts the given internal_target clock time to the external time, using the passed calibration parameters. This function performs the same calculation as Gst.Clock.adjust_unlocked() when called using the current calibration parameters, but doesn’t ensure a monotonically increasing result as Gst.Clock.adjust_unlocked() does.

Note: The self parameter is unused and can be None

New in version 1.6.

get_calibration()[source]¶

Returns:

internal:	a location to store the internal time
external:	a location to store the external time
rate_num:	a location to store the rate numerator
rate_denom:	a location to store the rate denominator

Return type: (internal: int, external: int, rate_num: int, rate_denom: int)

Gets the internal rate and reference time of self. See Gst.Clock.set_calibration() for more information.

internal, external, rate_num, and rate_denom can be left None if the caller is not interested in the values.

MT safe.

get_internal_time()[source]¶

Returns:	the internal time of the clock. Or `Gst.CLOCK_TIME_NONE` when given invalid input. MT safe.
Return type:	`int`

Gets the current internal time of the given clock. The time is returned unadjusted for the offset and the rate.

get_master()[source]¶

Returns:	a master `Gst.Clock` or `None` when this clock is not slaved to a master clock. Unref after usage. MT safe.
Return type:	`Gst.Clock` or `None`

Get the master clock that self is slaved to or None when the clock is not slaved to any master clock.

get_resolution()[source]¶

Returns:	the resolution of the clock in units of #GstClockTime. MT safe.
Return type:	`int`

Get the accuracy of the clock. The accuracy of the clock is the granularity of the values returned by Gst.Clock.get_time().

get_time()[source]¶

Returns:	the time of the clock. Or `Gst.CLOCK_TIME_NONE` when given invalid input. MT safe.
Return type:	`int`

Gets the current time of the given clock. The time is always monotonically increasing and adjusted according to the current offset and rate.

get_timeout()[source]¶

Returns:	the interval between samples.
Return type:	`int`

Get the amount of time that master and slave clocks are sampled.

is_synced()[source]¶

Returns:	`True` if the clock is currently synced
Return type:	`bool`

Checks if the clock is currently synced.

This returns if Gst.ClockFlags.NEEDS_STARTUP_SYNC is not set on the clock.

New in version 1.6.

new_periodic_id(start_time, interval)[source]¶

Parameters:

start_time (int) – the requested start time
interval (int) – the requested interval

Returns:

a #GstClockID that can be used to request the time notification.

MT safe.

Return type:

object

Get an ID from self to trigger a periodic notification. The periodic notifications will start at time start_time and will then be fired with the given interval. id should be unreffed after usage.

Free-function: Gst.Clock.id_unref

new_single_shot_id(time)[source]¶

Parameters:	time (`int`) – the requested time
Returns:	a #GstClockID that can be used to request the time notification. MT safe.
Return type:	`object`

Get a #GstClockID from self to trigger a single shot notification at the requested time. The single shot id should be unreffed after usage.

Free-function: Gst.Clock.id_unref

periodic_id_reinit(id, start_time, interval)[source]¶

Parameters:	id (`object`) – a #GstClockID start_time (`int`) – the requested start time interval (`int`) – the requested interval
Returns:	`True` if the GstClockID could be reinitialized to the provided time, else `False`.
Return type:	`bool`

Reinitializes the provided periodic id to the provided start time and interval. Does not modify the reference count.

set_calibration(internal, external, rate_num, rate_denom)[source]¶

Parameters:	internal (`int`) – a reference internal time external (`int`) – a reference external time rate_num (`int`) – the numerator of the rate of the clock relative to its internal time rate_denom (`int`) – the denominator of the rate of the clock

Adjusts the rate and time of self. 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 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 Gst.Clock.get_internal_time() when this function is called.

Subsequent calls to Gst.Clock.get_time() will return clock times computed as follows:

time = (internal_time - internal) * rate_num / rate_denom + external

This formula is implemented in Gst.Clock.adjust_unlocked(). Of course, it tries to do the integer arithmetic as precisely as possible.

Note that Gst.Clock.get_time() always returns increasing values so when you move the clock backwards, Gst.Clock.get_time() will report the previous value until the clock catches up.

MT safe.

set_master(master)[source]¶

Parameters:	master (`Gst.Clock` or `None`) – a master `Gst.Clock`
Returns:	`True` if the clock is capable of being slaved to a master clock. Trying to set a master on a clock without the `Gst.ClockFlags.CAN_SET_MASTER` flag will make this function return `False`. MT safe.
Return type:	`bool`

Set master as the master clock for self. self will be automatically calibrated so that 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 Gst.Clock.get_calibration().

master can be None in which case self will not be slaved anymore. It will however keep reporting its time adjusted with the last configured rate and time offsets.

set_resolution(resolution)[source]¶

Parameters:	resolution (`int`) – The resolution to set
Returns:	the new resolution of the clock.
Return type:	`int`

Set 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.ClockFlags.CAN_SET_RESOLUTION flag set.

set_synced(synced)[source]¶

Parameters:	synced (`bool`) – if the clock is synced

Sets self to synced and emits the Gst.Clock ::synced signal, and wakes up any thread waiting in Gst.Clock.wait_for_sync().

This function must only be called if Gst.ClockFlags.NEEDS_STARTUP_SYNC is set on the clock, and is intended to be called by subclasses only.

New in version 1.6.

set_timeout(timeout)[source]¶

Parameters:	timeout (`int`) – a timeout

Set the amount of time, in nanoseconds, to sample master and slave clocks

single_shot_id_reinit(id, time)[source]¶

Parameters:	id (`object`) – a #GstClockID time (`int`) – The requested time.
Returns:	`True` if the GstClockID could be reinitialized to the provided time, else `False`.
Return type:	`bool`

Reinitializes the provided single shot id to the provided time. Does not modify the reference count.

unadjust_unlocked(external)[source]¶

Parameters:	external (`int`) – an external clock time
Returns:	the internal time of the clock corresponding to external.
Return type:	`int`

Converts the given external clock time to the internal time of self, using the rate and reference time set with 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 Gst.Clock.adjust_unlocked().

unadjust_with_calibration(external_target, cinternal, cexternal, cnum, cdenom)[source]¶

Parameters:	external_target (`int`) – a clock time cinternal (`int`) – a reference internal time cexternal (`int`) – a reference external time cnum (`int`) – the numerator of the rate of the clock relative to its internal time cdenom (`int`) – the denominator of the rate of the clock
Returns:	the converted time of the clock.
Return type:	`int`

Converts the given external_target clock time to the internal time, using the passed calibration parameters. This function performs the same calculation as Gst.Clock.unadjust_unlocked() when called using the current calibration parameters.

Note: The self parameter is unused and can be None

New in version 1.8.

wait_for_sync(timeout)[source]¶

Parameters:	timeout (`int`) – timeout for waiting or `Gst.CLOCK_TIME_NONE`
Returns:	`True` if waiting was successful, or `False` on timeout
Return type:	`bool`

Waits until self is synced for reporting the current time. If timeout is Gst.CLOCK_TIME_NONE it will wait forever, otherwise it will time out after timeout nanoseconds.

For asynchronous waiting, the Gst.Clock ::synced signal can be used.

This returns immediately with True if Gst.ClockFlags.NEEDS_STARTUP_SYNC is not set on the clock, or if the clock is already synced.

New in version 1.6.

do_change_resolution(old_resolution, new_resolution) virtual¶

Parameters:	old_resolution (`int`) – new_resolution (`int`) –
Return type:	`int`

do_get_internal_time() virtual¶

Returns:	the internal time of the clock. Or `Gst.CLOCK_TIME_NONE` when given invalid input. MT safe.
Return type:	`int`

Gets the current internal time of the given clock. The time is returned unadjusted for the offset and the rate.

do_get_resolution() virtual¶

Returns:	the resolution of the clock in units of #GstClockTime. MT safe.
Return type:	`int`

Get the accuracy of the clock. The accuracy of the clock is the granularity of the values returned by Gst.Clock.get_time().

do_unschedule(entry) virtual¶

Parameters:	entry (`Gst.ClockEntry`) –

do_wait(entry, jitter) virtual¶

Parameters:	entry (`Gst.ClockEntry`) – jitter (`int`) –
Return type:	`Gst.ClockReturn`

do_wait_async(entry) virtual¶

Parameters:	entry (`Gst.ClockEntry`) –
Return type:	`Gst.ClockReturn`

Signal Details¶

Gst.Clock.signals.synced(clock, synced)¶

Signal Name:	`synced`
Flags:	`RUN_LAST`
Parameters:	clock (`Gst.Clock`) – The object which received the signal synced (`bool`) – if the clock is synced now

Signaled on clocks with 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.

New in version 1.6.

Property Details¶

Gst.Clock.props.timeout¶

Name:	`timeout`
Type:	`int`
Default Value:	`100000000`
Flags:	`READABLE`, `WRITABLE`

The amount of time, in nanoseconds, to sample master and slave clocks

Gst.Clock.props.window_size¶

Name:	`window-size`
Type:	`int`
Default Value:	`32`
Flags:	`READABLE`, `WRITABLE`

The size of the window used to calculate rate and offset

Gst.Clock.props.window_threshold¶

Name:	`window-threshold`
Type:	`int`
Default Value:	`4`
Flags:	`READABLE`, `WRITABLE`

The threshold to start calculating rate and offset