Gst.Query

Fields

Name Type Access Description
mini_object Gst.MiniObject r/w The parent Gst.MiniObject type
type Gst.QueryType r/w the Gst.QueryType

Methods

class new_accept_caps (caps)
class new_allocation (caps, need_pool)
class new_bitrate ()
class new_buffering (format)
class new_caps (filter)
class new_context (context_type)
class new_convert (src_format, value, dest_format)
class new_custom (type, structure)
class new_drain ()
class new_duration (format)
class new_formats ()
class new_latency ()
class new_position (format)
class new_scheduling ()
class new_seeking (format)
class new_segment (format)
class new_uri ()
  add_allocation_meta (api, params)
  add_allocation_param (allocator, params)
  add_allocation_pool (pool, size, min_buffers, max_buffers)
  add_buffering_range (start, stop)
  add_scheduling_mode (mode)
  find_allocation_meta (api)
  get_n_allocation_metas ()
  get_n_allocation_params ()
  get_n_allocation_pools ()
  get_n_buffering_ranges ()
  get_n_scheduling_modes ()
  get_structure ()
  has_scheduling_mode (mode)
  has_scheduling_mode_with_flags (mode, flags)
  parse_accept_caps ()
  parse_accept_caps_result ()
  parse_allocation ()
  parse_bitrate ()
  parse_buffering_percent ()
  parse_buffering_range ()
  parse_buffering_stats ()
  parse_caps ()
  parse_caps_result ()
  parse_context ()
  parse_context_type ()
  parse_convert ()
  parse_duration ()
  parse_latency ()
  parse_n_formats ()
  parse_nth_allocation_meta (index)
  parse_nth_allocation_param (index)
  parse_nth_allocation_pool (index)
  parse_nth_buffering_range (index)
  parse_nth_format (nth)
  parse_nth_scheduling_mode (index)
  parse_position ()
  parse_scheduling ()
  parse_seeking ()
  parse_segment ()
  parse_uri ()
  parse_uri_redirection ()
  parse_uri_redirection_permanent ()
  remove_nth_allocation_meta (index)
  remove_nth_allocation_param (index)
  remove_nth_allocation_pool (index)
  set_accept_caps_result (result)
  set_bitrate (nominal_bitrate)
  set_buffering_percent (busy, percent)
  set_buffering_range (format, start, stop, estimated_total)
  set_buffering_stats (mode, avg_in, avg_out, buffering_left)
  set_caps_result (caps)
  set_context (context)
  set_convert (src_format, src_value, dest_format, dest_value)
  set_duration (format, duration)
  set_formatsv (formats)
  set_latency (live, min_latency, max_latency)
  set_nth_allocation_param (index, allocator, params)
  set_nth_allocation_pool (index, pool, size, min_buffers, max_buffers)
  set_position (format, cur)
  set_scheduling (flags, minsize, maxsize, align)
  set_seeking (format, seekable, segment_start, segment_end)
  set_segment (rate, format, start_value, stop_value)
  set_uri (uri)
  set_uri_redirection (uri)
  set_uri_redirection_permanent (permanent)
  writable_structure ()

Details

class Gst.Query

Queries can be performed on pads (Gst.Pad.query()) and elements (Gst.Element.query()). Please note that some queries might need a running pipeline to work.

Queries can be created using the gst_query_new_*() functions. Query values can be set using gst_query_set_*(), and parsed using gst_query_parse_*() helpers.

The following example shows how to query the duration of a pipeline:

GstQuery *query;
gboolean res;
query = gst_query_new_duration (GST_FORMAT_TIME);
res = gst_element_query (pipeline, query);
if (res) {
  gint64 duration;
  gst_query_parse_duration (query, NULL, &duration);
  g_print ("duration = %"GST_TIME_FORMAT, GST_TIME_ARGS (duration));
} else {
  g_print ("duration query failed...");
}
gst_query_unref (query);
classmethod new_accept_caps(caps)[source]
Parameters:caps (Gst.Caps) – a fixed Gst.Caps
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new query object for querying if caps are accepted.

Free-function: gst_query_unref()

classmethod new_allocation(caps, need_pool)[source]
Parameters:
  • caps (Gst.Caps) – the negotiated caps
  • need_pool (bool) – return a pool
Returns:

a new Gst.Query

Return type:

Gst.Query

Constructs a new query object for querying the allocation properties.

Free-function: gst_query_unref()

classmethod new_bitrate()[source]
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new query object for querying the bitrate.

Free-function: gst_query_unref()

New in version 1.16.

classmethod new_buffering(format)[source]
Parameters:format (Gst.Format) – the default Gst.Format for the new query
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new query object for querying the buffering status of a stream.

Free-function: gst_query_unref()

classmethod new_caps(filter)[source]
Parameters:filter (Gst.Caps) – a filter
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new query object for querying the caps.

The CAPS query should return the allowable caps for a pad in the context of the element’s state, its link to other elements, and the devices or files it has opened. These caps must be a subset of the pad template caps. In the None state with no links, the CAPS query should ideally return the same caps as the pad template. In rare circumstances, an object property can affect the caps returned by the CAPS query, but this is discouraged.

For most filters, the caps returned by CAPS query is directly affected by the allowed caps on other pads. For demuxers and decoders, the caps returned by the srcpad’s getcaps function is directly related to the stream data. Again, the CAPS query should return the most specific caps it reasonably can, since this helps with autoplugging.

The filter is used to restrict the result caps, only the caps matching filter should be returned from the CAPS query. Specifying a filter might greatly reduce the amount of processing an element needs to do.

Free-function: gst_query_unref()

classmethod new_context(context_type)[source]
Parameters:context_type (str) – Context type to query
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new query object for querying the pipeline-local context.

Free-function: gst_query_unref()

New in version 1.2.

classmethod new_convert(src_format, value, dest_format)[source]
Parameters:
Returns:

a Gst.Query

Return type:

Gst.Query

Constructs a new convert query object. Use gst_query_unref() when done with it. A convert query is used to ask for a conversion between one format and another.

Free-function: gst_query_unref()

classmethod new_custom(type, structure)[source]
Parameters:
Returns:

a new Gst.Query

Return type:

Gst.Query or None

Constructs a new custom query object. Use gst_query_unref() when done with it.

Free-function: gst_query_unref()

classmethod new_drain()[source]
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new query object for querying the drain state.

Free-function: gst_query_unref()

classmethod new_duration(format)[source]
Parameters:format (Gst.Format) – the Gst.Format for this duration query
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new stream duration query object to query in the given format. Use gst_query_unref() when done with it. A duration query will give the total length of the stream.

Free-function: gst_query_unref()

classmethod new_formats()[source]
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new query object for querying formats of the stream.

Free-function: gst_query_unref()

classmethod new_latency()[source]
Returns:a Gst.Query
Return type:Gst.Query

Constructs a new latency query object. Use gst_query_unref() when done with it. A latency query is usually performed by sinks to compensate for additional latency introduced by elements in the pipeline.

Free-function: gst_query_unref()

classmethod new_position(format)[source]
Parameters:format (Gst.Format) – the default Gst.Format for the new query
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new query stream position query object. Use gst_query_unref() when done with it. A position query is used to query the current position of playback in the streams, in some format.

Free-function: gst_query_unref()

classmethod new_scheduling()[source]
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new query object for querying the scheduling properties.

Free-function: gst_query_unref()

classmethod new_seeking(format)[source]
Parameters:format (Gst.Format) – the default Gst.Format for the new query
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new query object for querying seeking properties of the stream.

Free-function: gst_query_unref()

classmethod new_segment(format)[source]
Parameters:format (Gst.Format) – the Gst.Format for the new query
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new segment query object. Use gst_query_unref() when done with it. A segment query is used to discover information about the currently configured segment for playback.

Free-function: gst_query_unref()

classmethod new_uri()[source]
Returns:a new Gst.Query
Return type:Gst.Query

Constructs a new query URI query object. Use gst_query_unref() when done with it. An URI query is used to query the current URI that is used by the source or sink.

Free-function: gst_query_unref()

add_allocation_meta(api, params)[source]
Parameters:

Add api with params as one of the supported metadata API to self.

add_allocation_param(allocator, params)[source]
Parameters:

Add allocator and its params as a supported memory allocator.

add_allocation_pool(pool, size, min_buffers, max_buffers)[source]
Parameters:

Set the pool parameters in self.

add_buffering_range(start, stop)[source]
Parameters:
  • start (int) – start position of the range
  • stop (int) – stop position of the range
Returns:

a bool indicating if the range was added or not.

Return type:

bool

Set the buffering-ranges array field in self. The current last start position of the array should be inferior to start.

add_scheduling_mode(mode)[source]
Parameters:mode (Gst.PadMode) – a Gst.PadMode

Add mode as one of the supported scheduling modes to self.

find_allocation_meta(api)[source]
Parameters:api (GObject.GType) – the metadata API
Returns:True when api is in the list of metadata.
index:the index
Return type:(bool, index: int)

Check if self has metadata api set. When this function returns True, index will contain the index where the requested API and the parameters can be found.

get_n_allocation_metas()[source]
Returns:the metadata API array size as a int.
Return type:int

Retrieve the number of values currently stored in the meta API array of the query’s structure.

get_n_allocation_params()[source]
Returns:the allocator array size as a int.
Return type:int

Retrieve the number of values currently stored in the allocator params array of the query’s structure.

If no memory allocator is specified, the downstream element can handle the default memory allocator. The first memory allocator in the query should be generic and allow mapping to system memory, all following allocators should be ordered by preference with the preferred one first.

get_n_allocation_pools()[source]
Returns:the pool array size as a int.
Return type:int

Retrieve the number of values currently stored in the pool array of the query’s structure.

get_n_buffering_ranges()[source]
Returns:the range array size as a int.
Return type:int

Retrieve the number of values currently stored in the buffered-ranges array of the query’s structure.

get_n_scheduling_modes()[source]
Returns:the scheduling mode array size as a int.
Return type:int

Retrieve the number of values currently stored in the scheduling mode array of the query’s structure.

get_structure()[source]
Returns:the Gst.Structure of the query. The structure is still owned by the query and will therefore be freed when the query is unreffed.
Return type:Gst.Structure or None

Get the structure of a query.

has_scheduling_mode(mode)[source]
Parameters:mode (Gst.PadMode) – the scheduling mode
Returns:True when mode is in the list of scheduling modes.
Return type:bool

Check if self has scheduling mode set.

When checking if upstream supports pull mode, it is usually not enough to just check for Gst.PadMode.PULL with this function, you also want to check whether the scheduling flags returned by Gst.Query.parse_scheduling() have the seeking flag set (meaning random access is supported, not only sequential pulls).

has_scheduling_mode_with_flags(mode, flags)[source]
Parameters:
Returns:

True when mode is in the list of scheduling modes and flags are compatible with query flags.

Return type:

bool

Check if self has scheduling mode set and flags is set in query scheduling flags.

parse_accept_caps()[source]
Returns:A pointer to the caps
Return type:caps: Gst.Caps

Get the caps from self. The caps remains valid as long as self remains valid.

parse_accept_caps_result()[source]
Returns:location for the result
Return type:result: bool

Parse the result from self and store in result.

parse_allocation()[source]
Returns:
caps:The Gst.Caps
need_pool:Whether a Gst.BufferPool is needed
Return type:(caps: Gst.Caps, need_pool: bool)

Parse an allocation query, writing the requested caps in caps and whether a pool is needed in need_pool, if the respective parameters are non-None.

Pool details can be retrieved using Gst.Query.get_n_allocation_pools() and Gst.Query.parse_nth_allocation_pool().

parse_bitrate()[source]
Returns:The resulting bitrate in bits per second
Return type:nominal_bitrate: int

Get the results of a bitrate query. See also Gst.Query.set_bitrate().

New in version 1.16.

parse_buffering_percent()[source]
Returns:
busy:if buffering is busy, or None
percent:a buffering percent, or None
Return type:(busy: bool, percent: int)

Get the percentage of buffered data. This is a value between 0 and 100. The busy indicator is True when the buffering is in progress.

parse_buffering_range()[source]
Returns:
format:the format to set for the segment_start and segment_end values, or None
start:the start to set, or None
stop:the stop to set, or None
estimated_total:
 estimated total amount of download time remaining in milliseconds, or None
Return type:(format: Gst.Format, start: int, stop: int, estimated_total: int)

Parse an available query, writing the format into format, and other results into the passed parameters, if the respective parameters are non-None

parse_buffering_stats()[source]
Returns:
mode:a buffering mode, or None
avg_in:the average input rate, or None
avg_out:the average output rat, 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_caps()[source]
Returns:A pointer to the caps filter
Return type:filter: Gst.Caps

Get the filter from the caps self. The caps remains valid as long as self remains valid.

parse_caps_result()[source]
Returns:A pointer to the caps
Return type:caps: Gst.Caps

Get the caps result from self. The caps remains valid as long as self remains valid.

parse_context()[source]
Returns:A pointer to store the Gst.Context
Return type:context: Gst.Context

Get the context from the context self. The context remains valid as long as self remains valid.

New in version 1.2.

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.QueryType.CONTEXT query.

New in version 1.2.

parse_convert()[source]
Returns:
src_format:the storage for the Gst.Format of the source value, or None
src_value:the storage for the source value, or None
dest_format:the storage for the Gst.Format of the destination value, or None
dest_value:the storage for the destination value, or None
Return type:(src_format: Gst.Format, src_value: int, dest_format: Gst.Format, dest_value: int)

Parse a convert query answer. Any of src_format, src_value, dest_format, and dest_value may be None, in which case that value is omitted.

parse_duration()[source]
Returns:
format:the storage for the Gst.Format of the duration value, or None.
duration:the storage for the total duration, or None.
Return type:(format: Gst.Format, duration: int)

Parse a duration query answer. Write the format of the duration into format, and the value into duration, if the respective variables are non-None.

parse_latency()[source]
Returns:
live:storage for live or None
min_latency:the storage for the min latency or None
max_latency:the storage for the max latency or None
Return type:(live: bool, min_latency: int, max_latency: int)

Parse a latency query answer.

parse_n_formats()[source]
Returns:the number of formats in this query.
Return type:n_formats: int

Parse the number of formats in the formats self.

parse_nth_allocation_meta(index)[source]
Parameters:index (int) – position in the metadata API array to read
Returns:a GObject.GType of the metadata API at index.
params:API specific parameters
Return type:(GObject.GType, params: Gst.Structure)

Parse an available query and get the metadata API at index of the metadata API array.

parse_nth_allocation_param(index)[source]
Parameters:index (int) – position in the allocator array to read
Returns:
allocator:variable to hold the result
params:parameters for the allocator
Return type:(allocator: Gst.Allocator, params: Gst.AllocationParams)

Parse an available query and get the allocator and its params at index of the allocator array.

parse_nth_allocation_pool(index)[source]
Parameters:index (int) – index to parse
Returns:
pool:the Gst.BufferPool
size:the buffer size
min_buffers:the min buffers
max_buffers:the max buffers
Return type:(pool: Gst.BufferPool, size: int, min_buffers: int, max_buffers: int)

Get the pool parameters in self.

Unref pool with Gst.Object.unref() when it’s not needed any more.

parse_nth_buffering_range(index)[source]
Parameters:index (int) – position in the buffered-ranges array to read
Returns:a bool indicating if the parsing succeeded.
start:the start position to set, or None
stop:the stop position to set, or None
Return type:(bool, start: int, stop: int)

Parse an available query and get the start and stop values stored at the index of the buffered ranges array.

parse_nth_format(nth)[source]
Parameters:nth (int) – the nth format to retrieve.
Returns:a pointer to store the nth format
Return type:format: Gst.Format

Parse the format query and retrieve the nth format from it into format. If the list contains less elements than nth, format will be set to Gst.Format.UNDEFINED.

parse_nth_scheduling_mode(index)[source]
Parameters:index (int) – position in the scheduling modes array to read
Returns:a Gst.PadMode of the scheduling mode at index.
Return type:Gst.PadMode

Parse an available query and get the scheduling mode at index of the scheduling modes array.

parse_position()[source]
Returns:
format:the storage for the Gst.Format of the position values (may be None)
cur:the storage for the current position (may be None)
Return type:(format: Gst.Format, cur: int)

Parse a position query, writing the format into format, and the position into cur, if the respective parameters are non-None.

parse_scheduling()[source]
Returns:
flags:Gst.SchedulingFlags
minsize:the suggested minimum size of pull requests
maxsize:the suggested maximum size of pull requests:
align:the suggested alignment of pull requests
Return type:(flags: Gst.SchedulingFlags, minsize: int, maxsize: int, align: int)

Set the scheduling properties.

parse_seeking()[source]
Returns:
format:the format to set for the segment_start and segment_end values, or None
seekable:the seekable flag to set, or None
segment_start:the segment_start to set, or None
segment_end:the segment_end to set, or None
Return type:(format: Gst.Format, seekable: bool, segment_start: int, segment_end: int)

Parse a seeking query, writing the format into format, and other results into the passed parameters, if the respective parameters are non-None

parse_segment()[source]
Returns:
rate:the storage for the rate of the segment, or None
format:the storage for the Gst.Format of the values, or None
start_value:the storage for the start value, or None
stop_value:the storage for the stop value, or None
Return type:(rate: float, format: Gst.Format, start_value: int, stop_value: int)

Parse a segment query answer. Any of rate, format, start_value, and stop_value may be None, which will cause this value to be omitted.

See Gst.Query.set_segment() for an explanation of the function arguments.

parse_uri()[source]
Returns:the storage for the current URI (may be None)
Return type:uri: str

Parse an URI query, writing the URI into uri as a newly allocated string, if the respective parameters are non-None. Free the string with GLib.free() after usage.

parse_uri_redirection()[source]
Returns:the storage for the redirect URI (may be None)
Return type:uri: str

Parse an URI query, writing the URI into uri as a newly allocated string, if the respective parameters are non-None. Free the string with GLib.free() after usage.

New in version 1.2.

parse_uri_redirection_permanent()[source]
Returns:if the URI redirection is permanent (may be None)
Return type:permanent: bool

Parse an URI query, and set permanent to True if there is a redirection and it should be considered permanent. If a redirection is permanent, applications should update their internal storage of the URI, otherwise they should make all future requests to the original URI.

New in version 1.4.

remove_nth_allocation_meta(index)[source]
Parameters:index (int) – position in the metadata API array to remove

Remove the metadata API at index of the metadata API array.

remove_nth_allocation_param(index)[source]
Parameters:index (int) – position in the allocation param array to remove

Remove the allocation param at index of the allocation param array.

New in version 1.2.

remove_nth_allocation_pool(index)[source]
Parameters:index (int) – position in the allocation pool array to remove

Remove the allocation pool at index of the allocation pool array.

New in version 1.2.

set_accept_caps_result(result)[source]
Parameters:result (bool) – the result to set

Set result as the result for the self.

set_bitrate(nominal_bitrate)[source]
Parameters:nominal_bitrate (int) – the nominal bitrate in bits per second

Set the results of a bitrate query. The nominal bitrate is the average bitrate expected over the length of the stream as advertised in file headers (or similar).

New in version 1.16.

set_buffering_percent(busy, percent)[source]
Parameters:
  • busy (bool) – if buffering is busy
  • percent (int) – a buffering percent

Set the percentage of buffered data. This is a value between 0 and 100. The busy indicator is True when the buffering is in progress.

set_buffering_range(format, start, stop, estimated_total)[source]
Parameters:
  • format (Gst.Format) – the format to set for the start and stop values
  • start (int) – the start to set
  • stop (int) – the stop to set
  • estimated_total (int) – estimated total amount of download time remaining in milliseconds

Set the available query result fields in self.

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_caps_result(caps)[source]
Parameters:caps (Gst.Caps) – A pointer to the caps

Set the caps result in self.

set_context(context)[source]
Parameters:context (Gst.Context) – the requested Gst.Context

Answer a context query by setting the requested context.

New in version 1.2.

set_convert(src_format, src_value, dest_format, dest_value)[source]
Parameters:

Answer a convert query by setting the requested values.

set_duration(format, duration)[source]
Parameters:

Answer a duration query by setting the requested value in the given format.

set_formatsv(formats)[source]
Parameters:formats ([Gst.Format]) – an array containing n_formats GstFormat values.

Set the formats query result fields in self. The number of formats passed in the formats array must be equal to n_formats.

set_latency(live, min_latency, max_latency)[source]
Parameters:
  • live (bool) – if there is a live element upstream
  • min_latency (int) – the minimal latency of the upstream elements
  • max_latency (int) – the maximal latency of the upstream elements

Answer a latency query by setting the requested values in the given format.

set_nth_allocation_param(index, allocator, params)[source]
Parameters:

Parse an available query and get the allocator and its params at index of the allocator array.

set_nth_allocation_pool(index, pool, size, min_buffers, max_buffers)[source]
Parameters:

Set the pool parameters in self.

set_position(format, cur)[source]
Parameters:

Answer a position query by setting the requested value in the given format.

set_scheduling(flags, minsize, maxsize, align)[source]
Parameters:

Set the scheduling properties.

set_seeking(format, seekable, segment_start, segment_end)[source]
Parameters:
  • format (Gst.Format) – the format to set for the segment_start and segment_end values
  • seekable (bool) – the seekable flag to set
  • segment_start (int) – the segment_start to set
  • segment_end (int) – the segment_end to set

Set the seeking query result fields in self.

set_segment(rate, format, start_value, stop_value)[source]
Parameters:
  • rate (float) – the rate of the segment
  • format (Gst.Format) – the Gst.Format of the segment values (start_value and stop_value)
  • start_value (int) – the start value
  • stop_value (int) – the stop value

Answer a segment query by setting the requested values. The normal playback segment of a pipeline is 0 to duration at the default rate of 1.0. If a seek was performed on the pipeline to play a different segment, this query will return the range specified in the last seek.

start_value and stop_value will respectively contain the configured playback range start and stop values expressed in format. The values are always between 0 and the duration of the media and start_value <= stop_value. rate will contain the playback rate. For negative rates, playback will actually happen from stop_value to start_value.

set_uri(uri)[source]
Parameters:uri (str) – the URI to set

Answer a URI query by setting the requested URI.

set_uri_redirection(uri)[source]
Parameters:uri (str) – the URI to set

Answer a URI query by setting the requested URI redirection.

New in version 1.2.

set_uri_redirection_permanent(permanent)[source]
Parameters:permanent (bool) – whether the redirect is permanent or not

Answer a URI query by setting the requested URI redirection to permanent or not.

New in version 1.4.

writable_structure()[source]
Returns:the Gst.Structure of the query. The structure is still owned by the query and will therefore be freed when the query is unreffed.
Return type:Gst.Structure

Get the structure of a query. This method should be called with a writable self so that the returned structure is guaranteed to be writable.