Aggregator

Added in version 1.14.

class Aggregator(**properties: Any)

Superclasses: Element, Object, InitiallyUnowned, 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 PadChainFunction, a PadEventFullFunction and a 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 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 peek_buffer() or has_buffer() are called, a reference is taken to the returned buffer, which stays valid until either:

    • pop_buffer() is called, in which case the caller is guaranteed that the buffer they receive is the same as the peeked buffer.

    • 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 peek_buffer() or 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 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 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) AggregatorPad for both their sink and source pads. See add_static_pad_template_with_gtype().

This class used to live in gst-plugins-bad and was moved to core.

Methods

class Aggregator
finish_buffer(buffer: Buffer) → 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.

Parameters:

buffer – the Buffer to push.

finish_buffer_list(bufferlist: BufferList) → 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.

Added in version 1.18.

Parameters:

bufferlist – the BufferList to push.

get_allocator() → tuple[Allocator, AllocationParams]

Lets Aggregator sub-classes get the memory allocator acquired by the base class and its params.

Unref the allocator after use it.

get_buffer_pool() → BufferPool | None
get_force_live() → bool

Subclasses may use the return value to inform whether they should return %GST_FLOW_EOS from their aggregate implementation.

Added in version 1.22.

get_ignore_inactive_pads() → bool

Added in version 1.20.

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.

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.

Added in version 1.18.

peek_next_sample(pad: AggregatorPad) → 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 Aggregator::samples-selected handler, and can be used to precisely control aggregating parameters for a given set of input samples.

Added in version 1.18.

Parameters:

pad

selected_samples(pts: int, dts: int, duration: int, info: 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 update_segment() is used by the subclass, it MUST be called before selected_samples().

This function MUST only be called from the GstAggregatorClass::aggregate() function.

Added in version 1.18.

Parameters:

  • pts – The presentation timestamp of the next output buffer

  • dts – The decoding timestamp of the next output buffer

  • duration – The duration of the next output buffer

  • info – a Structure containing additional information

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.

Added in version 1.22.

Parameters:

force_live

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.

Aggregator will still wait once on each newly-added pad, making sure upstream has had a fair chance to start up.

Added in version 1.20.

Parameters:

ignore – whether inactive pads should not be waited on

set_latency(min_latency: int, max_latency: int) → None

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

Parameters:

  • min_latency – minimum latency

  • max_latency – maximum latency

set_src_caps(caps: Caps) → None

Sets the caps to be used on the src pad.

Parameters:

caps – The Caps to set on the src pad.

simple_get_next_time() → int

This is a simple GstAggregatorClass::get_next_time implementation that just looks at the 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.

Added in version 1.16.

update_segment(segment: 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 selected_samples(), if it is used at all.

Added in version 1.18.

Parameters:

segment

Properties

class Aggregator
props.emit_signals: bool

Enables the emission of signals such as Aggregator::samples-selected

Added in version 1.18.

props.latency: int
props.min_upstream_latency: 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.

Added in version 1.16.

props.start_time: int
props.start_time_selection: AggregatorStartTimeSelection

Signals

class Aggregator.signals
samples_selected(segment: Segment, pts: int, dts: int, duration: int, info: Structure | None = None) → None

Signals that the Aggregator subclass has selected the next set of input samples it will aggregate. Handlers may call peek_next_sample() at that point.

Added in version 1.18.

Parameters:

  • segment – The Segment the next output buffer is part of

  • pts – The presentation timestamp of the next output buffer

  • dts – The decoding timestamp of the next output buffer

  • duration – The duration of the next output buffer

  • info – a Structure containing additional information

Virtual Methods

class Aggregator
do_aggregate(timeout: bool) → FlowReturn
Parameters:

timeout

do_clip(aggregator_pad: AggregatorPad, buf: Buffer) → Buffer
Parameters:

  • aggregator_pad

  • buf

do_decide_allocation(query: Query) → bool
Parameters:

query

do_finish_buffer(buffer: Buffer) → 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.

Parameters:

buffer – the Buffer to push.

do_finish_buffer_list(bufferlist: BufferList) → 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.

Added in version 1.18.

Parameters:

bufferlist – the BufferList to push.

do_fixate_src_caps(caps: Caps) → Caps
Parameters:

caps

do_flush() → FlowReturn
do_get_next_time() → int
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.

Added in version 1.18.

do_negotiated_src_caps(caps: Caps) → bool
Parameters:

caps

do_peek_next_sample(aggregator_pad: AggregatorPad) → 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 Aggregator::samples-selected handler, and can be used to precisely control aggregating parameters for a given set of input samples.

Added in version 1.18.

Parameters:

aggregator_pad

do_propose_allocation(pad: AggregatorPad, decide_query: Query, query: Query) → bool
Parameters:

  • pad

  • decide_query

  • query

do_sink_event(aggregator_pad: AggregatorPad, event: Event) → bool
Parameters:

  • aggregator_pad

  • event

do_sink_event_pre_queue(aggregator_pad: AggregatorPad, event: Event) → FlowReturn
Parameters:

  • aggregator_pad

  • event

do_sink_query(aggregator_pad: AggregatorPad, query: Query) → bool
Parameters:

  • aggregator_pad

  • query

do_sink_query_pre_queue(aggregator_pad: AggregatorPad, query: Query) → bool
Parameters:

  • aggregator_pad

  • query

do_src_activate(mode: PadMode, active: bool) → bool
Parameters:

  • mode

  • active

do_src_event(event: Event) → bool
Parameters:

event

do_src_query(query: Query) → bool
Parameters:

query

do_start() → bool
do_stop() → bool
do_update_src_caps(caps: Caps) → tuple[FlowReturn, Caps]
Parameters:

caps

Fields

class Aggregator
parent
priv
srcpad

The aggregator’s source pad