QPMBDeblock 0.2.0

Fast native H.264 QP and macroblock map extractor using FFmpeg

QPMBDeblock

Native H.264 QP and macroblock map extractor. Uses FFmpeg's AV_FRAME_DATA_VIDEO_ENC_PARAMS side-data to extract per-macroblock QP values from H.264 streams without log parsing.

Installation

pip install QPMBDeblock

Runtime requirement: FFmpeg must be installed and available in PATH.

Python API

from qpmbdeblock import h264QPparser

parser = h264QPparser("video.mkv")

# Extract + write in one step. Returns output path or None on failure.
result = parser.create_qp_map("output.qpmap.mkv")

# Or separately:
qpmap = parser.extract()           # numpy.ndarray (n_frames, mb_rows, mb_cols), dtype int8
parser.write_video(qpmap, "output.qpmap.mkv")

extract() returns a 3-D int8 NumPy array with QP values in [0, 63].

VapourSynth

from qpmbdeblock import VSqpmap_mask

# Generates output.qpmap.mkv on first call, loads it on subsequent calls.
qp = VSqpmap_mask(
    "video.mkv",
    reference_clip=src,   # required when scale_video=True (default)
    high_bitdepth=True,   # GRAY16, values 0–63
)

Parameter	Default	Description
qpmap_path	<video>.qpmap.mkv	Custom path for the QP map MKV
ffmpeg_path	"ffmpeg"	Path to ffmpeg executable
scale_video	True	Upscale 16× and crop to reference_clip dimensions
high_bitdepth	True	Output GRAY16 instead of GRAY8

Source plugin priority: bestsource → ffms2 → lsmas

Build from source

Requirements: CMake ≥ 3.15, C++17 compiler, FFmpeg dev headers, pybind11.

# Set FFmpeg location (Windows only, if not using pkg-config)
$env:FFMPEG_ROOT = "C:\path\to\ffmpeg-full_build-shared"

pip install .

On Linux/macOS with system FFmpeg:

apt install libavcodec-dev libavformat-dev libavutil-dev  # Debian/Ubuntu
pip install .

Output format

Lossless grayscale FFV1 MKV. Each pixel maps 1:1 to one macroblock. Pixel value = QP value (0–63). FPS matches the source video.