Gst.Message¶

Fields¶

Name	Type	Access	Description
cond	`GLib.Cond`	r
lock	`GLib.Mutex`	r
mini_object	`Gst.MiniObject`	r/w	the parent structure
seqnum	`int`	r/w	the sequence number of the message
src	`Gst.Object`	r/w	the src of the message
timestamp	`int`	r/w	the timestamp of the message
type	`Gst.MessageType`	r/w	the `Gst.MessageType` of the message

Methods¶

class	`new_application` (src, structure)
class	`new_async_done` (src, running_time)
class	`new_async_start` (src)
class	`new_buffering` (src, percent)
class	`new_clock_lost` (src, clock)
class	`new_clock_provide` (src, clock, ready)
class	`new_custom` (type, src, structure)
class	`new_device_added` (src, device)
class	`new_device_changed` (src, device, changed_device)
class	`new_device_removed` (src, device)
class	`new_duration_changed` (src)
class	`new_element` (src, structure)
class	`new_eos` (src)
class	`new_error` (src, error, debug)
class	`new_error_with_details` (src, error, debug, details)
class	`new_have_context` (src, context)
class	`new_info` (src, error, debug)
class	`new_info_with_details` (src, error, debug, details)
class	`new_instant_rate_request` (src, rate_multiplier)
class	`new_latency` (src)
class	`new_need_context` (src, context_type)
class	`new_new_clock` (src, clock)
class	`new_progress` (src, type, code, text)
class	`new_property_notify` (src, property_name, val)
class	`new_qos` (src, live, running_time, stream_time, timestamp, duration)
class	`new_redirect` (src, location, tag_list, entry_struct)
class	`new_request_state` (src, state)
class	`new_reset_time` (src, running_time)
class	`new_segment_done` (src, format, position)
class	`new_segment_start` (src, format, position)
class	`new_state_changed` (src, oldstate, newstate, pending)
class	`new_state_dirty` (src)
class	`new_step_done` (src, format, amount, rate, flush, intermediate, duration, eos)
class	`new_step_start` (src, active, format, amount, rate, flush, intermediate)
class	`new_stream_collection` (src, collection)
class	`new_stream_start` (src)
class	`new_stream_status` (src, type, owner)
class	`new_streams_selected` (src, collection)
class	`new_structure_change` (src, type, owner, busy)
class	`new_tag` (src, tag_list)
class	`new_toc` (src, toc, updated)
class	`new_warning` (src, error, debug)
class	`new_warning_with_details` (src, error, debug, details)
	`add_redirect_entry` (location, tag_list, entry_struct)
	`get_num_redirect_entries` ()
	`get_seqnum` ()
	`get_stream_status_object` ()
	`get_structure` ()
	`has_name` (name)
	`parse_async_done` ()
	`parse_buffering` ()
	`parse_buffering_stats` ()
	`parse_clock_lost` ()
	`parse_clock_provide` ()
	`parse_context_type` ()
	`parse_device_added` ()
	`parse_device_changed` ()
	`parse_device_removed` ()
	`parse_error` ()
	`parse_error_details` ()
	`parse_group_id` ()
	`parse_have_context` ()
	`parse_info` ()
	`parse_info_details` ()
	`parse_instant_rate_request` ()
	`parse_new_clock` ()
	`parse_progress` ()
	`parse_property_notify` ()
	`parse_qos` ()
	`parse_qos_stats` ()
	`parse_qos_values` ()
	`parse_redirect_entry` (entry_index)
	`parse_request_state` ()
	`parse_reset_time` ()
	`parse_segment_done` ()
	`parse_segment_start` ()
	`parse_state_changed` ()
	`parse_step_done` ()
	`parse_step_start` ()
	`parse_stream_collection` ()
	`parse_stream_status` ()
	`parse_streams_selected` ()
	`parse_structure_change` ()
	`parse_tag` ()
	`parse_toc` ()
	`parse_warning` ()
	`parse_warning_details` ()
	`set_buffering_stats` (mode, avg_in, avg_out, buffering_left)
	`set_group_id` (group_id)
	`set_qos_stats` (format, processed, dropped)
	`set_qos_values` (jitter, proportion, quality)
	`set_seqnum` (seqnum)
	`set_stream_status_object` (object)
	`streams_selected_add` (stream)
	`streams_selected_get_size` ()
	`streams_selected_get_stream` (idx)
	`writable_structure` ()

Details¶

class Gst.Message¶

Messages are implemented as a subclass of Gst.MiniObject with a generic 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 Gst.Bus.

The basic use pattern of posting a message on a Gst.Bus is as follows:

gst_bus_post (bus, gst_message_new_eos());

A Gst.Element usually posts messages on the bus provided by the parent container using Gst.Element.post_message().

classmethod new_application(src, structure)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
structure (Gst.Structure) – the structure for the message. The message will take ownership of the structure.

Returns:

The new application message.

MT safe.

Return type:

Gst.Message

Create a new application-typed message. GStreamer will never create these messages; they are a gift from us to you. Enjoy.

classmethod new_async_done(src, running_time)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
running_time (int) – the desired running_time

Returns:

The new async_done message.

MT safe.

Return type:

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.

classmethod new_async_start(src)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.

Returns:

The new async_start message.

MT safe.

Return type:

Gst.Message

This message is posted by elements when they start an ASYNC state change.

classmethod new_buffering(src, percent)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
percent (int) – The buffering percent

Returns:

The new buffering message.

Return type:

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.

classmethod new_clock_lost(src, clock)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
clock (Gst.Clock) – the clock that was lost

Returns:

The new clock lost message.

MT safe.

Return type:

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.

classmethod new_clock_provide(src, clock, ready)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
clock (Gst.Clock) – the clock it provides
ready (bool) – True if the sender can provide a clock

Returns:

the new provide clock message.

MT safe.

Return type:

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.

classmethod new_custom(type, src, structure)[source]¶

Parameters:

type (Gst.MessageType) – The Gst.MessageType to distinguish messages
src (Gst.Object or None) – The object originating the message.
structure (Gst.Structure or None) – the structure for the message. The message will take ownership of the structure.

Returns:

The new message.

MT safe.

Return type:

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 None.

classmethod new_device_added(src, device)[source]¶

Parameters:

src (Gst.Object or None) – The Gst.Object that created the message
device (Gst.Device) – The new Gst.Device

Returns:

a newly allocated Gst.Message

Return type:

Gst.Message

Creates a new device-added message. The device-added message is produced by Gst.DeviceProvider or a Gst.DeviceMonitor. They announce the appearance of monitored devices.

New in version 1.4.

classmethod new_device_changed(src, device, changed_device)[source]¶

Parameters:

src (Gst.Object or None) – The Gst.Object that created the message
device (Gst.Device) – The newly created device representing changed_device with its new configuration.
changed_device (Gst.Device) – The old version of the device.

Returns:

a newly allocated Gst.Message

Return type:

Gst.Message

Creates a new device-changed message. The device-changed message is produced by Gst.DeviceProvider or a Gst.DeviceMonitor. They announce that a device properties has changed and device represent the new modified version of changed_device.

New in version 1.16.

classmethod new_device_removed(src, device)[source]¶

Parameters:

src (Gst.Object or None) – The Gst.Object that created the message
device (Gst.Device) – The removed Gst.Device

Returns:

a newly allocated Gst.Message

Return type:

Gst.Message

Creates a new device-removed message. The device-removed message is produced by Gst.DeviceProvider or a Gst.DeviceMonitor. They announce the disappearance of monitored devices.

New in version 1.4.

classmethod new_duration_changed(src)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.

Returns:

The new duration-changed message.

MT safe.

Return type:

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.

classmethod new_element(src, structure)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
structure (Gst.Structure) – The structure for the message. The message will take ownership of the structure.

Returns:

The new element message.

MT safe.

Return type:

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 None.

classmethod new_eos(src)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.

Returns:

The new eos message.

MT safe.

Return type:

Gst.Message

Create a new eos message. This message is generated and posted in the sink elements of a Gst.Bin. The bin will only forward the EOS message to the application if all sinks have posted an EOS message.

classmethod new_error(src, error, debug)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
error (GLib.Error) – The GLib.Error for this message.
debug (str) – A debugging string.

Returns:

the new error message.

MT safe.

Return type:

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.

classmethod new_error_with_details(src, error, debug, details)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
error (GLib.Error) – The GLib.Error for this message.
debug (str) – A debugging string.
details (Gst.Structure or None) – A Gst.Structure with details

Returns:

the new error message.

Return type:

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.

New in version 1.10.

classmethod new_have_context(src, context)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
context (Gst.Context) – the context

Returns:

The new have-context message.

MT safe.

Return type:

Gst.Message

This message is posted when an element has a new local Gst.Context.

New in version 1.2.

classmethod new_info(src, error, debug)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
error (GLib.Error) – The GLib.Error for this message.
debug (str) – A debugging string.

Returns:

the new info message.

MT safe.

Return type:

Gst.Message

Create a new info message. The message will make copies of error and debug.

classmethod new_info_with_details(src, error, debug, details)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
error (GLib.Error) – The GLib.Error for this message.
debug (str) – A debugging string.
details (Gst.Structure or None) – A Gst.Structure with details

Returns:

the new warning message.

Return type:

Gst.Message

Create a new info message. The message will make copies of error and debug.

New in version 1.10.

classmethod new_instant_rate_request(src, rate_multiplier)[source]¶

Parameters:

src (Gst.Object or None) – The Gst.Object that posted the message
rate_multiplier (float) – the rate multiplier factor that should be applied

Returns:

a newly allocated Gst.Message

Return type:

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.EventType.INSTANT_RATE_SYNC_TIME event to notify the elements in the pipeline.

New in version 1.18.

classmethod new_latency(src)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.

Returns:

The new latency message.

MT safe.

Return type:

Gst.Message

This message can be posted by elements when their latency requirements have changed.

classmethod new_need_context(src, context_type)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
context_type (str) – The context type that is needed

Returns:

The new need-context message.

MT safe.

Return type:

Gst.Message

This message is posted when an element needs a specific Gst.Context.

New in version 1.2.

classmethod new_new_clock(src, clock)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
clock (Gst.Clock) – the new selected clock

Returns:

The new new clock message.

MT safe.

Return type:

Gst.Message

Create a new clock message. This message is posted whenever the pipeline selects a new clock for the pipeline.

classmethod new_progress(src, type, code, text)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
type (Gst.ProgressType) – a Gst.ProgressType
code (str) – a progress code
text (str) – free, user visible text describing the progress

Returns:

The new qos message.

Return type:

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.

classmethod new_property_notify(src, property_name, val)[source]¶

Parameters:

src (Gst.Object) – The Gst.Object whose property changed (may or may not be a Gst.Element)
property_name (str) – name of the property that changed
val (GObject.Value or None) – new property value, or None

Returns:

a newly allocated Gst.Message

Return type:

Gst.Message

New in version 1.10.

classmethod new_qos(src, live, running_time, stream_time, timestamp, duration)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
live (bool) – if the message was generated by a live element
running_time (int) – the running time of the buffer that generated the message
stream_time (int) – the stream time of the buffer that generated the message
timestamp (int) – the timestamps of the buffer that generated the message
duration (int) – the duration of the buffer that generated the message

Returns:

The new qos message.

MT safe.

Return type:

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.

classmethod new_redirect(src, location, tag_list, entry_struct)[source]¶

Parameters:

src (Gst.Object or None) – The Gst.Object whose property changed (may or may not be a Gst.Element)
location (str) – location string for the new entry
tag_list (Gst.TagList or None) – tag list for the new entry
entry_struct (Gst.Structure or None) – structure for the new entry

Returns:

a newly allocated Gst.Message

Return type:

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 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.

New in version 1.10.

classmethod new_request_state(src, state)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
state (Gst.State) – The new requested state

Returns:

the new request state message.

MT safe.

Return type:

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.

classmethod new_reset_time(src, running_time)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
running_time (int) – the requested running-time

Returns:

The new reset_time message.

MT safe.

Return type:

Gst.Message

This message is posted when the pipeline running-time should be reset to running_time, like after a flushing seek.

classmethod new_segment_done(src, format, position)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
format (Gst.Format) – The format of the position being done
position (int) – The position of the segment being done

Returns:

the new segment done message.

MT safe.

Return type:

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.

classmethod new_segment_start(src, format, position)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
format (Gst.Format) – The format of the position being played
position (int) – The position of the segment being played

Returns:

the new segment start message.

MT safe.

Return type:

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.

classmethod new_state_changed(src, oldstate, newstate, pending)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
oldstate (Gst.State) – the previous state
newstate (Gst.State) – the new (current) state
pending (Gst.State) – the pending (target) state

Returns:

the new state change message.

MT safe.

Return type:

Gst.Message

Create a state change message. This message is posted whenever an element changed its state.

classmethod new_state_dirty(src)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message

Returns:

the new state dirty message.

MT safe.

Return type:

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.

classmethod new_step_done(src, format, amount, rate, flush, intermediate, duration, eos)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
format (Gst.Format) – the format of amount
amount (int) – the amount of stepped data
rate (float) – the rate of the stepped amount
flush (bool) – is this an flushing step
intermediate (bool) – is this an intermediate step
duration (int) – the duration of the data
eos (bool) – the step caused EOS

Returns:

the new step_done message.

MT safe.

Return type:

Gst.Message

This message is posted by elements when they complete a part, when intermediate set to 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.

classmethod new_step_start(src, active, format, amount, rate, flush, intermediate)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
active (bool) – if the step is active or queued
format (Gst.Format) – the format of amount
amount (int) – the amount of stepped data
rate (float) – the rate of the stepped amount
flush (bool) – is this an flushing step
intermediate (bool) – is this an intermediate step

Returns:

The new step_start message.

MT safe.

Return type:

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 False when the element accepted the new step event and has queued it for execution in the streaming threads.

active is set to 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.

classmethod new_stream_collection(src, collection)[source]¶

Parameters:

src (Gst.Object or None) – The Gst.Object that created the message
collection (Gst.StreamCollection) – The Gst.StreamCollection

Returns:

a newly allocated Gst.Message

Return type:

Gst.Message

Creates a new stream-collection message. The message is used to announce new Gst.StreamCollection

New in version 1.10.

classmethod new_stream_start(src)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.

Returns:

The new stream_start message.

MT safe.

Return type:

Gst.Message

Create a new stream_start message. This message is generated and posted in the sink elements of a Gst.Bin. The bin will only forward the STREAM_START message to the application if all sinks have posted an STREAM_START message.

classmethod new_stream_status(src, type, owner)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
type (Gst.StreamStatusType) – The stream status type.
owner (Gst.Element) – the owner element of src.

Returns:

the new stream status message.

MT safe.

Return type:

Gst.Message

Create a new stream status message. This message is posted when a streaming thread is created/destroyed or when the state changed.

classmethod new_streams_selected(src, collection)[source]¶

Parameters:

src (Gst.Object or None) – The Gst.Object that created the message
collection (Gst.StreamCollection) – The Gst.StreamCollection

Returns:

a newly allocated Gst.Message

Return type:

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.EventType.SELECT_STREAMS event, or when an element (such as decodebin3) makes an initial selection of streams.

The message also contains the Gst.StreamCollection to which the various streams belong to.

Users of Gst.Message.new_streams_selected() can add the selected streams with Gst.Message.streams_selected_add().

New in version 1.10.

classmethod new_structure_change(src, type, owner, busy)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
type (Gst.StructureChangeType) – The change type.
owner (Gst.Element) – The owner element of src.
busy (bool) – Whether the structure change is busy.

Returns:

the new structure change message.

MT safe.

Return type:

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.

classmethod new_tag(src, tag_list)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
tag_list (Gst.TagList) – the tag list for the message.

Returns:

the new tag message.

MT safe.

Return type:

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.

classmethod new_toc(src, toc, updated)[source]¶

Parameters:

src (Gst.Object or None) – the object originating the message.
toc (Gst.Toc) – Gst.Toc structure for the message.
updated (bool) – whether TOC was updated or not.

Returns:

a new TOC message.

MT safe.

Return type:

Gst.Message

Create a new TOC message. The message is posted by elements that discovered or updated a TOC.

classmethod new_warning(src, error, debug)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
error (GLib.Error) – The GLib.Error for this message.
debug (str) – A debugging string.

Returns:

the new warning message.

MT safe.

Return type:

Gst.Message

Create a new warning message. The message will make copies of error and debug.

classmethod new_warning_with_details(src, error, debug, details)[source]¶

Parameters:

src (Gst.Object or None) – The object originating the message.
error (GLib.Error) – The GLib.Error for this message.
debug (str) – A debugging string.
details (Gst.Structure or None) – A Gst.Structure with details

Returns:

the new warning message.

Return type:

Gst.Message

Create a new warning message. The message will make copies of error and debug.

New in version 1.10.

add_redirect_entry(location, tag_list, entry_struct)[source]¶

Parameters:

location (str) – location string for the new entry
tag_list (Gst.TagList or None) – tag list for the new entry
entry_struct (Gst.Structure or None) – structure for the new entry

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.

New in version 1.10.

get_num_redirect_entries()[source]¶

Returns:: the number of entries stored in the message
Return type:: int

New in version 1.10.

get_seqnum()[source]¶

Returns:

The message’s sequence number.

MT safe.

Return type:

int

Retrieve the sequence number of a message.

Messages have ever-incrementing sequence numbers, which may also be set explicitly via 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.

get_stream_status_object()[source]¶

Returns:: a GObject.Value containing the object that manages the streaming thread. This object is usually of type Gst.Task but other types can be added in the future. The object remains valid as long as self is valid.
Return type:: GObject.Value or None

Extracts the object managing the streaming thread from self.

get_structure()[source]¶

Returns:

The structure of the message. The structure is still owned by the message, which means that you should not free it and that the pointer becomes invalid when you free the message.

MT safe.

Return type:

Gst.Structure or None

Access the structure of the message.

has_name(name)[source]¶

Parameters:: name (str) – name to check
Returns:: True if name matches the name of the message structure.
Return type:: bool

Checks if self has the given name. This function is usually used to check the name of a custom message.

parse_async_done()[source]¶

Returns:: Result location for the running_time or None
Return type:: running_time: int

Extract the running_time from the async_done message.

MT safe.

parse_buffering()[source]¶

Returns:: Return location for the percent.
Return type:: percent: int

Extracts the buffering percent from the Gst.Message. see also Gst.Message.new_buffering().

MT safe.

parse_buffering_stats()[source]¶

Returns:

mode:: a buffering mode, or None
avg_in:: the average input rate, or None
avg_out:: the average output rate, or None
buffering_left:: amount of buffering time left in milliseconds, or None

Return type:

(mode: Gst.BufferingMode, avg_in: int, avg_out: int, buffering_left: int)

Extracts the buffering stats values from self.

parse_clock_lost()[source]¶

Returns:: a pointer to hold the lost clock
Return type:: clock: Gst.Clock

Extracts the lost clock from the Gst.Message. The clock object returned remains valid until the message is freed.

MT safe.

parse_clock_provide()[source]¶

Returns:

clock:: a pointer to hold a clock object, or None
ready:: a pointer to hold the ready flag, or None

Return type:

(clock: Gst.Clock, ready: bool)

Extracts the clock and ready flag from the Gst.Message. The clock object returned remains valid until the message is freed.

MT safe.

parse_context_type()[source]¶

Returns:

a bool indicating if the parsing succeeded.

context_type:: the context type, or None

Return type:

(bool, context_type: str)

Parse a context type from an existing Gst.MessageType.NEED_CONTEXT message.

New in version 1.2.

parse_device_added()[source]¶

Returns:: A location where to store a pointer to the new Gst.Device, or None
Return type:: device: Gst.Device

Parses a device-added message. The device-added message is produced by Gst.DeviceProvider or a Gst.DeviceMonitor. It announces the appearance of monitored devices.

New in version 1.4.

parse_device_changed()[source]¶

Returns:

device:: A location where to store a pointer to the updated version of the Gst.Device, or None
changed_device:: A location where to store a pointer to the old version of the Gst.Device, or None

Return type:

(device: Gst.Device, changed_device: Gst.Device)

Parses a device-changed message. The device-changed message is produced by Gst.DeviceProvider or a 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.

New in version 1.16.

parse_device_removed()[source]¶

Returns:: A location where to store a pointer to the removed Gst.Device, or None
Return type:: device: Gst.Device

Parses a device-removed message. The device-removed message is produced by Gst.DeviceProvider or a Gst.DeviceMonitor. It announces the disappearance of monitored devices.

New in version 1.4.

parse_error()[source]¶

Returns:

gerror:: location for the GLib.Error
debug:: location for the debug message, or None

Return type:

(gerror: GLib.Error, debug: str or None)

Extracts the GLib.Error and debug string from the Gst.Message. The values returned in the output arguments are copies; the caller must free them when done.

Typical usage of this function might be:

...
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.

parse_error_details()[source]¶

Returns:: A pointer to the returned details
Return type:: structure: Gst.Structure or None

Returns the optional details structure, may be None if none. The returned structure must not be freed.

New in version 1.10.

parse_group_id()[source]¶

Returns:

True if the message had a group id set, False otherwise

MT safe.

group_id:: Result location for the group id or None

Return type:

(bool, group_id: int)

Extract the group from the STREAM_START message.

New in version 1.2.

parse_have_context()[source]¶

Returns:: Result location for the context or None
Return type:: context: Gst.Context

Extract the context from the HAVE_CONTEXT message.

MT safe.

New in version 1.2.

parse_info()[source]¶

Returns:

gerror:: location for the GLib.Error
debug:: location for the debug message, or None

Return type:

(gerror: GLib.Error, debug: str or None)

Extracts the GLib.Error and debug string from the Gst.Message. The values returned in the output arguments are copies; the caller must free them when done.

MT safe.

parse_info_details()[source]¶

Returns:: A pointer to the returned details
Return type:: structure: Gst.Structure or None

Returns the optional details structure, may be None if none The returned structure must not be freed.

New in version 1.10.

parse_instant_rate_request()[source]¶

Returns:: return location for the rate, or None
Return type:: rate_multiplier: float

Parses the rate_multiplier from the instant-rate-request message.

New in version 1.18.

parse_new_clock()[source]¶

Returns:: a pointer to hold the selected new clock
Return type:: clock: Gst.Clock

Extracts the new clock from the Gst.Message. The clock object returned remains valid until the message is freed.

MT safe.

parse_progress()[source]¶

Returns:

type:: location for the type
code:: location for the code
text:: location for the text

Return type:

(type: Gst.ProgressType, code: str, text: str)

Parses the progress type, code and text.

parse_property_notify()[source]¶

Returns:

object:: location where to store a pointer to the object whose property got changed, or None
property_name:: return location for the name of the property that got changed, or None
property_value:: return location for the new value of the property that got changed, or None. This will only be set if the property notify watch was told to include the value when it was set up

Return type:

(object: Gst.Object, property_name: str, property_value: GObject.Value or None)

Parses a property-notify message. These will be posted on the bus only when set up with Gst.Element.add_property_notify_watch() or Gst.Element.add_property_deep_notify_watch().

New in version 1.10.

parse_qos()[source]¶

Returns:

live:: if the message was generated by a live element
running_time:: the running time of the buffer that generated the message
stream_time:: the stream time of the buffer that generated the message
timestamp:: the timestamps of the buffer that generated the message
duration:: the duration of the buffer that generated the message

Return type:

(live: bool, running_time: int, stream_time: int, timestamp: int, duration: 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.

parse_qos_stats()[source]¶

Returns:

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).
processed:: Total number of units correctly processed since the last state change to READY or a flushing operation.
dropped:: Total number of units dropped since the last state change to READY or a flushing operation.

Return type:

(format: Gst.Format, processed: int, dropped: 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.

parse_qos_values()[source]¶

Returns:

jitter:: The difference of the running-time against the deadline.
proportion:: Long term prediction of the ideal rate relative to normal rate to get optimal quality.
quality:: An element dependent integer value that specifies the current quality level of the element. The default maximum quality is 1000000.

Return type:

(jitter: int, proportion: float, quality: int)

Extract the QoS values that have been calculated/analysed from the QoS data

MT safe.

parse_redirect_entry(entry_index)[source]¶

Parameters:

entry_index (int) – index of the entry to parse

Returns:

location:: return location for the pointer to the entry’s location string, or None
tag_list:: return location for the pointer to the entry’s tag list, or None
entry_struct:: return location for the pointer to the entry’s structure, or None

Return type:

(location: str, tag_list: Gst.TagList or None, entry_struct: Gst.Structure or None)

Parses the location and/or structure from the entry with the given index. The index must be between 0 and Gst.Message.get_num_redirect_entries() - 1. Returned pointers are valid for as long as this message exists.

New in version 1.10.

parse_request_state()[source]¶

Returns:: Result location for the requested state or None
Return type:: state: Gst.State

Extract the requested state from the request_state message.

MT safe.

parse_reset_time()[source]¶

Returns:: Result location for the running_time or None
Return type:: running_time: int

Extract the running-time from the RESET_TIME message.

MT safe.

parse_segment_done()[source]¶

Returns:

format:: Result location for the format, or None
position:: Result location for the position, or None

Return type:

(format: Gst.Format, position: int)

Extracts the position and format from the segment done message.

MT safe.

parse_segment_start()[source]¶

Returns:

format:: Result location for the format, or None
position:: Result location for the position, or None

Return type:

(format: Gst.Format, position: int)

Extracts the position and format from the segment start message.

MT safe.

parse_state_changed()[source]¶

Returns:

oldstate:: the previous state, or None
newstate:: the new (current) state, or None
pending:: the pending (target) state, or None

Return type:

(oldstate: Gst.State, newstate: Gst.State, pending: Gst.State)

Extracts the old and new states from the Gst.Message.

Typical usage of this function might be:

...
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.

parse_step_done()[source]¶

Returns:

format:: result location for the format
amount:: result location for the amount
rate:: result location for the rate
flush:: result location for the flush flag
intermediate:: result location for the intermediate flag
duration:: result location for the duration
eos:: result location for the EOS flag

Return type:

(format: Gst.Format, amount: int, rate: float, flush: bool, intermediate: bool, duration: int, eos: bool)

Extract the values the step_done message.

MT safe.

parse_step_start()[source]¶

Returns:

active:: result location for the active flag
format:: result location for the format
amount:: result location for the amount
rate:: result location for the rate
flush:: result location for the flush flag
intermediate:: result location for the intermediate flag

Return type:

(active: bool, format: Gst.Format, amount: int, rate: float, flush: bool, intermediate: bool)

Extract the values from step_start message.

MT safe.

parse_stream_collection()[source]¶

Returns:: A location where to store a pointer to the Gst.StreamCollection, or None
Return type:: collection: Gst.StreamCollection

Parses a stream-collection message.

New in version 1.10.

parse_stream_status()[source]¶

Returns:

type:: A pointer to hold the status type
owner:: The owner element of the message source

Return type:

(type: Gst.StreamStatusType, owner: Gst.Element)

Extracts the stream status type and owner the Gst.Message. The returned owner remains valid for as long as the reference to self is valid and should thus not be unreffed.

MT safe.

parse_streams_selected()[source]¶

Returns:: A location where to store a pointer to the Gst.StreamCollection, or None
Return type:: collection: Gst.StreamCollection

Parses a streams-selected message.

New in version 1.10.

parse_structure_change()[source]¶

Returns:

type:: A pointer to hold the change type
owner:: The owner element of the message source
busy:: a pointer to hold whether the change is in progress or has been completed

Return type:

(type: Gst.StructureChangeType, owner: Gst.Element, busy: bool)

Extracts the change type and completion status from the Gst.Message.

MT safe.

parse_tag()[source]¶

Returns:: return location for the tag-list.
Return type:: tag_list: Gst.TagList

Extracts the tag list from the Gst.Message. 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:

...
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.

parse_toc()[source]¶

Returns:

toc:: return location for the TOC.
updated:: return location for the updated flag.

Return type:

(toc: Gst.Toc, updated: bool)

Extract the TOC from the Gst.Message. The TOC returned in the output argument is a copy; the caller must free it with gst_toc_unref() when done.

MT safe.

parse_warning()[source]¶

Returns:

gerror:: location for the GLib.Error
debug:: location for the debug message, or None

Return type:

(gerror: GLib.Error, debug: str or None)

Extracts the GLib.Error and debug string from the Gst.Message. The values returned in the output arguments are copies; the caller must free them when done.

MT safe.

parse_warning_details()[source]¶

Returns:: A pointer to the returned details
Return type:: structure: Gst.Structure or None

Returns the optional details structure, may be None if none The returned structure must not be freed.

New in version 1.10.

set_buffering_stats(mode, avg_in, avg_out, buffering_left)[source]¶

Parameters:

mode (Gst.BufferingMode) – a buffering mode
avg_in (int) – the average input rate
avg_out (int) – the average output rate
buffering_left (int) – amount of buffering time left in milliseconds

Configures the buffering stats values in self.

set_group_id(group_id)[source]¶

Parameters:: group_id (int) – the group id

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.

New in version 1.2.

set_qos_stats(format, processed, dropped)[source]¶

Parameters:

format (Gst.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).
processed (int) – Total number of units correctly processed since the last state change to READY or a flushing operation.
dropped (int) – Total number of units dropped since the last state change to READY or a flushing operation.

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.

set_qos_values(jitter, proportion, quality)[source]¶

Parameters:

jitter (int) – The difference of the running-time against the deadline.
proportion (float) – Long term prediction of the ideal rate relative to normal rate to get optimal quality.
quality (int) – An element dependent integer value that specifies the current quality level of the element. The default maximum quality is 1000000.

Set the QoS values that have been calculated/analysed from the QoS data

MT safe.

set_seqnum(seqnum)[source]¶

Parameters:: seqnum (int) – A sequence number.

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 Gst.Message.get_seqnum() for more information.

MT safe.

set_stream_status_object(object)[source]¶

Parameters:: object (GObject.Value) – the object controlling the streaming

Configures the object handling the streaming thread. This is usually a Gst.Task object but other objects might be added in the future.

streams_selected_add(stream)[source]¶

Parameters:: stream (Gst.Stream) – a Gst.Stream to add to self

Adds the stream to the self.

New in version 1.10.

streams_selected_get_size()[source]¶

Returns:: The number of streams contained within.
Return type:: int

Returns the number of streams contained in the self.

New in version 1.10.

streams_selected_get_stream(idx)[source]¶

Parameters:: idx (int) – Index of the stream to retrieve
Returns:: A Gst.Stream
Return type:: Gst.Stream or None

Retrieves the Gst.Stream with index index from the self.

New in version 1.10.

writable_structure()[source]¶

Returns:

The structure of the message. The structure is still owned by the message, which means that you should not free it and that the pointer becomes invalid when you free the message. This function ensures that self is writable, and if so, will never return None.

MT safe.

Return type:

Gst.Structure

Get a writable version of the structure.

New in version 1.14.