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 the playback segment.
   6 By default a pipeline will play from position 0 to the total duration of the
   7 media at a rate of 1.0.
   8
   9 A seek is performed by sending a seek event to the sink elements of a
  10 pipeline. Sending the seek event to a bin will by default forward
  11 the event to all sinks in the bin.
  12
  13 When performing a seek, the start and stop values of the segment can be
  14 specified as absolute positions or relative to the currently configured
  15 playback segment. Note that it is not possible to seek relative to the current
  16 playback position. To seek relative to the current playback position, one must
  17 query the position first and then perform an absolute seek to the desired
  18 position.
  19
  20 Feedback of the seek operation can be immediately using the GST_SEEK_FLAG_FLUSH
  21 flag. With this flag, all pending data in the pipeline is discarded and playback
  22 starts from the new position immediately.
  23
  24 When the FLUSH flag is not set, the seek will be queued and executed as
  25 soon as possible, which might be after all queues are emptied.
  26
  27 Seeking can be performed in different formats such as time, frames
  28 or samples.
  29
  30 The seeking can be performed to a nearby key unit or to the exact
  31 (estimated) unit in the media (GST_SEEK_FLAG_KEY_UNIT). See below for more
  32 details on this.
  33
  34 The seeking can be performed by using an estimated target position or in an
  35 accurate way (GST_SEEK_FLAG_ACCURATE). For some formats this can result in
  36 having to scan the complete file in order to accurately find the target unit.
  37 See below for more details on this.
  38
  39 Non segment seeking will make the pipeline emit EOS when the configured
  40 segment has been played.
  41
  42 Segment seeking (using the GST_SEEK_FLAG_SEGMENT) will not emit an EOS at
  43 the end of the playback segment but will post a SEGMENT_DONE message on the
  44 bus. This message is posted by the element driving the playback in the
  45 pipeline, typically a demuxer.  After receiving the message, the application
  46 can reconnect the pipeline or issue other seek events in the pipeline.
  47 Since the message is posted as early as possible in the pipeline, the
  48 application has some time to issue a new seek to make the transition seamless.
  49 Typically the allowed delay is defined by the buffer sizes of the sinks as well
  50 as the size of any queues in the pipeline.
  51
  52 The seek can also change the playback speed of the configured segment.
  53 A speed of 1.0 is normal speed, 2.0 is double speed. Negative values
  54 mean backward playback.
  55
  56 When performing a seek with a playback rate different from 1.0, the
  57 GST_SEEK_FLAG_SKIP flag can be used to instruct decoders and demuxers that they
  58 are allowed to skip decoding. This can be useful when resource consumption is
  59 more important than accurately producing all frames.
  60
  61
  62 Seeking in push based elements
  63 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  64
  65
  66
  67
  68
  69
  70 Generating seeking events
  71 ~~~~~~~~~~~~~~~~~~~~~~~~~
  72
  73 A seek event is created with gst_event_new_seek ().
  74
  75
  76
  77 Seeking variants
  78 ~~~~~~~~~~~~~~~~
  79
  80 The different kinds of seeking methods and their internal workings are
  81 described below.
  82
  83
  84 FLUSH seeking
  85 ^^^^^^^^^^^^^
  86
  87 This is the most common way of performing a seek in a playback application.
  88 The application issues a seek on the pipeline and the new media is immediately
  89 played after the seek call returns.
  90
  91
  92 seeking without FLUSH
  93 ^^^^^^^^^^^^^^^^^^^^^
  94
  95 This seek type is typically performed after issuing segment seeks to finish
  96 the playback of the pipeline.
  97
  98 Performing a non-flushing seek in a PAUSED pipeline blocks until the pipeline
  99 is set to playing again since all data passing is blocked in the prerolled
 100 sinks.
 101
 102
 103 segment seeking with FLUSH
 104 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 105
 106 This seek is typically performed when starting seamless looping.
 107
 108
 109 segment seeking without FLUSH
 110 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 111
 112 This seek is typically performed when continuing seamless looping.
 113
 114
 115
 116 ========================================================================
 117  Demuxer/parser behaviour and SEEK_FLAG_KEY_UNIT and SEEK_FLAG_ACCURATE
 118 ========================================================================
 119
 120 This section aims to explain the behaviour expected by an element with regard
 121 to the KEY_UNIT and ACCURATE seek flags using the example of a parser or
 122 demuxer.
 123
 124 1. DEFAULT BEHAVIOUR:
 125
 126 When a seek to a certain position is requested, the demuxer/parser will
 127 do two things (ignoring flushing and segment seeks, and simplified for
 128 illustration purposes):
 129
 130  - send a segment event with a new start position
 131
 132  - start pushing data/buffers again
 133
 134 To ensure that the data corresponding to the requested seek position
 135 can actually be decoded, a demuxer or parser needs to start pushing data
 136 from a keyframe/keyunit at or before the requested seek position.
 137
 138 Unless requested differently (via the KEY_UNIT flag), the start of the
 139 segment event should be the requested seek position.
 140
 141 So by default a demuxer/parser will then start pushing data from
 142 position DATA and send a segment event with start position SEG_START,
 143 and DATA <= SEG_START.
 144
 145 If DATA < SEG_START, a well-behaved video decoder will start decoding frames
 146 from DATA, but take into account the segment configured by the demuxer via
 147 the segment event, and only actually output decoded video frames from
 148 SEG_START onwards, dropping all decoded frames that are before the
 149 segment start and adjusting the timestamp/duration of the buffer that
 150 overlaps the segment start ("clipping"). A not-so-well-behaved video decoder
 151 will start decoding frames from DATA and push decoded video frames out
 152 starting from position DATA, in which case the frames that are before
 153 the configured segment start will usually be dropped/clipped downstream
 154 (e.g. by the video sink).
 155
 156
 157 2. GST_SEEK_FLAG_KEY_UNIT:
 158
 159 If the KEY_UNIT flag is specified, the demuxer/parser should adjust the
 160 segment start to the position of the key frame closest to the requested
 161 seek position and then start pushing out data from there. The nearest
 162 key frame may be before or after the requested seek position, but many
 163 implementations will only look for the closest keyframe before the
 164 requested position.
 165
 166 Most media players and thumbnailers do (and should be doing) KEY_UNIT seeks
 167 by default, for performance reasons, to ensure almost-instant responsiveness
 168 when scrubbing (dragging the seek slider in PAUSED or PLAYING mode). This
 169 works well for most media, but results in suboptimal behaviour for a small
 170 number of 'odd' files (e.g. files that only have one keyframe at the very
 171 beginning, or only a few keyframes throughout the entire stream). At the
 172 time of writing, a solution for this still needs to be found, but could be
 173 implemented demuxer/parser-side, e.g. make demuxers/parsers ignore the
 174 KEY_UNIT flag if the position adjustment would be larger than 1/10th of
 175 the duration or somesuch.
 176
 177 Summary:
 178
 179  - if the KEY_UNIT flag is *not* specified, the demuxer/parser should
 180    start pushing data from a key unit preceding the seek position
 181    (or from the seek position if that falls on a key unit), and
 182    the start of the new segment should be the requested seek position.
 183
 184  - if the KEY_UNIT flag is specified, the demuxer/parser should start
 185    pushing data from the key unit nearest the seek position (or from
 186    the seek position if that falls on a key unit), and
 187    the start of the new segment should be adjusted to the position of
 188    that key unit which was nearest the requested seek position (ie.
 189    the new segment start should be the position from which data is
 190    pushed).
 191
 192
 193 3. GST_SEEK_FLAG_ACCURATE:
 194
 195 If the ACCURATE flag is specified in a seek request, the demuxer/parser
 196 is asked to do whatever it takes (!) to make sure that the position seeked
 197 to is accurate in relation to the beginning of the stream. This means that
 198 it is not acceptable to just approximate the position (e.g. using an average
 199 bitrate). The achieved position must be exact. In the worst case, the demuxer
 200 or parser needs to push data from the beginning of the file and let downstream
 201 clip everything before the requested segment start.
 202
 203 The ACCURATE flag does not affect what the segment start should be in
 204 relation to the requested seek position. Only the KEY_UNIT flag (or its
 205 absence) has any effect on that.
 206
 207 Video editors and frame-stepping applications usually use the ACCURATE flag.
 208
 209 Summary:
 210
 211  - if the ACCURATE flag is *not* specified, it is up to the demuxer/parser
 212    to decide how exact the seek should be. If the flag is not specified,
 213    the expectation is that the demuxer/parser does a resonable best effort
 214    attempt, trading speed for accuracy. In the absence of an index, the
 215    seek position may be approximated.
 216
 217  - if the ACCURATE flag is specified, absolute accuracy is required, and
 218    speed is of no concern. It is not acceptable to just approximate the
 219    seek position in that case.
 220
 221  - the ACCURATE flag does not imply that the segment starts at the
 222    requested seek position or should be adjusted to the nearest keyframe,
 223    only the KEY_UNIT flag determines that.
 224
 225
 226 4. ACCURATE and KEY_UNIT combinations:
 227
 228 All combinations of these two flags are valid:
 229
 230  - neither flag specified: segment starts at seek position, send data
 231    from preceding key frame (or earlier), feel free to approximate the
 232    seek position
 233
 234  - only KEY_UNIT specified: segment starts from position of nearest
 235    keyframe, send data from nearest keyframe, feel free to approximate the
 236    seek position
 237
 238  - only ACCURATE specified: segment starts at seek position, send data
 239    from preceding key frame (or earlier), do not approximate the seek
 240    position under any circumstances
 241
 242  - ACCURATE | KEY_UNIT specified: segment starts from position of nearest
 243    keyframe, send data from nearest key frame, do not approximate the seek
 244    position under any circumstances
 245