Query#

class Query(*args, **kwargs)#

Queries can be performed on pads (query()) and elements (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);

Constructors#

class Query

classmethod new_accept_caps(caps: Caps) → Query#

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

Free-function: gst_query_unref()

Parameters:: caps – a fixed Caps

classmethod new_allocation(caps: Caps | None, need_pool: bool) → Query#

Constructs a new query object for querying the allocation properties.

Free-function: gst_query_unref()

Parameters:

caps – the negotiated caps
need_pool – return a pool

classmethod new_bitrate() → Query#

Constructs a new query object for querying the bitrate.

Free-function: gst_query_unref()

Added in version 1.16.

classmethod new_buffering(format: Format) → Query#

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

Free-function: gst_query_unref()

Parameters:: format – the default Format for the new query

classmethod new_caps(filter: Caps) → 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 NULL 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()

Parameters:: filter – a filter

classmethod new_context(context_type: str) → Query#

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

Free-function: gst_query_unref()

Added in version 1.2.

Parameters:: context_type – Context type to query

classmethod new_convert(src_format: Format, value: int, dest_format: Format) → 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()

Parameters:

src_format – the source Format for the new query
value – the value to convert
dest_format – the target Format

classmethod new_custom(type: QueryType, structure: Structure | None = None) → Query#

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

Free-function: gst_query_unref()

Parameters:

type – the query type
structure – a structure for the query

classmethod new_drain() → Query#

Constructs a new query object for querying the drain state.

Free-function: gst_query_unref()

classmethod new_duration(format: Format) → 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()

Parameters:: format – the Format for this duration query

classmethod new_formats() → Query#

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

Free-function: gst_query_unref()

classmethod new_latency() → 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: Format) → 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()

Parameters:: format – the default Format for the new query

classmethod new_scheduling() → Query#

Constructs a new query object for querying the scheduling properties.

Free-function: gst_query_unref()

classmethod new_seeking(format: Format) → Query#

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

Free-function: gst_query_unref()

Parameters:: format – the default Format for the new query

classmethod new_segment(format: Format) → 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()

Parameters:: format – the Format for the new query

classmethod new_selectable() → Query#

Constructs a new query object for querying the stream selection capability.

Free-function: gst_query_unref()

Added in version 1.22.

classmethod new_uri() → 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()

Methods#

class Query

add_allocation_meta(api: GType, params: Structure | None = None) → None#

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

Parameters:

api – the metadata API
params – API specific parameters

add_allocation_param(allocator: Allocator | None = None, params: AllocationParams | None = None) → None#

Add allocator and its params as a supported memory allocator.

Parameters:

allocator – the memory allocator
params – a AllocationParams

add_allocation_pool(pool: BufferPool | None, size: int, min_buffers: int, max_buffers: int) → None#

Set the pool parameters in query.

Parameters:

pool – the BufferPool
size – the buffer size
min_buffers – the min buffers
max_buffers – the max buffers

add_buffering_range(start: int, stop: int) → bool#

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

Parameters:

start – start position of the range
stop – stop position of the range

add_scheduling_mode(mode: PadMode) → None#

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

Parameters:: mode – a PadMode

find_allocation_meta(api: GType) → Tuple[bool, int]#

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

Parameters:: api – the metadata API

get_n_allocation_metas() → int#: Retrieve the number of values currently stored in the meta API array of the query’s structure.

get_n_allocation_params() → 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() → int#: Retrieve the number of values currently stored in the pool array of the query’s structure.

get_n_buffering_ranges() → int#: Retrieve the number of values currently stored in the buffered-ranges array of the query’s structure.

get_n_scheduling_modes() → int#: Retrieve the number of values currently stored in the scheduling mode array of the query’s structure.

get_structure() → Structure | None#: Get the structure of a query.

has_scheduling_mode(mode: PadMode) → bool#

Check if query has scheduling mode set.

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

Parameters:: mode – the scheduling mode

has_scheduling_mode_with_flags(mode: PadMode, flags: SchedulingFlags) → bool#

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

Parameters:

mode – the scheduling mode
flags – SchedulingFlags

parse_accept_caps() → Caps#: Get the caps from query. The caps remains valid as long as query remains valid.

parse_accept_caps_result() → bool | None#: Parse the result from query and store in result.

parse_allocation() → Tuple[Caps | None, 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 get_n_allocation_pools() and parse_nth_allocation_pool().

parse_bitrate() → int#: Get the results of a bitrate query. See also set_bitrate().

Added in version 1.16.

parse_buffering_percent() → Tuple[bool, 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() → Tuple[Format, int, int, 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() → Tuple[BufferingMode, int, int, int]#: Extracts the buffering stats values from query.

parse_caps() → Caps#: Get the filter from the caps query. The caps remains valid as long as query remains valid.

parse_caps_result() → Caps | None#: Get the caps result from query. The caps remains valid as long as query remains valid.

parse_context() → Context | None#: Get the context from the context query. The context remains valid as long as query remains valid.

Added in version 1.2.

parse_context_type() → Tuple[bool, str]#: Parse a context type from an existing GST_QUERY_CONTEXT query.

Added in version 1.2.

parse_convert() → Tuple[Format, int, Format, 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() → Tuple[Format, 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() → Tuple[bool, int, int]#: Parse a latency query answer.

parse_n_formats() → int#: Parse the number of formats in the formats query.

parse_nth_allocation_meta(index: int) → Tuple[GType, Structure]#

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

Parameters:: index – position in the metadata API array to read

parse_nth_allocation_param(index: int) → Tuple[Allocator | None, AllocationParams]#

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

Parameters:: index – position in the allocator array to read

parse_nth_allocation_pool(index: int) → Tuple[BufferPool | None, int, int, int]#

Get the pool parameters in query.

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

Parameters:: index – index to parse

parse_nth_buffering_range(index: int) → Tuple[bool, int, int]#

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

Parameters:: index – position in the buffered-ranges array to read

parse_nth_format(nth: int) → 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.

Parameters:: nth – the nth format to retrieve.

parse_nth_scheduling_mode(index: int) → PadMode#

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

Parameters:: index – position in the scheduling modes array to read

parse_position() → Tuple[Format, int]#: Parse a position query, writing the format into format, and the position into cur, if the respective parameters are non-None.

parse_scheduling() → Tuple[SchedulingFlags, int, int, int]#: Set the scheduling properties.

parse_seeking() → Tuple[Format, bool, int, 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() → Tuple[float, Format, int, 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 set_segment() for an explanation of the function arguments.

parse_selectable() → bool#: Get the results of a selectable query. See also set_selectable().

Added in version 1.22.

parse_uri() → str | None#: 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 free() after usage.

parse_uri_redirection() → str | None#: 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 free() after usage.

Added in version 1.2.

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

Added in version 1.4.

remove_nth_allocation_meta(index: int) → None#

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

Parameters:: index – position in the metadata API array to remove

remove_nth_allocation_param(index: int) → None#

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

Added in version 1.2.

Parameters:: index – position in the allocation param array to remove

remove_nth_allocation_pool(index: int) → None#

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

Added in version 1.2.

Parameters:: index – position in the allocation pool array to remove

set_accept_caps_result(result: bool) → None#

Set result as the result for the query.

Parameters:: result – the result to set

set_bitrate(nominal_bitrate: int) → None#

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

Added in version 1.16.

Parameters:: nominal_bitrate – the nominal bitrate in bits per second

set_buffering_percent(busy: bool, percent: int) → None#

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.

Parameters:

busy – if buffering is busy
percent – a buffering percent

set_buffering_range(format: Format, start: int, stop: int, estimated_total: int) → None#

Set the available query result fields in query.

Parameters:

format – the format to set for the start and stop values
start – the start to set
stop – the stop to set
estimated_total – estimated total amount of download time remaining in milliseconds

set_buffering_stats(mode: BufferingMode, avg_in: int, avg_out: int, buffering_left: int) → None#

Configures the buffering stats values in query.

Parameters:

mode – a buffering mode
avg_in – the average input rate
avg_out – the average output rate
buffering_left – amount of buffering time left in milliseconds

set_caps_result(caps: Caps | None = None) → None#

Set the caps result in query.

Parameters:: caps – A pointer to the caps

set_context(context: Context | None = None) → None#

Answer a context query by setting the requested context.

Added in version 1.2.

Parameters:: context – the requested Context

set_convert(src_format: Format, src_value: int, dest_format: Format, dest_value: int) → None#

Answer a convert query by setting the requested values.

Parameters:

src_format – the source Format
src_value – the source value
dest_format – the destination Format
dest_value – the destination value

set_duration(format: Format, duration: int) → None#

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

Parameters:

format – the Format for the duration
duration – the duration of the stream

set_formatsv(formats: list[Format]) → None#

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

Parameters:: formats – an array containing n_formats GstFormat values.

set_latency(live: bool, min_latency: int, max_latency: int) → None#

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

Parameters:

live – if there is a live element upstream
min_latency – the minimal latency of the upstream elements
max_latency – the maximal latency of the upstream elements

set_nth_allocation_param(index: int, allocator: Allocator | None = None, params: AllocationParams | None = None) → None#

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

Parameters:

index – position in the allocator array to set
allocator – new allocator to set
params – parameters for the allocator

set_nth_allocation_pool(index: int, pool: BufferPool | None, size: int, min_buffers: int, max_buffers: int) → None#

Set the pool parameters in query.

Parameters:

index – index to modify
pool – the BufferPool
size – the buffer size
min_buffers – the min buffers
max_buffers – the max buffers

set_position(format: Format, cur: int) → None#

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

Parameters:

format – the requested Format
cur – the position to set

set_scheduling(flags: SchedulingFlags, minsize: int, maxsize: int, align: int) → None#

Set the scheduling properties.

Parameters:

flags – SchedulingFlags
minsize – the suggested minimum size of pull requests
maxsize – the suggested maximum size of pull requests
align – the suggested alignment of pull requests

set_seeking(format: Format, seekable: bool, segment_start: int, segment_end: int) → None#

Set the seeking query result fields in query.

Parameters:

format – the format to set for the segment_start and segment_end values
seekable – the seekable flag to set
segment_start – the segment_start to set
segment_end – the segment_end to set

set_segment(rate: float, format: Format, start_value: int, stop_value: int) → None#

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.

Parameters:

rate – the rate of the segment
format – the Format of the segment values (start_value and stop_value)
start_value – the start value
stop_value – the stop value

set_selectable(selectable: bool) → None#

Set the results of a selectable query. If the element answering the query can handle stream selection, selectable should be set to True.

Added in version 1.22.

Parameters:: selectable – Whether the element can handle stream selection.

set_uri(uri: str | None = None) → None#

Answer a URI query by setting the requested URI.

Parameters:: uri – the URI to set

set_uri_redirection(uri: str | None = None) → None#

Answer a URI query by setting the requested URI redirection.

Added in version 1.2.

Parameters:: uri – the URI to set

set_uri_redirection_permanent(permanent: bool) → None#

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

Added in version 1.4.

Parameters:: permanent – whether the redirect is permanent or not

writable_structure() → Structure#: Get the structure of a query. This method should be called with a writable query so that the returned structure is guaranteed to be writable.

Fields#

class Query

mini_object#: The parent MiniObject type

type#: The QueryType

Query#

Constructors#

Methods#

Fields#

This Page