markdown/design/messages.md

   1 # Messages
   2
   3 Messages are refcounted lightweight objects to signal the application of
   4 pipeline events.
   5
   6 Messages are implemented as a subclass of `GstMiniObject` with a generic
   7 `GstStructure` as the content. This allows for writing custom messages
   8 without requiring an API change while allowing a wide range of different
   9 types of messages.
  10
  11 Messages are posted by objects in the pipeline and are passed to the
  12 application using the `GstBus` (See also [gstbus](design/gstbus.md)
  13 and [gstpipeline](design/gstpipeline.md)).
  14
  15 ## Message types
  16
  17 **`GST_MESSAGE_EOS`**: Posted by sink elements. This message is posted to the
  18 application when all the sinks in a pipeline have posted an EOS message. When
  19 performing a flushing seek, the EOS state of the pipeline and sinks is reset.
  20
  21 **`GST_MESSAGE_ERROR`**: An element in the pipeline got into an error state.
  22 The message carries a GError and a debug string describing the error. This
  23 usually means that part of the pipeline is not streaming anymore.
  24
  25 **`GST_MESSAGE_WARNING`**: An element in the pipeline encountered a condition
  26 that made it produce a warning. This could be a recoverable decoding error or
  27 some other non fatal event. The pipeline continues streaming after a warning.
  28
  29 **`GST_MESSAGE_INFO`**: An element produced an informational message.
  30
  31 **`GST_MESSAGE_TAG`**: An element decoded metadata about the stream. The
  32 message carries a `GstTagList` with the tag information.
  33
  34 **`GST_MESSAGE_BUFFERING`**: An element is buffering data and that could
  35 potentially take some time. This message is typically emitted by elements that
  36 perform some sort of network buffering. While the pipeline is buffering it
  37 should remain in the PAUSED state. When the buffering is finished, it can
  38 resume PLAYING.
  39
  40 **`GST_MESSAGE_STATE_CHANGED`**: An element changed state in the pipeline.
  41 The message carries the old, new and pending state of the element.
  42
  43 **`GST_MESSAGE_STATE_DIRTY`**: An internal message used to instruct
  44 a pipeline hierarchy that a state recalculation must be performed because of an
  45 ASYNC state change completed. This message is not used anymore.
  46
  47 **`GST_MESSAGE_STEP_DONE`**: An element stepping frames has finished. This is
  48 currently not used.
  49
  50 **`GST_MESSAGE_CLOCK_PROVIDE`**: An element notifies its capability of
  51 providing a clock for the pipeline.
  52
  53 **`GST_MESSAGE_CLOCK_LOST`**: The current clock, as selected by the pipeline,
  54 became unusable. The pipeline will select a new clock on the next PLAYING state
  55 change.
  56
  57 **`GST_MESSAGE_NEW_CLOCK`**: A new clock was selected for the pipeline.
  58
  59 **`GST_MESSAGE_STRUCTURE_CHANGE`**: The pipeline changed its structure, This
  60 means elements were added or removed or pads were linked or unlinked. This
  61 message is not yet used.
  62
  63 **`GST_MESSAGE_STREAM_STATUS`**: Posted by an element when it
  64 starts/stops/pauses a streaming task. It contains information about the reason
  65 why the stream state changed along with the thread id. The application can use
  66 this information to detect failures in streaming threads and/or to adjust
  67 streaming thread priorities.
  68
  69 **`GST_MESSAGE_APPLICATION`**: The application posted a message. This message
  70 must be used when the application posts a message on the bus.
  71
  72 **`GST_MESSAGE_ELEMENT`**: Element-specific message. See the specific
  73 element's documentation
  74
  75 **`GST_MESSAGE_SEGMENT_START`**: An element started playback of a new
  76 segment. This message is not forwarded to applications but is used internally
  77 to schedule `SEGMENT_DONE` messages.
  78
  79 **`GST_MESSAGE_SEGMENT_DONE`**: An element or bin completed playback of
  80 a segment. This message is only posted on the bus if a SEGMENT seek is
  81 performed on a pipeline.
  82
  83 **`GST_MESSAGE_DURATION_CHANGED`**: An element posts this message when it has
  84 detected or updated the stream duration.
  85
  86 **`GST_MESSAGE_ASYNC_START`**: Posted by sinks when they start an
  87 asynchronous state change.
  88
  89 **`GST_MESSAGE_ASYNC_DONE`**: Posted by sinks when they receive the first
  90 data buffer and complete the asynchronous state change.
  91
  92 **`GST_MESSAGE_LATENCY`**: Posted by elements when the latency in a pipeline
  93 changed and a new global latency should be calculated by the pipeline or
  94 application.
  95
  96 **`GST_MESSAGE_REQUEST_STATE`**: Posted by elements when they want to change
  97 the state of the pipeline they are in. A typical use case would be an audio
  98 sink that requests the pipeline to pause in order to play a higher priority
  99 stream.
 100
 101 **`GST_MESSAGE_STEP_START`**: A stepping operation has started.
 102
 103 **`GST_MESSAGE_QOS`**: A buffer was dropped or an element changed its
 104 processing strategy for Quality of Service reasons.
 105
 106 **`GST_MESSAGE_PROGRESS`**: A progress message was posted. Progress messages
 107 inform the application about the state of asynchronous operations.
 108
 109 **`GST_MESSAGE_TOC`**: A new table of contents (TOC) was found or a previously
 110 found one was updated.
 111
 112 **`GST_MESSAGE_STREAM_START`**: Signals the start of a new stream.