markdown/design/events.md

   1 # Events
   2
   3 Events are objects passed around in parallel to the buffer dataflow to
   4 notify elements of various events.
   5
   6 Events are received on pads using the event function. Some events should
   7 be interleaved with the data stream so they require taking the
   8 `STREAM_LOCK`, others don’t.
   9
  10 Different types of events exist to implement various functionalities.
  11
  12 * `GST_EVENT_FLUSH_START`: data is to be discarded
  13 * `GST_EVENT_FLUSH_STOP`: data is allowed again
  14 * `GST_EVENT_CAPS`: Format information about the following buffers
  15 * `GST_EVENT_SEGMENT`: Timing information for the following buffers
  16 * `GST_EVENT_TAG`: Stream metadata.
  17 * `GST_EVENT_BUFFERSIZE`: Buffer size requirements
  18 * `GST_EVENT_SINK_MESSAGE`: An event turned into a message by sinks
  19 * `GST_EVENT_EOS`: no more data is to be expected on a pad.
  20 * `GST_EVENT_QOS`: A notification of the quality of service of the stream
  21 * `GST_EVENT_SEEK`: A seek should be performed to a new position in the stream
  22 * `GST_EVENT_NAVIGATION`: A navigation event.
  23 * `GST_EVENT_LATENCY`: Configure the latency in a pipeline
  24 * `GST_EVENT_STEP`: Stepping event
  25 * `GST_EVENT_RECONFIGURE`: stream reconfigure event
  26
  27 - `GST_EVENT_DRAIN`: Play all data downstream before returning.
  28   > not yet implemented, under investigation, might be needed to do
  29     still frames in DVD.
  30
  31 ## src pads
  32
  33 A `gst_pad_push_event()` on a srcpad will first store the sticky event
  34 in the sticky array before sending the event to the peer pad. If there
  35 is no peer pad and the event was not stored in the sticky array, FALSE
  36 is returned.
  37
  38 Flushing pads will refuse the events and will not store the sticky
  39 events.
  40
  41 ## sink pads
  42
  43 A `gst_pad_send_event()` on a sinkpad will call the event function on
  44 the pad. If the event function returns success, the sticky event is
  45 stored in the sticky event array and the event is marked for update.
  46
  47 When the pad is flushing, the `_send_event()` function returns FALSE
  48 immediately.
  49
  50 When the next data item is pushed, the pending events are pushed first.
  51
  52 This ensures that the event function is never called for flushing pads
  53 and that the sticky array only contains events for which the event
  54 function returned success.
  55
  56 ## pad link
  57
  58 When linking pads, the srcpad sticky events are marked for update when
  59 they are different from the sinkpad events. The next buffer push will
  60 push the events to the sinkpad.
  61
  62 ## FLUSH_START/STOP
  63
  64 A flush event is sent both downstream and upstream to clear any pending
  65 data from the pipeline. This might be needed to make the graph more
  66 responsive when the normal dataflow gets interrupted by for example a
  67 seek event.
  68
  69 Flushing happens in two stages.
  70
  71 1) a source element sends the `FLUSH_START` event to the downstream peer element.
  72    The downstream element starts rejecting buffers from the upstream elements. It
  73    sends the flush event further downstream and discards any buffers it is
  74    holding as well as return from the chain function as soon as possible.
  75    This makes sure that all upstream elements get unblocked.
  76    This event is not synchronized with the `STREAM_LOCK` and can be done in the
  77    application thread.
  78
  79 2) a source element sends the `FLUSH_STOP` event to indicate
  80    that the downstream element can accept buffers again. The downstream
  81    element sends the flush event to its peer elements. After this step dataflow
  82    continues. The `FLUSH_STOP` call is synchronized with the `STREAM_LOCK` so any
  83    data used by the chain function can safely freed here if needed. Any
  84    pending EOS events should be discarded too.
  85
  86 After the flush completes the second stage, data is flowing again in the
  87 pipeline and all buffers are more recent than those before the flush.
  88
  89 For elements that use the pullrange function, they send both flush
  90 events to the upstream pads in the same way to make sure that the
  91 pullrange function unlocks and any pending buffers are cleared in the
  92 upstream elements.
  93
  94 A `FLUSH_START` may instruct the pipeline to distribute a new `base_time`
  95 to elements so that the `running_time` is reset to 0. (see
  96 [clocks](design/clocks.md) and [synchronisation](design/synchronisation.md)).
  97
  98 ## EOS
  99
 100 The EOS event can only be sent on a sinkpad. It is typically emitted by
 101 the source element when it has finished sending data. This event is
 102 mainly sent in the streaming thread but can also be sent from the
 103 application thread.
 104
 105 The downstream element should forward the EOS event to its downstream
 106 peer elements. This way the event will eventually reach the sinks which
 107 should then post an EOS message on the bus when in PLAYING.
 108
 109 An element might want to flush its internally queued data before
 110 forwarding the EOS event downstream. This flushing can be done in the
 111 same thread as the one handling the EOS event.
 112
 113 For elements with multiple sink pads it might be possible to wait for
 114 EOS on all the pads before forwarding the event.
 115
 116 The EOS event should always be interleaved with the data flow, therefore
 117 the GStreamer core will take the `STREAM_LOCK`.
 118
 119 Sometimes the EOS event is generated by another element than the source,
 120 for example a demuxer element can generate an EOS event before the
 121 source element. This is not a problem, the demuxer does not send an EOS
 122 event to the upstream element but returns `GST_FLOW_EOS`, causing the
 123 source element to stop sending data.
 124
 125 An element that sends EOS on a pad should stop sending data on that pad.
 126 Source elements typically `pause()` their task for that purpose.
 127
 128 By default, a GstBin collects all EOS messages from all its sinks before
 129 posting the EOS message to its parent.
 130
 131 The EOS is only posted on the bus by the sink elements in the PLAYING
 132 state. If the EOS event is received in the PAUSED state, it is queued
 133 until the element goes to PLAYING.
 134
 135 A `FLUSH_STOP` event on an element flushes the EOS state and all pending
 136 EOS messages.
 137
 138 ## SEGMENT
 139
 140 A segment event is sent downstream by an element to indicate that the
 141 following group of buffers start and end at the specified positions. The
 142 newsegment event also contains the playback speed and the applied rate
 143 of the stream.
 144
 145 Since the stream time is always set to 0 at start and after a seek, a 0
 146 point for all next buffer’s timestamps has to be propagated through the
 147 pipeline using the SEGMENT event.
 148
 149 Before sending buffers, an element must send a SEGMENT event. An element
 150 is free to refuse buffers if they were not preceded by a SEGMENT event.
 151
 152 Elements that sync to the clock should store the SEGMENT start and end
 153 values and subtract the start value from the buffer timestamp before
 154 comparing it against the stream time (see [clocks](design/clocks.md)).
 155
 156 An element is allowed to send out buffers with the SEGMENT start time
 157 already subtracted from the timestamp. If it does so, it needs to send a
 158 corrected SEGMENT downstream, ie, one with start time 0.
 159
 160 A SEGMENT event should be generated as soon as possible in the pipeline
 161 and is usually generated by a demuxer or source. The event is generated
 162 before pushing the first buffer and after a seek, right before pushing
 163 the new buffer.
 164
 165 The SEGMENT event should be sent from the streaming thread and should be
 166 serialized with the buffers.
 167
 168 Buffers should be clipped within the range indicated by the newsegment
 169 event start and stop values. Sinks must drop buffers with timestamps out
 170 of the indicated segment range.
 171
 172 ## TAG
 173
 174 The tag event is sent downstream when an element has discovered metadata
 175 tags in a media file. Encoders can use this event to adjust their
 176 tagging system. A tag is serialized with buffers.
 177
 178 ## BUFFERSIZE
 179
 180 > **Note**
 181 >
 182 > This event is not yet implemented.
 183
 184 An element can suggest a buffersize for downstream elements. This is
 185 typically done by elements that produce data on multiple source pads
 186 such as demuxers.
 187
 188 ## QOS
 189
 190 A QOS, or quality of service message, is generated in an element to
 191 report to the upstream elements about the current quality of real-time
 192 performance of the stream. This is typically done by the sinks that
 193 measure the amount of framedrops they have. (see [qos](design/qos.md))
 194
 195 ## SEEK
 196
 197 A seek event is issued by the application to configure the playback
 198 range of a stream. It is called form the application thread and travels
 199 upstream.
 200
 201 The seek event contains the new start and stop position of playback
 202 after the seek is performed. Optionally the stop position can be left at
 203 -1 to continue playback to the end of the stream. The seek event also
 204 contains the new playback rate of the stream, 1.0 is normal playback,
 205 2.0 double speed and negative values mean backwards playback.
 206
 207 A seek usually flushes the graph to minimize latency after the seek.
 208 This behaviour is triggered by using the `SEEK_FLUSH` flag on the seek
 209 event.
 210
 211 The seek event usually starts from the sink elements and travels
 212 upstream from element to element until it reaches an element that can
 213 perform the seek. No intermediate element is allowed to assume that a
 214 seek to this location will happen. It is allowed to modify the start and
 215 stop times if it needs to do so. this is typically the case if a seek is
 216 requested for a non-time position.
 217
 218 The actual seek is performed in the application thread so that success
 219 or failure can be reported as a return value of the seek event. It is
 220 therefore important that before executing the seek, the element acquires
 221 the `STREAM_LOCK` so that the streaming thread and the seek get
 222 serialized.
 223
 224 The general flow of executing the seek with FLUSH is as follows:
 225
 226 1) unblock the streaming threads, they could be blocked in a chain
 227    function. This is done by sending a `FLUSH_START` on all srcpads or by pausing
 228    the streaming task, depending on the seek FLUSH flag.
 229    The flush will make sure that all downstream elements unlock and
 230    that control will return to this element chain/loop function.
 231    We cannot lock the `STREAM_LOCK` before doing this since it might
 232    cause a deadlock.
 233
 234 2) acquire the `STREAM_LOCK`. This will work since the chain/loop function
 235    was unlocked/paused in step 1).
 236
 237 3) perform the seek. since the `STREAM_LOCK` is held, the streaming thread
 238    will wait for the seek to complete. Most likely, the stream thread
 239    will pause because the peer elements are flushing.
 240
 241 4) send a `FLUSH_STOP` event to all peer elements to allow streaming again.
 242
 243 5) create a SEGMENT event to signal the new buffer timestamp base time.
 244    This event must be queued to be sent by the streaming thread.
 245
 246 6) start stopped tasks and unlock the `STREAM_LOCK`, dataflow will continue
 247    now from the new position.
 248
 249 More information about the different seek types can be found in
 250 [seeking](design/seeking.md).
 251
 252 ## NAVIGATION
 253
 254 A navigation event is generated by a sink element to signal the elements
 255 of a navigation event such as a mouse movement or button click.
 256 Navigation events travel upstream.
 257
 258 ## LATENCY
 259
 260 A latency event is used to configure a certain latency in the pipeline.
 261 It contains a single GstClockTime with the required latency. The latency
 262 value is calculated by the pipeline and distributed to all sink elements
 263 before they are set to PLAYING. The sinks will add the configured
 264 latency value to the timestamps of the buffer in order to delay their
 265 presentation. (See also [latency](design/latency.md)).
 266
 267 ## DRAIN
 268
 269 > **Note**
 270 >
 271 > This event is not yet implemented.
 272
 273 Drain event indicates that upstream is about to perform a real-time
 274 event, such as pausing to present an interactive menu or such, and needs
 275 to wait for all data it has sent to be played-out in the sink.
 276
 277 Drain should only be used by live elements, as it may otherwise occur
 278 during prerolling.
 279
 280 Usually after draining the pipeline, an element either needs to modify
 281 timestamps, or FLUSH to prevent subsequent data being discarded at the
 282 sinks for arriving late (only applies during playback scenarios).