GstVideo.VideoEncoder

g GObject.GInterface GObject.GInterface Gst.Preset Gst.Preset GObject.GInterface->Gst.Preset GObject.InitiallyUnowned GObject.InitiallyUnowned Gst.Object Gst.Object GObject.InitiallyUnowned->Gst.Object GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned Gst.Element Gst.Element GstVideo.VideoEncoder GstVideo.VideoEncoder Gst.Element->GstVideo.VideoEncoder Gst.Object->Gst.Element Gst.Preset->GstVideo.VideoEncoder

Subclasses:

None

Methods

Inherited:

Gst.Element (81), 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

Description

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

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)
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)
Parameters:
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)
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)
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()
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)
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()
Returns:

pending unfinished GstVideo.VideoCodecFrame.

Return type:

[GstVideo.VideoCodecFrame]

Get all pending unfinished GstVideo.VideoCodecFrame

get_latency()
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)
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()
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()
Returns:

oldest unfinished pending GstVideo.VideoCodecFrame

Return type:

GstVideo.VideoCodecFrame or None

Get the oldest unfinished pending GstVideo.VideoCodecFrame

get_output_state()
Returns:

GstVideo.VideoCodecState describing format of video data.

Return type:

GstVideo.VideoCodecState or None

Get the current GstVideo.VideoCodecState

is_qos_enabled()
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)
Parameters:

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()
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)
Parameters:
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)
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)
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)
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)
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)
Parameters:
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)
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

do_decide_allocation(query) virtual
Parameters:

query (Gst.Query) –

Return type:

bool

do_finish() virtual
Return type:

Gst.FlowReturn

do_flush() virtual
Return type:

bool

do_getcaps(filter) virtual
Parameters:

filter (Gst.Caps) –

Return type:

Gst.Caps

do_handle_frame(frame) virtual
Parameters:

frame (GstVideo.VideoCodecFrame) –

Return type:

Gst.FlowReturn

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

do_pre_push(frame) virtual
Parameters:

frame (GstVideo.VideoCodecFrame) –

Return type:

Gst.FlowReturn

do_propose_allocation(query) virtual
Parameters:

query (Gst.Query) –

Return type:

bool

do_reset(hard) virtual
Parameters:

hard (bool) –

Return type:

bool

do_set_format(state) virtual
Parameters:

state (GstVideo.VideoCodecState) –

Return type:

bool

do_sink_event(event) virtual
Parameters:

event (Gst.Event) –

Return type:

bool

do_sink_query(query) virtual
Parameters:

query (Gst.Query) –

Return type:

bool

do_src_event(event) virtual
Parameters:

event (Gst.Event) –

Return type:

bool

do_src_query(query) virtual
Parameters:

query (Gst.Query) –

Return type:

bool

do_start() virtual
Return type:

bool

do_stop() virtual
Return type:

bool

do_transform_meta(frame, meta) virtual
Parameters:
Return type:

bool

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