mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-20 07:16:55 +00:00
Code Issues 1 Projects Releases Wiki Activity

design: synchronisation: missing markup and readability fixes

Browse source
This commit is contained in:
Reynaldo H. Verdejo Pinochet 2016-12-30 00:51:09 -08:00
parent e7ba83d049
commit ea18d865ae
1 changed files with 55 additions and 55 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

110
markdown/design/synchronisation.md
View file

@ -15,7 +15,7 @@ components:
## A GstClock ## A GstClock
This object provides a counter that represents the current time in This object provides a counter that represents the current time in
nanoseconds. This value is called the absolute\_time. A `GstClock` nanoseconds. This value is called the `absolute_time`. A `GstClock`
always counts time upwards and does not necessarily start at 0. always counts time upwards and does not necessarily start at 0.
Different sources exist for this counter: Different sources exist for this counter:
@ -44,32 +44,32 @@ in an mpeg-ts stream).
## Running time ## Running time
After a pipeline selected a clock it will maintain the running\_time After a pipeline selected a clock it will maintain the `running_time`
based on the selected clock. This running\_time represents the total based on the selected clock. This `running_time` represents the total
time spent in the PLAYING state and is calculated as follows: time spent in the PLAYING state and is calculated as follows:
- If the pipeline is NULL/READY, the running\_time is undefined. - If the pipeline is NULL/READY, the `running_time` is undefined.
- In PAUSED, the running\_time remains at the time when it was last - In PAUSED, the `running_time` remains at the time when it was last
PAUSED. When the stream is PAUSED for the first time, the PAUSED. When the stream is `PAUSED` for the first time, the
running\_time is 0. `running_time` is 0.
- In PLAYING, the running\_time is the delta between the - In PLAYING, the `running_time` is the delta between the
absolute\_time and the base time. The base time is defined as the `absolute_time` and the base time. The base time is defined as the
absolute\_time minus the running\_time at the time when the pipeline `absolute_time` minus the `running_time` at the time when the pipeline
is set to PLAYING. is set to `PLAYING`.
- after a flushing seek, the running\_time is set to 0 (see - after a flushing seek, the `running_time` is set to 0 (see
[seeking](design/seeking.md)). This is accomplished by redistributing a new [seeking](design/seeking.md)). This is accomplished by redistributing a new
base\_time to the elements that got flushed. base\_time to the elements that got flushed.
This algorithm captures the running\_time when the pipeline is set from This algorithm captures the `running_time` when the pipeline is set from
PLAYING to PAUSED and restores this time based on the current `PLAYING` to `PAUSED` and restores this time based on the current
absolute\_time when going back to PLAYING. This allows for both clocks `absolute_time` when going back to `PLAYING`. This allows for both clocks
that progress when in the PAUSED state (systemclock) and clocks that that progress when in the `PAUSED` state (systemclock) and clocks that
don’t (audioclock). don’t (audioclock).
The clock and pipeline now provide a running\_time to all elements that The clock and pipeline now provide a `running_time` to all elements that
want to perform synchronisation. Indeed, the running time can be want to perform synchronisation. Indeed, the running time can be
observed in each element (during the PLAYING state) as: observed in each element (during the PLAYING state) as:
@ -77,14 +77,14 @@ observed in each element (during the PLAYING state) as:
C.running_time = absolute_time - base_time C.running_time = absolute_time - base_time
``` ```
We note C.running\_time as the running\_time obtained by looking at the We note `C.running_time` as the `running_time` obtained by looking at the
clock. This value is monotonically increasing at the rate of the clock. clock. This value is monotonically increasing at the rate of the clock.
## Timestamps ## Timestamps
The `GstBuffer` timestamps and the preceding SEGMENT event (See The `GstBuffer` timestamps and the preceding SEGMENT event (See
[streams](design/streams.md)) define a transformation of the buffer timestamps to [streams](design/streams.md)) define a transformation of the buffer timestamps
running\_time as follows: to `running_time` as follows:
The following notation is used: The following notation is used:
@ -97,17 +97,17 @@ The following notation is used:
- S.stop: stop field in the SEGMENT event. This is the highers allowed - S.stop: stop field in the SEGMENT event. This is the highers allowed
timestamp. timestamp.
- S.rate: rate field of SEGMENT event. This is the playback rate. - S.rate: rate field of SEGMENT event. This is the playback rate.
- S.base: a base time for the time. This is the total elapsed running_time of any - S.base: a base time for the time. This is the total elapsed `running_time`
previous segments. of any previous segments.
- S.offset: an offset to apply to S.start or S.stop. This is the amount that - S.offset: an offset to apply to S.start or S.stop. This is the amount that
has already been elapsed in the segment. has already been elapsed in the segment.
Valid buffers for synchronisation are those with B.timestamp between Valid buffers for synchronisation are those with B.timestamp between
S.start and S.stop (after applying the S.offset). All other buffers `S.start` and `S.stop` (after applying the `S.offset`). All other buffers
outside this range should be dropped or clipped to these boundaries (see outside this range should be dropped or clipped to these boundaries (see
also [segments](design/segments.md)). also [segments](design/segments.md)).
The following transformation to running_time exist: The following transformation to `running_time` exist:
``` ```
if (S.rate > 0.0) if (S.rate > 0.0)
@ -120,34 +120,34 @@ The following transformation to running_time exist:
B.timestamp = S.stop - S.offset - ((B.running_time - S.base) * ABS (S.rate)) B.timestamp = S.stop - S.offset - ((B.running_time - S.base) * ABS (S.rate))
``` ```
We write B.running_time as the running_time obtained from the SEGMENT We write `B.running_time` as the `running_time` obtained from the `SEGMENT`
event and the buffers of that segment. event and the buffers of that segment.
The first displayable buffer will yield a value of 0 (since B.timestamp The first displayable buffer will yield a value of 0 (since `B.timestamp
== S.start and S.offset and S.base == 0). == S.start and S.offset and S.base == 0`).
For S.rate \> 1.0, the timestamps will be scaled down to increase the For `S.rate > 1.0`, the timestamps will be scaled down to increase the
playback rate. Likewise, a rate between 0.0 and 1.0 will slow down playback rate. Likewise, a rate between 0.0 and 1.0 will slow down
playback. playback.
For negative rates, timestamps are received stop S.stop to S.start so For negative rates, timestamps are received stop S.stop to `S.start` so
that the first buffer received will be transformed into B.running\_time that the first buffer received will be transformed into `B.running_time`
of 0 (B.timestamp == S.stop and S.base == 0). of 0 (`B.timestamp == S.stop and S.base == 0`).
This makes it so that B.running\_time is always monotonically increasing This makes it so that `B.running_time` is always monotonically increasing
starting from 0 with both positive and negative rates. starting from 0 with both positive and negative rates.
## Synchronisation ## Synchronisation
As we have seen, we can get a running\_time: As we have seen, we can get a `running_time`:
- using the clock and the element’s base\_time with: - using the clock and the element’s `base_time` with:
``` ```
C.running_time = absolute_time - base_time C.running_time = absolute_time - base_time
``` ```
- using the buffer timestamp and the preceding SEGMENT event as (assuming - using the buffer timestamp and the preceding `SEGMENT` event as (assuming
positive playback rate): positive playback rate):
``` ```
@ -158,8 +158,8 @@ We prefix C. and B. before the two running times to note how they were
calculated. calculated.
The task of synchronized playback is to make sure that we play a buffer The task of synchronized playback is to make sure that we play a buffer
with B.running\_time at the moment when the clock reaches the same with `B.running_time` at the moment when the clock reaches the same
C.running\_time. `C.running_time`.
Thus the following must hold: Thus the following must hold:
@ -179,22 +179,22 @@ or:
absolute_time = B.running_time + base_time absolute_time = B.running_time + base_time
``` ```
The absolute\_time when a buffer with B.running\_time should be played The `absolute_time` when a buffer with `B.running_time` should be played
is noted with B.sync\_time. Thus: is noted with `B.sync_time`. Thus:
``` ```
B.sync_time = B.running_time + base_time B.sync_time = B.running_time + base_time
``` ```
One then waits for the clock to reach B.sync\_time before rendering the One then waits for the clock to reach `B.sync_time` before rendering the
buffer in the sink (See also [clocks](design/clocks.md)). buffer in the sink (See also [clocks](design/clocks.md)).
For multiple streams this means that buffers with the same running\_time For multiple streams this means that buffers with the same `running_time`
are to be displayed at the same time. are to be displayed at the same time.
A demuxer must make sure that the SEGMENT it emits on its output pads A demuxer must make sure that the `SEGMENT` it emits on its output pads
yield the same running\_time for buffers that should be played yield the same `running_time` for buffers that should be played
synchronized. This usually means sending the same SEGMENT on all pads synchronized. This usually means sending the same `SEGMENT` on all pads
and making sure that the synchronized buffers have the same timestamps. and making sure that the synchronized buffers have the same timestamps.
## Stream time ## Stream time
@ -204,40 +204,40 @@ value between 0 and the total duration of the media file.
It is the stream time that is used for: It is the stream time that is used for:
- report the POSITION query in the pipeline - report the `POSITION` query in the pipeline
- the position used in seek events/queries - the position used in seek events/queries
- the position used to synchronize controller values - the position used to synchronize controller values
Additional fields in the SEGMENT are used: Additional fields in the `SEGMENT` are used:
- S.time: time field in the SEGMENT event. This the stream-time of - `S.time`: time field in the `SEGMENT` event. This the stream-time of
S.start `S.start`
- S.applied\_rate: The rate already applied to the segment. - `S.applied_rate`: The rate already applied to the segment.
Stream time is calculated using the buffer times and the preceding Stream time is calculated using the buffer times and the preceding
SEGMENT event as follows: `SEGMENT` event as follows:
``` ```
stream_time = (B.timestamp - S.start) * ABS (S.applied_rate) + S.time stream_time = (B.timestamp - S.start) * ABS (S.applied_rate) + S.time
=> B.timestamp = (stream_time - S.time) / ABS(S.applied_rate) + S.start => B.timestamp = (stream_time - S.time) / ABS(S.applied_rate) + S.start
``` ```
For negative rates, B.timestamp will go backwards from S.stop to For negative rates, `B.timestamp` will go backwards from `S.stop` to
S.start, making the stream time go backwards: `S.start`, making the stream time go backwards:
``` ```
stream_time = (S.stop - B.timestamp) * ABS(S.applied_rate) + S.time stream_time = (S.stop - B.timestamp) * ABS(S.applied_rate) + S.time
=> B.timestamp = S.stop - (stream_time - S.time) / ABS(S.applied_rate) => B.timestamp = S.stop - (stream_time - S.time) / ABS(S.applied_rate)
``` ```
In the PLAYING state, it is also possible to use the pipeline clock to In the `PLAYING` state, it is also possible to use the pipeline clock to
derive the current stream\_time. derive the current `stream_time`.
Give the two formulas above to match the clock times with buffer Give the two formulas above to match the clock times with buffer
timestamps allows us to rewrite the above formula for stream\_time (and timestamps allows us to rewrite the above formula for `stream_time` (and
for positive rates). for positive rates).
``` ```