VCodecGst C++ library

v1.0.0

Table of contents

• Overview
• Versions
• Library files
• VCodecGst class description
  • VCodecGst class declaration
  • getVersion method
  • transcode method
  • setParam method
  • getParam method
  • executeCommand method
• Build and connect to your project
  • Build and connect to project
• Simple example
• Test application

Overview

The VCodecGst C++ library provides video encoding and decoding functions for H264, HEVC (H265), and JPEG codecs for Linux OS, based on GStreamer. The library supports software encoders/decoders and hardware encoders/decoders for Intel, Nvidia Jetson, NXP, and V4L2 platforms (for example, Raspberry PI). The VCodecGst video codec class inherits its interface and data structures from the VCodec interface library. The library depends on the open-source VCodec library (provides codec interface, source code included, Apache 2.0 license), the open-source GStreamer, and the open-source Logger library (provides functions to print logs, source code included, Apache 2.0 license). The library uses the C++17 standard and is compatible with Linux and Windows. Supported platforms and codecs:

Table 1 - Supported platforms and codecs.

Platform	H264 encoder	H264 decoder	H265 encoder	H265 decoder	JPEG encoder	JPEG decoder
CPU software	x264enc	avdec_h264	x265enc	avdec_h265	jpegenc	jpegdec
Intel	vaapih264enc	vaapih264dec	vaapih265enc	vaapih265dec	jpegenc (SW)	jpegdec (SW)
Nvidia Jetson	nvv4l2h264enc	nvv4l2decoder	nvv4l2h265enc	nvv4l2decoder	nvjpegenc	nvjpegdec
NXP	vpuenc_h264	vpudec	vpuenc_hevc	vpudec	jpegenc (SW)	jpegdec (SW)
V4L2 (Raspberry pi etc)	v4l2h264enc	v4l2h264dec	v4l2h265enc	v4l2h265dec	jpegenc (SW)	jpegdec (SW)
Rockchip (MPP)	mpph264enc	mppvideodec	mpph265enc	mppvideodec	mppjpegenc	mppjpegdec

Versions

Table 2 - Library versions.

Version	Release date	What’s new
1.0.0	12.11.2025	First version.

Library files

The library is supplied as source code only. The user is provided with a set of files in the form of a CMake project (repository). The repository structure is shown below:

CMakeLists.txt ------------- Main CMake file of the library.
3rdparty ------------------- Folder with third-party libraries.
    CMakeLists.txt --------- CMake file to include third-party libraries.
    VCodec ----------------- Folder with VCodec interface library files.
    Logger ----------------- Folder with Logger library files.
src ------------------------ Folder with library source code.
    CMakeLists.txt --------- CMake file of the library.
    VCodecGst.h ------------ Main library header file.
    VCodecGstVersion.h ----- Header file with library version.
    VCodecGstVersion.h.in -- File for CMake to generate version header.
    VCodecGst.cpp ---------- C++ implementation file.
test ----------------------- Folder for test application.
    CMakeLists.txt --------- CMake file for test application.
    main.cpp --------------- Source C++ file of test application.
example -------------------- Folder for simple example.
    CMakeLists.txt --------- CMake file of example.
    main.cpp --------------- Source C++ file of example.

VCodecGst class description

VCodecGst class declaration

The VCodecGst class is declared in the VCodecGst.h file. Class declaration:

namespace cr
{
namespace video
{
class VCodecGst : public VCodec
{
public:

    /// Get library version.
    static std::string getVersion();

    /// Class constructor.
    VCodecGst();

    /// Class destructor.
    ~VCodecGst();

    /// Encode video frame.
    bool transcode(Frame& src, Frame& dst);

    /// Set parameter value.
    bool setParam(VCodecParam id, float value);

    /// Get parameter value.
    float getParam(VCodecParam id);

    /// Execute command.
    bool executeCommand(VCodecCommand id);
};
}
}

getVersion method

The getVersion() method returns a string of the current VCodecGst class version. Method declaration:

static std::string getVersion();

The method can be used without a VCodecGst class instance:

std::cout << "VCodecGst class version: " << VCodecGst::getVersion() << std::endl;

Console output:

VCodecGst class version: 1.0.0

transcode method

The transcode(…) method is intended to encode and decode video frames (Frame class). The video codec encodes/decodes video frames frame-by-frame. Method declaration:

bool transcode(Frame& src, Frame& dst);

Parameter	Value
src	Source video frame (see Frame class description). To encode video data, the src frame must have the NV12 pixel format. To decode video data, the src frame must have a compressed pixel format (field fourcc of the Frame class): JPEG, H264, or HEVC.
dst	Result video frame (see Frame class description). To encode video data, the dst frame must have a compressed pixel format (field fourcc of the Frame class): JPEG, H264, or HEVC. The user must specify the output pixel format in advance. When decoding, the video codec will set the NV12 pixel format automatically.

Returns: TRUE if the frame was successfully encoded/decoded or FALSE if not.

setParam method

The setParam(…) method is designed to set new video codec parameter values. Method declaration:

bool setParam(VCodecParam id, float value);

Parameter	Description
id	Video codec parameter ID according to the VCodecParam enum.
value	Video codec parameter value. Valid values depend on the parameter ID.

Returns: TRUE if the parameter was set successfully or FALSE if not.

The VCodec.h file of the VCodec library defines IDs for parameters (VCodecParam enum) and IDs for commands (VCodecCommand enum). VCodecParam declaration:

namespace cr
{
namespace video
{
enum class VCodecParam
{
    /// [read/write] Log level: 0-Disable, 1-Console, 2-File, 3-Console and file.
    LOG_LEVEL = 1,
    /// [read/write] Bitrate, kbps. For H264 and H265 codecs.
    BITRATE_KBPS,
    /// [read/write] Minimum bitrate, kbps. For variable bitrate mode.
    MIN_BITRATE_KBPS,
    /// [read/write] Maximum bitrate, kbps. For variable bitrate mode.
    MAX_BITRATE_KBPS,
    /// [read/write] Bitrate mode: 0 - constant bitrate, 1 - variable bitrate.
    BITRATE_MODE,
    /// [read/write] Quality 0-100%. For JPEG codecs.
    QUALITY,
    /// [read/write] FPS. For H264 and H265 codecs.
    FPS,
    /// [read/write] GOP size. For H264 and H265 codecs.
    GOP,
    /// [read/write] H264 profile: 0 - Baseline, 1 - Main, 2 - High.
    H264_PROFILE,
    /// [read/write] Codec type. Depends on implementation.
    TYPE,
    /// [read/write] Custom parameter 1. Depends on implementation.
    CUSTOM_1,
    /// [read/write] Custom parameter 2. Depends on implementation.
    CUSTOM_2,
    /// [read/write] Custom parameter 3. Depends on implementation.
    CUSTOM_3
};
}
}

Table 3 - Video codec parameters description.

Parameter	Access	Description
LOG_LEVEL	read / write	Logging mode. Values: 0 - Disable. 1 - Only console (terminal). 2 - Only file. 3 - File and terminal (console).
BITRATE_KBPS	read / write	Bitrate in kbps. Default: 5000 kbps. For H264 and H265 (HEVC) encoding. According to this value, FPS, and GOP size, the video codec calculates parameters for H264 or H265 (HEVC) encoding.
MIN_BITRATE_KBPS	read / write	Minimum bitrate in kbps. Only for H264 and H265 (HEVC) codecs. Default: 2000 kbps. For variable bitrate mode in H264 and H265 (HEVC) encoding. Not currently used in GStreamer pipelines.
MAX_BITRATE_KBPS	read / write	Maximum bitrate in kbps. Only for H264 and H265 (HEVC) codecs. Default: 8000 kbps. For variable bitrate mode in H264 and H265 (HEVC) encoding. Not currently used in GStreamer pipelines.
BITRATE_MODE	read / write	Bitrate mode for H264 and H265 (HEVC) codecs only. Values: 0 - constant bitrate (default), 1 - variable bitrate. Not currently used in GStreamer pipelines.
QUALITY	read / write	Quality 1 (low quality) - 100 (maximum quality). Default: 20. For JPEG encoding (both hardware and software).
FPS	read / write	Frame rate (frames per second). Default: 30. For H264 and H265 (HEVC) encoding and decoding. According to this value, bitrate, and GOP size, the video codec calculates parameters for H264 and H265 (HEVC) encoding.
GOP	read / write	GOP size (period of key frames) for H264 and H265 (HEVC) encoding. Default: 30. Value 1 means each output frame is a key frame, 20 means every 20th frame is a key frame, etc.
H264_PROFILE	read / write	H264 profile for H264 encoding. Default: 0 (Baseline). 0 - Baseline. 1 - Main. 2 - High. Note: Profile is only used for Intel (VAAPI), Nvidia Jetson, and NXP hardware encoders. Software encoder always uses the specified profile.
TYPE	read / write	Type of encoder/decoder. Default: 0 (Software). 0 - Software (x264enc/x265enc, avdec_h264/avdec_h265, jpegenc/jpegdec). 1 - Intel hardware (vaapih264enc/vaapih265enc, vaapih264dec/vaapih265dec). 2 - Nvidia Jetson hardware (nvv4l2h264enc/nvv4l2h265enc, nvv4l2decoder, nvjpegenc/nvjpegdec). 3 - NXP hardware (vpuenc_h264/vpuenc_hevc, vpudec). 4 - V4L2 hardware for Raspberry Pi etc. (v4l2h264enc/v4l2h265enc, v4l2h264dec/v4l2h265dec). 5 - Rockchip (MPP) hardware (mpph264enc/mppvideodec, mpph265enc/mppvideodec, mppjpegenc/mppjpegdec).
CUSTOM_1	read / write	Not supported by the VCodecGst library.
CUSTOM_2	read / write	Not supported by the VCodecGst library.
CUSTOM_3	read / write	Not supported by the VCodecGst library.

getParam method

The getParam(…) method is designed to obtain video codec parameter values. Method declaration:

float getParam(VCodecParam id);

Parameter	Description
id	Video codec parameter ID according to the VCodecParam enum (see Table 3).

Returns: Parameter value or -1 if the parameter is not supported.

executeCommand method

The executeCommand(…) method is designed to execute video codec commands. Method declaration:

bool executeCommand(VCodecCommand id);

Parameter	Description
id	Video codec command ID according to the VCodecCommand enum.

Returns: TRUE if the command was successfully executed or FALSE if not.

The VCodec.h file of the VCodec library defines IDs for parameters (VCodecParam enum) and IDs for commands (VCodecCommand enum). VCodecCommand declaration:

enum class VCodecCommand
{
    /// Reset.
    RESET = 1,
    /// Generate key frame. For H264 and H265 codecs.
    MAKE_KEY_FRAME
};

Table 4 - Video codec commands description.

Command	Description
RESET	Reset the codec. Forces reinitialization of the GStreamer pipeline on the next transcode call.
MAKE_KEY_FRAME	Not supported by the VCodecGst library.

Build and connect to your project

Before compiling, you must install GStreamer packages for your system.

sudo apt-get install build-essential cmake g++ libgstreamer-dev

Build and connect to project

Typical commands to build the VCodecGst library:

cd VCodecGst
mkdir build
cd build
cmake ..
make

If you want to connect the VCodecGst library to your CMake project as source code, you can follow these steps. For example, if your repository has the following structure:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp

Create a 3rdparty folder in your repository and copy the VCodecGst repository folder to the 3rdparty folder. Your repository’s new structure:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    VCodecGst

Create a CMakeLists.txt file in the 3rdparty folder. The CMakeLists.txt should contain:

cmake_minimum_required(VERSION 3.13)

################################################################################
## 3RD-PARTY
## dependencies for the project
################################################################################
project(3rdparty LANGUAGES CXX)

################################################################################
## SETTINGS
## basic 3rd-party settings before use
################################################################################
# To inherit the top-level architecture when the project is used as a submodule.
SET(PARENT ${PARENT}_YOUR_PROJECT_3RDPARTY)
# Disable self-overwriting of parameters inside included subdirectories.
SET(${PARENT}_SUBMODULE_CACHE_OVERWRITE OFF CACHE BOOL "" FORCE)

################################################################################
## INCLUDING SUBDIRECTORIES
## Adding subdirectories according to the 3rd-party configuration
################################################################################
add_subdirectory(VCodecGst)

The 3rdparty/CMakeLists.txt file adds the VCodecGst folder to your project and excludes the test application and example (by default, the test application and example are excluded from compilation when VCodecGst is included as a sub-repository). Your repository’s new structure will be:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    VCodecGst

Next, you need to include the 3rdparty folder in the main CMakeLists.txt file of your repository. Add the following line at the end of your main CMakeLists.txt:

add_subdirectory(3rdparty)

Next, you need to include the VCodecGst library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} VCodecGst)

Done!

Simple example

This simple example opens a video file with OpenCV, captures video from the file, converts frames to the NV12 pixel format (required for the codec), and encodes them. Source code:

#include <iostream>
#include <opencv2/opencv.hpp>
#include "VCodecGst.h"

int main(void)
{
    // Create codec object and set params.
    cr::video::VCodec* encoder = new cr::video::VCodecGst();
    encoder->setParam(cr::video::VCodecParam::BITRATE_KBPS, 10000);
    encoder->setParam(cr::video::VCodecParam::FPS, 20);
    encoder->setParam(cr::video::VCodecParam::GOP, 30);
    encoder->setParam(cr::video::VCodecParam::H264_PROFILE, 0);

    // Open video file with OpenCV.
    cv::VideoCapture videoSource;
    if (!videoSource.open("test.mp4"))
        return -1;

    // Get frame size from video source.
    int width = (int)videoSource.get(cv::CAP_PROP_FRAME_WIDTH);
    int height = (int)videoSource.get(cv::CAP_PROP_FRAME_HEIGHT);

    // Init frames.
    cv::Mat inputFrameBgr(height, width, CV_8UC3);
    cv::Mat inputFrameYuv(height, width, CV_8UC3);
    cr::video::Frame nv12Frame(width, height, cr::video::Fourcc::NV12);
    cr::video::Frame h264Frame(width, height, cr::video::Fourcc::H264);

    // Main loop.
    while (true)
    {
        // Capture next video frame.
        videoSource >> inputFrameBgr;
        if (inputFrameBgr.empty())
        {
            // Set first video frame position.
            videoSource.set(cv::CAP_PROP_POS_FRAMES, 1);
            continue;
        }

        // Convert BGR to YUV.
        cvtColor(inputFrameBgr, inputFrameYuv, cv::COLOR_BGR2YUV);

        // Convert YUV to NV12 (replacing pixels). You can use something else.
        size_t p = height;
        nv12Frame.frameId++; // Just to show unique info.
        for (size_t i = 0; i < (size_t)height; i = i + 2)
        {
            for (size_t j = 0; j < (size_t)width; j = j + 2)
            {
                nv12Frame.data[i * (size_t)width + j] =
                inputFrameYuv.data[i * (size_t)width * 3 + j * 3];
                nv12Frame.data[i * (size_t)width + j + 1] =
                inputFrameYuv.data[i * (size_t)width * 3 + j * 3 + 3];
                nv12Frame.data[(i + 1) * (size_t)width + j] =
                inputFrameYuv.data[(i + 1) * (size_t)width * 3 + j * 3];
                nv12Frame.data[(i + 1) * (size_t)width + j + 1] =
                inputFrameYuv.data[(i + 1) * (size_t)width * 3 + j * 3 + 3];
                nv12Frame.data[p * width + j] =
                inputFrameYuv.data[i * (size_t)width * 3 + j * 3 + 1];
                nv12Frame.data[p * width + j + 1] =
                inputFrameYuv.data[i * (size_t)width * 3 + j * 3 + 2];
            }
            ++p;
        }

        // Encode data.
        if (!encoder->transcode(nv12Frame, h264Frame))
        {
            std::cout << "Can't encode frame" << std::endl;
            continue;
        }

        // Show info.
        std::cout << "[" << h264Frame.frameId << "] Size " <<
        h264Frame.size << " Compression ratio : %" <<
        (int)(100.0f * ((float)h264Frame.size / (float)nv12Frame.size)) <<
        std::endl;
    }
}

Test application

The test application (VCodecGst/test/main.cpp) for the VCodecGst C++ library demonstrates how the library works on various platforms. The test application generates artificial video, compresses it according to the user’s parameters (codec type, bitrate or JPEG quality, GOP size, and H264 profile), writes results to binary files out.h264, out.hevc, or out.mjpeg, and decompresses them. The application shows the encoding and decoding time for each video frame. To run the application, execute the following commands on Linux:

cd <application folder>
sudo chmod +x VCodecGstTest
./VCodecGstTest

After starting, you will see the following output:

====================================
VCodecGst v1.0.0 test
====================================

Enter Encoder type (0 - JPEG, 1 - H264, 2 - HEVC) :

Choose the codec type (0 - JPEG, 1 - H264, 2 - HEVC). If the H264 codec is chosen, you will see the following message:

====================================
VCodecGst v1.0.0 test
====================================

Enter Encoder type (0 - JPEG, 1 - H264, 2 - HEVC) : 1
Enter type of backend (0 - Software, 1 - Intel HW, 2 - Nvidia HW, 3 - NXP HW, 4 - V4L2 HW, 5 - Rockchip HW) : 0
Default params:
Bitrate, kbps 5000
Minimum bitrate, kbps 3000
Maximum bitrate, kbps 7000
Bitrate mode (0 - constant, 1 - variable) 0
FPS: 30
GOP size: 30
Video width 1920
Video height 1080
H264 Profile: 0
Use default params (0 - no, 1 - yes) : 1
Set number frames: 10  
Set noise mode (0 - no noise, 1 - noise) : 0

The user can set custom parameters. When the parameters are chosen, the test application will start encoding frames until stopped (or until the specified number of frames is reached). During encoding, the application shows the encoded data size, encoding time, and decoding time:

Data size 1382400 / 11081   encoding time  34183 us / decoding time 8062 us
Data size 1382400 / 299   encoding time  3389 us / decoding time 1828 us
Data size 1382400 / 2704   encoding time  2878 us / decoding time 1056 us
Data size 1382400 / 6504   encoding time  2452 us / decoding time 1084 us
Data size 1382400 / 348   encoding time  2064 us / decoding time 559 us
Data size 1382400 / 329   encoding time  1957 us / decoding time 861 us
Data size 1382400 / 332   encoding time  2384 us / decoding time 662 us
Data size 1382400 / 20070   encoding time  2414 us / decoding time 1044 us
Data size 1382400 / 20833   encoding time  2297 us / decoding time 656 us
Data size 1382400 / 20834   encoding time  1952 us / decoding time 670 us

---

Table of contents