:right-sidebar: True Message =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Message(*args, **kwargs) :no-contents-entry: Messages are implemented as a subclass of :obj:`~gi.repository.Gst.MiniObject` with a generic :obj:`~gi.repository.Gst.Structure` as the content. This allows for writing custom messages without requiring an API change while allowing a wide range of different types of messages. Messages are posted by objects in the pipeline and are passed to the application using the :obj:`~gi.repository.Gst.Bus`\. The basic use pattern of posting a message on a :obj:`~gi.repository.Gst.Bus` is as follows: .. code-block:: C :dedent: gst_bus_post (bus, gst_message_new_eos()); A :obj:`~gi.repository.Gst.Element` usually posts messages on the bus provided by the parent container using :func:`~gi.repository.Gst.Element.post_message`. Constructors ------------ .. rst-class:: interim-class .. class:: Message :no-index: .. classmethod:: new_application(src: ~gi.repository.Gst.Object | None, structure: ~gi.repository.Gst.Structure) -> ~gi.repository.Gst.Message Create a new application-typed message. GStreamer will never create these messages; they are a gift from us to you. Enjoy. :param src: The object originating the message. :param structure: the structure for the message. The message will take ownership of the structure. .. classmethod:: new_async_done(src: ~gi.repository.Gst.Object | None, running_time: int) -> ~gi.repository.Gst.Message The message is posted when elements completed an ASYNC state change. ``running_time`` contains the time of the desired running_time when this elements goes to PLAYING. A value of ``GST_CLOCK_TIME_NONE`` for ``running_time`` means that the element has no clock interaction and thus doesn't care about the running_time of the pipeline. :param src: The object originating the message. :param running_time: the desired running_time .. classmethod:: new_async_start(src: ~gi.repository.Gst.Object | None = None) -> ~gi.repository.Gst.Message This message is posted by elements when they start an ASYNC state change. :param src: The object originating the message. .. classmethod:: new_buffering(src: ~gi.repository.Gst.Object | None, percent: int) -> ~gi.repository.Gst.Message Create a new buffering message. This message can be posted by an element that needs to buffer data before it can continue processing. ``percent`` should be a value between 0 and 100. A value of 100 means that the buffering completed. When ``percent`` is < 100 the application should PAUSE a PLAYING pipeline. When ``percent`` is 100, the application can set the pipeline (back) to PLAYING. The application must be prepared to receive BUFFERING messages in the PREROLLING state and may only set the pipeline to PLAYING after receiving a message with ``percent`` set to 100, which can happen after the pipeline completed prerolling. MT safe. :param src: The object originating the message. :param percent: The buffering percent .. classmethod:: new_clock_lost(src: ~gi.repository.Gst.Object | None, clock: ~gi.repository.Gst.Clock) -> ~gi.repository.Gst.Message Create a clock lost message. This message is posted whenever the clock is not valid anymore. If this message is posted by the pipeline, the pipeline will select a new clock again when it goes to PLAYING. It might therefore be needed to set the pipeline to PAUSED and PLAYING again. :param src: The object originating the message. :param clock: the clock that was lost .. classmethod:: new_clock_provide(src: ~gi.repository.Gst.Object | None, clock: ~gi.repository.Gst.Clock, ready: bool) -> ~gi.repository.Gst.Message Create a clock provide message. This message is posted whenever an element is ready to provide a clock or lost its ability to provide a clock (maybe because it paused or became EOS). This message is mainly used internally to manage the clock selection. :param src: The object originating the message. :param clock: the clock it provides :param ready: :const:`True` if the sender can provide a clock .. classmethod:: new_custom(type: ~gi.repository.Gst.MessageType, src: ~gi.repository.Gst.Object | None = None, structure: ~gi.repository.Gst.Structure | None = None) -> ~gi.repository.Gst.Message Create a new custom-typed message. This can be used for anything not handled by other message-specific functions to pass a message to the app. The structure field can be :const:`None`. :param type: The :obj:`~gi.repository.Gst.MessageType` to distinguish messages :param src: The object originating the message. :param structure: the structure for the message. The message will take ownership of the structure. .. classmethod:: new_device_added(src: ~gi.repository.Gst.Object | None, device: ~gi.repository.Gst.Device) -> ~gi.repository.Gst.Message Creates a new device-added message. The device-added message is produced by :obj:`~gi.repository.Gst.DeviceProvider` or a :obj:`~gi.repository.Gst.DeviceMonitor`\. They announce the appearance of monitored devices. .. versionadded:: 1.4 :param src: The :obj:`~gi.repository.Gst.Object` that created the message :param device: The new :obj:`~gi.repository.Gst.Device` .. classmethod:: new_device_changed(src: ~gi.repository.Gst.Object | None, device: ~gi.repository.Gst.Device, changed_device: ~gi.repository.Gst.Device) -> ~gi.repository.Gst.Message Creates a new device-changed message. The device-changed message is produced by :obj:`~gi.repository.Gst.DeviceProvider` or a :obj:`~gi.repository.Gst.DeviceMonitor`\. They announce that a device properties has changed and ``device`` represent the new modified version of ``changed_device``\. .. versionadded:: 1.16 :param src: The :obj:`~gi.repository.Gst.Object` that created the message :param device: The newly created device representing ``changed_device`` with its new configuration. :param changed_device: The old version of the device. .. classmethod:: new_device_removed(src: ~gi.repository.Gst.Object | None, device: ~gi.repository.Gst.Device) -> ~gi.repository.Gst.Message Creates a new device-removed message. The device-removed message is produced by :obj:`~gi.repository.Gst.DeviceProvider` or a :obj:`~gi.repository.Gst.DeviceMonitor`\. They announce the disappearance of monitored devices. .. versionadded:: 1.4 :param src: The :obj:`~gi.repository.Gst.Object` that created the message :param device: The removed :obj:`~gi.repository.Gst.Device` .. classmethod:: new_duration_changed(src: ~gi.repository.Gst.Object | None = None) -> ~gi.repository.Gst.Message Create a new duration changed message. This message is posted by elements that know the duration of a stream when the duration changes. This message is received by bins and is used to calculate the total duration of a pipeline. :param src: The object originating the message. .. classmethod:: new_element(src: ~gi.repository.Gst.Object | None, structure: ~gi.repository.Gst.Structure) -> ~gi.repository.Gst.Message Create a new element-specific message. This is meant as a generic way of allowing one-way communication from an element to an application, for example "the firewire cable was unplugged". The format of the message should be documented in the element's documentation. The structure field can be :const:`None`. :param src: The object originating the message. :param structure: The structure for the message. The message will take ownership of the structure. .. classmethod:: new_eos(src: ~gi.repository.Gst.Object | None = None) -> ~gi.repository.Gst.Message Create a new eos message. This message is generated and posted in the sink elements of a GstBin. The bin will only forward the EOS message to the application if all sinks have posted an EOS message. :param src: The object originating the message. .. classmethod:: new_error(src: ~gi.repository.Gst.Object | None, error: ~gi.repository.GLib.GError, debug: str) -> ~gi.repository.Gst.Message Create a new error message. The message will copy ``error`` and ``debug``\. This message is posted by element when a fatal event occurred. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline. :param src: The object originating the message. :param error: The GError for this message. :param debug: A debugging string. .. classmethod:: new_error_with_details(src: ~gi.repository.Gst.Object | None, error: ~gi.repository.GLib.GError, debug: str, details: ~gi.repository.Gst.Structure | None = None) -> ~gi.repository.Gst.Message Create a new error message. The message will copy ``error`` and ``debug``\. This message is posted by element when a fatal event occurred. The pipeline will probably (partially) stop. The application receiving this message should stop the pipeline. .. versionadded:: 1.10 :param src: The object originating the message. :param error: The GError for this message. :param debug: A debugging string. :param details: A GstStructure with details .. classmethod:: new_have_context(src: ~gi.repository.Gst.Object | None, context: ~gi.repository.Gst.Context) -> ~gi.repository.Gst.Message This message is posted when an element has a new local :obj:`~gi.repository.Gst.Context`\. .. versionadded:: 1.2 :param src: The object originating the message. :param context: the context .. classmethod:: new_info(src: ~gi.repository.Gst.Object | None, error: ~gi.repository.GLib.GError, debug: str) -> ~gi.repository.Gst.Message Create a new info message. The message will make copies of ``error`` and ``debug``\. :param src: The object originating the message. :param error: The GError for this message. :param debug: A debugging string. .. classmethod:: new_info_with_details(src: ~gi.repository.Gst.Object | None, error: ~gi.repository.GLib.GError, debug: str, details: ~gi.repository.Gst.Structure | None = None) -> ~gi.repository.Gst.Message Create a new info message. The message will make copies of ``error`` and ``debug``\. .. versionadded:: 1.10 :param src: The object originating the message. :param error: The GError for this message. :param debug: A debugging string. :param details: A GstStructure with details .. classmethod:: new_instant_rate_request(src: ~gi.repository.Gst.Object | None, rate_multiplier: float) -> ~gi.repository.Gst.Message Creates a new instant-rate-request message. Elements handling the instant-rate-change event must post this message. The message is handled at the pipeline, and allows the pipeline to select the running time when the rate change should happen and to send an ``GST_EVENT_INSTANT_RATE_SYNC_TIME`` event to notify the elements in the pipeline. .. versionadded:: 1.18 :param src: The :obj:`~gi.repository.Gst.Object` that posted the message :param rate_multiplier: the rate multiplier factor that should be applied .. classmethod:: new_latency(src: ~gi.repository.Gst.Object | None = None) -> ~gi.repository.Gst.Message This message can be posted by elements when their latency requirements have changed. :param src: The object originating the message. .. classmethod:: new_need_context(src: ~gi.repository.Gst.Object | None, context_type: str) -> ~gi.repository.Gst.Message This message is posted when an element needs a specific :obj:`~gi.repository.Gst.Context`\. .. versionadded:: 1.2 :param src: The object originating the message. :param context_type: The context type that is needed .. classmethod:: new_new_clock(src: ~gi.repository.Gst.Object | None, clock: ~gi.repository.Gst.Clock) -> ~gi.repository.Gst.Message Create a new clock message. This message is posted whenever the pipeline selects a new clock for the pipeline. :param src: The object originating the message. :param clock: the new selected clock .. classmethod:: new_progress(src: ~gi.repository.Gst.Object | None, type: ~gi.repository.Gst.ProgressType, code: str, text: str) -> ~gi.repository.Gst.Message Progress messages are posted by elements when they use an asynchronous task to perform actions triggered by a state change. ``code`` contains a well defined string describing the action. ``text`` should contain a user visible string detailing the current action. :param src: The object originating the message. :param type: a :obj:`~gi.repository.Gst.ProgressType` :param code: a progress code :param text: free, user visible text describing the progress .. classmethod:: new_property_notify(src: ~gi.repository.Gst.Object, property_name: str, val: ~gi.repository.GObject.Value | None = None) -> ~gi.repository.Gst.Message .. versionadded:: 1.10 :param src: The :obj:`~gi.repository.Gst.Object` whose property changed (may or may not be a :obj:`~gi.repository.Gst.Element`\) :param property_name: name of the property that changed :param val: new property value, or :const:`None` .. classmethod:: new_qos(src: ~gi.repository.Gst.Object | None, live: bool, running_time: int, stream_time: int, timestamp: int, duration: int) -> ~gi.repository.Gst.Message A QOS message is posted on the bus whenever an element decides to drop a buffer because of QoS reasons or whenever it changes its processing strategy because of QoS reasons (quality adjustments such as processing at lower accuracy). This message can be posted by an element that performs synchronisation against the clock (live) or it could be dropped by an element that performs QoS because of QOS events received from a downstream element (!live). ``running_time``\, ``stream_time``\, ``timestamp``\, ``duration`` should be set to the respective running-time, stream-time, timestamp and duration of the (dropped) buffer that generated the QoS event. Values can be left to GST_CLOCK_TIME_NONE when unknown. :param src: The object originating the message. :param live: if the message was generated by a live element :param running_time: the running time of the buffer that generated the message :param stream_time: the stream time of the buffer that generated the message :param timestamp: the timestamps of the buffer that generated the message :param duration: the duration of the buffer that generated the message .. classmethod:: new_redirect(src: ~gi.repository.Gst.Object | None, location: str, tag_list: ~gi.repository.Gst.TagList | None = None, entry_struct: ~gi.repository.Gst.Structure | None = None) -> ~gi.repository.Gst.Message Creates a new redirect message and adds a new entry to it. Redirect messages are posted when an element detects that the actual data has to be retrieved from a different location. This is useful if such a redirection cannot be handled inside a source element, for example when HTTP 302/303 redirects return a non-HTTP URL. The redirect message can hold multiple entries. The first one is added when the redirect message is created, with the given location, tag_list, entry_struct arguments. Use :func:`~gi.repository.Gst.Message.add_redirect_entry` to add more entries. Each entry has a location, a tag list, and a structure. All of these are optional. The tag list and structure are useful for additional metadata, such as bitrate statistics for the given location. By default, message recipients should treat entries in the order they are stored. The recipient should therefore try entry #0 first, and if this entry is not acceptable or working, try entry #1 etc. Senders must make sure that they add entries in this order. However, recipients are free to ignore the order and pick an entry that is "best" for them. One example would be a recipient that scans the entries for the one with the highest bitrate tag. The specified location string is copied. However, ownership over the tag list and structure are transferred to the message. .. versionadded:: 1.10 :param src: The :obj:`~gi.repository.Gst.Object` whose property changed (may or may not be a :obj:`~gi.repository.Gst.Element`\) :param location: location string for the new entry :param tag_list: tag list for the new entry :param entry_struct: structure for the new entry .. classmethod:: new_request_state(src: ~gi.repository.Gst.Object | None, state: ~gi.repository.Gst.State) -> ~gi.repository.Gst.Message This message can be posted by elements when they want to have their state changed. A typical use case would be an audio server that wants to pause the pipeline because a higher priority stream is being played. :param src: The object originating the message. :param state: The new requested state .. classmethod:: new_reset_time(src: ~gi.repository.Gst.Object | None, running_time: int) -> ~gi.repository.Gst.Message This message is posted when the pipeline running-time should be reset to ``running_time``\, like after a flushing seek. :param src: The object originating the message. :param running_time: the requested running-time .. classmethod:: new_segment_done(src: ~gi.repository.Gst.Object | None, format: ~gi.repository.Gst.Format, position: int) -> ~gi.repository.Gst.Message Create a new segment done message. This message is posted by elements that finish playback of a segment as a result of a segment seek. This message is received by the application after all elements that posted a segment_start have posted the segment_done. :param src: The object originating the message. :param format: The format of the position being done :param position: The position of the segment being done .. classmethod:: new_segment_start(src: ~gi.repository.Gst.Object | None, format: ~gi.repository.Gst.Format, position: int) -> ~gi.repository.Gst.Message Create a new segment message. This message is posted by elements that start playback of a segment as a result of a segment seek. This message is not received by the application but is used for maintenance reasons in container elements. :param src: The object originating the message. :param format: The format of the position being played :param position: The position of the segment being played .. classmethod:: new_state_changed(src: ~gi.repository.Gst.Object | None, oldstate: ~gi.repository.Gst.State, newstate: ~gi.repository.Gst.State, pending: ~gi.repository.Gst.State) -> ~gi.repository.Gst.Message Create a state change message. This message is posted whenever an element changed its state. :param src: The object originating the message. :param oldstate: the previous state :param newstate: the new (current) state :param pending: the pending (target) state .. classmethod:: new_state_dirty(src: ~gi.repository.Gst.Object | None = None) -> ~gi.repository.Gst.Message Create a state dirty message. This message is posted whenever an element changed its state asynchronously and is used internally to update the states of container objects. :param src: The object originating the message .. classmethod:: new_step_done(src: ~gi.repository.Gst.Object | None, format: ~gi.repository.Gst.Format, amount: int, rate: float, flush: bool, intermediate: bool, duration: int, eos: bool) -> ~gi.repository.Gst.Message This message is posted by elements when they complete a part, when ``intermediate`` set to :const:`True`, or a complete step operation. ``duration`` will contain the amount of time (in GST_FORMAT_TIME) of the stepped ``amount`` of media in format ``format``\. :param src: The object originating the message. :param format: the format of ``amount`` :param amount: the amount of stepped data :param rate: the rate of the stepped amount :param flush: is this an flushing step :param intermediate: is this an intermediate step :param duration: the duration of the data :param eos: the step caused EOS .. classmethod:: new_step_start(src: ~gi.repository.Gst.Object | None, active: bool, format: ~gi.repository.Gst.Format, amount: int, rate: float, flush: bool, intermediate: bool) -> ~gi.repository.Gst.Message This message is posted by elements when they accept or activate a new step event for ``amount`` in ``format``\. ``active`` is set to :const:`False` when the element accepted the new step event and has queued it for execution in the streaming threads. ``active`` is set to :const:`True` when the element has activated the step operation and is now ready to start executing the step in the streaming thread. After this message is emitted, the application can queue a new step operation in the element. :param src: The object originating the message. :param active: if the step is active or queued :param format: the format of ``amount`` :param amount: the amount of stepped data :param rate: the rate of the stepped amount :param flush: is this an flushing step :param intermediate: is this an intermediate step .. classmethod:: new_stream_collection(src: ~gi.repository.Gst.Object | None, collection: ~gi.repository.Gst.StreamCollection) -> ~gi.repository.Gst.Message Creates a new stream-collection message. The message is used to announce new :obj:`~gi.repository.Gst.StreamCollection` .. versionadded:: 1.10 :param src: The :obj:`~gi.repository.Gst.Object` that created the message :param collection: The :obj:`~gi.repository.Gst.StreamCollection` .. classmethod:: new_stream_start(src: ~gi.repository.Gst.Object | None = None) -> ~gi.repository.Gst.Message Create a new stream_start message. This message is generated and posted in the sink elements of a GstBin. The bin will only forward the STREAM_START message to the application if all sinks have posted an STREAM_START message. :param src: The object originating the message. .. classmethod:: new_stream_status(src: ~gi.repository.Gst.Object | None, type: ~gi.repository.Gst.StreamStatusType, owner: ~gi.repository.Gst.Element) -> ~gi.repository.Gst.Message Create a new stream status message. This message is posted when a streaming thread is created/destroyed or when the state changed. :param src: The object originating the message. :param type: The stream status type. :param owner: the owner element of ``src``\. .. classmethod:: new_streams_selected(src: ~gi.repository.Gst.Object | None, collection: ~gi.repository.Gst.StreamCollection) -> ~gi.repository.Gst.Message Creates a new steams-selected message. The message is used to announce that an array of streams has been selected. This is generally in response to a ``GST_EVENT_SELECT_STREAMS`` event, or when an element (such as decodebin3) makes an initial selection of streams. The message also contains the :obj:`~gi.repository.Gst.StreamCollection` to which the various streams belong to. Users of :func:`~gi.repository.Gst.Message.new_streams_selected` can add the selected streams with :func:`~gi.repository.Gst.Message.streams_selected_add`. .. versionadded:: 1.10 :param src: The :obj:`~gi.repository.Gst.Object` that created the message :param collection: The :obj:`~gi.repository.Gst.StreamCollection` .. classmethod:: new_structure_change(src: ~gi.repository.Gst.Object | None, type: ~gi.repository.Gst.StructureChangeType, owner: ~gi.repository.Gst.Element, busy: bool) -> ~gi.repository.Gst.Message Create a new structure change message. This message is posted when the structure of a pipeline is in the process of being changed, for example when pads are linked or unlinked. ``src`` should be the sinkpad that unlinked or linked. :param src: The object originating the message. :param type: The change type. :param owner: The owner element of ``src``\. :param busy: Whether the structure change is busy. .. classmethod:: new_tag(src: ~gi.repository.Gst.Object | None, tag_list: ~gi.repository.Gst.TagList) -> ~gi.repository.Gst.Message Create a new tag message. The message will take ownership of the tag list. The message is posted by elements that discovered a new taglist. :param src: The object originating the message. :param tag_list: the tag list for the message. .. classmethod:: new_toc(src: ~gi.repository.Gst.Object | None, toc: ~gi.repository.Gst.Toc, updated: bool) -> ~gi.repository.Gst.Message Create a new TOC message. The message is posted by elements that discovered or updated a TOC. :param src: the object originating the message. :param toc: :obj:`~gi.repository.Gst.Toc` structure for the message. :param updated: whether TOC was updated or not. .. classmethod:: new_warning(src: ~gi.repository.Gst.Object | None, error: ~gi.repository.GLib.GError, debug: str) -> ~gi.repository.Gst.Message Create a new warning message. The message will make copies of ``error`` and ``debug``\. :param src: The object originating the message. :param error: The GError for this message. :param debug: A debugging string. .. classmethod:: new_warning_with_details(src: ~gi.repository.Gst.Object | None, error: ~gi.repository.GLib.GError, debug: str, details: ~gi.repository.Gst.Structure | None = None) -> ~gi.repository.Gst.Message Create a new warning message. The message will make copies of ``error`` and ``debug``\. .. versionadded:: 1.10 :param src: The object originating the message. :param error: The GError for this message. :param debug: A debugging string. :param details: A GstStructure with details Methods ------- .. rst-class:: interim-class .. class:: Message :no-index: .. method:: add_redirect_entry(location: str, tag_list: ~gi.repository.Gst.TagList | None = None, entry_struct: ~gi.repository.Gst.Structure | None = None) -> None Creates and appends a new entry. The specified location string is copied. However, ownership over the tag list and structure are transferred to the message. .. versionadded:: 1.10 :param location: location string for the new entry :param tag_list: tag list for the new entry :param entry_struct: structure for the new entry .. method:: get_num_redirect_entries() -> int .. versionadded:: 1.10 .. method:: get_seqnum() -> int Retrieve the sequence number of a message. Messages have ever-incrementing sequence numbers, which may also be set explicitly via :func:`~gi.repository.Gst.Message.set_seqnum`. Sequence numbers are typically used to indicate that a message corresponds to some other set of messages or events, for example a SEGMENT_DONE message corresponding to a SEEK event. It is considered good practice to make this correspondence when possible, though it is not required. Note that events and messages share the same sequence number incrementor; two events or messages will never have the same sequence number unless that correspondence was made explicitly. .. method:: get_stream_status_object() -> ~gi.repository.GObject.Value | None Extracts the object managing the streaming thread from ``message``\. .. method:: get_structure() -> ~gi.repository.Gst.Structure | None Access the structure of the message. .. method:: has_name(name: str) -> bool Checks if ``message`` has the given ``name``\. This function is usually used to check the name of a custom message. :param name: name to check .. method:: parse_async_done() -> int Extract the running_time from the async_done message. MT safe. .. method:: parse_buffering() -> int Extracts the buffering percent from the GstMessage. see also :func:`~gi.repository.Gst.Message.new_buffering`. MT safe. .. method:: parse_buffering_stats() -> ~typing.Tuple[~gi.repository.Gst.BufferingMode, int, int, int] Extracts the buffering stats values from ``message``\. .. method:: parse_clock_lost() -> ~gi.repository.Gst.Clock Extracts the lost clock from the GstMessage. The clock object returned remains valid until the message is freed. MT safe. .. method:: parse_clock_provide() -> ~typing.Tuple[~gi.repository.Gst.Clock, bool] Extracts the clock and ready flag from the GstMessage. The clock object returned remains valid until the message is freed. MT safe. .. method:: parse_context_type() -> ~typing.Tuple[bool, str] Parse a context type from an existing GST_MESSAGE_NEED_CONTEXT message. .. versionadded:: 1.2 .. method:: parse_device_added() -> ~gi.repository.Gst.Device Parses a device-added message. The device-added message is produced by :obj:`~gi.repository.Gst.DeviceProvider` or a :obj:`~gi.repository.Gst.DeviceMonitor`\. It announces the appearance of monitored devices. .. versionadded:: 1.4 .. method:: parse_device_changed() -> ~typing.Tuple[~gi.repository.Gst.Device, ~gi.repository.Gst.Device] Parses a device-changed message. The device-changed message is produced by :obj:`~gi.repository.Gst.DeviceProvider` or a :obj:`~gi.repository.Gst.DeviceMonitor`\. It announces the disappearance of monitored devices. \* It announce that a device properties has changed and ``device`` represents the new modified version of ``changed_device``\. .. versionadded:: 1.16 .. method:: parse_device_removed() -> ~gi.repository.Gst.Device Parses a device-removed message. The device-removed message is produced by :obj:`~gi.repository.Gst.DeviceProvider` or a :obj:`~gi.repository.Gst.DeviceMonitor`\. It announces the disappearance of monitored devices. .. versionadded:: 1.4 .. method:: parse_error() -> ~typing.Tuple[~gi.repository.GLib.GError, str | None] Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done. Typical usage of this function might be: .. code-block:: C :dedent: ... switch (GST_MESSAGE_TYPE (msg)) { case GST_MESSAGE_ERROR: { GError *err = NULL; gchar *dbg_info = NULL; gst_message_parse_error (msg, &err, &dbg_info); g_printerr ("ERROR from element %s: %s\n", GST_OBJECT_NAME (msg->src), err->message); g_printerr ("Debugging info: %s\n", (dbg_info) ? dbg_info : "none"); g_error_free (err); g_free (dbg_info); break; } ... } ... MT safe. .. method:: parse_error_details() -> ~gi.repository.Gst.Structure | None Returns the optional details structure, may be NULL if none. The returned structure must not be freed. .. versionadded:: 1.10 .. method:: parse_group_id() -> ~typing.Tuple[bool, int] Extract the group from the STREAM_START message. .. versionadded:: 1.2 .. method:: parse_have_context() -> ~gi.repository.Gst.Context Extract the context from the HAVE_CONTEXT message. MT safe. .. versionadded:: 1.2 .. method:: parse_info() -> ~typing.Tuple[~gi.repository.GLib.GError, str | None] Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done. MT safe. .. method:: parse_info_details() -> ~gi.repository.Gst.Structure | None Returns the optional details structure, may be NULL if none The returned structure must not be freed. .. versionadded:: 1.10 .. method:: parse_instant_rate_request() -> float Parses the rate_multiplier from the instant-rate-request message. .. versionadded:: 1.18 .. method:: parse_new_clock() -> ~gi.repository.Gst.Clock Extracts the new clock from the GstMessage. The clock object returned remains valid until the message is freed. MT safe. .. method:: parse_progress() -> ~typing.Tuple[~gi.repository.Gst.ProgressType, str, str] Parses the progress ``type``\, ``code`` and ``text``\. .. method:: parse_property_notify() -> ~typing.Tuple[~gi.repository.Gst.Object, str, ~gi.repository.GObject.Value | None] Parses a property-notify message. These will be posted on the bus only when set up with :func:`~gi.repository.Gst.Element.add_property_notify_watch` or :func:`~gi.repository.Gst.Element.add_property_deep_notify_watch`. .. versionadded:: 1.10 .. method:: parse_qos() -> ~typing.Tuple[bool, int, int, int, int] Extract the timestamps and live status from the QoS message. The returned values give the running_time, stream_time, timestamp and duration of the dropped buffer. Values of GST_CLOCK_TIME_NONE mean unknown values. MT safe. .. method:: parse_qos_stats() -> ~typing.Tuple[~gi.repository.Gst.Format, int, int] Extract the QoS stats representing the history of the current continuous pipeline playback period. When ``format`` is ``GST_FORMAT_UNDEFINED`` both ``dropped`` and ``processed`` are invalid. Values of -1 for either ``processed`` or ``dropped`` mean unknown values. MT safe. .. method:: parse_qos_values() -> ~typing.Tuple[int, float, int] Extract the QoS values that have been calculated/analysed from the QoS data MT safe. .. method:: parse_redirect_entry(entry_index: int) -> ~typing.Tuple[str, ~gi.repository.Gst.TagList | None, ~gi.repository.Gst.Structure | None] Parses the location and/or structure from the entry with the given index. The index must be between 0 and :func:`~gi.repository.Gst.Message.get_num_redirect_entries` - 1. Returned pointers are valid for as long as this message exists. .. versionadded:: 1.10 :param entry_index: index of the entry to parse .. method:: parse_request_state() -> ~gi.repository.Gst.State Extract the requested state from the request_state message. MT safe. .. method:: parse_reset_time() -> int Extract the running-time from the RESET_TIME message. MT safe. .. method:: parse_segment_done() -> ~typing.Tuple[~gi.repository.Gst.Format, int] Extracts the position and format from the segment done message. MT safe. .. method:: parse_segment_start() -> ~typing.Tuple[~gi.repository.Gst.Format, int] Extracts the position and format from the segment start message. MT safe. .. method:: parse_state_changed() -> ~typing.Tuple[~gi.repository.Gst.State, ~gi.repository.Gst.State, ~gi.repository.Gst.State] Extracts the old and new states from the GstMessage. Typical usage of this function might be: .. code-block:: C :dedent: ... switch (GST_MESSAGE_TYPE (msg)) { case GST_MESSAGE_STATE_CHANGED: { GstState old_state, new_state; gst_message_parse_state_changed (msg, &old_state, &new_state, NULL); g_print ("Element %s changed state from %s to %s.\n", GST_OBJECT_NAME (msg->src), gst_element_state_get_name (old_state), gst_element_state_get_name (new_state)); break; } ... } ... MT safe. .. method:: parse_step_done() -> ~typing.Tuple[~gi.repository.Gst.Format, int, float, bool, bool, int, bool] Extract the values the step_done message. MT safe. .. method:: parse_step_start() -> ~typing.Tuple[bool, ~gi.repository.Gst.Format, int, float, bool, bool] Extract the values from step_start message. MT safe. .. method:: parse_stream_collection() -> ~gi.repository.Gst.StreamCollection Parses a stream-collection message. .. versionadded:: 1.10 .. method:: parse_stream_status() -> ~typing.Tuple[~gi.repository.Gst.StreamStatusType, ~gi.repository.Gst.Element] Extracts the stream status type and owner the GstMessage. The returned owner remains valid for as long as the reference to ``message`` is valid and should thus not be unreffed. MT safe. .. method:: parse_streams_selected() -> ~gi.repository.Gst.StreamCollection Parses a streams-selected message. .. versionadded:: 1.10 .. method:: parse_structure_change() -> ~typing.Tuple[~gi.repository.Gst.StructureChangeType, ~gi.repository.Gst.Element, bool] Extracts the change type and completion status from the GstMessage. MT safe. .. method:: parse_tag() -> ~gi.repository.Gst.TagList Extracts the tag list from the GstMessage. The tag list returned in the output argument is a copy; the caller must free it when done. Typical usage of this function might be: .. code-block:: C :dedent: ... switch (GST_MESSAGE_TYPE (msg)) { case GST_MESSAGE_TAG: { GstTagList *tags = NULL; gst_message_parse_tag (msg, &tags); g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src)); handle_tags (tags); gst_tag_list_unref (tags); break; } ... } ... MT safe. .. method:: parse_toc() -> ~typing.Tuple[~gi.repository.Gst.Toc, bool] Extract the TOC from the :obj:`~gi.repository.Gst.Message`\. The TOC returned in the output argument is a copy; the caller must free it with :func:`~gi.repository.Gst.toc_unref` when done. MT safe. .. method:: parse_warning() -> ~typing.Tuple[~gi.repository.GLib.GError, str | None] Extracts the GError and debug string from the GstMessage. The values returned in the output arguments are copies; the caller must free them when done. MT safe. .. method:: parse_warning_details() -> ~gi.repository.Gst.Structure | None Returns the optional details structure, may be NULL if none The returned structure must not be freed. .. versionadded:: 1.10 .. method:: set_buffering_stats(mode: ~gi.repository.Gst.BufferingMode, avg_in: int, avg_out: int, buffering_left: int) -> None Configures the buffering stats values in ``message``\. :param mode: a buffering mode :param avg_in: the average input rate :param avg_out: the average output rate :param buffering_left: amount of buffering time left in milliseconds .. method:: set_group_id(group_id: int) -> None Sets the group id on the stream-start message. All streams that have the same group id are supposed to be played together, i.e. all streams inside a container file should have the same group id but different stream ids. The group id should change each time the stream is started, resulting in different group ids each time a file is played for example. MT safe. .. versionadded:: 1.2 :param group_id: the group id .. method:: set_qos_stats(format: ~gi.repository.Gst.Format, processed: int, dropped: int) -> None Set the QoS stats representing the history of the current continuous pipeline playback period. When ``format`` is ``GST_FORMAT_UNDEFINED`` both ``dropped`` and ``processed`` are invalid. Values of -1 for either ``processed`` or ``dropped`` mean unknown values. MT safe. :param format: Units of the 'processed' and 'dropped' fields. Video sinks and video filters will use GST_FORMAT_BUFFERS (frames). Audio sinks and audio filters will likely use GST_FORMAT_DEFAULT (samples). :param processed: Total number of units correctly processed since the last state change to READY or a flushing operation. :param dropped: Total number of units dropped since the last state change to READY or a flushing operation. .. method:: set_qos_values(jitter: int, proportion: float, quality: int) -> None Set the QoS values that have been calculated/analysed from the QoS data MT safe. :param jitter: The difference of the running-time against the deadline. :param proportion: Long term prediction of the ideal rate relative to normal rate to get optimal quality. :param quality: An element dependent integer value that specifies the current quality level of the element. The default maximum quality is 1000000. .. method:: set_seqnum(seqnum: int) -> None Set the sequence number of a message. This function might be called by the creator of a message to indicate that the message relates to other messages or events. See :func:`~gi.repository.Gst.Message.get_seqnum` for more information. MT safe. :param seqnum: A sequence number. .. method:: set_stream_status_object(object: ~gi.repository.GObject.Value) -> None Configures the object handling the streaming thread. This is usually a GstTask object but other objects might be added in the future. :param object: the object controlling the streaming .. method:: streams_selected_add(stream: ~gi.repository.Gst.Stream) -> None Adds the ``stream`` to the ``message``\. .. versionadded:: 1.10 :param stream: a :obj:`~gi.repository.Gst.Stream` to add to ``message`` .. method:: streams_selected_get_size() -> int Returns the number of streams contained in the ``message``\. .. versionadded:: 1.10 .. method:: streams_selected_get_stream(idx: int) -> ~gi.repository.Gst.Stream | None Retrieves the :obj:`~gi.repository.Gst.Stream` with index ``index`` from the ``message``\. .. versionadded:: 1.10 :param idx: Index of the stream to retrieve .. method:: writable_structure() -> ~gi.repository.Gst.Structure Get a writable version of the structure. .. versionadded:: 1.14 Fields ------ .. rst-class:: interim-class .. class:: Message :no-index: .. attribute:: cond .. attribute:: lock .. attribute:: mini_object The parent structure .. attribute:: seqnum The sequence number of the message .. attribute:: src The src of the message .. attribute:: timestamp The timestamp of the message .. attribute:: type The :obj:`~gi.repository.Gst.MessageType` of the message