:right-sidebar: True Query =================================================================== .. currentmodule:: gi.repository.Gst .. class:: Query(*args, **kwargs) :no-contents-entry: :Constructors: :: Query() new_accept_caps(caps:Gst.Caps) -> Gst.Query new_allocation(caps:Gst.Caps=None, need_pool:bool) -> Gst.Query new_bitrate() -> Gst.Query new_buffering(format:Gst.Format) -> Gst.Query new_caps(filter:Gst.Caps) -> Gst.Query new_context(context_type:str) -> Gst.Query new_convert(src_format:Gst.Format, value:int, dest_format:Gst.Format) -> Gst.Query new_custom(type:Gst.QueryType, structure:Gst.Structure=None) -> Gst.Query new_drain() -> Gst.Query new_duration(format:Gst.Format) -> Gst.Query new_formats() -> Gst.Query new_latency() -> Gst.Query new_position(format:Gst.Format) -> Gst.Query new_scheduling() -> Gst.Query new_seeking(format:Gst.Format) -> Gst.Query new_segment(format:Gst.Format) -> Gst.Query new_selectable() -> Gst.Query new_uri() -> Gst.Query Constructors ------------ .. rst-class:: interim-class .. class:: Query :no-index: .. classmethod:: new_accept_caps(caps: ~gi.repository.Gst.Caps) -> ~gi.repository.Gst.Query Constructs a new query object for querying if ``caps`` are accepted. Free-function: gst_query_unref() :param caps: a fixed :obj:`~gi.repository.Gst.Caps` .. classmethod:: new_allocation(caps: ~gi.repository.Gst.Caps | None, need_pool: bool) -> ~gi.repository.Gst.Query Constructs a new query object for querying the allocation properties. Free-function: gst_query_unref() :param caps: the negotiated caps :param need_pool: return a pool .. classmethod:: new_bitrate() -> ~gi.repository.Gst.Query Constructs a new query object for querying the bitrate. Free-function: gst_query_unref() .. versionadded:: 1.16 .. classmethod:: new_buffering(format: ~gi.repository.Gst.Format) -> ~gi.repository.Gst.Query Constructs a new query object for querying the buffering status of a stream. Free-function: gst_query_unref() :param format: the default :obj:`~gi.repository.Gst.Format` for the new query .. classmethod:: new_caps(filter: ~gi.repository.Gst.Caps) -> ~gi.repository.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 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() :param filter: a filter .. classmethod:: new_context(context_type: str) -> ~gi.repository.Gst.Query Constructs a new query object for querying the pipeline-local context. Free-function: gst_query_unref() .. versionadded:: 1.2 :param context_type: Context type to query .. classmethod:: new_convert(src_format: ~gi.repository.Gst.Format, value: int, dest_format: ~gi.repository.Gst.Format) -> ~gi.repository.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() :param src_format: the source :obj:`~gi.repository.Gst.Format` for the new query :param value: the value to convert :param dest_format: the target :obj:`~gi.repository.Gst.Format` .. classmethod:: new_custom(type: ~gi.repository.Gst.QueryType, structure: ~gi.repository.Gst.Structure | None = None) -> ~gi.repository.Gst.Query Constructs a new custom query object. Use gst_query_unref() when done with it. Free-function: gst_query_unref() :param type: the query type :param structure: a structure for the query .. classmethod:: new_drain() -> ~gi.repository.Gst.Query Constructs a new query object for querying the drain state. Free-function: gst_query_unref() .. classmethod:: new_duration(format: ~gi.repository.Gst.Format) -> ~gi.repository.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() :param format: the :obj:`~gi.repository.Gst.Format` for this duration query .. classmethod:: new_formats() -> ~gi.repository.Gst.Query Constructs a new query object for querying formats of the stream. Free-function: gst_query_unref() .. classmethod:: new_latency() -> ~gi.repository.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: ~gi.repository.Gst.Format) -> ~gi.repository.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() :param format: the default :obj:`~gi.repository.Gst.Format` for the new query .. classmethod:: new_scheduling() -> ~gi.repository.Gst.Query Constructs a new query object for querying the scheduling properties. Free-function: gst_query_unref() .. classmethod:: new_seeking(format: ~gi.repository.Gst.Format) -> ~gi.repository.Gst.Query Constructs a new query object for querying seeking properties of the stream. Free-function: gst_query_unref() :param format: the default :obj:`~gi.repository.Gst.Format` for the new query .. classmethod:: new_segment(format: ~gi.repository.Gst.Format) -> ~gi.repository.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() :param format: the :obj:`~gi.repository.Gst.Format` for the new query .. classmethod:: new_selectable() -> ~gi.repository.Gst.Query Constructs a new query object for querying the stream selection capability. Free-function: gst_query_unref() .. versionadded:: 1.22 .. classmethod:: new_uri() -> ~gi.repository.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() Methods ------- .. rst-class:: interim-class .. class:: Query :no-index: .. method:: add_allocation_meta(api: type, params: ~gi.repository.Gst.Structure | None = None) -> None Add ``api`` with ``params`` as one of the supported metadata API to ``query``. :param api: the metadata API :param params: API specific parameters .. method:: add_allocation_param(allocator: ~gi.repository.Gst.Allocator | None = None, params: ~gi.repository.Gst.AllocationParams | None = None) -> None Add ``allocator`` and its ``params`` as a supported memory allocator. :param allocator: the memory allocator :param params: a :obj:`~gi.repository.Gst.AllocationParams` .. method:: add_allocation_pool(pool: ~gi.repository.Gst.BufferPool | None, size: int, min_buffers: int, max_buffers: int) -> None Set the pool parameters in ``query``. :param pool: the :obj:`~gi.repository.Gst.BufferPool` :param size: the buffer size :param min_buffers: the min buffers :param max_buffers: the max buffers .. method:: 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``. :param start: start position of the range :param stop: stop position of the range .. method:: add_scheduling_mode(mode: ~gi.repository.Gst.PadMode) -> None Add ``mode`` as one of the supported scheduling modes to ``query``. :param mode: a :obj:`~gi.repository.Gst.PadMode` .. method:: find_allocation_meta(api: type) -> tuple[bool, int] Check if ``query`` has metadata ``api`` set. When this function returns :const:`True`, ``index`` will contain the index where the requested API and the parameters can be found. :param api: the metadata API .. method:: get_n_allocation_metas() -> int Retrieve the number of values currently stored in the meta API array of the query's structure. .. method:: 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. .. method:: get_n_allocation_pools() -> int Retrieve the number of values currently stored in the pool array of the query's structure. .. method:: get_n_buffering_ranges() -> int Retrieve the number of values currently stored in the buffered-ranges array of the query's structure. .. method:: get_n_scheduling_modes() -> int Retrieve the number of values currently stored in the scheduling mode array of the query's structure. .. method:: get_structure() -> ~gi.repository.Gst.Structure | None Get the structure of a query. .. method:: has_scheduling_mode(mode: ~gi.repository.Gst.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 > :func:`~gi.repository.Gst.Query.parse_scheduling` have the seeking flag set (meaning > random access is supported, not only sequential pulls). :param mode: the scheduling mode .. method:: has_scheduling_mode_with_flags(mode: ~gi.repository.Gst.PadMode, flags: ~gi.repository.Gst.SchedulingFlags) -> bool Check if ``query`` has scheduling mode set and ``flags`` is set in query scheduling flags. :param mode: the scheduling mode :param flags: :obj:`~gi.repository.Gst.SchedulingFlags` .. method:: parse_accept_caps() -> ~gi.repository.Gst.Caps Get the caps from ``query``. The caps remains valid as long as ``query`` remains valid. .. method:: parse_accept_caps_result() -> bool Parse the result from ``query`` and store in ``result``. .. method:: parse_allocation() -> tuple[~gi.repository.Gst.Caps, 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-:const:`None`. Pool details can be retrieved using :func:`~gi.repository.Gst.Query.get_n_allocation_pools` and :func:`~gi.repository.Gst.Query.parse_nth_allocation_pool`. .. method:: parse_bitrate() -> int Get the results of a bitrate query. See also :func:`~gi.repository.Gst.Query.set_bitrate`. .. versionadded:: 1.16 .. method:: parse_buffering_percent() -> tuple[bool, int] Get the percentage of buffered data. This is a value between 0 and 100. The ``busy`` indicator is :const:`True` when the buffering is in progress. .. method:: parse_buffering_range() -> tuple[~gi.repository.Gst.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-:const:`None` .. method:: parse_buffering_stats() -> tuple[~gi.repository.Gst.BufferingMode, int, int, int] Extracts the buffering stats values from ``query``. .. method:: parse_caps() -> ~gi.repository.Gst.Caps Get the filter from the caps ``query``. The caps remains valid as long as ``query`` remains valid. .. method:: parse_caps_result() -> ~gi.repository.Gst.Caps Get the caps result from ``query``. The caps remains valid as long as ``query`` remains valid. .. method:: parse_context() -> ~gi.repository.Gst.Context Get the context from the context ``query``. The context remains valid as long as ``query`` remains valid. .. versionadded:: 1.2 .. method:: parse_context_type() -> tuple[bool, str] Parse a context type from an existing GST_QUERY_CONTEXT query. .. versionadded:: 1.2 .. method:: parse_convert() -> tuple[~gi.repository.Gst.Format, int, ~gi.repository.Gst.Format, int] Parse a convert query answer. Any of ``src_format``, ``src_value``, ``dest_format``, and ``dest_value`` may be :const:`None`, in which case that value is omitted. .. method:: parse_duration() -> tuple[~gi.repository.Gst.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-:const:`None`. .. method:: parse_latency() -> tuple[bool, int, int] Parse a latency query answer. .. method:: parse_n_formats() -> int Parse the number of formats in the formats ``query``. .. method:: parse_nth_allocation_meta(index: int) -> tuple[type, ~gi.repository.Gst.Structure] Parse an available query and get the metadata API at ``index`` of the metadata API array. :param index: position in the metadata API array to read .. method:: parse_nth_allocation_param(index: int) -> tuple[~gi.repository.Gst.Allocator, ~gi.repository.Gst.AllocationParams] Parse an available query and get the allocator and its params at ``index`` of the allocator array. :param index: position in the allocator array to read .. method:: parse_nth_allocation_pool(index: int) -> tuple[~gi.repository.Gst.BufferPool, int, int, int] Get the pool parameters in ``query``. Unref ``pool`` with :func:`~gi.repository.Gst.Object.unref` when it's not needed any more. :param index: index to parse .. method:: 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. :param index: position in the buffered-ranges array to read .. method:: parse_nth_format(nth: int) -> ~gi.repository.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. :param nth: the nth format to retrieve. .. method:: parse_nth_scheduling_mode(index: int) -> ~gi.repository.Gst.PadMode Parse an available query and get the scheduling mode at ``index`` of the scheduling modes array. :param index: position in the scheduling modes array to read .. method:: parse_position() -> tuple[~gi.repository.Gst.Format, int] Parse a position query, writing the format into ``format``, and the position into ``cur``, if the respective parameters are non-:const:`None`. .. method:: parse_scheduling() -> tuple[~gi.repository.Gst.SchedulingFlags, int, int, int] Set the scheduling properties. .. method:: parse_seeking() -> tuple[~gi.repository.Gst.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-:const:`None` .. method:: parse_segment() -> tuple[float, ~gi.repository.Gst.Format, int, int] Parse a segment query answer. Any of ``rate``, ``format``, ``start_value``, and ``stop_value`` may be :const:`None`, which will cause this value to be omitted. See :func:`~gi.repository.Gst.Query.set_segment` for an explanation of the function arguments. .. method:: parse_selectable() -> bool Get the results of a selectable query. See also :func:`~gi.repository.Gst.Query.set_selectable`. .. versionadded:: 1.22 .. method:: parse_uri() -> str Parse an URI query, writing the URI into ``uri`` as a newly allocated string, if the respective parameters are non-:const:`None`. Free the string with :func:`~gi.repository.GLib.free` after usage. .. method:: parse_uri_redirection() -> str Parse an URI query, writing the URI into ``uri`` as a newly allocated string, if the respective parameters are non-:const:`None`. Free the string with :func:`~gi.repository.GLib.free` after usage. .. versionadded:: 1.2 .. method:: parse_uri_redirection_permanent() -> bool Parse an URI query, and set ``permanent`` to :const:`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. .. versionadded:: 1.4 .. method:: remove_nth_allocation_meta(index: int) -> None Remove the metadata API at ``index`` of the metadata API array. :param index: position in the metadata API array to remove .. method:: remove_nth_allocation_param(index: int) -> None Remove the allocation param at ``index`` of the allocation param array. .. versionadded:: 1.2 :param index: position in the allocation param array to remove .. method:: remove_nth_allocation_pool(index: int) -> None Remove the allocation pool at ``index`` of the allocation pool array. .. versionadded:: 1.2 :param index: position in the allocation pool array to remove .. method:: set_accept_caps_result(result: bool) -> None Set ``result`` as the result for the ``query``. :param result: the result to set .. method:: 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). .. versionadded:: 1.16 :param nominal_bitrate: the nominal bitrate in bits per second .. method:: 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 :const:`True` when the buffering is in progress. :param busy: if buffering is busy :param percent: a buffering percent .. method:: set_buffering_range(format: ~gi.repository.Gst.Format, start: int, stop: int, estimated_total: int) -> None Set the available query result fields in ``query``. :param format: the format to set for the ``start`` and ``stop`` values :param start: the start to set :param stop: the stop to set :param estimated_total: estimated total amount of download time remaining in milliseconds .. method:: set_buffering_stats(mode: ~gi.repository.Gst.BufferingMode, avg_in: int, avg_out: int, buffering_left: int) -> None Configures the buffering stats values in ``query``. :param mode: a buffering mode :param avg_in: the average input rate :param avg_out: the average output rate :param buffering_left: amount of buffering time left in milliseconds .. method:: set_caps_result(caps: ~gi.repository.Gst.Caps | None = None) -> None Set the ``caps`` result in ``query``. :param caps: A pointer to the caps .. method:: set_context(context: ~gi.repository.Gst.Context | None = None) -> None Answer a context query by setting the requested context. .. versionadded:: 1.2 :param context: the requested :obj:`~gi.repository.Gst.Context` .. method:: set_convert(src_format: ~gi.repository.Gst.Format, src_value: int, dest_format: ~gi.repository.Gst.Format, dest_value: int) -> None Answer a convert query by setting the requested values. :param src_format: the source :obj:`~gi.repository.Gst.Format` :param src_value: the source value :param dest_format: the destination :obj:`~gi.repository.Gst.Format` :param dest_value: the destination value .. method:: set_duration(format: ~gi.repository.Gst.Format, duration: int) -> None Answer a duration query by setting the requested value in the given format. :param format: the :obj:`~gi.repository.Gst.Format` for the duration :param duration: the duration of the stream .. method:: set_formatsv(formats: ~typing.Sequence[~gi.repository.Gst.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``. :param formats: an array containing ``n_formats`` ``GstFormat`` values. .. method:: set_latency(live: bool, min_latency: int, max_latency: int) -> None Answer a latency query by setting the requested values in the given format. :param live: if there is a live element upstream :param min_latency: the minimal latency of the upstream elements :param max_latency: the maximal latency of the upstream elements .. method:: set_nth_allocation_param(index: int, allocator: ~gi.repository.Gst.Allocator | None = None, params: ~gi.repository.Gst.AllocationParams | None = None) -> None Parse an available query and get the allocator and its params at ``index`` of the allocator array. :param index: position in the allocator array to set :param allocator: new allocator to set :param params: parameters for the allocator .. method:: set_nth_allocation_pool(index: int, pool: ~gi.repository.Gst.BufferPool | None, size: int, min_buffers: int, max_buffers: int) -> None Set the pool parameters in ``query``. :param index: index to modify :param pool: the :obj:`~gi.repository.Gst.BufferPool` :param size: the buffer size :param min_buffers: the min buffers :param max_buffers: the max buffers .. method:: set_position(format: ~gi.repository.Gst.Format, cur: int) -> None Answer a position query by setting the requested value in the given format. :param format: the requested :obj:`~gi.repository.Gst.Format` :param cur: the position to set .. method:: set_scheduling(flags: ~gi.repository.Gst.SchedulingFlags, minsize: int, maxsize: int, align: int) -> None Set the scheduling properties. :param flags: :obj:`~gi.repository.Gst.SchedulingFlags` :param minsize: the suggested minimum size of pull requests :param maxsize: the suggested maximum size of pull requests :param align: the suggested alignment of pull requests .. method:: set_seeking(format: ~gi.repository.Gst.Format, seekable: bool, segment_start: int, segment_end: int) -> None Set the seeking query result fields in ``query``. :param format: the format to set for the ``segment_start`` and ``segment_end`` values :param seekable: the seekable flag to set :param segment_start: the segment_start to set :param segment_end: the segment_end to set .. method:: set_segment(rate: float, format: ~gi.repository.Gst.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``. :param rate: the rate of the segment :param format: the :obj:`~gi.repository.Gst.Format` of the segment values (``start_value`` and ``stop_value``) :param start_value: the start value :param stop_value: the stop value .. method:: 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 :const:`True`. .. versionadded:: 1.22 :param selectable: Whether the element can handle stream selection. .. method:: set_uri(uri: str | None = None) -> None Answer a URI query by setting the requested URI. :param uri: the URI to set .. method:: set_uri_redirection(uri: str | None = None) -> None Answer a URI query by setting the requested URI redirection. .. versionadded:: 1.2 :param uri: the URI to set .. method:: set_uri_redirection_permanent(permanent: bool) -> None Answer a URI query by setting the requested URI redirection to permanent or not. .. versionadded:: 1.4 :param permanent: whether the redirect is permanent or not .. method:: writable_structure() -> ~gi.repository.Gst.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 ------ .. rst-class:: interim-class .. class:: Query :no-index: .. attribute:: mini_object The parent :obj:`~gi.repository.Gst.MiniObject` type .. attribute:: type The :obj:`~gi.repository.Gst.QueryType`