Media.Streaming.GStreamer.Core.Clock

Abstract class of global clocks.

Detail

GStreamer uses a global clock to synchronize the plugins in a pipeline. Different clock implementations are possible by implementing this abstract base class.

The Clock returns a monotonically increasing time with the method clockGetTime. 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 stream time. Usually all renderers synchronize to the global clock using the buffer timestamps, the newsegment events and the element's base time, see GstPipeline.

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

One first needs to create a ClockID for the periodic or single shot notification using clockNewSingleShotID or clockNewPeriodicID.

To perform a blocking wait for the specific time of the ClockID use clockIDWait. This calls can be interrupted with the clockIDUnschedule call. If the blocking wait is unscheduled a return value of ClockUnscheduled is returned.

Periodic callbacks scheduled async will be repeadedly called automatically until it is unscheduled. To schedule a sync periodic callback, clockIDWait 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 ClockID that has been unscheduled cannot be used again for any wait operation; a new ClockID should be created.

It is possible to perform a blocking wait on the same ClockID from multiple threads. However, registering the same ClockID for multiple async notifications is not possible, the callback will only be called for the thread registering the entry last.

These clock operations do not operate on the stream time, so the callbacks will also occur when not in the 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 ClockFlagCanSetMaster flag set, it can be slaved to another Clock with clockSetMaster. 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 clockSetCalibration. This feature is mostly useful for plugins that have an internal clock but must operate with another clock selected by the GstPipeline. They can track the offset and rate difference of their internal clock relative to the master clock by using the clockGetCalibration function.

The master/slave synchronisation can be tuned with the the clockTimeout, clockWindowSize and clockWindowThreshold properties. The clockTimeout property defines the interval to sample the master clock and run the calibration functions. clockWindowSize defines the number of samples to use when calibrating and clockWindowThreshold defines the minimum number of samples before the calibration is performed.

Types

data Clock

Instances

Eq Clock

Ord Clock

GObjectClass Clock

ClockClass Clock

ObjectClass Clock

class ObjectClass o => ClockClass o

Instances

ClockClass NetClientClock

ClockClass SystemClock

ClockClass AudioClock

ClockClass Clock

castToClock :: GObjectClass obj => obj -> Clock

gTypeClock :: GType

A time value measured in nanoseconds.

type ClockTime = Word64

A time value in nanoseconds.

The ClockTime value representing an invalid time.

clockTimeNone :: ClockTime

The undefined ClockTime value.

clockTimeIsValid

Arguments

:: ClockTime

clockTime

-> Bool

True if clockTime is valid, False otherwise

Returns True if the given ClockTime is valid, and False otherwise.

The ClockTime value representing 1 second, i.e. 1e9.

second :: ClockTime

The ClockTime value representing 1 millisecond, i.e. 1e6.

msecond :: ClockTime

The ClockTime value representing 1 microsecond, i.e. 1e3.

usecond :: ClockTime

The ClockTime value representing 1 nanosecond, i.e. 1.

nsecond :: ClockTime

A value holding the difference between two ClockTimes.

type ClockTimeDiff = Int64

An opaque identifier for a timer event.

data ClockID

An enumeration type returned by clockIDWait.

data ClockReturn

Constructors

ClockOk

ClockEarly

ClockUnscheduled

ClockBusy

ClockBadtime

ClockError

ClockUnsupported

Instances

Enum ClockReturn

Eq ClockReturn

Show ClockReturn

The flags a Clock may have.

data ClockFlags

The flags that a Clock may have.

Constructors

ClockCanDoSingleSync

the clock can do a single sync timeout request

ClockCanDoSingleAsync

the clock can do a single async timeout request

ClockCanDoPeriodicSync

the clock can do periodic sync timeout requests

ClockCanDoPeriodicAsync

the clock can do periodic async timeout requests

ClockCanSetResolution

the clock's resolution can be changed

ClockCanSetMaster

the clock can be slaved to a master clock

Instances

Bounded ClockFlags

Enum ClockFlags

Eq ClockFlags

Show ClockFlags

Flags ClockFlags

clockGetFlags

Arguments

:: ClockClass clockT

=> clockT

clock

-> IO [ClockFlags]

the flags currently set on the clock

Get the flags set on the clock.

clockSetFlags

Arguments

:: ClockClass clockT

=> clockT

clock

-> [ClockFlags]

flags - the flags to be set

-> IO ()

Set the given flags on the clock.

clockUnsetFlags

Arguments

:: ClockClass clockT

=> clockT

clock

-> [ClockFlags]

flags - the flags to be unset

-> IO ()

Unset the given flags on the clock.

Clock Operations

clockAddObservation :: ClockClass clock => clock -> ClockTime -> ClockTime -> IO (Maybe Double)

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 a calibration is performed, the correlation coefficient of the interpolation will be returned. A value of 1.0 means the clocks are in perfect sync. This value can be used to control the sampling frequency of the master and slave clocks.

clockSetMaster

Arguments

:: (ClockClass clock, ClockClass master)

=> clock

clock

-> Maybe master

master

-> IO Bool

True if clock is capable of being slaved to the master clock, otherwise False

Set master as the master clock for clock. The clock will automatically be calibrated so that clockGetTime 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 clockGetCalibration.

The master clock can be Nothing in which case clock will not be slaved any longer. It will, however, continue to report its time adjusted using the last configured rate and time offsets.

Note that if clock does not have the ClockFlagCanSetMaster flag set, this function will not succeed and return False.

clockGetMaster

Arguments

:: ClockClass clock

=> clock

clock

-> IO (Maybe Clock)

the master that clock is slaved to, or Nothing

Return the master that clock is slaved to, or Nothing if clock is not slaved.

clockSetResolution :: ClockClass clock => clock -> ClockTime -> IO ClockTime

Set the resolution of clock. Some clocks have the possibility to operate with different resolution 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 ClockFlagCanSetResolution flag set.

clockGetResolution

Arguments

:: ClockClass clock

=> clock

clock -

-> IO ClockTime

the resolution currently set in clock

Get the resolution of the clock. The resolution of the clock is the granularity of the values returned by clockGetTime.

clockGetTime

Arguments

:: ClockClass clock

=> clock

clock

-> IO ClockTime

the current time in clock

Get the current time stored in clock. The time is always monotonically increasing and adjusted according to the current offset and rate.

clockNewSingleShotID

Arguments

:: ClockClass clock

=> clock

clock

-> ClockTime

clockTime

-> IO ClockID

a single shot notification id triggered at clockTime

Get a ClockID from clock to trigger a single shot notification at the requested time.

clockNewPeriodicID

Arguments

:: ClockClass clock

=> clock

clock

-> ClockTime

startTime

-> ClockTime

interval

-> IO ClockID

a periodic notification id

Get a ClockID from clock to trigger periodic notifications. The notifications will start at time startTime and then be fired at each interval after.

clockGetInternalTime

Arguments

:: ClockClass clock

=> clock

clock

-> IO ClockTime

the clock's internal time value

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

clockGetCalibration

Arguments

:: ClockClass clock

=> clock

clock

-> IO (ClockTime, ClockTime, Ratio ClockTime)

the clock's internal time, external (adjusted) time, and skew rate

Gets the internal rate and reference time of clock. See clockSetCalibration for more information.

clockSetCalibration

Arguments

:: ClockClass clock

=> clock

clock

-> ClockTime

internal

-> ClockTime

external

-> Ratio ClockTime

rate

-> IO ()

Adjusts the rate and time of clock. A rate of 1 % 1 is the normal speed of the clock. Larger values make the clock go faster.

The parameters internal and external specifying that clockGetTime should have returned external when the clock had internal time internal. The parameter internal should not be in the future; that is, it should be less than the value returned by clockGetInternalTime when this function is called.

Subsequent calls to clockGetTime will return clock times computed as follows:

 (clock_internal - internal) * rate + external

Note that clockGetTime always returns increasing values, so if the clock is moved backwards, clockGetTime will report the previous value until the clock catches up.

clockIDGetTime

Arguments

:: ClockID

clockID

-> IO ClockTime

Get the time of clockID.

clockIDWait

Arguments

:: ClockID

clockID

-> IO (ClockReturn, Maybe ClockTimeDiff)

Perform a blocking wait on clockID. The parameter clockID should have been created with clockNewSingleShotID or clockNewPeriodicID, and should not been unscheduled with a call to clockIDUnschedule.

If second value in the returned pair is not Nothing, it will contain the difference against the clock and the time of clockID when this method was called. Positive values indicate how late clockID was relative to the clock. Negative values indicate how much time was spend waiting on the clock before the function returned.

clockIDUnschedule

Arguments

:: ClockID

clockID

-> IO ()

Cancel an outstanding request with clockID. After this call, clockID cannot be used anymore to recieve notifications; you must create a new ClockID.

Clock Properties

clockTimeout :: ClockClass clockT => Attr clockT ClockTime

The amount of time, in nanoseconds, between samples.

clockWindowSize :: ClockClass clockT => Attr clockT Int

The size of the window used to calculate rate and offset.

clockWindowThreshold :: ClockClass clockT => Attr clockT Int

The threshold to start calculating rate and offset.