docs/design/part-streams.txt

   1 Streams
   2 -------
   3
   4   This document describes the objects that are passed from element to
   5   element in the streaming thread.
   6
   7
   8 Stream objects
   9 ~~~~~~~~~~~~~~
  10
  11 The following objects are to be expected in the streaming thread:
  12
  13  - events
  14     - SEGMENT           (S)
  15     - EOS               (EOS)  *
  16     - TAG               (T)
  17  - buffers              (B)    *
  18
  19 Objects marked with * need to be synchronised to the clock in sinks
  20 and live sources.
  21
  22
  23 Typical stream
  24 ~~~~~~~~~~~~~~
  25
  26  A typical stream starts with a segment event that marks the
  27  buffer timestamp range. After that buffers are sent one after the
  28  other. After the last buffer an EOS marks the end of the stream. No
  29  more buffers are to be processed after the EOS event.
  30
  31   +-+ +-++-+     +-+ +---+
  32   |S| |B||B| ... |B| |EOS|
  33   +-+ +-++-+     +-+ +---+
  34
  35   1) SEGMENT, rate, start/stop, time
  36      - marks valid buffer timestamp range (start, stop)
  37      - marks stream_time of buffers (time). This is the stream time of buffers
  38        with a timestamp of NS.start.
  39      - marks playback rate (rate). This is the required playback rate.
  40      - marks applied rate (applied_rate). This is the already applied playback
  41        rate. (See also part-trickmodes.txt)
  42      - marks running_time of buffers. This is the time used to synchronize
  43        against the clock.
  44
  45   2) N buffers
  46      - displayable buffers are between start/stop of the SEGMENT. Buffers
  47        outside the segment range should be dropped or clipped.
  48
  49      - running_time:
  50
  51          if (NS.rate > 0.0)
  52            running_time = (B.timestamp - NS.start) / NS.abs_rate + NS.accum
  53          else
  54            running_time = (NS.stop - B.timestamp) / NS.abs_rate + NS.accum
  55
  56         * a monotonically increasing value that can be used to synchronize
  57           against the clock (See also part-synchronisation.txt).
  58
  59      - stream_time:
  60
  61          stream_time = (B.timestamp - NS.start) * NS.abs_applied_rate + NS.time
  62
  63         * current position in stream between 0 and duration.
  64
  65   3) EOS
  66      - marks the end of data, nothing is to be expected after EOS, elements
  67        should refuse more data and return GST_FLOW_UNEXPECTED. A FLUSH_STOP
  68        event clears the EOS state of an element.
  69
  70