1 EARLY DOCUMENT, NOT EXACTLY AS IMPLEMENTED
2 ------------------------------------------
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.
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.
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.
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.
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.
59 Vertical events travel from elements to their parents. They are targetted 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
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
93 event_data: data specific to the event type.
96 The different event types
97 -------------------------
99 The following names in brackets correspong to the event's type property.
101 GST_EVENT_DISCONTINUOUS
102 direction(s): downstream
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)
112 direction(s): upstream
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.
128 direction(s): upstream
130 This event indicates that all buffered data should be flushed out immediately.
133 direction(s): downstream, vertical
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
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 suppy any information they can as soon as possible.
148 direction(s): upstream
149 void (*GstHasInfoCallback) (gchar *name, GstPropsEntry *info, gpointer data);
152 GstHasInfoCallback callback;
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.
164 direction(s): vertical
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.
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 informations need to copy or add a reference them.
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
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.
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.
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.
217 Following are some simple use cases describing how events are generated. The pipeline
218 decriptions use gst-launch syntax. "..." indicates that something follows there but is
219 not important for the example.
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
227 - After the file was played, the filesrc emits a "DISCONTINUOUS" of type EOS.
229 * filesrc ! mad ! ...
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
235 - Mad will emit a SEEK event to BYTEOFFSET_END; offset = -sizeof(ID3_info) to read out the ID3
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
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 informations. This one will be send downstream and vertical.
250 * ... ! avimux ! filesink
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 containig 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.
261 * filesrc ! gunzip ! mikmod ! osssink
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
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 occurence 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.
283 Open questions are issues that should probably be solved by events but can not be solved
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
292 Issues / changes (to be deleted in final version)
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
308 ? src = NULL, when app inserts event?
309 ? How do elements handle events they cannot use? (eg filesrc getting timebased
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
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
327 ? should the second example be done with region requesting instead of events?
328 ? "location" or "URI"?
329 ? What about suggesting buffer sizes?