Skip to content

Encoder

Jump to bottom
ReferenceType edited this page Mar 12, 2025 · 8 revisions

H264Encoder Class

The H264Encoder class provides an H.264 encoder based on Cisco's OpenH264 library. It allows you to encode RGB and YUV images into H.264 video streams.

Table of Contents

Overview

The H264Encoder class wraps the Cisco OpenH264 library and acts as a facade for ease of use. It supports various initialization modes, runtime configuration adjustments, and different input image formats.

Features:

  • Encodes RGB,BGR,RGBA,BGRA and YUV(I420Planar or NV12 interleaved) images to H.264.
  • Supports runtime configuration adjustments (bitrate, FPS, options).
  • Provides multiple initialization methods for different scenarios.
  • Implements IDisposable for proper resource management.

Constructors

Constructor Description
H264Encoder() Creates a new instance using the default Cisco DLL name which is defined in. Defines.CiscoDllName
H264Encoder(string ciscoDllPath) Creates a new instance using the specified Cisco DLL path.(LoadLibraryW on windows,dlopen with RTLD_LAZY on linux)

Properties

Property Type Description
EnableDebugPrints bool Enables or disables debug prints during initialization.

Methods

Method Return Type Description
GetDefaultParameters() TagEncParamExt Retrieves the default advanced configuration parameters.
Initialize(int width, int height, int bitrate, int fps, ConfigType configType) int Initializes the encoder with basic parameters and a pre-configured configuration type.
Initialize(TagEncParamBase param) int Initializes the encoder with base encoding parameters.
Initialize(TagEncParamExt param) int Initializes the encoder with advanced encoding parameters.
ForceIntraFrame() bool Forces an intra frame(IDR) on the next encode.
SetMaxBitrate(int target) void Sets the maximum bitrate.
SetTargetFps(float target) void Sets the target frames per second.
GetOption<T>(ENCODER_OPTION option, out T value) bool Gets an encoder option.
GetOptionRef<T>(ENCODER_OPTION option, ref T value) bool Gets an encoder option, allowing reuse of the value.
SetOption<T>(ENCODER_OPTION option, T value) bool Sets an encoder option.
Encode(RgbImage im, out EncodedData[] ed) bool Encodes an RGB image.
Encode(YUVNV12ImagePointer yuv, out EncodedData[] ed) bool Encodes a YUV NV12 image.
Encode(YUVImagePointer yuv, out EncodedData[] ed) bool Encodes a YUV I420P image.
Encode(YuvImage yuv, out EncodedData[] ed) bool Encodes a YUV I420P image from reference.
Dispose() void Disposes of the encoder and releases native resources.

Premade Configurations

Enum Member Description
CameraBasic Standard setting for camera capture.
ScreenCaptureBasic Standard setting for screen capture.
CameraCaptureAdvanced Advanced configuration for camera capture.
ScreenCaptureAdvanced Advanced configuration for screen capture.
CameraCaptureAdvancedHP Advanced camera capture with parallel encoder(might sacrifice quality).
ScreenCaptureAdvancedHp Advanced screen capture with parallel encoder(might sacrifice quality).

Usage Examples

Encoder(also Decoder) is a stateful object and you should manage the lifetimes on your program.

Creating and Initializing an Encoder with Basic Parameters

using (var encoder = new H264Encoder())
{
    int width = 1280;
    int height = 720;
    int bitrate = 2000000; // 2 Mbps
    int fps = 30;
    ConfigType configType = ConfigType.CameraCaptureAdvanced;

    encoder.Initialize(width, height, bitrate, fps, configType);

    // Encode an RgbImage
    RgbImage image = new RgbImage(ImageFormat.Rgb, width, height);
    if (encoder.Encode(image, out EncodedData[] encodedData))
    {
            // Process encoded data
    }

}

Creating and Initializing an Encoder with Advanced Parameters

using (var encoder = new H264Encoder())
{
    var param = encoder.GetDefaultParameters();
    // modify the parameters..
    encoder.Initialize(param);

    // Encode an YUV NV12(emulate some source)
    var nv12 = new YUVNV12ImagePointer(...);
    if (encoder.Encode(nv12, out EncodedData[] encodedData))
    {
        // Process encoded data
    }
}

Setting Runtime Configuration

encoder.SetMaxBitrate(2000000); // 2 Mbps
encoder.SetTargetFps(30.0f);
encoder.ForceIntraFrame();

Getting and Setting Options

int idrInterval;
if (encoder.GetOption(ENCODER_OPTION.ENCODER_OPTION_IDR_INTERVAL, out idrInterval))
{
    if (idrInterval<120)
    {
        encoder.SetOption(ENCODER_OPTION.ENCODER_OPTION_IDR_INTERVAL, 120);
    }
}

Remarks

bool value = encoder.Encode(..,out EncodedData[] encodedData) returns a bool value which indicates encoding is actually performed or not. if the Boolean value is false it means frame is skipped. This generally happens to hit the target bit rate.

On single layer(standard use case) for IDR frames you get more than one EncodedData, the first frame is a metadata and it will produce neither an image nor an error when decoded. Decoder can work with both frame by frame or merged, That is, you can either give the frames one by one, or merge them together into contiguous bytes and do one shot decoding.

Clone this wiki locally