markdown/manual/building/bus.md

   1 ---
   2 title: Bus
   3 ...
   4
   5 # Bus
   6
   7 A bus is a simple system that takes care of forwarding messages from the
   8 streaming threads to an application in its own thread context. The
   9 advantage of a bus is that an application does not need to be
  10 thread-aware in order to use GStreamer, even though GStreamer itself is
  11 heavily threaded.
  12
  13 Every pipeline contains a bus by default, so applications do not need to
  14 create a bus or anything. The only thing applications should do is set a
  15 message handler on a bus, which is similar to a signal handler to an
  16 object. When the mainloop is running, the bus will periodically be
  17 checked for new messages, and the callback will be called when any
  18 message is available.
  19
  20 ## How to use a bus
  21
  22 There are two different ways to use a bus:
  23
  24   - Run a GLib/Gtk+ main loop (or iterate the default GLib main context
  25     yourself regularly) and attach some kind of watch to the bus. This
  26     way the GLib main loop will check the bus for new messages and
  27     notify you whenever there are messages.
  28
  29     Typically you would use `gst_bus_add_watch ()` or
  30     `gst_bus_add_signal_watch ()` in this case.
  31
  32     To use a bus, attach a message handler to the bus of a pipeline
  33     using `gst_bus_add_watch ()`. This handler will be called whenever
  34     the pipeline emits a message to the bus. In this handler, check the
  35     signal type (see next section) and do something accordingly. The
  36     return value of the handler should be TRUE to keep the handler
  37     attached to the bus, return FALSE to remove it.
  38
  39   - Check for messages on the bus yourself. This can be done using
  40     `gst_bus_peek ()` and/or `gst_bus_poll ()`.
  41
  42
  43 {{ bus_example.c }}
  44
  45 It is important to know that the handler will be called in the thread
  46 context of the mainloop. This means that the interaction between the
  47 pipeline and application over the bus is *asynchronous*, and thus not
  48 suited for some real-time purposes, such as cross-fading between audio
  49 tracks, doing (theoretically) gapless playback or video effects. All
  50 such things should be done in the pipeline context, which is easiest by
  51 writing a GStreamer plug-in. It is very useful for its primary purpose,
  52 though: passing messages from pipeline to application. The advantage of
  53 this approach is that all the threading that GStreamer does internally
  54 is hidden from the application and the application developer does not
  55 have to worry about thread issues at all.
  56
  57 Note that if you're using the default GLib mainloop integration, you
  58 can, instead of attaching a watch, connect to the “message” signal on
  59 the bus. This way you don't have to `switch()` on all possible message
  60 types; just connect to the interesting signals in form of
  61 “message::\<type\>”, where \<type\> is a specific message type (see
  62 the next section for an explanation of message types).
  63
  64 The above snippet could then also be written as:
  65
  66 ``` c
  67 GstBus *bus;
  68
  69 [..]
  70
  71 bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline);
  72 gst_bus_add_signal_watch (bus);
  73 g_signal_connect (bus, "message::error", G_CALLBACK (cb_message_error), NULL);
  74 g_signal_connect (bus, "message::eos", G_CALLBACK (cb_message_eos), NULL);
  75
  76 [..]
  77
  78 ```
  79
  80 If you aren't using GLib mainloop, the asynchronous message signals
  81 won't be available by default. You can however install a custom sync
  82 handler that wakes up the custom mainloop and that uses
  83 `gst_bus_async_signal_func ()` to emit the signals. (see also
  84 [documentation](http://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstBus.html)
  85 for details)
  86
  87 ## Message types
  88
  89 GStreamer has a few pre-defined message types that can be passed over
  90 the bus. The messages are extensible, however. Plug-ins can define
  91 additional messages, and applications can decide to either have specific
  92 code for those or ignore them. All applications are strongly recommended
  93 to at least handle error messages by providing visual feedback to the
  94 user.
  95
  96 All messages have a message source, type and timestamp. The message
  97 source can be used to see which element emitted the message. For some
  98 messages, for example, only the ones emitted by the top-level pipeline
  99 will be interesting to most applications (e.g. for state-change
 100 notifications). Below is a list of all messages and a short explanation
 101 of what they do and how to parse message-specific content.
 102
 103   - Error, warning and information notifications: those are used by
 104     elements if a message should be shown to the user about the state of
 105     the pipeline. Error messages are fatal and terminate the
 106     data-passing. The error should be repaired to resume pipeline
 107     activity. Warnings are not fatal, but imply a problem nevertheless.
 108     Information messages are for non-problem notifications. All those
 109     messages contain a `GError` with the main error type and message,
 110     and optionally a debug string. Both can be extracted using
 111     `gst_message_parse_error
 112                                             ()`, `_parse_warning ()` and `_parse_info ()`. Both error and debug
 113     strings should be freed after use.
 114
 115   - End-of-stream notification: this is emitted when the stream has
 116     ended. The state of the pipeline will not change, but further media
 117     handling will stall. Applications can use this to skip to the next
 118     song in their playlist. After end-of-stream, it is also possible to
 119     seek back in the stream. Playback will then continue automatically.
 120     This message has no specific arguments.
 121
 122   - Tags: emitted when metadata was found in the stream. This can be
 123     emitted multiple times for a pipeline (e.g. once for descriptive
 124     metadata such as artist name or song title, and another one for
 125     stream-information, such as samplerate and bitrate). Applications
 126     should cache metadata internally. `gst_message_parse_tag
 127                                             ()` should be used to parse the taglist, which should be
 128     `gst_tag_list_unref ()`'ed when no longer needed.
 129
 130   - State-changes: emitted after a successful state change.
 131     `gst_message_parse_state_changed ()` can be used to parse the old
 132     and new state of this transition.
 133
 134   - Buffering: emitted during caching of network-streams. One can
 135     manually extract the progress (in percent) from the message by
 136     extracting the “buffer-percent” property from the structure returned
 137     by `gst_message_get_structure
 138                                                     ()`. See also [Buffering](manual/advanced/buffering.md).
 139
 140   - Element messages: these are special messages that are unique to
 141     certain elements and usually represent additional features. The
 142     element's documentation should mention in detail which element
 143     messages a particular element may send. As an example, the 'qtdemux'
 144     QuickTime demuxer element may send a 'redirect' element message on
 145     certain occasions if the stream contains a redirect instruction.
 146
 147   - Application-specific messages: any information on those can be
 148     extracted by getting the message structure (see above) and reading
 149     its fields. Usually these messages can safely be ignored.
 150
 151     Application messages are primarily meant for internal use in
 152     applications in case the application needs to marshal information
 153     from some thread into the main thread. This is particularly useful
 154     when the application is making use of element signals (as those
 155     signals will be emitted in the context of the streaming thread).