:right-sidebar: True Aggregator =================================================================== .. currentmodule:: gi.repository.GstBase .. versionadded:: 1.14 .. class:: Aggregator(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gst.Element`, :class:`~gi.repository.Gst.Object`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` :Constructors: :: Aggregator(**properties) Methods ------- .. rst-class:: interim-class .. class:: Aggregator :no-index: .. method:: finish_buffer(buffer: ~gi.repository.Gst.Buffer) -> ~gi.repository.Gst.FlowReturn This method will push the provided output buffer downstream. If needed, mandatory events such as stream-start, caps, and segment events will be sent before pushing the buffer. :param buffer: the :obj:`~gi.repository.Gst.Buffer` to push. .. method:: finish_buffer_list(bufferlist: ~gi.repository.Gst.BufferList) -> ~gi.repository.Gst.FlowReturn This method will push the provided output buffer list downstream. If needed, mandatory events such as stream-start, caps, and segment events will be sent before pushing the buffer. .. versionadded:: 1.18 :param bufferlist: the :obj:`~gi.repository.Gst.BufferList` to push. .. method:: get_allocator() -> tuple[~gi.repository.Gst.Allocator, ~gi.repository.Gst.AllocationParams] Lets :obj:`~gi.repository.GstBase.Aggregator` sub-classes get the memory ``allocator`` acquired by the base class and its ``params``. Unref the ``allocator`` after use it. .. method:: get_buffer_pool() -> ~gi.repository.Gst.BufferPool | None .. method:: get_force_live() -> bool Subclasses may use the return value to inform whether they should return ``%GST_FLOW_EOS`` from their aggregate implementation. .. versionadded:: 1.22 .. method:: get_ignore_inactive_pads() -> bool .. versionadded:: 1.20 .. method:: get_latency() -> int Retrieves the latency values reported by ``self`` in response to the latency query, or ``%GST_CLOCK_TIME_NONE`` if there is not live source connected and the element will not wait for the clock. Typically only called by subclasses. .. method:: negotiate() -> bool Negotiates src pad caps with downstream elements. Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in any case. But marks it again if ``GstAggregatorClass``::negotiate fails. .. versionadded:: 1.18 .. method:: peek_next_sample(pad: ~gi.repository.GstBase.AggregatorPad) -> ~gi.repository.Gst.Sample | None Use this function to determine what input buffers will be aggregated to produce the next output buffer. This should only be called from a :obj:`~gi.repository.GstBase.Aggregator`::samples-selected handler, and can be used to precisely control aggregating parameters for a given set of input samples. .. versionadded:: 1.18 :param pad: .. method:: selected_samples(pts: int, dts: int, duration: int, info: ~gi.repository.Gst.Structure | None = None) -> None Subclasses should call this when they have prepared the buffers they will aggregate for each of their sink pads, but before using any of the properties of the pads that govern *how* aggregation should be performed, for example z-index for video aggregators. If :func:`~gi.repository.GstBase.Aggregator.update_segment` is used by the subclass, it MUST be called before :func:`~gi.repository.GstBase.Aggregator.selected_samples`. This function MUST only be called from the ``GstAggregatorClass``::aggregate() function. .. versionadded:: 1.18 :param pts: The presentation timestamp of the next output buffer :param dts: The decoding timestamp of the next output buffer :param duration: The duration of the next output buffer :param info: a :obj:`~gi.repository.Gst.Structure` containing additional information .. method:: set_force_live(force_live: bool) -> None Subclasses should call this at construction time in order for ``self`` to aggregate on a timeout even when no live source is connected. .. versionadded:: 1.22 :param force_live: .. method:: set_ignore_inactive_pads(ignore: bool) -> None Subclasses should call this when they don't want to time out waiting for a pad that hasn't yet received any buffers in live mode. :obj:`~gi.repository.GstBase.Aggregator` will still wait once on each newly-added pad, making sure upstream has had a fair chance to start up. .. versionadded:: 1.20 :param ignore: whether inactive pads should not be waited on .. method:: set_latency(min_latency: int, max_latency: int) -> None Lets :obj:`~gi.repository.GstBase.Aggregator` sub-classes tell the baseclass what their internal latency is. Will also post a LATENCY message on the bus so the pipeline can reconfigure its global latency if the values changed. :param min_latency: minimum latency :param max_latency: maximum latency .. method:: set_src_caps(caps: ~gi.repository.Gst.Caps) -> None Sets the caps to be used on the src pad. :param caps: The :obj:`~gi.repository.Gst.Caps` to set on the src pad. .. method:: simple_get_next_time() -> int This is a simple ``GstAggregatorClass``::get_next_time implementation that just looks at the :obj:`~gi.repository.Gst.Segment` on the srcpad of the aggregator and bases the next time on the running time there. This is the desired behaviour in most cases where you have a live source and you have a dead line based aggregator subclass. .. versionadded:: 1.16 .. method:: update_segment(segment: ~gi.repository.Gst.Segment) -> None Subclasses should use this to update the segment on their source pad, instead of directly pushing new segment events downstream. Subclasses MUST call this before :func:`~gi.repository.GstBase.Aggregator.selected_samples`, if it is used at all. .. versionadded:: 1.18 :param segment: Properties ---------- .. rst-class:: interim-class .. class:: Aggregator :no-index: .. attribute:: props.emit_signals :type: bool Enables the emission of signals such as :obj:`~gi.repository.GstBase.Aggregator`::samples-selected .. versionadded:: 1.18 .. attribute:: props.latency :type: int .. attribute:: props.min_upstream_latency :type: int Force minimum upstream latency (in nanoseconds). When sources with a higher latency are expected to be plugged in dynamically after the aggregator has started playing, this allows overriding the minimum latency reported by the initial source(s). This is only taken into account when larger than the actually reported minimum latency. .. versionadded:: 1.16 .. attribute:: props.start_time :type: int .. attribute:: props.start_time_selection :type: ~gi.repository.GstBase.AggregatorStartTimeSelection Signals ------- .. rst-class:: interim-class .. class:: Aggregator.signals :no-index: .. method:: samples_selected(segment: ~gi.repository.Gst.Segment, pts: int, dts: int, duration: int, info: ~gi.repository.Gst.Structure | None = None) -> None Signals that the :obj:`~gi.repository.GstBase.Aggregator` subclass has selected the next set of input samples it will aggregate. Handlers may call :func:`~gi.repository.GstBase.Aggregator.peek_next_sample` at that point. .. versionadded:: 1.18 :param segment: The :obj:`~gi.repository.Gst.Segment` the next output buffer is part of :param pts: The presentation timestamp of the next output buffer :param dts: The decoding timestamp of the next output buffer :param duration: The duration of the next output buffer :param info: a :obj:`~gi.repository.Gst.Structure` containing additional information Virtual Methods --------------- .. rst-class:: interim-class .. class:: Aggregator :no-index: .. method:: do_aggregate(timeout: bool) -> ~gi.repository.Gst.FlowReturn Mandatory. Called when buffers are queued on all sinkpads. Classes should iterate the GstElement->sinkpads and peek or steal buffers from the :obj:`~gi.repository.GstBase.AggregatorPad`. If the subclass returns GST_FLOW_EOS, sending of the eos event will be taken care of. Once / if a buffer has been constructed from the aggregated buffers, the subclass should call _finish_buffer. :param timeout: .. method:: do_clip(aggregator_pad: ~gi.repository.GstBase.AggregatorPad, buf: ~gi.repository.Gst.Buffer) -> ~gi.repository.Gst.Buffer Optional. Called when a buffer is received on a sink pad, the task of clipping it and translating it to the current segment falls on the subclass. The function should use the segment of data and the negotiated media type on the pad to perform clipping of input buffer. This function takes ownership of buf and should output a buffer or return NULL in if the buffer should be dropped. :param aggregator_pad: :param buf: .. method:: do_decide_allocation(query: ~gi.repository.Gst.Query) -> bool Optional. Allows the subclass to influence the allocation choices. Setup the allocation parameters for allocating output buffers. The passed in query contains the result of the downstream allocation query. :param query: .. method:: do_finish_buffer(buffer: ~gi.repository.Gst.Buffer) -> ~gi.repository.Gst.FlowReturn This method will push the provided output buffer downstream. If needed, mandatory events such as stream-start, caps, and segment events will be sent before pushing the buffer. :param buffer: the :obj:`~gi.repository.Gst.Buffer` to push. .. method:: do_finish_buffer_list(bufferlist: ~gi.repository.Gst.BufferList) -> ~gi.repository.Gst.FlowReturn This method will push the provided output buffer list downstream. If needed, mandatory events such as stream-start, caps, and segment events will be sent before pushing the buffer. .. versionadded:: 1.18 :param bufferlist: the :obj:`~gi.repository.Gst.BufferList` to push. .. method:: do_fixate_src_caps(caps: ~gi.repository.Gst.Caps) -> ~gi.repository.Gst.Caps Optional. Fixate and return the src pad caps provided. The function takes ownership of ``caps`` and returns a fixated version of ``caps``. ``caps`` is not guaranteed to be writable. :param caps: .. method:: do_flush() -> ~gi.repository.Gst.FlowReturn Optional. Called after a successful flushing seek, once all the flush stops have been received. Flush pad-specific data in :obj:`~gi.repository.GstBase.AggregatorPad`->flush. .. method:: do_get_next_time() -> int Optional. Called when the element needs to know the running time of the next rendered buffer for live pipelines. This causes deadline based aggregation to occur. Defaults to returning GST_CLOCK_TIME_NONE causing the element to wait for buffers on all sink pads before aggregating. .. method:: do_negotiate() -> bool Negotiates src pad caps with downstream elements. Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in any case. But marks it again if ``GstAggregatorClass``::negotiate fails. .. versionadded:: 1.18 .. method:: do_negotiated_src_caps(caps: ~gi.repository.Gst.Caps) -> bool Optional. Notifies subclasses what caps format has been negotiated :param caps: .. method:: do_peek_next_sample(aggregator_pad: ~gi.repository.GstBase.AggregatorPad) -> ~gi.repository.Gst.Sample | None Use this function to determine what input buffers will be aggregated to produce the next output buffer. This should only be called from a :obj:`~gi.repository.GstBase.Aggregator`::samples-selected handler, and can be used to precisely control aggregating parameters for a given set of input samples. .. versionadded:: 1.18 :param aggregator_pad: .. method:: do_propose_allocation(pad: ~gi.repository.GstBase.AggregatorPad, decide_query: ~gi.repository.Gst.Query, query: ~gi.repository.Gst.Query) -> bool Optional. Allows the subclass to handle the allocation query from upstream. :param pad: :param decide_query: :param query: .. method:: do_sink_event(aggregator_pad: ~gi.repository.GstBase.AggregatorPad, event: ~gi.repository.Gst.Event) -> bool Optional. Called when an event is received on a sink pad, the subclass should always chain up. :param aggregator_pad: :param event: .. method:: do_sink_event_pre_queue(aggregator_pad: ~gi.repository.GstBase.AggregatorPad, event: ~gi.repository.Gst.Event) -> ~gi.repository.Gst.FlowReturn Optional. Called when an event is received on a sink pad before queueing up serialized events. The subclass should always chain up (Since: 1.18). :param aggregator_pad: :param event: .. method:: do_sink_query(aggregator_pad: ~gi.repository.GstBase.AggregatorPad, query: ~gi.repository.Gst.Query) -> bool Optional. Called when a query is received on a sink pad, the subclass should always chain up. :param aggregator_pad: :param query: .. method:: do_sink_query_pre_queue(aggregator_pad: ~gi.repository.GstBase.AggregatorPad, query: ~gi.repository.Gst.Query) -> bool Optional. Called when a query is received on a sink pad before queueing up serialized queries. The subclass should always chain up (Since: 1.18). :param aggregator_pad: :param query: .. method:: do_src_activate(mode: ~gi.repository.Gst.PadMode, active: bool) -> bool Optional. Called when the src pad is activated, it will start/stop its pad task right after that call. :param mode: :param active: .. method:: do_src_event(event: ~gi.repository.Gst.Event) -> bool Optional. Called when an event is received on the src pad, the subclass should always chain up. :param event: .. method:: do_src_query(query: ~gi.repository.Gst.Query) -> bool Optional. Called when a query is received on the src pad, the subclass should always chain up. :param query: .. method:: do_start() -> bool Optional. Called when the element goes from READY to PAUSED. The subclass should get ready to process aggregated buffers. .. method:: do_stop() -> bool Optional. Called when the element goes from PAUSED to READY. The subclass should free all resources and reset its state. .. method:: do_update_src_caps(caps: ~gi.repository.Gst.Caps) -> tuple[~gi.repository.Gst.FlowReturn, ~gi.repository.Gst.Caps] :param caps: Fields ------ .. rst-class:: interim-class .. class:: Aggregator :no-index: .. attribute:: parent .. attribute:: priv .. attribute:: srcpad The aggregator's source pad