GstBase.Aggregator¶

Subclasses:: None

Methods¶

Inherited:: Gst.Element (82), Gst.Object (27), GObject.Object (37)
Structs:: Gst.ElementClass (10), GObject.ObjectClass (5)

	`finish_buffer` (buffer)
	`finish_buffer_list` (bufferlist)
	`get_allocator` ()
	`get_buffer_pool` ()
	`get_force_live` ()
	`get_ignore_inactive_pads` ()
	`get_latency` ()
	`negotiate` ()
	`peek_next_sample` (pad)
	`selected_samples` (pts, dts, duration, info)
	`set_force_live` (force_live)
	`set_ignore_inactive_pads` (ignore)
	`set_latency` (min_latency, max_latency)
	`set_src_caps` (caps)
	`simple_get_next_time` ()
	`update_segment` (segment)

Virtual Methods¶

Inherited:: Gst.Element (16), Gst.Object (1), GObject.Object (7)

	`do_aggregate` (timeout)
	`do_clip` (aggregator_pad, buf)
	`do_decide_allocation` (query)
	`do_finish_buffer` (buffer)
	`do_finish_buffer_list` (bufferlist)
	`do_fixate_src_caps` (caps)
	`do_flush` ()
	`do_get_next_time` ()
	`do_negotiate` ()
	`do_negotiated_src_caps` (caps)
	`do_peek_next_sample` (aggregator_pad)
	`do_propose_allocation` (pad, decide_query, query)
	`do_sink_event` (aggregator_pad, event)
	`do_sink_event_pre_queue` (aggregator_pad, event)
	`do_sink_query` (aggregator_pad, query)
	`do_sink_query_pre_queue` (aggregator_pad, query)
	`do_src_activate` (mode, active)
	`do_src_event` (event)
	`do_src_query` (query)
	`do_start` ()
	`do_stop` ()
	`do_update_src_caps` (caps)

Properties¶

Inherited:: Gst.Object (2)

Name	Type	Flags	Short Description
`emit-signals`	`bool`	r/w	Send signals
`latency`	`int`	r/w	Additional latency in live mode to allow upstream to take longer to produce buffers for the current position (in nanoseconds)
`min-upstream-latency`	`int`	r/w	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. (nanoseconds)
`start-time`	`int`	r/w	Start time to use if start-time-selection=set
`start-time-selection`	`GstBase.AggregatorStartTimeSelection`	r/w	Decides which start time is output

Signals¶

Inherited:: Gst.Element (3), Gst.Object (1), GObject.Object (1)

Name	Short Description
`samples-selected`	Signals that the `GstBase.Aggregator` subclass has selected the next set of input samples it will aggregate.

Fields¶

Inherited:: Gst.Element (3), Gst.Object (1), GObject.Object (1)

Name	Type	Access	Description
parent	`Gst.Element`	r
srcpad	`Gst.Pad`	r	the aggregator’s source pad

Class Details¶

class GstBase.Aggregator(**kwargs)¶

Bases:: Gst.Element
Abstract:: Yes
Structure:: GstBase.AggregatorClass

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 Gst.PadChainFunction, a Gst.PadEventFullFunction and a 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 GstBase.AggregatorPad with the GstBase.AggregatorPad.peek_buffer() method, and remove it from the pad with the GstBase.AggregatorPad.pop_buffer () method. When a buffer has been taken with pop_buffer (), a new buffer can be queued on that pad.
When GstBase.AggregatorPad.peek_buffer() or GstBase.AggregatorPad.has_buffer() are called, a reference is taken to the returned buffer, which stays valid until either:
- 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.
- 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 GstBase.AggregatorClass.aggregate returns.
Subsequent calls to GstBase.AggregatorPad.peek_buffer() or 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 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 GstBase.Aggregator.finish_buffer_list().
Same goes for EOS events, which should not be pushed directly by the subclass, it should instead return Gst.FlowReturn.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.BufferFlags.GAP and Gst.BufferFlags.DROPPABLE to ease their identification and subsequent processing. In addition, if the gap event was flagged with Gst.GapFlags.DATA, a custom meta is added to the resulting gap buffer (GstAggregatorMissingDataMeta).
Subclasses must use (a subclass of) GstBase.AggregatorPad for both their sink and source pads. See Gst.ElementClass.add_static_pad_template_with_gtype().

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

New in version 1.14.

finish_buffer(buffer)[source]¶

Parameters:: buffer (Gst.Buffer) – the Gst.Buffer to push.
Return type:: 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.

finish_buffer_list(bufferlist)[source]¶

Parameters:: bufferlist (Gst.BufferList) – the Gst.BufferList to push.
Return type:: 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.

New in version 1.18.

get_allocator()[source]¶

Returns:

allocator:: the Gst.Allocator used
params:: the Gst.AllocationParams of allocator

Return type:

(allocator: Gst.Allocator or None, params: Gst.AllocationParams)

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

Unref the allocator after use it.

get_buffer_pool()[source]¶

Returns:: the instance of the Gst.BufferPool used by trans; free it after use it
Return type:: Gst.BufferPool or None

get_force_live()[source]¶

Returns:: whether live status was forced on self.
Return type:: bool

Subclasses may use the return value to inform whether they should return Gst.FlowReturn.EOS from their aggregate implementation.

New in version 1.22.

get_ignore_inactive_pads()[source]¶

Returns:: whether inactive pads will not be waited on
Return type:: bool

New in version 1.20.

get_latency()[source]¶

Returns:: The latency or Gst.CLOCK_TIME_NONE if the element does not sync
Return type:: 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()[source]¶

Returns:: True if the negotiation succeeded, else False.
Return type:: bool

Negotiates src pad caps with downstream elements. Unmarks Gst.PadFlags.NEED_RECONFIGURE in any case. But marks it again if #GstAggregatorClass::negotiate fails.

New in version 1.18.

peek_next_sample(pad)[source]¶

Parameters:: pad (GstBase.AggregatorPad) –
Returns:: The sample that is about to be aggregated. It may hold a Gst.Buffer or a Gst.BufferList. The contents of its info structure is subclass-dependent, and documented on a subclass basis. The buffers held by the sample are not writable.
Return type:: Gst.Sample or 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 GstBase.Aggregator ::samples-selected handler, and can be used to precisely control aggregating parameters for a given set of input samples.

New in version 1.18.

selected_samples(pts, dts, duration, info)[source]¶

Parameters:

pts (int) – The presentation timestamp of the next output buffer
dts (int) – The decoding timestamp of the next output buffer
duration (int) – The duration of the next output buffer
info (Gst.Structure or None) – a Gst.Structure containing additional information

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 GstBase.Aggregator.update_segment() is used by the subclass, it MUST be called before GstBase.Aggregator.selected_samples().

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

New in version 1.18.

set_force_live(force_live)[source]¶

Parameters:: force_live (bool) –

Subclasses should call this at construction time in order for self to aggregate on a timeout even when no live source is connected.

New in version 1.22.

set_ignore_inactive_pads(ignore)[source]¶

Parameters:: ignore (bool) – whether inactive pads should not be waited on

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.

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

New in version 1.20.

set_latency(min_latency, max_latency)[source]¶

Parameters:

min_latency (int) – minimum latency
max_latency (int) – maximum latency

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

set_src_caps(caps)[source]¶

Parameters:: caps (Gst.Caps) – The Gst.Caps to set on the src pad.

Sets the caps to be used on the src pad.

simple_get_next_time()[source]¶

Returns:: The running time based on the position
Return type:: int

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

New in version 1.16.

update_segment(segment)[source]¶

Parameters:: segment (Gst.Segment) –

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 GstBase.Aggregator.selected_samples(), if it is used at all.

New in version 1.18.

do_aggregate(timeout) virtual¶

Parameters:: timeout (bool) –
Return type:: Gst.FlowReturn

Mandatory. Called when buffers are queued on all sinkpads. Classes should iterate the Gst.Element->sinkpads and peek or steal buffers from the GstBase.AggregatorPads. If the subclass returns Gst.FlowReturn.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.

do_clip(aggregator_pad, buf) virtual¶

Parameters:

aggregator_pad (GstBase.AggregatorPad) –
buf (Gst.Buffer) –

Return type:

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 None in if the buffer should be dropped.

do_decide_allocation(query) virtual¶

Parameters:: query (Gst.Query) –
Return type:: 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.

do_finish_buffer(buffer) virtual¶

Parameters:: buffer (Gst.Buffer) – the Gst.Buffer to push.
Return type:: 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.

do_finish_buffer_list(bufferlist) virtual¶

Parameters:: bufferlist (Gst.BufferList) – the Gst.BufferList to push.
Return type:: 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.

New in version 1.18.

do_fixate_src_caps(caps) virtual¶

Parameters:: caps (Gst.Caps) –
Return type:: 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.

do_flush() virtual¶

Return type:: Gst.FlowReturn

Optional. Called after a successful flushing seek, once all the flush stops have been received. Flush pad-specific data in GstBase.AggregatorPad->flush.

do_get_next_time() virtual¶

Return type:: 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.

do_negotiate() virtual¶

Returns:: True if the negotiation succeeded, else False.
Return type:: bool

Negotiates src pad caps with downstream elements. Unmarks Gst.PadFlags.NEED_RECONFIGURE in any case. But marks it again if #GstAggregatorClass::negotiate fails.

New in version 1.18.

do_negotiated_src_caps(caps) virtual¶

Parameters:: caps (Gst.Caps) –
Return type:: bool

Optional. Notifies subclasses what caps format has been negotiated

do_peek_next_sample(aggregator_pad) virtual¶

Parameters:: aggregator_pad (GstBase.AggregatorPad) –
Returns:: The sample that is about to be aggregated. It may hold a Gst.Buffer or a Gst.BufferList. The contents of its info structure is subclass-dependent, and documented on a subclass basis. The buffers held by the sample are not writable.
Return type:: Gst.Sample or 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 GstBase.Aggregator ::samples-selected handler, and can be used to precisely control aggregating parameters for a given set of input samples.

New in version 1.18.

do_propose_allocation(pad, decide_query, query) virtual¶

Parameters:

pad (GstBase.AggregatorPad) –
decide_query (Gst.Query) –
query (Gst.Query) –

Return type:

bool

Optional. Allows the subclass to handle the allocation query from upstream.

do_sink_event(aggregator_pad, event) virtual¶

Parameters:

aggregator_pad (GstBase.AggregatorPad) –
event (Gst.Event) –

Return type:

bool

Optional. Called when an event is received on a sink pad, the subclass should always chain up.

do_sink_event_pre_queue(aggregator_pad, event) virtual¶

Parameters:

aggregator_pad (GstBase.AggregatorPad) –
event (Gst.Event) –

Return type:

Gst.FlowReturn

Optional. Called when an event is received on a sink pad before queueing up serialized events. The subclass should always chain up

New in version 1.18.

do_sink_query(aggregator_pad, query) virtual¶

Parameters:

aggregator_pad (GstBase.AggregatorPad) –
query (Gst.Query) –

Return type:

bool

Optional. Called when a query is received on a sink pad, the subclass should always chain up.

do_sink_query_pre_queue(aggregator_pad, query) virtual¶

Parameters:

aggregator_pad (GstBase.AggregatorPad) –
query (Gst.Query) –

Return type:

bool

Optional. Called when a query is received on a sink pad before queueing up serialized queries. The subclass should always chain up

New in version 1.18.

do_src_activate(mode, active) virtual¶

Parameters:

mode (Gst.PadMode) –
active (bool) –

Return type:

bool

Optional. Called when the src pad is activated, it will start/stop its pad task right after that call.

do_src_event(event) virtual¶

Parameters:: event (Gst.Event) –
Return type:: bool

Optional. Called when an event is received on the src pad, the subclass should always chain up.

do_src_query(query) virtual¶

Parameters:: query (Gst.Query) –
Return type:: bool

Optional. Called when a query is received on the src pad, the subclass should always chain up.

do_start() virtual¶

Return type:: bool

Optional. Called when the element goes from READY to PAUSED. The subclass should get ready to process aggregated buffers.

do_stop() virtual¶

Return type:: bool

Optional. Called when the element goes from PAUSED to READY. The subclass should free all resources and reset its state.

do_update_src_caps(caps) virtual¶

Parameters:: caps (Gst.Caps) –
Return type:: (Gst.FlowReturn, ret: Gst.Caps)

Signal Details¶

GstBase.Aggregator.signals.samples_selected(aggregator, segment, pts, dts, duration, info)¶

Signal Name:

samples-selected

Flags:

RUN_FIRST

Parameters:

aggregator (GstBase.Aggregator) – The object which received the signal
segment (Gst.Segment) – The Gst.Segment the next output buffer is part of
pts (int) – The presentation timestamp of the next output buffer
dts (int) – The decoding timestamp of the next output buffer
duration (int) – The duration of the next output buffer
info (Gst.Structure or None) – a Gst.Structure containing additional information

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

New in version 1.18.

Property Details¶

GstBase.Aggregator.props.emit_signals¶

Name:: emit-signals
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

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

New in version 1.18.

GstBase.Aggregator.props.latency¶

Name:: latency
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

Additional latency in live mode to allow upstream to take longer to produce buffers for the current position (in nanoseconds)

GstBase.Aggregator.props.min_upstream_latency¶

Name:: min-upstream-latency
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

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.

New in version 1.16.

GstBase.Aggregator.props.start_time¶

Name:: start-time
Type:: int
Default Value:: 18446744073709551615
Flags:: READABLE, WRITABLE

Start time to use if start-time-selection=set

GstBase.Aggregator.props.start_time_selection¶

Name:: start-time-selection
Type:: GstBase.AggregatorStartTimeSelection
Default Value:: GstBase.AggregatorStartTimeSelection.ZERO
Flags:: READABLE, WRITABLE

Decides which start time is output