docs/design/part-seeking.txt

   1 Seeking
   2 -------
   3
   4 Seeking in GStreamer means configuring the pipeline for playback of the
   5 media between a certain start and stop time, called a segment.
   6
   7 Different kinds of seeking exist:
   8
   9  - immediate seeking with low latency (FLUSH seek)
  10  - seeking without flush, playback will start from the new
  11    position after all the queues are emptied with old data.
  12  - segment seeking with and without FLUSH, this can be used to
  13    implement seamless looping or NLE functionality.
  14
  15 Seeking can be performed in different formats such as time, frames
  16 or samples.
  17
  18 Seeking can be performed to an absolute position or relative to the
  19 current configured segment.
  20
  21 For seeking to work reliably, all plugins in the pipeline need to follow
  22 the well-defined rules in this document.
  23
  24 Non segment seeking will make the pipeline emit EOS when the configured
  25 segment has been played.
  26
  27 Segment seeking will not emit an EOS at the end of the range but will
  28 post a SEGMENT_DONE message on the bus. This message is posted by the
  29 earliest element in the pipeline, typically a demuxer. After receiving
  30 the message, the application can reconnect the pipeline or issue other
  31 seek events in the pipeline. Since the message is posted as early as
  32 possible in the pipeline, the application has some time to issue a new
  33 seek to make the transition seamless. Typically the allowed delay is
  34 defined by the buffer sizes of the sinks as well as the size of any
  35 queues in the pipeline.
  36
  37 The seek can also  change the playback speed of the configured segment.
  38 A speed of 1.0 is normal speed, 2.0 is double speed. Negative values
  39 mean backward playback.
  40
  41
  42 Generating seeking events
  43 -------------------------
  44
  45
  46
  47
  48
  49 The different kinds of seeking methods and their internal workings are
  50 described below.
  51
  52
  53 FLUSH seeking
  54 -------------
  55
  56 This is the most common way of performing a seek in a playback application.
  57 The application issues a seek on the pipeline and the new media is immediatly
  58 played after the seek calls returns.
  59
  60
  61 seeking without FLUSH
  62 ---------------------
  63
  64 This seek type is typically performed after issuing segment seeks to finish
  65 the playback of the pipeline.
  66
  67 Performing a non-flushing seek in a PAUSED pipeline blocks until the pipeline
  68 is set to playing again since all data passing is blocked in the prerolled
  69 sinks.
  70
  71
  72 segment seeking with FLUSH
  73 --------------------------
  74
  75 This seek is typically performed when starting seamless looping.
  76
  77
  78 segment seeking without FLUSH
  79 -----------------------------
  80
  81 This seek is typically performed when continuing seamless looping.
  82