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 matchingfilter
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()
- 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
Methods
- class Query
- add_allocation_meta(api: type, params: Structure | None = None) None
Add
api
withparams
as one of the supported metadata API toquery
.- Parameters:
api – the metadata API
params – API specific parameters
- add_allocation_param(allocator: Allocator | None = None, params: AllocationParams | None = None) None
Add
allocator
and itsparams
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 tostart
.- 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 toquery
.- Parameters:
mode – a
PadMode
- find_allocation_meta(api: type) tuple[bool, int]
Check if
query
has metadataapi
set. When this function returnsTrue
,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.
- 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 andflags
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 asquery
remains valid.
- parse_allocation() tuple[Caps, bool]
Parse an allocation query, writing the requested caps in
caps
and whether a pool is needed inneed_pool
, if the respective parameters are non-None
.Pool details can be retrieved using
get_n_allocation_pools()
andparse_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 isTrue
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 asquery
remains valid.
- parse_caps_result() Caps
Get the caps result from
query
. The caps remains valid as long asquery
remains valid.
- parse_context() Context
Get the context from the context
query
. The context remains valid as long asquery
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
, anddest_value
may beNone
, 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 intoduration
, if the respective variables are non-None
.
- parse_nth_allocation_meta(index: int) tuple[type, 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, 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, int, int, int]
Get the pool parameters in
query
.Unref
pool
withunref()
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 intoformat
. If the list contains less elements thannth
,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 intocur
, if the respective parameters are non-None
.
- 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
, andstop_value
may beNone
, 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
Parse an URI query, writing the URI into
uri
as a newly allocated string, if the respective parameters are non-None
. Free the string withfree()
after usage.
- parse_uri_redirection() 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 withfree()
after usage.Added in version 1.2.
- parse_uri_redirection_permanent() bool
Parse an URI query, and set
permanent
toTrue
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 thequery
.- 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 isTrue
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
andstop
valuesstart – 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 inquery
.- 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.
- 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 durationduration – the duration of the stream
- set_formatsv(formats: Sequence[Format]) None
Set the formats query result fields in
query
. The number of formats passed in theformats
array must be equal ton_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
andsegment_end
valuesseekable – 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
andstop_value
will respectively contain the configured playback range start and stop values expressed informat
. The values are always between 0 and the duration of the media andstart_value
<=stop_value
.rate
will contain the playback rate. For negative rates, playback will actually happen fromstop_value
tostart_value
.- Parameters:
rate – the rate of the segment
format – the
Format
of the segment values (start_value
andstop_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 toTrue
.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
Fields
- class Query
- mini_object
The parent
MiniObject
type