docs: update synchronization docs

1 files changed, 32 insertions, 29 deletions

diff --git a/docs/design/part-synchronisation.txt b/docs/design/part-synchronisation.txt
index 68ac0f0f43..bdaa244817 100644
--- a/docs/design/part-synchronisation.txt
+++ b/docs/design/part-synchronisation.txt
@@ -77,38 +77,38 @@ The following notation is used:
  B: GstBuffer 
   - B.timestamp = buffer timestamp (GST_BUFFER_TIMESTAMP)
 
- NS:  SEGMENT event preceeding the buffers.
-  - NS.start: start field in the SEGMENT event
-  - NS.stop: stop field in the SEGMENT event
-  - NS.rate: rate field of SEGMENT event
-  - NS.abs_rate: absolute value of rate field of SEGMENT event
-  - NS.time: time field in the SEGMENT event
-  - NS.accum: total accumulated time of all previous SEGMENT events. This
-              field is kept in the GstSegment structure.
-
-Valid buffers for synchronisation are those with B.timestamp between NS.start
-and NS.stop. All other buffers outside this range should be dropped or clipped
-to these boundaries (see also part-segments.txt).
+ S:  SEGMENT event preceeding the buffers.
+  - S.start: start field in the SEGMENT event
+  - S.stop: stop field in the SEGMENT event
+  - S.rate: rate field of SEGMENT event
+  - S.abs_rate: absolute value of rate field of SEGMENT event
+  - S.time: time field in the SEGMENT event
+  - S.base: a base time for the time.
+  - S.offset: an offset to apply to S.start or S.stop
+
+Valid buffers for synchronisation are those with B.timestamp between 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 also part-segments.txt).
 
 The following transformation to running_time exist:
 
-    if (NS.rate > 0.0)
-      B.running_time = (B.timestamp - NS.start) / NS.abs_rate + NS.accum
-    else
-      B.running_time = (NS.stop - B.timestamp) / NS.abs_rate + NS.accum
+  if (S.rate > 0.0)
+    B.running_time = (B.timestamp - (S.start + S.offset)) / S.abs_rate + S.base
+  else
+    B.running_time = ((S.stop - S.offset) - B.timestamp) / S.abs_rate + S.base
 
 We write B.running_time as the running_time obtained from the SEGMENT event
 and the buffers of that segment.
 
 The first displayable buffer will yield a value of 0 (since B.timestamp ==
-NS.start and NS.accum == 0).
+S.start and S.offset and S.base == 0).
 
-For NS.rate > 1.0, the timestamps will be scaled down to increase the playback
+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.
 
-For negative rates, timestamps are received stop NS.stop to NS.start so that the
+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 of 0 (B.timestamp ==
-NS.stop and NS.accum == 0).
+S.stop and S.accum == 0).
 
 
 Synchronisation
@@ -123,7 +123,7 @@ As we have seen, we can get a running_time:
  - using the buffer timestamp and the preceeding SEGMENT event as (assuming
    positive playback rate):
 
-    B.running_time = (B.timestamp - NS.start) / NS.abs_rate + NS.accum
+    B.running_time = (B.timestamp - (S.start + S.offset)) / S.abs_rate + S.base
 
 We prefix C. and B. before the two running times to note how they were
 calculated.
@@ -175,9 +175,9 @@ It is the stream time that is used for:
 Stream time is calculated using the buffer times and the preceeding SEGMENT
 event as follows:
 
-    stream_time = (B.timestamp - NS.start) * NS.abs_applied_rate + NS.time
+    stream_time = (B.timestamp - S.start) * S.abs_applied_rate + S.time
  
-For negative rates, B.timestamp will go backwards from NS.stop to NS.start,
+For negative rates, B.timestamp will go backwards from S.stop to S.start,
 making the stream time go backwards.
 
 In the PLAYING state, it is also possible to use the pipeline clock to derive
@@ -187,21 +187,24 @@ Give the two formulas above to match the clock times with buffer timestamps
 allows us to rewrite the above formula for stream_time (and for positive rates).
 
     C.running_time = absolute_time - base_time
-    B.running_time = (B.timestamp - NS.start) / NS.abs_rate + NS.accum
+    B.running_time = (B.timestamp - (S.start + S.offset)) / S.abs_rate + S.base
 
   =>
-    (B.timestamp - NS.start) / NS.abs_rate + NS.accum = absolute_time - base_time;
+    (B.timestamp - (S.start + S.offset)) / S.abs_rate + S.base = absolute_time - base_time;
 
   =>
-    (B.timestamp - NS.start) / NS.abs_rate = absolute_time - base_time - NS.accum;
+    (B.timestamp - (S.start + S.offset)) / S.abs_rate = absolute_time - base_time - S.base;
 
   =>
-    (B.timestamp - NS.start) = (absolute_time - base_time - NS.accum) * NS.abs_rate
+    (B.timestamp - (S.start + S.offset)) = (absolute_time - base_time - S.base) * S.abs_rate
 
-  filling (B.timestamp - NS.start) in the above formule for stream time
+  =>
+    (B.timestamp - S.start) = S.offset + (absolute_time - base_time - S.base) * S.abs_rate
+
+  filling (B.timestamp - S.start) in the above formule for stream time
 
   =>
-    stream_time = (absolute_time - base_time - NS.accum) * NS.abs_rate * NS.abs_applied_rate + NS.time
+    stream_time = (S.offset + (absolute_time - base_time - S.base) * S.abs_rate) * S.abs_applied_rate + S.time
 
 This last formula is typically used in sinks to report the current position in
 an accurate and efficient way.