markdown/pwg/advanced/events.md

   1 ---
   2 title: 'Events: Seeking, Navigation and More'
   3 ...
   4
   5 # Events: Seeking, Navigation and More
   6
   7 There are many different event types but only two ways they can travel
   8 in the pipeline: downstream or upstream. It is very important to
   9 understand how both of these methods work because if one element in the
  10 pipeline is not handling them correctly the whole event system of the
  11 pipeline is broken. We will try to explain here how these methods work
  12 and how elements are supposed to implement them.
  13
  14 ## Downstream events
  15
  16 Downstream events are received through the sink pad's event handler, as
  17 set using `gst_pad_set_event_function ()` when the pad was created.
  18
  19 Downstream events can travel in two ways: they can be in-band
  20 (serialised with the buffer flow) or out-of-band (travelling through the
  21 pipeline instantly, possibly not in the same thread as the streaming
  22 thread that is processing the buffers, skipping ahead of buffers being
  23 processed or queued in the pipeline). The most common downstream events
  24 (SEGMENT, CAPS, TAG, EOS) are all serialised with the buffer flow.
  25
  26 Here is a typical event function:
  27
  28 ``` c
  29 static gboolean
  30 gst_my_filter_sink_event (GstPad  *pad, GstObject * parent, GstEvent * event)
  31 {
  32   GstMyFilter *filter;
  33   gboolean ret;
  34
  35   filter = GST_MY_FILTER (parent);
  36   ...
  37
  38   switch (GST_EVENT_TYPE (event)) {
  39     case GST_EVENT_SEGMENT:
  40       /* maybe save and/or update the current segment (e.g. for output
  41        * clipping) or convert the event into one in a different format
  42        * (e.g. BYTES to TIME) or drop it and set a flag to send a segment
  43        * event in a different format later */
  44       ret = gst_pad_push_event (filter->src_pad, event);
  45       break;
  46     case GST_EVENT_EOS:
  47       /* end-of-stream, we should close down all stream leftovers here */
  48       gst_my_filter_stop_processing (filter);
  49       ret = gst_pad_push_event (filter->src_pad, event);
  50       break;
  51     case GST_EVENT_FLUSH_STOP:
  52       gst_my_filter_clear_temporary_buffers (filter);
  53       ret = gst_pad_push_event (filter->src_pad, event);
  54       break;
  55     default:
  56       ret = gst_pad_event_default (pad, parent, event);
  57       break;
  58   }
  59
  60   ...
  61   return ret;
  62 }
  63
  64 ```
  65
  66 If your element is chain-based, you will almost always have to implement
  67 a sink event function, since that is how you are notified about
  68 segments, caps and the end of the stream.
  69
  70 If your element is exclusively loop-based, you may or may not want a
  71 sink event function (since the element is driving the pipeline it will
  72 know the length of the stream in advance or be notified by the flow
  73 return value of `gst_pad_pull_range()`. In some cases even loop-based
  74 element may receive events from upstream though (for example audio
  75 decoders with an id3demux or apedemux element in front of them, or
  76 demuxers that are being fed input from sources that send additional
  77 information about the stream in custom events, as DVD sources do).
  78
  79 ## Upstream events
  80
  81 Upstream events are generated by an element somewhere downstream in the
  82 pipeline (example: a video sink may generate navigation events that
  83 informs upstream elements about the current position of the mouse
  84 pointer). This may also happen indirectly on request of the application,
  85 for example when the application executes a seek on a pipeline this seek
  86 request will be passed on to a sink element which will then in turn
  87 generate an upstream seek event.
  88
  89 The most common upstream events are seek events, Quality-of-Service
  90 (QoS) and reconfigure events.
  91
  92 An upstream event can be sent using the `gst_pad_send_event` function.
  93 This function simply call the default event handler of that pad. The
  94 default event handler of pads is `gst_pad_event_default`, and it
  95 basically sends the event to the peer of the internally linked pad. So
  96 upstream events always arrive on the src pad of your element and are
  97 handled by the default event handler except if you override that handler
  98 to handle it yourself. There are some specific cases where you have to
  99 do that :
 100
 101   - If you have multiple sink pads in your element. In that case you
 102     will have to decide which one of the sink pads you will send the
 103     event to (if not all of them).
 104
 105   - If you need to handle that event locally. For example a navigation
 106     event that you will want to convert before sending it upstream, or a
 107     QoS event that you want to handle.
 108
 109 The processing you will do in that event handler does not really matter
 110 but there are important rules you have to absolutely respect because one
 111 broken element event handler is breaking the whole pipeline event
 112 handling. Here they are :
 113
 114   - Always handle events you won't handle using the default
 115     `gst_pad_event_default` method. This method will depending on the
 116     event, forward the event or drop it.
 117
 118   - If you are generating some new event based on the one you received
 119     don't forget to gst\_event\_unref the event you received.
 120
 121   - Event handler function are supposed to return TRUE or FALSE
 122     indicating if the event has been handled or not. Never simply return
 123     TRUE/FALSE in that handler except if you really know that you have
 124     handled that event.
 125
 126   - Remember that the event handler might be called from a different
 127     thread than the streaming thread, so make sure you use appropriate
 128     locking everywhere.
 129
 130 ## All Events Together
 131
 132 In this chapter follows a list of all defined events that are currently
 133 being used, plus how they should be used/interpreted. You can check the
 134 what type a certain event is using the GST\_EVENT\_TYPE macro (or if you
 135 need a string for debugging purposes you can use
 136 GST\_EVENT\_TYPE\_NAME).
 137
 138 In this chapter, we will discuss the following events:
 139
 140   - [Stream Start](#stream-start)
 141
 142   - [Caps](#caps)
 143
 144   - [Segment](#segment)
 145
 146   - [Tag (metadata)](#tag-metadata)
 147
 148   - [End of Stream (EOS)](#end-of-stream-eos)
 149
 150   - [Table Of Contents](#table-of-contents)
 151
 152   - [Gap](#gap)
 153
 154   - [Flush Start](#flush-start)
 155
 156   - [Flush Stop](#flush-stop)
 157
 158   - [Quality Of Service (QOS)](#quality-of-service-qos)
 159
 160   - [Seek Request](#seek-request)
 161
 162   - [Navigation](#navigation)
 163
 164 For more comprehensive information about events and how they should be
 165 used correctly in various circumstances please consult the GStreamer
 166 design documentation. This section only gives a general overview.
 167
 168 ### Stream Start
 169
 170 WRITEME
 171
 172 ### Caps
 173
 174 The CAPS event contains the format description of the following buffers.
 175 See [Caps negotiation](pwg/advanced/negotiation.md) for more information
 176 about negotiation.
 177
 178 ### Segment
 179
 180 A segment event is sent downstream to announce the range of valid
 181 timestamps in the stream and how they should be transformed into
 182 running-time and stream-time. A segment event must always be sent before
 183 the first buffer of data and after a flush (see above).
 184
 185 The first segment event is created by the element driving the pipeline,
 186 like a source operating in push-mode or a demuxer/decoder operating
 187 pull-based. This segment event then travels down the pipeline and may be
 188 transformed on the way (a decoder, for example, might receive a segment
 189 event in BYTES format and might transform this into a segment event in
 190 TIMES format based on the average bitrate).
 191
 192 Depending on the element type, the event can simply be forwarded using
 193 `gst_pad_event_default ()`, or it should be parsed and a modified event
 194 should be sent on. The last is true for demuxers, which generally have a
 195 byte-to-time conversion concept. Their input is usually byte-based, so
 196 the incoming event will have an offset in byte units
 197 (`GST_FORMAT_BYTES`), too. Elements downstream, however, expect segment
 198 events in time units, so that it can be used to synchronize against the
 199 pipeline clock. Therefore, demuxers and similar elements should not
 200 forward the event, but parse it, free it and send a segment event (in
 201 time units, `GST_FORMAT_TIME`) further downstream.
 202
 203 The segment event is created using the function `gst_event_new_segment
 204 ()`. See the API reference and design document for details about its
 205 parameters.
 206
 207 Elements parsing this event can use gst\_event\_parse\_segment() to
 208 extract the event details. Elements may find the GstSegment API useful
 209 to keep track of the current segment (if they want to use it for output
 210 clipping, for example).
 211
 212 ### Tag (metadata)
 213
 214 Tagging events are being sent downstream to indicate the tags as parsed
 215 from the stream data. This is currently used to preserve tags during
 216 stream transcoding from one format to the other. Tags are discussed
 217 extensively in [Tagging (Metadata and
 218 Streaminfo)](pwg/advanced/tagging.md). Most elements will simply
 219 forward the event by calling `gst_pad_event_default ()`.
 220
 221 The tag event is created using the function `gst_event_new_tag ()`, but
 222 more often elements will send a tag event downstream that will be
 223 converted into a message on the bus by sink elements. All of these
 224 functions require a filled-in taglist as argument, which they will take
 225 ownership of.
 226
 227 Elements parsing this event can use the function `gst_event_parse_tag
 228 ()` to acquire the taglist that the event contains.
 229
 230 ### End of Stream (EOS)
 231
 232 End-of-stream events are sent if the stream that an element sends out is
 233 finished. An element receiving this event (from upstream, so it receives
 234 it on its sinkpad) will generally just process any buffered data (if
 235 there is any) and then forward the event further downstream. The
 236 `gst_pad_event_default ()` takes care of all this, so most elements do
 237 not need to support this event. Exceptions are elements that explicitly
 238 need to close a resource down on EOS, and N-to-1 elements. Note that the
 239 stream itself is *not* a resource that should be closed down on EOS\!
 240 Applications might seek back to a point before EOS and continue playing
 241 again.
 242
 243 The EOS event has no properties, which makes it one of the simplest
 244 events in GStreamer. It is created using the `gst_event_new_eos()`
 245 function.
 246
 247 It is important to note that *only elements driving the pipeline should
 248 ever send an EOS event*. If your element is chain-based, it is not
 249 driving the pipeline. Chain-based elements should just return
 250 GST\_FLOW\_EOS from their chain function at the end of the stream (or
 251 the configured segment), the upstream element that is driving the
 252 pipeline will then take care of sending the EOS event (or alternatively
 253 post a SEGMENT\_DONE message on the bus depending on the mode of
 254 operation). If you are implementing your own source element, you also do
 255 not need to ever manually send an EOS event, you should also just return
 256 GST\_FLOW\_EOS in your create or fill function (assuming your element
 257 derives from GstBaseSrc or GstPushSrc).
 258
 259 ### Table Of Contents
 260
 261 WRITEME
 262
 263 ### Gap
 264
 265 WRITEME
 266
 267 ### Flush Start
 268
 269 The flush start event is sent downstream (in push mode) or upstream (in
 270 pull mode) if all buffers and caches in the pipeline should be emptied.
 271 “Queue” elements will empty their internal list of buffers when they
 272 receive this event, for example. File sink elements (e.g. “filesink”)
 273 will flush the kernel-to-disk cache (`fdatasync ()` or `fflush ()`) when
 274 they receive this event. Normally, elements receiving this event will
 275 simply just forward it, since most filter or filter-like elements don't
 276 have an internal cache of data. `gst_pad_event_default ()` does just
 277 that, so for most elements, it is enough to forward the event using the
 278 default event handler.
 279
 280 As a side-effect of flushing all data from the pipeline, this event
 281 unblocks the streaming thread by making all pads reject data until they
 282 receive a [Flush Stop](#flush-stop) signal (elements trying to push data
 283 will get a FLUSHING flow return and stop processing data).
 284
 285 The flush-start event is created with the `gst_event_new_flush_start
 286 ()`. Like the EOS event, it has no properties. This event is usually
 287 only created by elements driving the pipeline, like source elements
 288 operating in push-mode or pull-range based demuxers/decoders.
 289
 290 ### Flush Stop
 291
 292 The flush-stop event is sent by an element driving the pipeline after a
 293 flush-start and tells pads and elements downstream that they should
 294 accept events and buffers again (there will be at least a SEGMENT event
 295 before any buffers first though).
 296
 297 If your element keeps temporary caches of stream data, it should clear
 298 them when it receives a FLUSH-STOP event (and also whenever its chain
 299 function receives a buffer with the DISCONT flag set).
 300
 301 The flush-stop event is created with `gst_event_new_flush_stop ()`. It
 302 has one parameter that controls if the running-time of the pipeline
 303 should be reset to 0 or not. Normally after a flushing seek, the
 304 running\_time is set back to 0.
 305
 306 ### Quality Of Service (QOS)
 307
 308 The QOS event contains a report about the current real-time performance
 309 of the stream. See more info in [Quality Of Service
 310 (QoS)](pwg/advanced/qos.md).
 311
 312 ### Seek Request
 313
 314 Seek events are meant to request a new stream position to elements. This
 315 new position can be set in several formats (time, bytes or “default
 316 units” \[a term indicating frames for video, channel-independent samples
 317 for audio, etc.\]). Seeking can be done with respect to the end-of-file
 318 or start-of-file, and usually happens in upstream direction (downstream
 319 seeking is done by sending a SEGMENT event with the appropriate offsets
 320 for elements that support that, like filesink).
 321
 322 Elements receiving seek events should, depending on the element type,
 323 either just forward it upstream (filters, decoders), change the format
 324 in which the event is given and then forward it (demuxers), or handle
 325 the event by changing the file pointer in their internal stream resource
 326 (file sources, demuxers/decoders driving the pipeline in pull-mode) or
 327 something else.
 328
 329 Seek events are built up using positions in specified formats (time,
 330 bytes, units). They are created using the function `gst_event_new_seek
 331 ()`. Note that many plugins do not support seeking from the end of the
 332 stream. An element not driving the pipeline and forwarding a seek
 333 request should not assume that the seek succeeded or actually happened,
 334 it should operate based on the SEGMENT events it receives.
 335
 336 Elements parsing this event can do this using `gst_event_parse_seek()`.
 337
 338 ### Navigation
 339
 340 Navigation events are sent upstream by video sinks to inform upstream
 341 elements of where the mouse pointer is, if and where mouse pointer
 342 clicks have happened, or if keys have been pressed or released.
 343
 344 All this information is contained in the event structure which can be
 345 obtained with `gst_event_get_structure ()`.
 346
 347 Check out the navigationtest element in gst-plugins-good for an idea how
 348 to extract navigation information from this event.