QPMBDeblock 0.4.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
)

Source plugin priority: bestsource → ffms2 → lsmas

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

Extracting Unfiltered Raw H.264 Video

You can also use this library to get a VapourSynth VideoNode of an H.264 stream with the in-loop deblocking filter disabled, essentially showing the raw block artifacts before any post-processing is applied by the codec itself. This relies on PyAV.

from qpmbdeblock.h264_indexer import h264_no_inloop_filter

# Returns a pure VS clip without the deblock filter.
# Since libavcodec is used frame extraction can be random-access frame accurate.
# During the first run, a '.idx' file will be built to ensure accurate seeking.
clip_nodeblock = h264_no_inloop_filter("video.mkv")

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 .