| 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? |