GI.GstVideo.Objects.VideoEncoder

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

GstVideoEncoder and subclass should cooperate as follows.

Configuration

• Initially, GstVideoEncoder calls start when the encoder element is activated, which allows subclass to perform any global setup.
• GstVideoEncoder calls setFormat 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.
• GstVideoEncoder calls stop at end of all processing.

Data processing

• Base class collects input data and metadata into a frame and hands this to subclass' handleFrame.

• If codec processing results in encoded data, subclass should call gstVideoEncoderFinishFrame to have encoded data pushed downstream.
• If implemented, baseclass calls subclass prePush just prior to pushing to allow subclasses to modify some metadata on the buffer. If it returns GST_FLOW_OK, the buffer is pushed downstream.
• GstVideoEncoderClass will handle both srcpad and sinkpad events. Sink events will be passed to subclass if event callback has been provided.

Shutdown phase

• GstVideoEncoder 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 gstVideoEncoderFinishFrame.

Things that subclass need to take care of:

• Provide pad templates
• Provide source pad caps before pushing the first buffer
• Accept data in handleFrame and provide encoded results to gstVideoEncoderFinishFrame.

Exported types

newtype VideoEncoder

Constructors

VideoEncoder (ManagedPtr VideoEncoder)

Instances

GObject VideoEncoder

Methods

gobjectType :: VideoEncoder -> IO GType

IsObject VideoEncoder

IsPreset VideoEncoder

IsElement VideoEncoder

IsObject VideoEncoder

IsVideoEncoder VideoEncoder

class GObject o => IsVideoEncoder o

Instances

(GObject a, UnknownAncestorError Constraint VideoEncoder a) => IsVideoEncoder a

IsVideoEncoder VideoEncoder

toVideoEncoder :: (MonadIO m, IsVideoEncoder o) => o -> m VideoEncoder

noVideoEncoder :: Maybe VideoEncoder

Methods

allocateOutputBuffer

videoEncoderAllocateOutputBuffer

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> Word64

size: size of the buffer

-> m Buffer

Returns: allocated buffer

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

allocateOutputFrame

videoEncoderAllocateOutputFrame

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> VideoCodecFrame

frame: a VideoCodecFrame

-> Word64

size: size of the buffer

-> m FlowReturn

Returns: FlowReturnOk if an output buffer could be allocated

Helper function that allocates a buffer to hold an encoded video frame for encoder's current 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.

finishFrame

videoEncoderFinishFrame

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> VideoCodecFrame

frame: an encoded VideoCodecFrame

-> m FlowReturn

Returns: a FlowReturn resulting from sending data downstream

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

getAllocator

videoEncoderGetAllocator

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> m (Allocator, AllocationParams)

Lets VideoEncoder sub-classes to know the memory allocator used by the base class and its params.

Unref the allocator after use it.

getFrame

videoEncoderGetFrame

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a GstVideoEnccoder

-> Int32

frameNumber: system_frame_number of a frame

-> m VideoCodecFrame

Returns: pending unfinished VideoCodecFrame identified by frameNumber.

Get a pending unfinished VideoCodecFrame

getFrames

videoEncoderGetFrames

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> m [VideoCodecFrame]

Returns: pending unfinished VideoCodecFrame.

Get all pending unfinished VideoCodecFrame

getLatency

videoEncoderGetLatency

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> m (Word64, Word64)

Query the configured encoding latency. Results will be returned via minLatency and maxLatency.

getOldestFrame

videoEncoderGetOldestFrame

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> m VideoCodecFrame

Returns: oldest unfinished pending VideoCodecFrame

Get the oldest unfinished pending VideoCodecFrame

getOutputState

videoEncoderGetOutputState

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> m VideoCodecState

Returns: VideoCodecState describing format of video data.

Get the current VideoCodecState

mergeTags

videoEncoderMergeTags

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> Maybe TagList

tags: a TagList to merge, or NULL to unset previously-set tags

-> TagMergeMode

mode: the TagMergeMode to use, usually GST_TAG_MERGE_REPLACE

-> m ()

Sets the video encoder tags and how they should be merged with any upstream stream tags. This will override any tags previously-set with videoEncoderMergeTags.

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

videoEncoderNegotiate

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> m Bool

Returns: TRUE if the negotiation succeeded, else FALSE.

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

proxyGetcaps

videoEncoderProxyGetcaps

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

enc: a VideoEncoder

-> Maybe Caps

caps: initial caps

-> Maybe Caps

filter: filter caps

-> m Caps

Returns: a Caps owned by caller

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

setHeaders

videoEncoderSetHeaders

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> [Buffer]

headers: a list of Buffer containing the codec header

-> m ()

Set the codec headers to be sent downstream whenever requested.

setLatency

videoEncoderSetLatency

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> Word64

minLatency: minimum latency

-> Word64

maxLatency: maximum latency

-> m ()

Informs baseclass of encoding latency.

setMinPts

videoEncoderSetMinPts

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> Word64

minPts: minimal PTS that will be passed to handle_frame

-> m ()

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 accomodate first DTS, which may be less than first PTS

Since 1.6

setOutputState

videoEncoderSetOutputState

Arguments

:: (HasCallStack, MonadIO m, IsVideoEncoder a)

=> a

encoder: a VideoEncoder

-> Caps

caps: the Caps to use for the output

-> Maybe VideoCodecState

reference: An optional reference gstVideoCodecState

-> m VideoCodecState

Returns: the newly configured output state.

Creates a new VideoCodecState with the specified caps as the output state for the encoder. Any previously set output state on encoder 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 VideoCodecState.

If the subclass wishes to copy over existing fields (like pixel aspect ratio, or framerate) from an existing 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 VideoCodecState.

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