docs/random/events

   1 EARLY DOCUMENT, NOT EXACTLY AS IMPLEMENTED
   2 ------------------------------------------
   3
   4 EVENTS RFC
   5 ==========
   6
   7
   8 Scope
   9 -----
  10 This document tries to describe a possible implementation of an event
  11 system for GStreamer that is able to handle all known problems and works
  12 better than the current (0.3.1) system which evolved over time.
  13
  14
  15 Definition
  16 ----------
  17
  18 The event system is designed to be a mechanism for communication between
  19 elements. They are used to get information to the right point when this
  20 point cannot be known in advance.
  21 Events can be generated by either an element or the application and are
  22 processed by elements.
  23
  24
  25 Event Handling
  26 --------------
  27
  28 Events may be inserted into a pipeline in the PAUSED or PLAYING state. Some
  29 events may travel during the PAUSED state, others may only travel when PLAYING.
  30 The insertion of events during the NULL or READY state should be supported if
  31 at all possible. Events may not be processed in those states though.
  32 After an event is inserted into the pipeline, no assumption may be made on how
  33 the event will be processed. It is eg wrong to assume that an event that is
  34 inserted at the beginning of the pipeline may come out at the end.
  35 There are 3 different directions an event can be processed.
  36
  37 * downstream events
  38
  39   Downstream events are inserted on source pads and travel along the pipeline.
  40   They are handled like buffers and processed in order. If event x is inserted
  41   into a pipeline after buffer y, they are guaranteed to travel in that order.
  42   Downstream events therefore only travel when the pipeline is PLAYING.
  43   Downstream events must be handled by the routines that handle buffers, too.
  44   An example downstream event is the event signalling that the stream has ended.
  45   Please keep in mind that downstream events take the same way as buffers. So a
  46   ghost pad will never receive these events.
  47
  48 * upstream events
  49
  50   Upstream events are inserted on sink pads and travel backwards through the
  51   pipeline. They travel as fast as possible. Source pads must have a handler
  52   function in place to process events. A default handler is implemented.
  53   An example upstream event is an event that seeks inside the stream.
  54   Please keep in mind that upstream events take the same way as buffers in reverse
  55   direction. This means that ghost pads will never receive them.
  56
  57 * vertical events
  58
  59   Vertical events travel from elements to their parents. They are targeted at
  60   the application. Vertical events should be used for information that an
  61   application cannot receive in an easy way by using callbacks or properties.
  62   Vertical events are send to the application by the pipeline that collects those
  63   events and supplies a callback for the application. Vertical events are also only
  64   happening when the pipeline is in PAUSED or PLAZING state.
  65   An example vertical event is the error event informing the application about
  66   unexpected behaviour.
  67
  68
  69 The GstEvent object
  70 -------------------
  71
  72 struct _GstEvent {
  73   GstData data;
  74
  75   GstEventType  type;
  76   guint64       timestamp;
  77   GstObject     *src;
  78
  79   union {
  80     ...
  81   } event_data;
  82 };
  83
  84 data:       The parent object.
  85 type:       The type of the event. GStreamer aims to keep the number of different
  86             plugin types as small as possible.
  87 timestamp:  The time when the event was created. This property is used to identify
  88             duplicated events. If the application inserts an event, the timestamp
  89             is set by the element receiving the event from the application.
  90 src:        The element that created the event. If an application inserts an event,
  91             the element that received the event from the application sets itself as
  92             the source.
  93 event_data: data specific to the event type.
  94
  95
  96 The different event types
  97 -------------------------
  98
  99 The following names in brackets correspong to the event's type property.
 100
 101 GST_EVENT_DISCONTINUOUS
 102 direction(s): downstream
 103 event_data: struct {
 104               GstDiscontType type;
 105             } discontinuous;
 106 This event is used to indicate that the current stream does not continue. Possible
 107 indications are a new stream (type = GST_DISCONT_NEW), the happening of a seek
 108 (type = GST_DISCONT_SEEK) or the end of the stream when no more data is available.
 109 (type = GST_DISCONT_EOS)
 110
 111 GST_EVENT_SEEK
 112 direction(s): upstream
 113 event_data: struct {
 114               GstSeekType type;
 115               gint64 offset;
 116               gboolean flush;
 117             } seek;
 118 This event is used if a seek is needed. Uses include applications or the avi demuxer
 119 element requesting the end of the stream first. The seek can happen absolute (SET),
 120 relative to the current position (CUR) or relative to the end (END). It is possible
 121 to seek by frames (FRAME), time in microseconds (TIME) or bytes (BYTE). This is
 122 indicated by the type field, which takes the values
 123 GST_SEEK_FRAME/TIME/BYTEOFFSET_SET/CUR/END. The offset field indicates how many units
 124 should be seeked. Negative values indicate seeking backwards from the indicated position.
 125 The flush field indicates if buffered data shuold be flushed or discarded.
 126
 127 GST_EVENT_FLUSH
 128 direction(s): upstream
 129 event_data: none
 130 This event indicates that all buffered data should be flushed out immediately.
 131
 132 GST_EVENT_INFO
 133 direction(s): downstream, vertical
 134 event_data: struct {
 135               GstProps *props;
 136             } info;
 137 The Info event is used to transport meta information like bitrate, author, title,
 138 interpret or stream length. Most info events will be emitted vertical and downstream
 139 at the same time. Vertical emission ensures that an application knows about those
 140 properties and downstream emission ensures that elements can compute own information
 141 from these infos. (eg converting stream length in bytes to song length in
 142 microseconds).
 143 Props consist of key / value pairs, where the key is a string identifier and the value
 144 is a GstPropEntry. Many key strings are predefined to allow consistency between elements.
 145 Elements should try to supply any information they can as soon as possible.
 146
 147 GST_EVENT_HAS_INFO
 148 direction(s): upstream
 149 void (*GstHasInfoCallback) (gchar *name, GstPropsEntry *info, gpointer data);
 150 event_data: struct {
 151               GList *info;
 152               GstHasInfoCallback callback;
 153               gpointer data;
 154             } has_info;
 155 The has_info event might be inserted by an application to find out if a pipeline can supply
 156 the specified infos. the info list contains all information that the application is
 157 interested in. If an element can supply information it calls the supplied callback with the
 158 name of the information it can supply, the information if it is already available or NULL and
 159 the data. If this event is destroyed, it will call the callback with name = NULL to indicate
 160 that no more data will be received.
 161 This event will for example be used by playlists when they generate information.
 162
 163 GST_EVENT_ERROR
 164 direction(s): vertical
 165 event_data: struct {
 166               gchar *message
 167             } error;
 168 An error event is emitted, whenever a recoverable error occurs that the application
 169 should know about. The usage should be similar to GLibs GError. An example would be
 170 "connection closed" for a host to host plugin.
 171
 172
 173 Reference Counting
 174 ------------------
 175
 176 References to events are handled similar to buffers. An element receives an event with
 177 a single reference. If it forwards the event, this reference is lost.
 178 Events own a reference to the element that created them. They take care of all of all
 179 data inside them too (strings, props). So elements and applications that want to keep
 180 this information need to copy or add a reference them.
 181
 182
 183 Changing Events
 184 ---------------
 185 It is not allowed to change any data inside an event. Changing events can only be
 186 accomplished by removing the reference to them and not forwarding the event and then
 187 creating a new one.
 188
 189
 190 Default Behaviour
 191 -----------------
 192
 193 * downstream events
 194
 195   These are not handled by default, because they must be handled by the chain handler
 196   of the sink pad. There is however a function called gst_pad_event_default(GstPad *,
 197   GstData *) that will take care of events if your code doesn't want to handle them.
 198   But your code must be aware that not everything that your chain function receives
 199   is a buffer. It could be an event.
 200
 201 * upstream events
 202
 203   Upstream events are handled by a default handler function that is inserted on sink
 204   pads when they are created. This function simply forwards the event to all connected
 205   sink pads of the element. You are free to change this handler.
 206
 207 * vertical events
 208
 209   Vertical events can not be received by elements. Bins have a default handler function
 210   that simply forwards the event to their parent. Pipelines offer callbacks for events.
 211   You may change this handler for your custom bins.
 212
 213
 214 Use Cases
 215 ---------
 216
 217 Following are some simple use cases describing how events are generated. The pipeline
 218 descriptions use gst-launch syntax. "..." indicates that something follows there but is
 219 not important for the example.
 220
 221 * filesrc ! fakesink
 222
 223   - When starting the pipeline, filesrc will emit a DISCONTINUOUS event of type NEW
 224     indicating a new stream.
 225   - Following that event will be an INFO event containing the length of the file/stream
 226     in bytes.
 227   - After the file was played, the filesrc emits a "DISCONTINUOUS" of type EOS.
 228
 229 * filesrc ! mad ! ...
 230
 231   - When starting, filesrc emits a DISCONTINUOUS event followed by an INFO event (see above).
 232     The mad plugin remembers the length of the file and removes the INFO element as it
 233     is no longer of use. The DISCONTINUOUS event has passed mad after making sure, that all
 234     buffers are cleared.
 235   - Mad will emit a SEEK event to BYTEOFFSET_END; offset = -sizeof(ID3_info) to read out the ID3
 236     information.
 237   - Filesrc emits a DISCONTINUOUS event of type SEEK to indicate that it seeked to the end.
 238     This event will not be passed on by mad.
 239   - after receiving the ID 3 information, mad will issue an INFO event containing all data
 240     it extracted. This event will probably only be passed vertical as ID3 information is of
 241     no use to other elements.
 242   - mad then ISSUES a SEEK event of type BYTEOFFSET_SET; offset = 0 to make the filesrc start
 243     playing the file.
 244   - The filesrc will reset its offset and issue a DISCONTINUOUS event of type SEEK. This event
 245     will not be forwarded by mad.
 246   - When playing starts, mad is able to compute bitrate and other information including playing
 247     time with the help of the previous length information supplied by the filesrc. It will then
 248     issue another INFO event with that information. This one will be send downstream and vertical.
 249
 250 * ... ! avimux ! filesink
 251
 252   This example is showing a more exotic way of using events. The reader should be aware that AVI
 253   files have a limited filesize. Only 4 GB are allowed. We now show what happens when the avimux
 254   encoder hits that limit.
 255   - When the internal counter of avimux shows that it is approaching the filesize limit, the
 256     avimux element pushes a buffer containing the footer to the filesink.
 257   - After that it issues a DISCONTINUOUS event of the type DISCONT_NEW indicating a new stream.
 258     The filesink will close the file and reopen a new one.
 259   - The avimux plugin resets its internal size counter and restarts sending data to the new file.
 260
 261 * filesrc ! gunzip ! mikmod ! osssink
 262
 263   (please note that this example is purely theoretical. It should just show ideas)
 264   During playback, an application is interested in "interpret", "title", "length_time",
 265   "length_size" and "URI" of the current stream.
 266   - The application creates a HAS_INFO event and inserts it at the end of the pipeline into the
 267     osssink.
 268   - The osssink cannot supply any info so it forwards the event to the mikmod element.
 269   - The mikmod element can supply "title" and "length_time". It calls the supplied callback twice
 270     and gives these two options. It forwards the event to the gunzip element.
 271   - The gunzip element has already decoded the whole data so it knows the size of the stream. It
 272     calls the callback for "length_size" and forwards the event.
 273   - The filesrc supplies the "URI" and the "length_size" for a second time. It is now up to the
 274     application's callback function to handle this second occurrence of "length_size" information.
 275     The filesrc does not forward the event and dereferences it.
 276   - During disposal of the event, the callback function is called again with name=NULL. The
 277     application now knows that no "title" can be supplied.
 278
 279
 280 Open Questions
 281 --------------
 282
 283 Open questions are issues that should probably be solved by events but can not be solved
 284 currently.
 285
 286 * A filesink needs to be able to inform elements of a restricted file size. Simply closing
 287   the file and opening a new one might not work because elements might need to supply a
 288   footer. (eg avimux)
 289
 290
 291
 292 Issues / changes (to be deleted in final version)
 293 ----------------
 294
 295 ? Are the event directions distinct? Or is it possible that some type of event
 296   can travel eg upstream _and_ vertical?
 297 ? How are upstream/vertical events supposed to be handled if they occur when
 298   the element is READY or NULL? Buffer the event? How many events should be
 299   buffered? Maybe a READY element is attached to a PLAYING/PAUSED one and
 300   constantly receiving events, no?
 301 ! The EOS event was merged with the DISCONTINUOUS event.
 302 ? Does the DISCONTINUOUS event need a "flush" option?
 303 ? Should chain funcs be changed to expect GstData instead of GstBuffer?
 304   It's a little bit misleading if events can arrive there.
 305 ! added information about timestamp.
 306 ? Should timestamps of "follow up" events (eg conversion of seek) keep the
 307   timestamp?
 308 ? src = NULL, when app inserts event?
 309 ? How do elements handle events they cannot use? (eg filesrc getting timebased
 310   seek request)
 311 ? Somebody fix the GST_EVENT_FLUSH part.
 312 ? GValue or GstProps for INFO events? First requires to open up the props headers
 313   and writing some API to ease the retrieval of the elements, the second requires
 314   a rewrite of GST_EVENT_INFO.
 315 ? GQuark/GValue possible in INFO events?
 316 ! Merged INFO and PROPS event. They are nearly the same. Added documentation.
 317 ? Need to work out the ERROR event.
 318 ! changed prototype for gst_pad_event_default to accept buffers so the function checks
 319   if it is an event and not every chain handler has to.
 320 ! added HAS_INFO event. An alternative to the callback function could be another vertical
 321   event.
 322 ? Should HAS_INFO callback supply the element calling the function?
 323 ? Use case one: start with discont event?
 324 ? Do we need a state change event?
 325 ? Should we make elements supply information as soon as possible or only upon HAS_INFO
 326   request?
 327 ? should the second example be done with region requesting instead of events?
 328 ? "location" or "URI"?
 329 ? What about suggesting buffer sizes?
 330 ? What about QoS?