git.maemo.org Git - mafwsubrenderer/blob - gst-plugins-base-subtitles0.10/docs/design/draft-keyframe-force.txt

   1 Forcing keyframes
   2 -----------------
   3
   4 Consider the following use case:
   5
   6   We have a pipeline that performs video and audio capture from a live source,
   7   compresses and muxes the streams and writes the resulting data into a file.
   8
   9   Inside the uncompressed video data we have a specific pattern inserted at
  10   specific moments that should trigger a switch to a new file, meaning, we close
  11   the existing file we are writing to and start writing to a new file.
  12
  13   We want the new file to start with a keyframe so that one can start decoding
  14   the file immediatly.
  15
  16 Components:
  17
  18   1) We need an element that is able to detect the pattern in the video stream.
  19
  20   2) We need to inform the video encoder that it should start encoding a keyframe
  21      starting from exactly the frame with the pattern.
  22
  23   3) We need to inform the demuxer that it should flush out any pending data and
  24      start creating the start of a new file with the keyframe as a first video
  25      frame.
  26
  27   4) We need to inform the sink element that it should start writing to the next
  28      file. This requires application interaction to instruct the sink of the new
  29      filename. The application should also be free to ignore the boundary and
  30      continue to write to the existing file. The application will typically use
  31      an event pad probe to detect the custom event.
  32
  33 Implementation:
  34
  35  The implementation would consist of generating a GST_EVENT_CUSTOM_DOWNSTREAM
  36  event that marks the keyframe boundary. This event is inserted into the
  37  pipeline by the application upon a certain trigger. In the above use case this
  38  trigger would be given by the element that detects the pattern, in the form of
  39  an element message.
  40
  41  The custom event would travel further downstream to instruct encoder, muxer and
  42  sink about the possible switch.
  43
  44  The information passed in the event consists of:
  45
  46   name:  GstForceKeyUnit
  47          (G_TYPE_UINT64)"timestamp"    : the timestamp of the buffer that
  48                                          triggered the event.
  49          (G_TYPE_UINT64)"stream-time"  : the stream position that triggered the
  50                                          event.
  51          (G_TYPE_UINT64)"running-time" : the running time of the stream when the
  52                                          event was triggered.
  53          (G_TYPE_BOOLEAN)"all-headers" : Send all headers, including those in
  54                                          the caps or those sent at the start of
  55                                          the stream.
  56
  57          ....                          : optional other data fields.
  58
  59   Note that this event is purely informational, no element is required to
  60   perform an action but it should forward the event downstream, just like any
  61   other event it does not handle.
  62
  63   Elements understanding the event should behave as follows:
  64
  65   1) The video encoder receives the event before the next frame. Upon reception
  66      of the event it schedules to encode the next frame as a keyframe.
  67      Before pushing out the encoded keyframe it must push the GstForceKeyUnit
  68      event downstream.
  69
  70   2) The muxer receives the GstForceKeyUnit event and flushes out its current state,
  71      preparing to produce data that can be used as a keyunit. Before pushing out
  72      the new data it pushes the GstForceKeyUnit event downstream.
  73
  74   3) The application receives the GstForceKeyUnit on a sink padprobe of the sink
  75      and reconfigures the sink to make it perform new actions after receiving
  76      the next buffer.
  77
  78
  79 Upstream
  80 --------
  81
  82 When using RTP packets can get lost or receivers can be added at any time,
  83 they may request a new key frame.
  84
  85 An downstream element sends an upstream "GstForceKeyUnit" event up the
  86 pipeline.
  87
  88 When an element produces some kind of key unit in output, but has
  89 no such concept in its input (like an encoder that takes raw frames),
  90 it consumes the event (doesn't pass it upstream), and instead sends
  91 a downstream GstForceKeyUnit event and a new keyframe.