docs/design/part-streams.txt

Streams
-------

  This document describes the objects that are passed from element to
  element in the streaming thread.


Stream objects
~~~~~~~~~~~~~~

The following objects are to be expected in the streaming thread:

 - events
    - STREAM_START      (START)
    - SEGMENT           (SEGMENT)
    - EOS             * (EOS)
    - TAG               (T)
 - buffers            * (B)

Objects marked with * need to be synchronised to the clock in sinks
and live sources.


Typical stream
~~~~~~~~~~~~~~

 A typical stream starts with a stream start event that marks the
 start of the stream, followed by a segment event that marks the
 buffer timestamp range. After that buffers are sent one after the
 other. After the last buffer an EOS marks the end of the stream. No
 more buffers are to be processed after the EOS event.

  +-----+-------+ +-++-+     +-+ +---+
  |START|SEGMENT| |B||B| ... |B| |EOS|
  +-----+-------+ +-++-+     +-+ +---+

  1) STREAM_START
     - marks the start of a stream; unlike the SEGMENT event, there
       will be no STREAM_START event after flushing seeks.

  2) SEGMENT, rate, start/stop, time
     - marks valid buffer timestamp range (start, stop)
     - marks stream_time of buffers (time). This is the stream time of buffers
       with a timestamp of S.start.
     - marks playback rate (rate). This is the required playback rate.
     - marks applied rate (applied_rate). This is the already applied playback
       rate. (See also part-trickmodes.txt)
     - marks running_time of buffers. This is the time used to synchronize
       against the clock.

  3) N buffers
     - displayable buffers are between start/stop of the SEGMENT (S). Buffers
       outside the segment range should be dropped or clipped.

     - running_time: 
     
         if (S.rate > 0.0)
           running_time = (B.timestamp - S.start) / ABS (S.rate) + S.base
         else
           running_time = (S.stop - B.timestamp) / ABS (S.rate) + S.base

        * a monotonically increasing value that can be used to synchronize 
	  against the clock (See also part-synchronisation.txt).

     - stream_time:

         stream_time = (B.timestamp - S.start) * ABS (S.applied_rate) + S.time

        * current position in stream between 0 and duration.

  4) EOS
     - marks the end of data, nothing is to be expected after EOS, elements
       should refuse more data and return GST_FLOW_EOS. A FLUSH_STOP
       event clears the EOS state of an element.


Elements
~~~~~~~~

These events are generated typically either by the GstBaseSrc class for
sources operating in push mode, or by a parser/demuxer operating in pull-mode
and pushing parsed/demuxed data downstream.