gstreamer/docs/design/part-gstpipeline.txt

GstPipeline
-----------

A GstPipeline is usually a toplevel bin and provides all of its 
children with a clock.

A GstPipeline also provides a toplevel GstBus (see part-gstbus.txt)

The pipeline also calculates the stream time based on the selected
clock (see part-clocks.txt).

The pipeline manages the seek operation for the application.


State changes
-------------

In addition to the normal state change procedure of its parent class
GstBin, the pipeline performs the following actions during a state change:

 - NULL -> READY:
    - set the bus to non-flushing

 - READY -> PAUSED:
    - reset the stream time to 0

 - PAUSED -> PLAYING:
    - Select and set a clock.
    - calculate base time using the stream time.

 - PAUSED -> PLAYING:
    - calculate the stream time when the pipeline was stopped.

 - READY -> NULL:
    - set the bus to flushing


Clock selection
---------------

Since all of the children of a GstPipeline must use the same clock, the
pipeline must select a clock.

The default clock selection algorithm works as follows:

 - If the application selected a clock, use that clock. (see below)
 - use clock of source elements (*)
 - use clock of other element, starting from the sinks going upstream. 
   (+)
 - use GstSystemClock.

(*) currently not implemented.
(+) traversing the graph upstream to find the best clock is not implemented,
    currently the first element found that provides a clock is used.

The application can influence this clock selection with two methods:
gst_pipeline_use_clock() and gst_pipeline_auto_clock(). 

The _use_clock() method forces the use of a specific clock on the pipeline 
regardless of what clock providers are children of the pipeline. Setting 
NULL disables the clock completely and makes the pipeline run as fast as 
possible.

The _auto_clock() method removes the fixed clock and reactivates the auto-
matic clock selection algorithm described above.

Seeking
-------

When performing a seek on the pipeline element using gst_element_send_event(),
the pipeline performs the following actions:

 - record the current state of the pipeline.
 - set the pipeline to paused if a FLUSHING seek is requested
 - send the seek event to all sinks
 - when a FLUSH seek is done, the stream_time is set 0 again.
 - restore old state of the pipeline.