wearable/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     - NEW_SEGMENT       (NS)
  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 newsegment 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   |NS| |B||B| ... |B| |EOS|
  33   +--+ +-++-+     +-+ +---+
  34
  35   1) NEW_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
  43   2) N buffers
  44      - displayable buffers are between start/stop of the NEW_SEGMENT. Buffers
  45        outside the segment range should be dropped or clipped.
  46
  47      - running_time:
  48
  49          if (NS.rate > 0.0)
  50            running_time = (B.timestamp - NS.start) / NS.abs_rate + NS.accum
  51          else
  52            running_time = (NS.stop - B.timestamp) / NS.abs_rate + NS.accum
  53
  54         * a monotonically increasing value that can be used to synchronize
  55           against the clock (See also part-synchronisation.txt).
  56
  57      - stream_time:
  58
  59          stream_time = (B.timestamp - NS.start) * NS.abs_applied_rate + NS.time
  60
  61         * current position in stream between 0 and duration.
  62
  63   3) EOS
  64      - marks the end of data, nothing is to be expected after EOS, elements
  65        should refuse more data and return GST_FLOW_UNEXPECTED. A FLUSH_STOP
  66        event clears the EOS state of an element.
  67
  68