VCodecLibav C++ library

v1.3.4

Table of contents

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

Overview

The VCodecLibav C++ library provides video encoding and decoding functions for H264, HEVC (H265), and JPEG codecs for Linux and Windows OS based on FFmpeg. The library supports software encoders/decoders and Intel hardware encoders/decoders. The library is compatible with any CPU (software encoder) that supports FFmpeg. The VCodecLibav video codec class inherits 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 Libav library (part of FFmpeg, linked), and the open-source Logger (provides functions to print logs, source code included, Apache 2.0 license). The library uses the C++17 standard. FFmpeg codecs used:

Codec	FFmpeg encoder	FFmpeg decoder
H264	h264_vaapi (Intel VAAPI-based codec) for hardware encoding on Linux and h264_qsv for hardware encoding on Windows. For software encoding, libx264 is used for both Linux and Windows.	h264_qsv (Intel QuickSync-based) for hardware decoding or libx264 for software decoding on both Linux and Windows.
HEVC (H265)	hevc_vaapi (Intel VAAPI-based codec) for hardware encoding on Linux and hevc_qsv for hardware encoding on Windows. For software encoding, libx265 is used for both Linux and Windows.	hevc_qsv (Intel QuickSync-based) for hardware decoding or libx265 for software decoding on both Linux and Windows.
JPEG	mjpeg_vaapi (Intel VAAPI-based codec) for hardware encoding on Linux and mjpeg_qsv for hardware encoding on Windows. For software encoding, mjpeg is used for both Linux and Windows. Warning: The mjpeg software codec produces JPEG that is not fully compatible (doesn’t have DHT like standard JPEG does).	mjpeg_qsv (Intel QuickSync-based) for hardware decoding and mjpeg for software decoding.

The primary difference between software (SW) and hardware (HW) encoders and decoders is the latency they introduce. SW encoders and decoders have zero frame latency, but they take more time than HW encoders and decoders. On the other hand, HW encoders have 1 frame latency, and HW decoders have 3 frames latency for H264 codecs. Encoding/decoding time on 11th Gen Intel(R) Core(TM) i5-1145G7E @ 2.60GHz, Ubuntu 22.10, msec:

Hardware codec / resolution	1920x1080	1280x720	640x512
H264	5 msec / 3 msec	2 msec / 1.6 msec	0.6 msec / 0.5 msec
H265	5 msec / 3 msec	3 msec / 1.2 msec	2 msec / 0.6 msec
JPEG	2 msec / 4 msec	1 msec / 1.5 msec	0.3 msec / 0.6 msec
Software codec (1 thread) / resolution	1920x1080	1280x720	640x512
H264	8 msec / 3 msec	3.5 msec / 1.5 msec	1.8 msec / 0.9 msec
H265	35 msec / 10 msec	25 msec / 8 msec	15 msec / 7 msec
JPEG	4 msec / 3 msec	1.8 msec / 1.4 msec	0.9 msec / 0.7 msec

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	29.06.2023	First version.
1.0.1	02.07.2023	- Source code cleaned up. - Documentation updated.
1.0.2	16.11.2023	- VCodec class updated.
1.0.3	20.12.2023	- Add specific encoder settings for noisy video. - Example added.
1.1.0	17.01.2024	- Added software encoder/decoder support for JPEG, H264, and HEVC. - Examples updated.
1.1.1	11.03.2024	- Added Windows support. - Documentation updated.
1.1.2	26.04.2024	- Submodules updated. - Documentation updated.
1.1.3	17.05.2024	- Submodules updated. - Documentation updated.
1.2.0	16.09.2024	- Added data action commands RESET and MAKE_KEY_FRAME.
1.2.1	10.10.2024	- Fixed resolution alignment issue for SW codec.
1.2.2	21.10.2024	- Fixed constant bitrate encoding settings for software encoder.
1.3.0	01.11.2024	- Fixed settings for CBR and VBR mode for hardware and software encoders. - Updated VCodec interface with variable bitrate params. - Added variable bitrate params.
1.3.1	06.11.2024	- Fixed device name initialization in test application.
1.3.2	19.11.2024	- Added x264 speed preset control (ultrafast or superfast).
1.3.3	03.04.2025	- Logger submodule update.
1.3.4	02.11.2025	- VCodec submodule update. - Documentation update.

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.
    VCodecLibav.h ------------ Main library header file.
    VCodecLibavVersion.h ----- Header file with library version.
    VCodecLibavVersion.h.in -- File for CMake to generate version header.
    VCodecLibav.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.

VCodecLibav class description

VCodecLibav class declaration

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

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

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

    /// Class constructor.
    VCodecLibav();

    /// Class destructor.
    ~VCodecLibav();

    /// 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 version of the VCodecLibav class. Method declaration:

static std::string getVersion();

This method can be used without a VCodecLibav class instance:

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

Console output:

VCodecLibav class version: 1.3.4

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 NV12 pixel format. To decode video data, the src frame must have a compressed pixel format (field fourcc of 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 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 encoded/decoded successfully 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,
    /// Custom 1. Depends on implementation.
    CUSTOM_1,
    /// Custom 2. Depends on implementation.
    CUSTOM_2,
    /// Custom 3. Depends on implementation.
    CUSTOM_3
};
}
}

Table 2 - Video codec parameters description. Some parameters are not supported by the VCodecLibav library.

Parameter	Access	Description
LOG_LEVEL	read / write	Logging mode. Values: 0 - Disable. 1 - Only file. 2 - Only terminal (console). 3 - File and terminal.
BITRATE_KBPS	read / write	Bitrate, 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. - Sets special settings for noisy video if bitrate is 0 for hardware encoding. - For software JPEG encoding, increasing bitrate gives higher quality.
MIN_BITRATE_KBPS	read / write	Minimum bitrate, kbps. Only for H264 and H265 (HEVC) codecs. Default: 2000 kbps. For variable bitrate mode in H264 and H265 (HEVC) encoding.
MAX_BITRATE_KBPS	read / write	Maximum bitrate, kbps. Only for H264 and H265 (HEVC) codecs. Default: 8000 kbps. For variable bitrate mode in H264 and H265 (HEVC) encoding.
BITRATE_MODE	read / write	Bitrate mode for H264 and H265 (HEVC) codecs only. Values: 0 - constant bitrate (default), 1 - variable bitrate.
QUALITY	read / write	Quality 0 (low quality) - 100% (maximum quality). Only for hardware JPEG encoding. Not supported by JPEG software encoding.
FPS	read / write	Frames per second. For H264 and H265 (HEVC) encoding only. According to this value, FPS, 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. Value: 1 - each output frame is a key frame, 20 - each 20th frame is a key frame, etc.
H264_PROFILE	read / write	H264 profile for H264 encoding: 0 - Baseline. 1 - Main. 2 - High. For hardware encoding only.
TYPE	read / write	Type of encoder/decoder: 0 - hardware (default). 1 - software.
CUSTOM_1	read / write	Number of threads for software encoder/decoder. Thread count for software encoder/decoder H264 / HEVC (H265) (not for JPEG): 1-32, default value 1. Note: When using one thread, the software encoder produces only one slice per frame. When using multiple threads, frames can have multiple slices, which can affect RTSP servers.
CUSTOM_2	read / write	x264 codec speed preset: 0 - ultrafast (default), 1 - superfast.
CUSTOM_3	read / write	Not supported by the VCodecLibav 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 2).

Returns: Parameter value or -1 if the parameter doesn’t exist in the particular video codec class.

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 executed 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). VCodecCommand declaration:

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

Table 3 - Video codec commands description. Some commands may be unsupported by particular video codec classes.

Command	Description
RESET	Reset codec.
MAKE_KEY_FRAME	Generate key frame for H264 and HEVC codecs. The next frame will be a key frame for H264 and HEVC codecs.

Build and connect to your project

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

Installation on Linux

sudo apt-get install -y build-essential cmake ffmpeg libavcodec-dev libavutil-dev libavformat-dev libavdevice-dev libavfilter-dev libcurl4

Installation on Windows

To install the FFmpeg package in Windows, follow these steps:

1. Go to the latest build of FFmpeg and download ffmpeg-master-latest-win64-lgpl-shared.zip (64-bit libraries under LGPL license without software encoders/decoders, only hardware encoders/decoders) or download ffmpeg-master-latest-win64-gpl-shared.zip (64-bit libraries under GPL license with software and hardware encoders/decoders).
2. Extract the zip file to any folder (recommended path: C:/libs/ffmpeg/ffmpeg-master-latest-win64-lgpl-shared or C:/libs/ffmpeg/ffmpeg-master-latest-win64-gpl-shared). The extracted folder must contain the following folders: bin, include, lib, etc.
3. Add the path to FFmpeg libraries to Windows system variables. To do this, go to (Windows 11): Settings -> System -> Advanced system settings -> Environment Variables.
4. Create a new variable in the System variables section with the name FFmpeg_DIR and the path to your FFmpeg files (for example, C:/libs/ffmpeg/ffmpeg-master-latest-win64-gpl-shared) and save the changes. If the system variable FFmpeg_DIR is not set, the library will try to find FFmpeg libraries in the C:/libs/ffmpeg/ffmpeg-master-latest-win64-gpl-shared folder.
5. Sometimes a Windows reboot is required to implement the changes.

Build and connect to project

Typical commands to build the VCodecLibav library:

cd VCodecLibav
mkdir build
cd build
cmake ..
make

If you want to connect the VCodecLibav 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 VCodecLibav repository folder to the 3rdparty folder. The new structure of your repository:

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

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)

################################################################################
## CONFIGURATION
## 3rd-party submodules configuration
################################################################################
SET(${PARENT}_SUBMODULE_VCODEC_LIBAV                    ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_VCODEC_LIBAV)
    SET(${PARENT}_VCODEC_LIBAV                          ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_VCODEC_LIBAV_TEST                     OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_VCODEC_LIBAV_EXAMPLE                  OFF CACHE BOOL "" FORCE)
endif()

################################################################################
## INCLUDING SUBDIRECTORIES
## Adding subdirectories according to the 3rd-party configuration
################################################################################
if (${PARENT}_SUBMODULE_VCODEC_LIBAV)
    add_subdirectory(VCodecLibav)
endif()

The 3rdparty/CMakeLists.txt file adds the VCodecLibav folder to your project and excludes the test application and example (by default, the test application and example are excluded from compilation if VCodecLibav 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
    VCodecLibav

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 VCodecLibav library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} VCodecLibav)

Done!

Simple example

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

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

int main(void)
{
    // Create codec object and set params.
    cr::video::VCodec* encoder = new cr::video::VCodecLibav();
    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 (pixel format conversion). You can use alternative methods.
        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 (VCodecLibav/test/main.cpp) for the VCodecLibav C++ library demonstrates how the library works on Intel platforms. The test application generates artificial video, compresses it according to user 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 encoding and decoding time for each video frame. To run the application, perform the following commands on Linux or simply run VCodecLibavTest.exe on Windows:

cd <application folder>
sudo chmod +x VCodecLibavTest
./VCodecLibav

After starting, you will see the following output:

====================================
VCodecLibav v1.3.4 test
====================================

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

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

====================================
VCodecLibav v1.3.4 test
====================================

Enter Encoder type (0 - JPEG, 1 - H264, 2 - HEVC) : 1
Enter backend type (0 - hardware, 1 - software): 1
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 1280
Video height 720
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 parameters are chosen, the test application will start writing encoded frames until stopped (if the user sets a number of frames). 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