docs/design/part-framestep.txt

   1 Frame step
   2 ----------
   3
   4 This document outlines the details of the frame stepping functionality in
   5 GStreamer.
   6
   7 The stepping functionality operates on the current playback segment, position
   8 and rate as it was configured with a regular seek event. In contrast to the seek
   9 event, it operates very closely to the sink and thus has a very low latency and
  10 is not slowed down by queues and does not actually perform any seeking logic.
  11 For this reason we want to include a new API instead of reusing the seek API.
  12
  13 The following requirements are needed:
  14
  15  - The ability to walk forwards and backwards in the stream.
  16  - Arbitrary increments in any supported format (time, frames, bytes ...)
  17  - High speed, minimal overhead. This mechanism is not more expensive than
  18    simple playback.
  19  - switching between forwards and backwards stepping should be fast.
  20  - Maintain synchronisation between streams.
  21  - Get feedback of the amount of skipped data.
  22  - Ability to play a certain amount of data at an arbitrary speed.
  23
  24 We want a system where we can step frames in PAUSED as well as play short
  25 segments of data in PLAYING.
  26
  27
  28 Use Cases
  29 ~~~~~~~~~
  30
  31  * frame stepping in video only pipeline in PAUSED
  32
  33     .-----.    .-------.              .------.    .-------.
  34     | src |    | demux |    .-----.   | vdec |    | vsink |
  35     |    src->sink    src1->|queue|->sink   src->sink     |
  36     '-----'    '-------'    '-----'   '------'    '-------'
  37
  38     - app sets the pipeline to PAUSED to block on the preroll picture
  39     - app seeks to required position in the stream. This can be done with a
  40       positive or negative rate depending on the required frame stepping
  41       direction.
  42     - app steps frames (in GST_FORMAT_DEFAULT or GST_FORMAT_BUFFER). The
  43       pipeline loses its PAUSED state until the required number of frames have
  44       been skipped, it then prerolls again. This skipping is purely done in
  45       the sink.
  46     - sink posts STEP_DONE with amount of frames stepped and corresponding time
  47       interval.
  48
  49  * frame stepping in audio/video pipeline in PAUSED
  50
  51     .-----.    .-------.              .------.    .-------.
  52     | src |    | demux |    .-----.   | vdec |    | vsink |
  53     |    src->sink    src1->|queue|->sink   src->sink     |
  54     '-----'    |       |    '-----'   '------'    '-------'
  55                |       |              .------.    .-------.
  56                |       |    .-----.   | adec |    | asink |
  57                |      src2->|queue|->sink   src->sink     |
  58                '-------'    '-----'   '------'    '-------'
  59
  60
  61     - app sets the pipeline to PAUSED to block on the preroll picture
  62     - app seeks to required position in the stream. This can be done with a
  63       positive or negative rate depending on the required frame stepping
  64       direction.
  65     - app steps frames (in GST_FORMAT_DEFAULT or GST_FORMAT_BUFFER) or an amount
  66       of time on the video sink. The pipeline loses its PAUSED state until the
  67       required number of frames have been skipped, it then prerolls again.
  68       This skipping is purely done in the sink.
  69     - sink posts STEP_DONE with amount of frames stepped and corresponding time
  70       interval.
  71     - the app skips the same amount of time on the audiosink to align the
  72       streams again. When huge amount of video frames are skipped, there needs
  73       to be enough queueing in the pipeline to compensate for the accumulated
  74       audio.
  75
  76  * frame stepping in audio/video pipeline in PLAYING
  77
  78     - app sets the pipeline to PAUSED to block on the preroll picture
  79     - app seeks to required position in the stream. This can be done with a
  80       positive or negative rate depending on the required frame stepping
  81       direction.
  82     - app configures frames steps (in GST_FORMAT_DEFAULT or GST_FORMAT_BUFFER) or
  83       an amount of time on the sink. The step event has a flag indicating live
  84       stepping so that the stepping will only happens in PLAYING.
  85     - app sets pipeline to PLAYING. The pipeline continues PLAYING until it
  86       consumed the amount of time.
  87     - sink posts STEP_DONE with amount of frames stepped and corresponding time
  88       interval. The sink will then wait for another step event. Since the
  89       STEP_DONE message was emited by the sink when it handed off the buffer to
  90       the device, there is usually sufficient time to queue a new STEP event so
  91       that one can seamlessly continue stepping.
  92
  93
  94 events
  95 ~~~~~~
  96
  97 A new GST_EVENT_STEP event is introduced to start the step operation.
  98 The step event is created with the following fields in the structure:
  99
 100   "format", GST_TYPE_FORMAT
 101      The format of the step units
 102
 103   "amount", G_TYPE_UINT64
 104      The amount of units to step. -1 resumes normal non-stepping behaviour to
 105      the end of the segment.
 106
 107   "rate", G_TYPE_DOUBLE
 108      The rate at which the frames should be stepped in PLAYING mode. 1.0 is
 109      the normal playback speed and direction of the segment, 2.0
 110      is double speed. A speed of 0.0 is not allowed. When performing a
 111      flushing step, the speed is not relevant. Note that we don't allow negative
 112      rates here, use a seek with a negative rate first to reverse the playback
 113      direction.
 114
 115   "flush", G_TYPE_BOOLEAN
 116      when flushing is TRUE, the step is performed immediately:
 117
 118       - In the PAUSED state the pipeline loses the PAUSED state, the requested
 119         amount of data is skipped and the pipeline prerolls again when a
 120         non-intermediate step completes.
 121         When the pipeline was stepping while the event is sent, the current step
 122         operation is updated with the new amount and format. The sink will do a
 123         best effort to comply with the new amount.
 124       - In the PLAYING state, the pipeline loses the PLAYING state, the
 125         requested amount of data is skipped (not rendered) from the previous STEP
 126         request or from the position of the last PAUSED if no previous STEP
 127         operation was performed. The pipeline goes back to the PLAYING state
 128         when a non-intermediate step completes.
 129
 130      When flushing is FALSE, the step will be performed later.
 131
 132       - In the PAUSED state the step will be done when going to PLAYING. Any
 133         previous step operation will be overridden with the new STEP event.
 134       - In the PLAYING state the step operation will be performed after the
 135         current step operation completes. If there was no previous step
 136         operation, the step operation will be performed from the position of the
 137         last PAUSED state.
 138
 139   "intermediate", G_TYPE_BOOLEAN
 140      Signal that this step operation is an intermediate step, part of a series
 141      of step operations. It is mostly interesting for stepping in the PAUSED state
 142      because the sink will only perform a preroll after a non-intermediate step
 143      operation completes. Intermediate steps are useful to flush out data from
 144      other sinks in order to not cause excessive queueing. In the PLAYING state
 145      the intermediate flag has no visual effect. In all states, the intermediate
 146      flag is passed to the corresponding GST_MESSAGE_STEP_DONE.
 147
 148
 149 The application will create a STEP event to start or stop the stepping
 150 operation. Both stepping in PAUSED and PLAYING can be performed by means of
 151 the flush flag.
 152
 153 The event is usually sent to the pipeline, which will typically distribute the
 154 event to all of its sinks. For some use cases, like frame stepping on video
 155 frames only, the event should only be sent to the video sink and upon reception
 156 of the STEP_DONE message, one can step the other sinks to align the streams
 157 again.
 158
 159 For large stepping amounts, there needs to be enough queueing in front of all
 160 the sinks. If large steps need to be performed, they can be split up into
 161 smaller step operations using the "intermediate" flag on the step.
 162
 163 Since the step event does not update the base_time of any of the elements, the
 164 sinks should keep track of the amount of stepped data in order to remain
 165 synchronized against the clock.
 166
 167
 168 messages
 169 ~~~~~~~~
 170
 171 A GST_MESSAGE_STEP_START is created. It contains the following fields.
 172
 173   "active"
 174      If the step was queued or activated.
 175
 176   "format", GST_TYPE_FORMAT
 177      The format of the step units that queued/activated.
 178
 179   "amount", G_TYPE_UINT64
 180      The amount of units that were queued/activated.
 181
 182   "rate", G_TYPE_DOUBLE
 183      The rate and direction at which the frames were queued/activated.
 184
 185   "flush", G_TYPE_BOOLEAN
 186      If the queued/activated frames will be flushed.
 187
 188   "intermediate", G_TYPE_BOOLEAN
 189      If this is an intermediate step operation that queued/activated.
 190
 191 The STEP_START message is emited 2 times:
 192
 193   * first when an element received the STEP event and queued it. The "active"
 194     field will be FALSE in this case.
 195
 196   * second when the step operation started in the streaming thread. The "active"
 197     field is TRUE in this case. After this message is emited, the application
 198     can queue a new step operation.
 199
 200 The purpose of this message is to find out how many elements participate in the
 201 step operation and to queue new step operations at the earliest possible
 202 moment.
 203
 204 A new GST_MESSAGE_STEP_DONE message is created. It contains the following
 205 fields:
 206
 207   "format", GST_TYPE_FORMAT
 208      The format of the step units that completed.
 209
 210   "amount", G_TYPE_UINT64
 211      The amount of units that were stepped.
 212
 213   "rate", G_TYPE_DOUBLE
 214      The rate and direction at which the frames were stepped.
 215
 216   "flush", G_TYPE_BOOLEAN
 217      If the stepped frames were flushed.
 218
 219   "intermediate", G_TYPE_BOOLEAN
 220      If this is an intermediate step operation that completed.
 221
 222   "duration", G_TYPE_UINT64
 223      The total duration of the stepped units in GST_FORMAT_TIME.
 224
 225   "eos", G_TYPE_BOOLEAN
 226      The step ended because of EOS.
 227
 228 The message is emited by the element that performs the step operation. The
 229 purpose is to return the duration in GST_FORMAT_TIME of the stepped media. This
 230 especially interesting to align other stream in case of stepping frames on the
 231 video sink element.
 232
 233
 234 Direction switch
 235 ~~~~~~~~~~~~~~~~
 236
 237 When quickly switching between a forwards and a backwards step of, for example,
 238 one video frame, we need either:
 239
 240   a) issue a new seek to change the direction from the current position.
 241   b) cache a certain number of stepped frames and walk the cache.
 242
 243 option a) might be very slow.
 244 For option b) we would ideally like to offload this caching functionality to a
 245 separate element, which means that we need to forward the STEP event upstream.
 246 It's unclear how this could work in a generic way. What is a demuxer supposed
 247 to do when it received a step event? a flushing seek to what stream position?
 248