View source for GStreamer Daemon - Receiving Messages from the Bus

{{GStreamer Daemon/Head | previous=Sending Events | next=EOS}}
A [https://gstreamer.freedesktop.org/documentation/application-development/basics/bus.html GStreamer bus] takes care of forwarding messages from a pipeline.  A bus is needed so applications do not need to be thread-aware, even though the underlying pipeline is heavily threaded.  For GStreamer Daemon, the concept of a bus is not important, but we use the terminology to maintain consistency with GStreamer.  What is important is a pipeline can generate messages and GStreamer Daemon allows those messages to flow back to the client application.

This wiki describes the basics of how to interact with GStreamer bus properties. Specifically, how to receive messages from the bus. You'll find that the family of commands used to interact with pipelines are prefixed with '''bus_<action>'''. 

__TOC__

== Read bus ==

In order to read a bus use the following command:

 <b>bus_read <i>&#60;name&#62;</i> </b>
        Read the bus of the <i>pipeline</i>.

== Read and filter bus ==
Sometimes is important to read and filter some messages from the bus, Gstd has the capability to read and filter (ie:error+warning+eos), In order to read and filter use the following command:

 <b>bus_filter <i>&#60;name&#62;</i> <i>&#60;filter&#62;</i> </b>
        Read and filter the bus of the <i>pipeline</i>.

== Bus timeout ==
This command will block while waiting for messages set with the bus_filter command. You can specify a maximum time with the timeout parameter, the time argument is set on nanoseconds. 
 <b>bus_timeout <i>&#60;name&#62;</i> <i>&#60;time in nanoseconds&#62;</i> </b>
        bus timeout of the <i>pipeline</i>.

== Messages ==
There are lots of [https://gstreamer.freedesktop.org/data/doc/gstreamer/head/gstreamer/html/GstMessage.html bus messages] that are defined.  The documentation tends to lag the implementation, so if you want the latest, most complete list of support bus messages, look at the <tt>gstd_msg_type_get_type</tt> table in [https://github.com/RidgeRun/gstd-1.x/blob/master/gstd/gstd_msg_type.c gstd_msg_type.c].

The following table lists the supported bus messages.  You can use either a hyphen or underscore in the bus message name.

{|  class="wikitable col-2-center"
! Bus Message !! Version !! Meaning
|-
| eos || all || After the pipeline sink element finishes processing EOS, the bus reports the event to the application.
|-
| error || all || An element in the pipeline is in the error state.
|-
| warning || all || An element in the pipeline encountered a recoverable error.
|-
| info || all || An element in the pipeline produced some information.
|-
| tag || all || An element in the pipeline decoded metadata about the stream.
|-
| buffering || all || An element in the pipeline is buffering would add a delay until the buffer is full.
|-
| clock_lost || all || The pipeline clock is unusable.
|-
| new_clock || all || A new clock was selected for the pipeline.
|-
| structure_change || all || The buffer flow through the pipeline changed.
|-
| stream_status || all || The pipeline started, stopped, or paused.
|-
| element || all || Element specific message.
|-
| segment_start || all || New stream segment being processed.
|-
| segment_done || all || Segment seek requested and segment playback completed.
|-
| duration_changed || all || Stream duration changed.
|-
| latency || all || Pipeline latency changed.
|-
| async_start || all || Pipeline sink element changed its asynchronous processing behavior.
|-
| async_done || all || Pipeline sink element received first stream buffer after changing its asynchronous processing behavior.
|-
| request_state || all || Element in pipeline wants to change its state.
|-
| step_start || all || Pipeline stepping operation started.
|-
| qos || all || A buffer in the pipeline was dropped or an element changed its processing strategy for Quality of Service reasons.
|-
| progress || all || A pipeline element has made progress processing an asynchronous operation.
|-
| toc || all || Pipeline encountered a new table of contents.
|-
| reset_time || all || 
|-
| stream_start || all || Pipeline processing new stream.
|-
| extended || minor > 4 ||
|-
| device_added || minor > 4 ||
|-
| device_removed || minor > 4 ||
|-
| property_notify || minor > 10 ||
|-
| stream_collection || minor > 10 ||
|-
| streams_selected || minor > 10 ||
|-
| redirect || minor > 10 ||
|}

== Examples Application ==
A very useful application using a bus filter is when is needed to know if there is an error or EOS. These examples show how to use the bus filter and bus read. 

=== Error bus filter ===
This example only filter errors with an infinite timeout. 

<br>&rArr; ''Gstd Commands:''
<syntaxhighlight lang="bash" line="line" style="background-color:lavender">
# Create the pipeline that generate an error  
pipeline_create p filesrc location=/tmp/test.avi ! identity error-after=2000 ! avidemux ! avdec_mpeg4 ! fpsdisplaysink 

# Filter only a message error
bus_filter p error

# Play the pipeline
pipeline_play p

# Waiting until bus read a message error 
bus_read p 

</syntaxhighlight>

=== Error bus filter and timeout===
This example only filter errors with a 100s of timeout. If did get an error message it returns

<br>&rArr; ''Gstd Commands:''
<syntaxhighlight lang="bash" line="line" style="background-color:lavender">
# Create the pipeline that generate an error  
pipeline_create p filesrc location=/tmp/test.avi ! identity error-after=2000 ! avidemux ! avdec_mpeg4 ! fpsdisplaysink 

# Filter only a message error
bus_filter p error

# wait 100s to read message error, if not, returns 
bus_timeout p 100000000000 

# Play the pipeline
pipeline_play p

# Waiting until bus read a message error 
bus_read p 

</syntaxhighlight>

=== Error+EOS bus filter ===
This example filter errors and eos messages with an infinite timeout. 

<br>&rArr; ''Gstd Commands:''
<syntaxhighlight lang="bash" line="line" style="background-color:lavender">
# Create the pipeline that generate an eos  
pipeline_create p filesrc location=/tmp/test.avi  ! avidemux ! avdec_mpeg4 ! fpsdisplaysink 

# Filter a message error and EOS message
bus_filter p error+eos

# Play the pipeline
pipeline_play p

# Waiting until bus read a message error or eos message
bus_read p 

</syntaxhighlight>

<br>&rArr; ''Example Gstd <tt>bus_read</tt> Response:''
<syntaxhighlight lang="bash" line="line" style="background-color:lavender">

{
  "code" : 0,
  "description" : "Success",
  "response" : {
    "type" : "error",
    "source" : "avidemux2",
    "timestamp" : "99:99:99.999999999",
    "seqnum" : 104,
    "message" : "Internal data stream error.",
    "debug" : "gstavidemux.c(5713): gst_avi_demux_loop (): /GstPipeline:p/GstAviDemux:avidemux2:\nstreaming stopped, reason not-linked"
  }
}
</syntaxhighlight>


{{GStreamer Daemon/Foot | previous=Sending Events | next=EOS}}