docs/design/part-events.txt

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