: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` Manages a set of pads with the purpose of aggregating their buffers. Control is given to the subclass when all pads have data. - Base class for mixers and muxers. Subclasses should at least implement the ``GstAggregatorClass``::aggregate virtual method. - Installs a :obj:`~gi.repository.Gst.PadChainFunction`\, a :obj:`~gi.repository.Gst.PadEventFullFunction` and a :obj:`~gi.repository.Gst.PadQueryFunction` to queue all serialized data packets per sink pad. Subclasses should not overwrite those, but instead implement ``GstAggregatorClass``::sink_event and ``GstAggregatorClass``::sink_query as needed. - When data is queued on all pads, the aggregate vmethod is called. - One can peek at the data on any given GstAggregatorPad with the :func:`~gi.repository.GstBase.AggregatorPad.peek_buffer` method, and remove it from the pad with the gst_aggregator_pad_pop_buffer () method. When a buffer has been taken with pop_buffer (), a new buffer can be queued on that pad. - When :func:`~gi.repository.GstBase.AggregatorPad.peek_buffer` or :func:`~gi.repository.GstBase.AggregatorPad.has_buffer` are called, a reference is taken to the returned buffer, which stays valid until either: - :func:`~gi.repository.GstBase.AggregatorPad.pop_buffer` is called, in which case the caller is guaranteed that the buffer they receive is the same as the peeked buffer. - :func:`~gi.repository.GstBase.AggregatorPad.drop_buffer` is called, in which case the caller is guaranteed that the dropped buffer is the one that was peeked. - the subclass implementation of ``GstAggregatorClass``.aggregate returns. Subsequent calls to :func:`~gi.repository.GstBase.AggregatorPad.peek_buffer` or :func:`~gi.repository.GstBase.AggregatorPad.has_buffer` return / check the same buffer that was returned / checked, until one of the conditions listed above is met. Subclasses are only allowed to call these methods from the aggregate thread. - If the subclass wishes to push a buffer downstream in its aggregate implementation, it should do so through the :func:`~gi.repository.GstBase.Aggregator.finish_buffer` method. This method will take care of sending and ordering mandatory events such as stream start, caps and segment. Buffer lists can also be pushed out with :func:`~gi.repository.GstBase.Aggregator.finish_buffer_list`. - Same goes for EOS events, which should not be pushed directly by the subclass, it should instead return GST_FLOW_EOS in its aggregate implementation. - Note that the aggregator logic regarding gap event handling is to turn these into gap buffers with matching PTS and duration. It will also flag these buffers with GST_BUFFER_FLAG_GAP and GST_BUFFER_FLAG_DROPPABLE to ease their identification and subsequent processing. In addition, if the gap event was flagged with GST_GAP_FLAG_MISSING_DATA, a custom meta is added to the resulting gap buffer (GstAggregatorMissingDataMeta). - Subclasses must use (a subclass of) :obj:`~gi.repository.GstBase.AggregatorPad` for both their sink and source pads. See :func:`~gi.repository.Gst.ElementClass.add_static_pad_template_with_gtype`. This class used to live in gst-plugins-bad and was moved to core. Methods ------- .. rst-class:: interim-class .. class:: Aggregator :no-index: .. method:: do_aggregate(self, timeout: bool) -> ~gi.repository.Gst.FlowReturn :param timeout: .. method:: do_clip(self, aggregator_pad: ~gi.repository.GstBase.AggregatorPad, buf: ~gi.repository.Gst.Buffer) -> ~gi.repository.Gst.Buffer :param aggregator_pad: :param buf: .. method:: do_decide_allocation(self, query: ~gi.repository.Gst.Query) -> bool :param query: .. method:: do_finish_buffer(self, buffer: ~gi.repository.Gst.Buffer) -> ~gi.repository.Gst.FlowReturn :param buffer: .. method:: do_finish_buffer_list(self, bufferlist: ~gi.repository.Gst.BufferList) -> ~gi.repository.Gst.FlowReturn :param bufferlist: .. method:: do_fixate_src_caps(self, caps: ~gi.repository.Gst.Caps) -> ~gi.repository.Gst.Caps :param caps: .. method:: do_flush(self) -> ~gi.repository.Gst.FlowReturn .. method:: do_get_next_time(self) -> int .. method:: do_negotiate(self) -> bool .. method:: do_negotiated_src_caps(self, caps: ~gi.repository.Gst.Caps) -> bool :param caps: .. method:: do_peek_next_sample(self, aggregator_pad: ~gi.repository.GstBase.AggregatorPad) -> ~gi.repository.Gst.Sample | None :param aggregator_pad: .. method:: do_propose_allocation(self, pad: ~gi.repository.GstBase.AggregatorPad, decide_query: ~gi.repository.Gst.Query, query: ~gi.repository.Gst.Query) -> bool :param pad: :param decide_query: :param query: .. method:: do_sink_event(self, aggregator_pad: ~gi.repository.GstBase.AggregatorPad, event: ~gi.repository.Gst.Event) -> bool :param aggregator_pad: :param event: .. method:: do_sink_event_pre_queue(self, aggregator_pad: ~gi.repository.GstBase.AggregatorPad, event: ~gi.repository.Gst.Event) -> ~gi.repository.Gst.FlowReturn :param aggregator_pad: :param event: .. method:: do_sink_query(self, aggregator_pad: ~gi.repository.GstBase.AggregatorPad, query: ~gi.repository.Gst.Query) -> bool :param aggregator_pad: :param query: .. method:: do_sink_query_pre_queue(self, aggregator_pad: ~gi.repository.GstBase.AggregatorPad, query: ~gi.repository.Gst.Query) -> bool :param aggregator_pad: :param query: .. method:: do_src_activate(self, mode: ~gi.repository.Gst.PadMode, active: bool) -> bool :param mode: :param active: .. method:: do_src_event(self, event: ~gi.repository.Gst.Event) -> bool :param event: .. method:: do_src_query(self, query: ~gi.repository.Gst.Query) -> bool :param query: .. method:: do_start(self) -> bool .. method:: do_stop(self) -> bool .. method:: do_update_src_caps(self, caps: ~gi.repository.Gst.Caps) -> ~typing.Tuple[~gi.repository.Gst.FlowReturn, ~gi.repository.Gst.Caps] :param caps: .. 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() -> ~typing.Tuple[~gi.repository.Gst.Allocator | None, ~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 The type of the None singleton. .. versionadded:: 1.18 .. attribute:: props.latency :type: int The type of the None singleton. .. attribute:: props.min_upstream_latency :type: int The type of the None singleton. .. versionadded:: 1.16 .. attribute:: props.start_time :type: int The type of the None singleton. .. attribute:: props.start_time_selection :type: ~gi.repository.GstBase.AggregatorStartTimeSelection The type of the None singleton. 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 The type of the None singleton. .. 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 The type of the None singleton. :param timeout: .. method:: do_clip(aggregator_pad: ~gi.repository.GstBase.AggregatorPad, buf: ~gi.repository.Gst.Buffer) -> ~gi.repository.Gst.Buffer The type of the None singleton. :param aggregator_pad: :param buf: .. method:: do_decide_allocation(query: ~gi.repository.Gst.Query) -> bool The type of the None singleton. :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 The type of the None singleton. :param caps: .. method:: do_flush() -> ~gi.repository.Gst.FlowReturn The type of the None singleton. .. method:: do_get_next_time() -> int The type of the None singleton. .. 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 The type of the None singleton. :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 The type of the None singleton. :param pad: :param decide_query: :param query: .. method:: do_sink_event(aggregator_pad: ~gi.repository.GstBase.AggregatorPad, event: ~gi.repository.Gst.Event) -> bool The type of the None singleton. :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 The type of the None singleton. :param aggregator_pad: :param event: .. method:: do_sink_query(aggregator_pad: ~gi.repository.GstBase.AggregatorPad, query: ~gi.repository.Gst.Query) -> bool The type of the None singleton. :param aggregator_pad: :param query: .. method:: do_sink_query_pre_queue(aggregator_pad: ~gi.repository.GstBase.AggregatorPad, query: ~gi.repository.Gst.Query) -> bool The type of the None singleton. :param aggregator_pad: :param query: .. method:: do_src_activate(mode: ~gi.repository.Gst.PadMode, active: bool) -> bool The type of the None singleton. :param mode: :param active: .. method:: do_src_event(event: ~gi.repository.Gst.Event) -> bool The type of the None singleton. :param event: .. method:: do_src_query(query: ~gi.repository.Gst.Query) -> bool The type of the None singleton. :param query: .. method:: do_start() -> bool The type of the None singleton. .. method:: do_stop() -> bool The type of the None singleton. .. method:: do_update_src_caps(caps: ~gi.repository.Gst.Caps) -> ~typing.Tuple[~gi.repository.Gst.FlowReturn, ~gi.repository.Gst.Caps] The type of the None singleton. :param caps: Fields ------ .. rst-class:: interim-class .. class:: Aggregator :no-index: .. attribute:: parent .. attribute:: priv .. attribute:: srcpad The aggregator's source pad