videorecordermp4_web_logo

VideoRecorderMp4 C++ library

v2.0.0

Table of contents

Overview

The VideoRecorderMp4 C++ library provides functionality for recording video to files with control over file and folder size. It records .mp4 video files and accepts frames in H264, HEVC and JPEG compressed formats. The library is cross-platform and compatible with Windows and Linux. It uses the C++17 standard and depends on the Frame (describes the video frame class, source code included, Apache 2.0 license). Additionally, the test application depends on the VSourceFile library (source code included) to prepare test H264, HEVC or JPEG frames.

Versions

Table 1 - Library versions.

Version Release date What’s new
1.0.0 31.03.2025 - First version.
1.0.1 14.08.2025 - Fix compiler warnings.
1.0.2 15.11.2025 - VCodecLibav submodule updated for test application.
1.0.3 17.04.2026 - VCodecLibav submodule updated for test application.
2.0.0 08.05.2026 - Remove mp4v2 dependency.
- Implement mp4 container packer.
- Added HEVC and JPEG support.
- Remove VCodecLibav from the test app.
- Added VSourceFile to the test app.
- Rewrite the test app.

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 3rd-party libraries.
    CMakeLists.txt ---------------- CMake file of 3rd-party libraries folder.
    Frame ------------------------- Folder with Frame library source code.
src ------------------------------- Folder with library source code.
    CMakeLists.txt ---------------- CMake file of the library.
    Mp4Container.cpp -------------- MP4 container packer implementation.
    Mp4Container.h ---------------- MP4 container packer header.
    Mp4Node.cpp ------------------- MP4 box node classes implementation.
    Mp4Node.h --------------------- MP4 box node classes declarations.
    VideoRecorderMp4.cpp ---------- C++ implementation file.
    VideoRecorderMp4.h ------------ Main library header file.
    VideoRecorderMp4Version.h ----- Header file with library version.
    VideoRecorderMp4Version.h.in -- CMake service file to generate version header.
static ---------------------------- Static assets.
    in.h264 ----------------------- Raw H.264 Annex B bitstream for the test app.
    in.hevc ----------------------- Raw H.265 Annex B bitstream for the test app.
    in.mjpeg ---------------------- Concatenated JPEG frames for the test app.
test ------------------------------ Folder for test application.
    3rdparty ---------------------- Folder with 3rd-party libraries for test application.
        CMakeLists.txt ------------ CMake file of 3rd-party libraries folder.
        VSourceFile --------------- Folder with VSourceFile library source code.
    CMakeLists.txt ---------------- CMake file for test application.
    main.cpp ---------------------- Source code of test application.

VideoRecorderMp4 class description

VideoRecorderMp4 class declaration

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

namespace cr
{
namespace video
{
/// Video recorder class.
class VideoRecorderMp4
{
public:

    /// Class destructor.
    ~VideoRecorderMp4();

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

    /// Init video recorder.
    bool init(std::string initString);

    /// Write video frame.
    bool write(Frame& frame);

    /// Stop video recording.
    void stop();
};
}
}

getVersion method

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

static std::string getVersion();

The method can be used without a VideoRecorderMp4 class instance:

std::cout << "VideoRecorderMp4 v" << cr::video::VideoRecorderMp4::getVersion();

Console output:

VideoRecorderMp4 v2.0.0

init method

The init(…) method initializes the video recorder. The method checks if the destination folder exists; if it does not, it will be created. Method declaration:

bool init(std::string initString);
Parameter Value
initString Initialization string. Format: <folder>;<maxFolderSizeMB>;<maxFileSizeMB>;<prefix>;<fps>.
Example: “video;2000;200;test;30”.
Initialization string parameters:
folder - Folder path to store video. The method will check if this folder exists, and if not, the method will create it.
maxFolderSizeMB - Maximum folder size (size of all files) in megabytes.
maxFileSizeMB - Maximum video file size in megabytes. If the size of the currently recorded video file exceeds the specified size, the library will stop recording and create a new file.
prefix - Prefix for file names.
fps - FPS of the output file. This value will be recorded in the .mp4 video file header for playback.
Final file example format: prefix_day_month_year_hour_minute_second.mp4, for example: testVideo_10_12_2025_09_30_20.mp4.

Returns: TRUE if the video recorder is initialized or FALSE if not.

write method

The write(…) method writes a frame in H264, HEVC or JPEG format to the output video file. Method declaration:

bool write(Frame& frame);
Parameter Value
frame Frame object to write. It must be in H264, HEVC or JPEG compressed format.

Returns: TRUE if the video frame was recorded or FALSE if not.

stop method

The stop() method stops video recording and finalizes the output .mp4 file. Calling it explicitly is recommended so the file is closed promptly. Method declaration:

void stop();

Build and connect to your project

The VSourceFile library is required by the test application and is bundled as source code in test/3rdparty/VSourceFile. Typical commands to build the VideoRecorderMp4 library:

cd VideoRecorderMp4 
mkdir build
cd build
cmake ..
make

If you want to connect the VideoRecorderMp4 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 and copy the VideoRecorderMp4 repository folder there. Your repository’s new structure:

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

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
################################################################################
if (${PARENT}_SUBMODULE_VIDEO_RECORDER_MP4)
    add_subdirectory(VideoRecorderMp4)
endif()

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

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

target_link_libraries(${PROJECT_NAME} VideoRecorderMp4)

Done!

Test application

The test application is designed to verify that the VideoRecorderMp4 library packs frames into the MP4 container correctly. After starting, the test application will prompt the user to set the codec type (JPEG, H264, HEVC), the folder name, the maximum folder size, and the maximum file size. The application reads raw encoded frames from a static file in the current working directory: in.h264 for H264, in.hevc for HEVC, or in.mjpeg for JPEG. These bitstreams live in the static/ folder; the test app’s CMakeLists.txt has a post-build step that copies all static/in.* files next to the executable, so they are ready to use right after build - no manual copy needed. To run the application, execute the following commands on Linux or simply run VideoRecorderMp4Test.exe on Windows:

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

The test application will start and ask for the source codec:

##################################
VideoRecorderMp4 v2.0.0 test
##################################
Enter source codec (0 - JPEG, 1 - H264, 2 - HEVC):

Choose the desired codec:

  • 0 - JPEG.
  • 1 - H264.
  • 2 - HEVC.

Next, the application will ask for the folder to write video to:

##################################
VideoRecorderMp4 v2.0.0 test
##################################
Enter source codec (0 - JPEG, 1 - H264, 2 - HEVC): 1
Enter folder to write video:

Then the application will ask for the maximum folder size in MB:

##################################
VideoRecorderMp4 v2.0.0 test
##################################
Enter source codec (0 - JPEG, 1 - H264, 2 - HEVC): 1
Enter folder to write video: testFolder
Enter max folder size, MB:

Then the application will ask for the maximum file size in MB:

##################################
VideoRecorderMp4 v2.0.0 test
##################################
Enter source codec (0 - JPEG, 1 - H264, 2 - HEVC): 1
Enter folder to write video: testFolder
Enter max folder size, MB: 20
Enter max file size, MB:

After all settings are entered, the test application starts reading frames from the input file and packing them into the MP4 container:

##################################
VideoRecorderMp4 v2.0.0 test
##################################
Enter source codec (0 - JPEG, 1 - H264, 2 - HEVC): 1
Enter folder to write video: testFolder
Enter max folder size, MB: 20
Enter max file size, MB: 5
Press Ctrl+C to interrupt the recording.

The application processes each frame and writes it into an MP4 file in the destination folder. Don’t worry if the file size does not appear to grow immediately - the OS may cache some data and flush it to disk later.

The recording can be interrupted by pressing Ctrl+C. After that, you can finish the recording or restart it:

^CRecording is interrupted.
 0 - Stop recording and exit test.
 1 - Start new recording.
Choose option:

Table of contents