framewright

A drop-in replacement for cv::VideoCapture and cv::VideoWriter that gives you frame-precise seeking, color space control, HDR10 writing, and lossless encoding.

Available for C++, Python, and JavaScript — Node.js and browsers via WebAssembly (see wasm/README.md).

What framewright adds over OpenCV

Reading

Writing

Verified accuracy

Measured by reading BT.709-tagged lossless test videos with both libraries (OpenCV 4.13.0 and framewright on macOS). Both produce identical pixel values when metadata is present — framewright adds control, not a different answer:

cmake -B build -DFRAMEWRIGHT_BUILD_EXAMPLES=ON && cmake --build build
./build/compare_readers your_video.mp4

Migrating from OpenCV

framewright is a drop-in replacement. The API follows the same conventions (BGR cv::Mat frames):

Reading

// OpenCV
cv::VideoCapture cap("video.mp4");
cv::Mat frame;
cap.read(frame);

// framewright — same API, more capabilities
framewright::VideoReader reader;
reader.open("video.mp4");
cv::Mat frame;
reader.read(frame);

// seek backward (not possible with cv::VideoCapture)
reader.seek(0);
reader.read(frame);

// inspect color metadata
std::cout << "Color space: " << reader.getColorSpace() << std::endl;
std::cout << "Pixel format: " << av_get_pix_fmt_name(reader.getPixelFormat()) << std::endl;

Writing

// OpenCV
cv::VideoWriter w("out.mp4",
    cv::VideoWriter::fourcc('a','v','c','1'),
    30, cv::Size(1920, 1080));
w.write(frame);

// framewright — same pattern, more control
framewright::VideoWriter w;
w.open("out.mp4", AV_CODEC_ID_H264, 1920, 1080, {30, 1});
w.write(frame);
w.release();

Property mapping

Quick start

C++

#include <framewright/framewright.h>

// Read with correct BT.709 color conversion
framewright::VideoReader reader;
reader.open("input.mp4", /*force_bt709=*/true);

cv::Mat frame;
while (reader.read(frame)) {
    // frame is BGR cv::Mat with correct pixel values
}

// Write HDR10 HEVC
framewright::VideoWriterOptions opts;
opts.pix_fmt = AV_PIX_FMT_YUV420P10LE;
opts.is_10bit = true;

framewright::VideoWriter writer;
writer.open("output.mp4", AV_CODEC_ID_HEVC, 3840, 2160,
            {60000, 1001}, opts);  // 59.94 fps
writer.write(hdr_frame);  // CV_16UC3 BGR
writer.release();

Python

import framewright

reader = framewright.VideoReader()
reader.open("input.mp4", force_bt709=True)
for frame in reader:  # numpy (H, W, 3) uint8 BGR
    print(frame.shape, frame.dtype)

writer = framewright.VideoWriter()
writer.open("output.mp4", codec="h264", width=1920, height=1080, fps=30)
writer.write(frame)
writer.release()

Reading HDR video

HDR sources (BT.2020 with PQ/SMPTE 2084 or HLG transfer) always get the correct BT.2020 color matrix. Beyond the matrix you have three choices:

// 1. Display-ready SDR: linearize PQ/HLG, tone map (peak from the source's
//    mastering metadata when present, 1000 nits otherwise), convert BT.2020
//    primaries to BT.709, encode with BT.709 gamma.
framewright::VideoReaderOptions opts;
opts.hdr_mode = framewright::HdrMode::ToneMapSDR;
reader.open("hdr10.mp4", opts);
reader.read(frame);   // CV_8UC3, looks right on an SDR display

// 2. Full-precision code values for your own pipeline: the transfer function
//    is NOT applied, so PQ/HLG data stays encoded, at 16-bit precision.
reader.open("hdr10.mp4");
reader.read16(frame); // CV_16UC3; pair with getColorTransfer()/getColorPrimaries()

// 2b. Linear light for image math: transfer function removed (PQ/HLG/SDR),
//     float BGR normalized so 1.0 == SDR reference white (100 nits).
//     HDR highlights exceed 1.0. Primaries unchanged.
reader.readLinear(frame); // CV_32FC3

// 3. Default read() is unchanged: matrix-only conversion. For HDR sources the
//    result remains HDR-encoded (washed out as sRGB) and a warning is logged.

Python: reader.open("hdr10.mp4", tone_map_hdr=True), reader.read16(), reader.read_linear().

New to color management? docs/COLOR.md explains matrices, range, primaries, transfer functions, linear light, and tone mapping — and which framewright call gives you which.

Only codec-level color metadata is honored. Frame-level dynamic metadata (HDR10+, Dolby Vision RPUs) is ignored: Dolby Vision profile 5 content (ICtCp) decodes with approximated colors and a warning.

Building

As a dependency (CMake FetchContent)

include(FetchContent)
FetchContent_Declare(
    framewright
    GIT_REPOSITORY https://github.com/kmatzen/framewright.git
    GIT_TAG main
)
FetchContent_MakeAvailable(framewright)

target_link_libraries(your_target PRIVATE framewright::framewright)

Standalone

mkdir build && cd build
cmake .. -DFRAMEWRIGHT_BUILD_EXAMPLES=ON
make -j$(nproc)

Python

pip install framewright

Binary wheels (Linux x86_64, macOS arm64, Windows AMD64, CPython 3.9–3.13) bundle a statically linked, LGPL FFmpeg and OpenCV core — no system dependencies needed. One consequence of the LGPL build: the wheels contain no x264/x265, so H.264/HEVC writing is unavailable in wheel installs (open() returns false with "codec not found"); reading — including all HDR paths — and FFV1 lossless writing are fully functional. For H.264/HEVC writing, install from source against a system FFmpeg that includes them:

pip install framewright --no-binary framewright   # needs OpenCV + FFmpeg dev packages

Requirements

• C++17 compiler
• OpenCV 4.0+
• FFmpeg 4.2+ (libavformat, libavcodec, libswscale, libavutil)

Windows

Dependency lookup no longer hard-requires pkg-config (Windows has none by default): CMake tries pkg-config first, then falls back to a plain find_library search. The easiest way to get both dependencies is vcpkg in manifest mode, using the vcpkg.json in this repo:

git clone https://github.com/microsoft/vcpkg
.\vcpkg\bootstrap-vcpkg.bat

cmake -B build -G Ninja `
    -DCMAKE_TOOLCHAIN_FILE=.\vcpkg\scripts\buildsystems\vcpkg.cmake `
    -DVCPKG_TARGET_TRIPLET=x64-windows `
    -DFRAMEWRIGHT_BUILD_TESTS=ON
cmake --build build

Windows support is a recent addition (#93) and covered by CI, but is newer than the Linux/macOS builds -- report anything that looks platform-specific. Binary wheels are available (pip install framewright also works on Windows) — they're built the same LGPL-only, statically-linked way as the Linux/macOS wheels, so the same H.264/HEVC-writing caveat above applies.

Logging

By default, framewright only logs errors. To see informational output:

framewright::setLogLevel(framewright::LogLevel::Info);     // See everything
framewright::setLogLevel(framewright::LogLevel::Error);    // Errors only (default)
framewright::setLogLevel(framewright::LogLevel::Quiet);    // Silence all output

API

framewright::VideoReader

framewright::VideoWriter

framewright::VideoWriterOptions

Supported codecs: H.264, H.265/HEVC (8-bit and 10-bit), FFV1 (lossless RGB).

License

MIT