| Gtk2Hs | Contents | Index

Media.Streaming.GStreamer.Core.Clock

Contents

Detail
Types
Clock Operations
Clock Properties

Synopsis

data Clock
class ObjectClass o => ClockClass o
castToClock :: GObjectClass obj => obj -> Clock
toClock :: ClockClass o => o -> Clock
type ClockTime = Word64
clockTimeNone :: ClockTime
clockTimeIsValid :: ClockTime -> Bool
second :: ClockTime
msecond :: ClockTime
usecond :: ClockTime
nsecond :: ClockTime
type ClockTimeDiff = Int64
data ClockID

data ClockReturn

= ClockOk
| ClockEarly
| ClockUnscheduled
| ClockBusy
| ClockBadtime
| ClockError
| ClockUnsupported

data ClockFlags

= ClockCanDoSingleSync
| ClockCanDoSingleAsync
| ClockCanDoPeriodicSync
| ClockCanDoPeriodicAsync
| ClockCanSetResolution
| ClockCanSetMaster

clockGetFlags :: ClockClass clockT => clockT -> IO [ClockFlags]
clockSetFlags :: ClockClass clockT => clockT -> [ClockFlags] -> IO ()
clockUnsetFlags :: ClockClass clockT => clockT -> [ClockFlags] -> IO ()
clockAddObservation :: ClockClass clock => clock -> ClockTime -> ClockTime -> IO (Maybe Double)
clockSetMaster :: (ClockClass clock, ClockClass master) => clock -> Maybe master -> IO Bool
clockGetMaster :: ClockClass clock => clock -> IO (Maybe Clock)
clockSetResolution :: ClockClass clock => clock -> ClockTime -> IO ClockTime
clockGetResolution :: ClockClass clock => clock -> IO ClockTime
clockGetTime :: ClockClass clock => clock -> IO ClockTime
clockNewSingleShotID :: ClockClass clock => clock -> ClockTime -> IO ClockID
clockNewPeriodicID :: ClockClass clock => clock -> ClockTime -> ClockTime -> IO ClockID
clockGetInternalTime :: ClockClass clock => clock -> IO ClockTime
clockGetCalibration :: ClockClass clock => clock -> IO (ClockTime, ClockTime, Ratio ClockTime)
clockSetCalibration :: ClockClass clock => clock -> ClockTime -> ClockTime -> Ratio ClockTime -> IO ()
clockIDGetTime :: ClockID -> IO ClockTime
clockIDWait :: ClockID -> IO (ClockReturn, Maybe ClockTimeDiff)
clockIDUnschedule :: ClockID -> IO ()
clockTimeout :: ClockClass clockT => Attr clockT ClockTime
clockWindowSize :: ClockClass clockT => Attr clockT Int
clockWindowThreshold :: ClockClass clockT => Attr clockT Int

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

GObjectClass Clock
ClockClass Clock
ObjectClass Clock

class ObjectClass o => ClockClass o

Instances

ClockClass SystemClock
ClockClass Clock
ClockClass NetClientClock
ClockClass AudioClock

castToClock :: GObjectClass obj => obj -> Clock
toClock :: ClockClass o => o -> Clock
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

:: 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 `ClockTime`s.
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

:: ClockClass clockT |

=> clockT

    clock

-> IO [ClockFlags] | the flags currently set on the clock
Get the flags set on the clock.

clockSetFlags

:: ClockClass clockT |

=> clockT

    clock

-> [ClockFlags] | `flags` - the flags to be set
-> IO () |
Set the given flags on the clock.

clockUnsetFlags

:: 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

:: (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

:: 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

:: 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

:: 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

:: 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

:: 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

:: 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

:: 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

:: 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

:: ClockID

    clockID

-> IO ClockTime |
Get the time of `clockID`.

clockIDWait

:: 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

:: 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.
Produced by Haddock version 2.4.2