In this chapter follows a list of all defined events that are currently being used, plus how they should be used/interpreted. You can check the what type a certain event is using the GST_EVENT_TYPE macro (or if you need a string for debugging purposes you can use GST_EVENT_TYPE_NAME).
In this chapter, we will discuss the following events:
For more comprehensive information about events and how they should be used correctly in various circumstances please consult the GStreamer design documentation. This section only gives a general overview.
The CAPS event contains the format description of the following buffers. See Caps negotiation for more information about negotiation.
A segment event is sent downstream to announce the range of valid timestamps in the stream and how they should be transformed into running-time and stream-time. A segment event must always be sent before the first buffer of data and after a flush (see above).
The first segment event is created by the element driving the pipeline, like a source operating in push-mode or a demuxer/decoder operating pull-based. This segment event then travels down the pipeline and may be transformed on the way (a decoder, for example, might receive a segment event in BYTES format and might transform this into a segment event in TIMES format based on the average bitrate).
Depending on the element type, the event can simply be forwarded using
gst_pad_event_default (), or it should be parsed
and a modified event should be sent on. The last is true for demuxers,
which generally have a byte-to-time conversion concept. Their input
is usually byte-based, so the incoming event will have an offset in
byte units (
GST_FORMAT_BYTES), too. Elements
downstream, however, expect segment events in time units, so that
it can be used to synchronize against the pipeline clock. Therefore,
demuxers and similar elements should not forward the event, but parse
it, free it and send a segment event (in time units,
GST_FORMAT_TIME) further downstream.
The segment event is created using the function
gst_event_new_segment (). See the API
reference and design document for details about its parameters.
Elements parsing this event can use gst_event_parse_segment() to extract the event details. Elements may find the GstSegment API useful to keep track of the current segment (if they want to use it for output clipping, for example).
Tagging events are being sent downstream to indicate the tags as parsed
from the stream data. This is currently used to preserve tags during
stream transcoding from one format to the other. Tags are discussed
extensively in Chapter 22. Most
elements will simply forward the event by calling
The tag event is created using the function
gst_event_new_tag (), but more often elements will
send a tag event downstream that will be converted into a message
on the bus by sink elements.
All of these functions require a filled-in taglist as
argument, which they will take ownership of.
Elements parsing this event can use the function
gst_event_parse_tag () to acquire the
taglist that the event contains.
End-of-stream events are sent if the stream that an element sends out
is finished. An element receiving this event (from upstream, so it
receives it on its sinkpad) will generally just process any buffered
data (if there is any) and then forward the event further downstream.
gst_pad_event_default () takes care of all
this, so most elements do not need to support this event. Exceptions are
elements that explicitly need to close a resource down on EOS, and
N-to-1 elements. Note that the stream itself is not
a resource that should be closed down on EOS! Applications might seek
back to a point before EOS and continue playing again.
The EOS event has no properties, which makes it one of the simplest
events in GStreamer. It is created using the
It is important to note that only elements driving the pipeline should ever send an EOS event. If your element is chain-based, it is not driving the pipeline. Chain-based elements should just return GST_FLOW_EOS from their chain function at the end of the stream (or the configured segment), the upstream element that is driving the pipeline will then take care of sending the EOS event (or alternatively post a SEGMENT_DONE message on the bus depending on the mode of operation). If you are implementing your own source element, you also do not need to ever manually send an EOS event, you should also just return GST_FLOW_EOS in your create or fill function (assuming your element derives from GstBaseSrc or GstPushSrc).
The flush start event is sent downstream (in push mode) or upstream
(in pull mode) if all buffers and caches in the pipeline should be
emptied. "Queue" elements will
empty their internal list of buffers when they receive this event, for
example. File sink elements (e.g. "filesink") will flush
the kernel-to-disk cache (
fdatasync () or
fflush ()) when they receive this event. Normally,
elements receiving this event will simply just forward it, since most
filter or filter-like elements don't have an internal cache of data.
gst_pad_event_default () does just that, so for
most elements, it is enough to forward the event using the default
As a side-effect of flushing all data from the pipeline, this event unblocks the streaming thread by making all pads reject data until they receive a Flush Stop signal (elements trying to push data will get a FLUSHING flow return and stop processing data).
The flush-start event is created with the
Like the EOS event, it has no properties. This event is usually
only created by elements driving the pipeline, like source elements
operating in push-mode or pull-range based demuxers/decoders.
The flush-stop event is sent by an element driving the pipeline after a flush-start and tells pads and elements downstream that they should accept events and buffers again (there will be at least a SEGMENT event before any buffers first though).
If your element keeps temporary caches of stream data, it should clear them when it receives a FLUSH-STOP event (and also whenever its chain function receives a buffer with the DISCONT flag set).
The flush-stop event is created with
gst_event_new_flush_stop (). It has one
parameter that controls if the running-time of the pipeline should
be reset to 0 or not. Normally aftera flushing seek, the
running_time is set back to 0.
The QOS event contains a report about the current real-time performance of the stream. See more info in Chapter 19.
Seek events are meant to request a new stream position to elements. This new position can be set in several formats (time, bytes or "default units" [a term indicating frames for video, channel-independent samples for audio, etc.]). Seeking can be done with respect to the end-of-file or start-of-file, and usually happens in upstream direction (downstream seeking is done by sending a SEGMENT event with the appropriate offsets for elements that support that, like filesink).
Elements receiving seek events should, depending on the element type, either just forward it upstream (filters, decoders), change the format in which the event is given and then forward it (demuxers), or handle the event by changing the file pointer in their internal stream resource (file sources, demuxers/decoders driving the pipeline in pull-mode) or something else.
Seek events are built up using positions in specified formats (time,
bytes, units). They are created using the function
gst_event_new_seek (). Note that many plugins do
not support seeking from the end of the stream.
An element not driving the pipeline and forwarding a seek
request should not assume that the seek succeeded or actually happened,
it should operate based on the SEGMENT events it receives.
Elements parsing this event can do this using
Navigation events are sent upstream by video sinks to inform upstream elements of where the mouse pointer is, if and where mouse pointer clicks have happened, or if keys have been pressed or released.
All this information is contained in the event structure which can
be obtained with
Check out the navigationtest element in gst-plugins-good for an idea how to extract navigation information from this event.