wearable/docs/design/part-trickmodes.txt

   1 Trickmodes
   2 ----------
   3
   4 GStreamer provides API for performing various trickmode playback. This includes:
   5
   6  - server side trickmodes
   7  - client side fast/slow forward playback
   8  - client side fast/slow backwards playback
   9
  10 Server side trickmodes mean that a source (network source) can provide a
  11 stream with different playback speed and direction. The client does not have to
  12 perform any special algorithms to decode this stream.
  13
  14 Client side trickmodes mean that the decoding client (GStreamer) performs the
  15 needed algorithms to change the direction and speed of the media file.
  16
  17 Seeking can both be done in a playback pipeline and a transcoding pipeline.
  18
  19
  20 General seeking overview
  21 ~~~~~~~~~~~~~~~~~~~~~~~~~
  22
  23 Consider a typical playback pipeline:
  24
  25                           .---------.  .------.
  26               .-------.   | decoder |->| sink |
  27   .--------.  |       |-->'---------'  '------'
  28   | source |->| demux |
  29   '--------'  |       |-->.---------.  .------.
  30               '-------'   | decoder |->| sink |
  31                           '---------'  '------'
  32
  33 The pipeline is initially configured to play back at speed 1.0 starting from
  34 position 0 and stopping at the total duration of the file.
  35
  36 When performing a seek, the following steps have to be taken by the application:
  37
  38 Create a seek event
  39 ^^^^^^^^^^^^^^^^^^^
  40
  41 The seek event contains:
  42
  43 - various flags describing:
  44   - where to seek to (KEY_UNIT)
  45   - how accurate the seek should be (ACCURATE)
  46   - how to perform the seek (FLUSH)
  47   - what to do when the stop position is reached (SEGMENT).
  48   - extra playback options (SKIP)
  49 - a format to seek in, this can be time, bytes, units (frames, samples), ...
  50 - a playback rate, 1.0 is normal playback speed, positive values bigger than 1.0
  51   mean fast playback. negative values mean reverse playback. A playback speed of
  52   0.0 is not allowed (but is equivalent to PAUSING the pipeline).
  53 - a start position, this value has to be between 0 and the total duration of the
  54   file. It can also be relative to the previously configured start value.
  55 - a stop position, this value has to be between 0 and the total duration. It can
  56   also be relative to the previously configured stop value.
  57
  58 See also gst_event_new_seek().
  59
  60
  61 Send the seek event
  62 ^^^^^^^^^^^^^^^^^^^
  63
  64 Send the new seek event to the pipeline with gst_element_send_event().
  65
  66 By default the pipeline will send the event to all sink elements.
  67 By default an element will forward the event upstream on all sinkpads.
  68 Elements can modify the format of the seek event. The most common format is
  69 GST_FORMAT_TIME.
  70
  71 One element will actually perform the seek, this is usually the demuxer or
  72 source element. For more information on how to perform the different seek
  73 types see part-seeking.txt.
  74
  75 For client side trickmode a NEW_SEGMENT event will be sent downstream with
  76 the new rate and start/stop positions. All elements prepare themselves to
  77 handle the rate (see below). The applied rate of the NEW_SEGMENT event will
  78 be set to 1.0 to indicate that no rate adjustment has been done.
  79
  80 for server side trick mode a NEW_SEGMENT event is sent downstream with a
  81 rate of 1.0 and the start/stop positions. The elements will configure themselves
  82 for normal playback speed since the server will perform the rate conversions.
  83 The applied rate will be set to the rate that will be applied by the server. This
  84 is done to insure that the position reporting performed in the sink is aware
  85 of the trick mode.
  86
  87 When the seek succeeds, the _send_event() function will return TRUE.
  88
  89
  90 Server side trickmode
  91 ~~~~~~~~~~~~~~~~~~~~~
  92
  93 The source element operates in push mode. It can reopen a server connection requesting
  94 a new byte or time position and a new playback speed. The capabilities can be queried
  95 from the server when the connection is opened.
  96
  97 We assume the source element is derived from the GstPushSrc base class. The base source
  98 should be configured with gst_base_src_set_format (src, GST_FORMAT_TIME).
  99
 100 The do_seek method will be called on the push src subclass with the seek information
 101 passed in the GstSegment argument.
 102
 103 The rate value in the segment should be used to reopen the connection to the server
 104 requesting data at the new speed and possibly a new playback position.
 105
 106 When the server connection was successfully reopened, set the rate of the segment
 107 to 1.0 so that the client side trickmode is not enabled. The applied rate in the
 108 segment is set to the rate transformation done by the server.
 109
 110 Alternatively a combination of client side and serverside trickmode can be used, for
 111 example if the server does not support certain rates, the client can perform rate
 112 conversion for the remainder.
 113
 114
 115                source               server
 116    do_seek       |                     |
 117      ----------->|                     |
 118                  |  reopen connection  |
 119                  |-------------------->|
 120                  |                     .
 121                  |   success           .
 122                  |<--------------------|
 123        modify    |                     |
 124      rate to 1.0 |                     |
 125                  |                     |
 126       return     |                     |
 127        TRUE      |                     |
 128                  |                     |
 129
 130 After performing the seek, the source will inform the downstream elements of the
 131 new segment that is to be played back. Since the segment will have a rate of 1.0,
 132 no client side trick modes are enabled. The segment will have an applied rate
 133 different from 1.0 to indicate that the media contains data with non-standard
 134 playback speed or direction.
 135
 136
 137 client side forward trickmodes
 138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 139
 140 The seek happens as stated above. a NEW_SEGMENT event is sent downstream with a rate
 141 different from 1.0. Plugins receiving the NEW_SEGMENT can decide to perform the
 142 rate conversion of the media data (retimestamp video frames, resample audio, ...).
 143
 144 If a plugin decides to resample or retimestamp, it should modify the NEW_SEGMENT with
 145 a rate of 1.0 and update the applied rate so that downstream elements don't resample
 146 again but are aware that the media has been modified.
 147
 148 The GStreamer base audio and video sinks will resample automatically if they receive
 149 a NEW_SEGMENT event with a rate different from 1.0. The position reporting in the
 150 base audio and video sinks will also depend on the applied rate of the segment
 151 information.
 152
 153 When the SKIP flag is set, frames can be dropped in the elements. If S is the
 154 speedup factor, a good algorithm for implementing frame skipping is to send audio in
 155 chunks of Nms (usualy 300ms is good) and then skip ((S-1) * Nns) of audio data.
 156 For the video we send only the keyframes in the (S * Nns) interval. In this
 157 case, the demuxer would scale the timestamps and would set an applied rate of S.
 158
 159
 160 client side backwards trickmode
 161 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 162
 163 For backwards playback the following rules apply:
 164
 165  - the rate in the NEW_SEGMENT is less than 0.0.
 166  - the NEW_SEGMENT start position is less than the stop position, playback will
 167    however happen from stop to start in reverse.
 168  - the time member in the NEW_SEGMENT is set to the stream time of the start
 169    position.
 170
 171 For plugins the following rules apply:
 172
 173  - A source plugin sends data in chunks starting from the last chunk of the
 174    file. The actual bytes are not reversed. Each chunk that is not forward
 175    continuous with the previous chunk is marked with a DISCONT flag.
 176
 177  - A demuxer accumulates the chunks. As soon as a keyframe is found, everything
 178    starting from the keyframe up to the accumulated data is sent downstream.
 179    Timestamps on the buffers are set starting from the stop position to start,
 180    effectively going backwards. Chunks are marked with DISCONT when they are not
 181    forward continuous with the previous buffer.
 182
 183  - A video decoder decodes and accumulates all decoded frames. If a buffer with
 184    a DISCONT, accumulate NEWSEGMENT or EOS is received, all accumulated frames
 185    are sent downsteam in reverse.
 186
 187  - An audio decoder decodes and accumulates all decoded audio. If a buffer with
 188    a DISCONT, accumulate NEWSEGMENT or EOS is received, all accumulated audio
 189    is sent downstream in reverse order. Some audio codecs need the previous
 190    data buffer to decode the current one, in that case, the previous DISCONT
 191    buffer needs to be combined with the last non-DISCONT buffer to generate the
 192    last bit of output.
 193
 194  - A sink reverses (for audio) and retimestamps (audio, video) the buffers
 195    before playing them back. Retimestamping occurs relative to the stop
 196    position, making the timestamps increase again and suitable for synchronizing
 197    against the clock.
 198    Audio sinks also have to perform simple resampling before playing the
 199    samples.
 200
 201  - for transcoding, audio and video resamplers can be used to reverse, resample
 202    and retimestamp the buffers. Any rate adjustments performed on the media must
 203    be added to the applied_rate and subtracted from the rate members in the
 204    NEWSEGMENT event.
 205
 206  In SKIP mode, the same algorithm as for forward SKIP mode can be used.
 207
 208
 209 Notes
 210 ~~~~~
 211
 212  - The clock/running_time keeps running forward.
 213  - backwards playback potentially uses a lot of memory as frames and undecoded
 214    data gets buffered.
 215
 216