GstVideo.VideoEncoder¶

Subclasses:: None

Methods¶

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

	`allocate_output_buffer` (size)
	`allocate_output_frame` (frame, size)
	`finish_frame` (frame)
	`finish_subframe` (frame)
	`get_allocator` ()
	`get_frame` (frame_number)
	`get_frames` ()
	`get_latency` ()
	`get_max_encode_time` (frame)
	`get_min_force_key_unit_interval` ()
	`get_oldest_frame` ()
	`get_output_state` ()
	`is_qos_enabled` ()
	`merge_tags` (tags, mode)
	`negotiate` ()
	`proxy_getcaps` (caps, filter)
	`set_headers` (headers)
	`set_latency` (min_latency, max_latency)
	`set_min_force_key_unit_interval` (interval)
	`set_min_pts` (min_pts)
	`set_output_state` (caps, reference)
	`set_qos_enabled` (enabled)

Virtual Methods¶

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

	`do_close` ()
	`do_decide_allocation` (query)
	`do_finish` ()
	`do_flush` ()
	`do_getcaps` (filter)
	`do_handle_frame` (frame)
	`do_negotiate` ()
	`do_open` ()
	`do_pre_push` (frame)
	`do_propose_allocation` (query)
	`do_reset` (hard)
	`do_set_format` (state)
	`do_sink_event` (event)
	`do_sink_query` (query)
	`do_src_event` (event)
	`do_src_query` (query)
	`do_start` ()
	`do_stop` ()
	`do_transform_meta` (frame, meta)

Properties¶

Inherited:: Gst.Object (2)

Name	Type	Flags	Short Description
`min-force-key-unit-interval`	`int`	r/w	Minimum interval between force-keyunit requests in nanoseconds
`qos`	`bool`	r/w	Handle Quality-of-Service events from downstream

Signals¶

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

Fields¶

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

Name	Type	Access
element	`Gst.Element`	r
input_segment	`Gst.Segment`	r
output_segment	`Gst.Segment`	r
padding	[`object`]	r
sinkpad	`Gst.Pad`	r
srcpad	`Gst.Pad`	r
stream_lock	`GLib.RecMutex`	r

Class Details¶

class GstVideo.VideoEncoder(**kwargs)¶

Bases:: Gst.Element, Gst.Preset
Abstract:: Yes
Structure:: GstVideo.VideoEncoderClass

This base class is for video encoders turning raw video into encoded video data.

GstVideo.VideoEncoder and subclass should cooperate as follows.

Configuration

Initially, GstVideo.VideoEncoder calls start when the encoder element is activated, which allows subclass to perform any global setup.
GstVideo.VideoEncoder calls set_format to inform subclass of the format of input video data that it is about to receive. Subclass should setup for encoding and configure base class as appropriate (e.g. latency). While unlikely, it might be called more than once, if changing input parameters require reconfiguration. Baseclass will ensure that processing of current configuration is finished.
GstVideo.VideoEncoder calls stop at end of all processing.

Data processing

Base class collects input data and metadata into a frame and hands this to subclass’ handle_frame.
- If codec processing results in encoded data, subclass should call gst_video_encoder_finish_frame to have encoded data pushed downstream.
- If implemented, baseclass calls subclass pre_push just prior to pushing to allow subclasses to modify some metadata on the buffer. If it returns Gst.FlowReturn.OK, the buffer is pushed downstream.
- GstVideo.VideoEncoderClass will handle both srcpad and sinkpad events. Sink events will be passed to subclass if event callback has been provided.

Shutdown phase

GstVideo.VideoEncoder class calls stop to inform the subclass that data parsing will be stopped.

Subclass is responsible for providing pad template caps for source and sink pads. The pads need to be named “sink” and “src”. It should also be able to provide fixed src pad caps in getcaps by the time it calls gst_video_encoder_finish_frame.

Things that subclass need to take care of:

Provide pad templates
Provide source pad caps before pushing the first buffer
Accept data in handle_frame and provide encoded results to gst_video_encoder_finish_frame.

The GstVideo.VideoEncoder :qos property will enable the Quality-of-Service features of the encoder which gather statistics about the real-time performance of the downstream elements. If enabled, subclasses can use GstVideo.VideoEncoder.get_max_encode_time() to check if input frames are already late and drop them right away to give a chance to the pipeline to catch up.

allocate_output_buffer(size)[source]¶

Parameters:: size (int) – size of the buffer
Returns:: allocated buffer
Return type:: Gst.Buffer

Helper function that allocates a buffer to hold an encoded video frame for self's current GstVideo.VideoCodecState.

allocate_output_frame(frame, size)[source]¶

Parameters:

frame (GstVideo.VideoCodecFrame) – a GstVideo.VideoCodecFrame
size (int) – size of the buffer

Returns:

Gst.FlowReturn.OK if an output buffer could be allocated

Return type:

Gst.FlowReturn

Helper function that allocates a buffer to hold an encoded video frame for self's current GstVideo.VideoCodecState. Subclass should already have configured video state and set src pad caps.

The buffer allocated here is owned by the frame and you should only keep references to the frame, not the buffer.

finish_frame(frame)[source]¶

Parameters:: frame (GstVideo.VideoCodecFrame) – an encoded GstVideo.VideoCodecFrame
Returns:: a Gst.FlowReturn resulting from sending data downstream
Return type:: Gst.FlowReturn

frame must have a valid encoded data buffer, whose metadata fields are then appropriately set according to frame data or no buffer at all if the frame should be dropped. It is subsequently pushed downstream or provided to pre_push. In any case, the frame is considered finished and released.

After calling this function the output buffer of the frame is to be considered read-only. This function will also change the metadata of the buffer.

finish_subframe(frame)[source]¶

Parameters:: frame (GstVideo.VideoCodecFrame) – a GstVideo.VideoCodecFrame being encoded
Returns:: a Gst.FlowReturn resulting from pushing the buffer downstream.
Return type:: Gst.FlowReturn

If multiple subframes are produced for one input frame then use this method for each subframe, except for the last one. Before calling this function, you need to fill frame->output_buffer with the encoded buffer to push.

You must call GstVideo.VideoEncoder.finish_frame() for the last sub-frame to tell the encoder that the frame has been fully encoded.

This function will change the metadata of frame and frame->output_buffer will be pushed downstream.

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 GstVideo.VideoEncoder sub-classes to know the memory allocator used by the base class and its params.

Unref the allocator after use it.

get_frame(frame_number)[source]¶

Parameters:: frame_number (int) – system_frame_number of a frame
Returns:: pending unfinished GstVideo.VideoCodecFrame identified by frame_number.
Return type:: GstVideo.VideoCodecFrame or None

Get a pending unfinished GstVideo.VideoCodecFrame

get_frames()[source]¶

Returns:: pending unfinished GstVideo.VideoCodecFrame.
Return type:: [GstVideo.VideoCodecFrame]

Get all pending unfinished GstVideo.VideoCodecFrame

get_latency()[source]¶

Returns:

min_latency:: address of variable in which to store the configured minimum latency, or None
max_latency:: address of variable in which to store the configured maximum latency, or None

Return type:

(min_latency: int, max_latency: int)

Query the configured encoding latency. Results will be returned via min_latency and max_latency.

get_max_encode_time(frame)[source]¶

Parameters:: frame (GstVideo.VideoCodecFrame) – a GstVideo.VideoCodecFrame
Returns:: max decoding time.
Return type:: int

Determines maximum possible encoding time for frame that will allow it to encode and arrive in time (as determined by QoS events). In particular, a negative result means encoding in time is no longer possible and should therefore occur as soon/skippy as possible.

If no QoS events have been received from downstream, or if GstVideo.VideoEncoder :qos is disabled this function returns GObject.G_MAXINT64.

New in version 1.14.

get_min_force_key_unit_interval()[source]¶

Returns:: the minimum force-keyunit interval
Return type:: int

Returns the minimum force-keyunit interval, see GstVideo.VideoEncoder.set_min_force_key_unit_interval() for more details.

New in version 1.18.

get_oldest_frame()[source]¶

Returns:: oldest unfinished pending GstVideo.VideoCodecFrame
Return type:: GstVideo.VideoCodecFrame or None

Get the oldest unfinished pending GstVideo.VideoCodecFrame

get_output_state()[source]¶

Returns:: GstVideo.VideoCodecState describing format of video data.
Return type:: GstVideo.VideoCodecState or None

Get the current GstVideo.VideoCodecState

is_qos_enabled()[source]¶

Returns:: True if the encoder is configured to perform Quality-of-Service.
Return type:: bool

Checks if self is currently configured to handle Quality-of-Service events from downstream.

New in version 1.14.

merge_tags(tags, mode)[source]¶

Parameters:

tags (Gst.TagList or None) – a Gst.TagList to merge, or None to unset previously-set tags
mode (Gst.TagMergeMode) – the Gst.TagMergeMode to use, usually Gst.TagMergeMode.REPLACE

Sets the video encoder tags and how they should be merged with any upstream stream tags. This will override any tags previously-set with GstVideo.VideoEncoder.merge_tags().

Note that this is provided for convenience, and the subclass is not required to use this and can still do tag handling on its own.

MT safe.

negotiate()[source]¶

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

Negotiate with downstream elements to currently configured GstVideo.VideoCodecState. Unmark Gst.PadFlags.NEED_RECONFIGURE in any case. But mark it again if negotiate fails.

proxy_getcaps(caps, filter)[source]¶

Parameters:

caps (Gst.Caps or None) – initial caps
filter (Gst.Caps or None) – filter caps

Returns:

a Gst.Caps owned by caller

Return type:

Gst.Caps

Returns caps that express caps (or sink template caps if caps == None) restricted to resolution/format/… combinations supported by downstream elements (e.g. muxers).

set_headers(headers)[source]¶

Parameters:: headers ([Gst.Buffer]) – a list of Gst.Buffer containing the codec header

Set the codec headers to be sent downstream whenever requested.

set_latency(min_latency, max_latency)[source]¶

Parameters:

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

Informs baseclass of encoding latency. If the provided values changed from previously provided ones, this will also post a LATENCY message on the bus so the pipeline can reconfigure its global latency.

set_min_force_key_unit_interval(interval)[source]¶

Parameters:: interval (int) – minimum interval

Sets the minimum interval for requesting keyframes based on force-keyunit events. Setting this to 0 will allow to handle every event, setting this to Gst.CLOCK_TIME_NONE causes force-keyunit events to be ignored.

New in version 1.18.

set_min_pts(min_pts)[source]¶

Parameters:: min_pts (int) – minimal PTS that will be passed to handle_frame

Request minimal value for PTS passed to handle_frame.

For streams with reordered frames this can be used to ensure that there is enough time to accommodate first DTS, which may be less than first PTS

New in version 1.6.

set_output_state(caps, reference)[source]¶

Parameters:

caps (Gst.Caps) – the Gst.Caps to use for the output
reference (GstVideo.VideoCodecState or None) – An optional reference GstVideoCodecState

Returns:

the newly configured output state.

Return type:

GstVideo.VideoCodecState or None

Creates a new GstVideo.VideoCodecState with the specified caps as the output state for the encoder. Any previously set output state on self will be replaced by the newly created one.

The specified caps should not contain any resolution, pixel-aspect-ratio, framerate, codec-data, …. Those should be specified instead in the returned GstVideo.VideoCodecState.

If the subclass wishes to copy over existing fields (like pixel aspect ratio, or framerate) from an existing GstVideo.VideoCodecState, it can be provided as a reference.

If the subclass wishes to override some fields from the output state (like pixel-aspect-ratio or framerate) it can do so on the returned GstVideo.VideoCodecState.

The new output state will only take effect (set on pads and buffers) starting from the next call to GstVideo.VideoEncoder.finish_frame().

set_qos_enabled(enabled)[source]¶

Parameters:: enabled (bool) – the new qos value.

Configures self to handle Quality-of-Service events from downstream.

New in version 1.14.

do_close() virtual¶

Return type:: bool

Optional. Called when the element changes to Gst.State.NULL. Allows closing external resources.

do_decide_allocation(query) virtual¶

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

Optional. Setup the allocation parameters for allocating output buffers. The passed in query contains the result of the downstream allocation query. Subclasses should chain up to the parent implementation to invoke the default handler.

do_finish() virtual¶

Return type:: Gst.FlowReturn

Optional. Called to request subclass to dispatch any pending remaining data (e.g. at EOS).

do_flush() virtual¶

Return type:: bool

Optional. Flush all remaining data from the encoder without pushing it downstream.

New in version 1.2.

do_getcaps(filter) virtual¶

Parameters:: filter (Gst.Caps) –
Return type:: Gst.Caps

Optional. Allows for a custom sink getcaps implementation (e.g. for multichannel input specification). If not implemented, default returns GstVideo.VideoEncoder.proxy_getcaps applied to sink template caps.

do_handle_frame(frame) virtual¶

Parameters:: frame (GstVideo.VideoCodecFrame) –
Return type:: Gst.FlowReturn

Provides input frame to subclass.

do_negotiate() virtual¶

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

Negotiate with downstream elements to currently configured GstVideo.VideoCodecState. Unmark Gst.PadFlags.NEED_RECONFIGURE in any case. But mark it again if negotiate fails.

do_open() virtual¶

Return type:: bool

Optional. Called when the element changes to Gst.State.READY. Allows opening external resources.

do_pre_push(frame) virtual¶

Parameters:: frame (GstVideo.VideoCodecFrame) –
Return type:: Gst.FlowReturn

Optional. Allows subclass to push frame downstream in whatever shape or form it deems appropriate. If not provided, provided encoded frame data is simply pushed downstream.

do_propose_allocation(query) virtual¶

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

Optional. Propose buffer allocation parameters for upstream elements. Subclasses should chain up to the parent implementation to invoke the default handler.

do_reset(hard) virtual¶

Parameters:: hard (bool) –
Return type:: bool

Optional. Allows subclass (encoder) to perform post-seek semantics reset. Deprecated.

do_set_format(state) virtual¶

Parameters:: state (GstVideo.VideoCodecState) –
Return type:: bool

Optional. Notifies subclass of incoming data format. GstVideo.VideoCodecState fields have already been set according to provided caps.

do_sink_event(event) virtual¶

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

Optional. Event handler on the sink pad. This function should return True if the event was handled and should be discarded (i.e. not unref’ed). Subclasses should chain up to the parent implementation to invoke the default handler.

do_sink_query(query) virtual¶

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

Optional. Query handler on the sink pad. This function should return True if the query could be performed. Subclasses should chain up to the parent implementation to invoke the default handler.

New in version 1.4.

do_src_event(event) virtual¶

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

Optional. Event handler on the source pad. This function should return True if the event was handled and should be discarded (i.e. not unref’ed). Subclasses should chain up to the parent implementation to invoke the default handler.

do_src_query(query) virtual¶

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

Optional. Query handler on the source pad. This function should return True if the query could be performed. Subclasses should chain up to the parent implementation to invoke the default handler.

New in version 1.4.

do_start() virtual¶

Return type:: bool

Optional. Called when the element starts processing. Allows opening external resources.

do_stop() virtual¶

Return type:: bool

Optional. Called when the element stops processing. Allows closing external resources.

do_transform_meta(frame, meta) virtual¶

Parameters:

frame (GstVideo.VideoCodecFrame) –
meta (Gst.Meta) –

Return type:

bool

Optional. Transform the metadata on the input buffer to the output buffer. By default this method is copies all meta without tags and meta with only the “video” tag. subclasses can implement this method and return True if the metadata is to be copied.

New in version 1.6.

Property Details¶

GstVideo.VideoEncoder.props.min_force_key_unit_interval¶

Name:: min-force-key-unit-interval
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

Minimum interval between force-keyunit requests in nanoseconds. See GstVideo.VideoEncoder.set_min_force_key_unit_interval() for more details.

New in version 1.18.

GstVideo.VideoEncoder.props.qos¶

Name:: qos
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE

Handle Quality-of-Service events from downstream