QPMBDeblock

Modern, high-performance in-memory H.264 QP map extractor and raw stream decoder for VapourSynth and Python, backed by native C++ FFmpeg (libavcodec/libavformat).

Features

• 100% In-Memory Architecture: No temporary disk MKV files, no slow IPC pipes, zero disk wear.
• Fast C++ LRU Cache: 64-frame in-memory circular cache with sub-millisecond seeking and sub-400MB memory footprint.
• Synchronized Three-Stream Pipeline: Single entrypoint open_h264_source() yielding:
  1. clip_src: Reference clip loaded via vapoursynth-bestsource.
  2. qpmap: Macroblock QP map (GRAY8 / GRAY16, or full YUV with ITU-T Table 8-15 chroma derivation).
  3. clip_nodeblock: Video decoded with in-loop deblocking filter disabled (skip_loop_filter = AVDISCARD_ALL).
• Full Bit-Depth & Chroma Subsampling Support: Seamlessly decodes 8-bit and 10-bit H.264 streams across 4:2:0, 4:2:2, and 4:4:4 profiles (High, High 10, High 4:2:2, High 4:4:4 Predictive).
• Automated PPS Chroma Offset Detection: Automatically parses and extracts chroma_qp_index_offset / second_chroma_qp_index_offset from the stream's Picture Parameter Set (PPS).
• Corrupted Block Tracking: Automatically detects and clamps corrupted blocks (QP == -1) to 0, reporting exact macroblock coordinates via console logs and frame properties (QPCorrupted, QPCorruptedCoords).

Installation

pip install QPMBDeblock

Pre-built binary wheels are distributed for Windows (x86_64) and Linux (x86_64, aarch64) with dynamic FFmpeg shared libraries bundled in compliance with LGPL v2.1.

VapourSynth Quickstart

import vapoursynth as vs
from qpmbdeblock import open_h264_source

core = vs.core

# Open all three 1:1 frame-synchronized VideoNodes in-memory
clip_src, qpmap, clip_nodeblock = open_h264_source(
    "video.mkv",
    scale_video=True,       # Upscale QP map to match clip_src dimensions (Point resize)
    high_bitdepth=True,     # Output QP map in GRAY16 (values 0-63 scaled)
    chroma_qpmap=False,     # True = derive full YUV chroma planes; False = single GRAY plane
    chroma_qp_offset=None,  # None = auto-detect PPS offsets from video; or provide manual int/(cb, cr)
)

# Set outputs for previewing (e.g. vsview)
clip_src.set_output(0)
qpmap.set_output(1)
clip_nodeblock.set_output(2)

Frame Properties

qpmap automatically injects diagnostic and stream metadata into VapourSynth frame properties:

Deblocking Filter Usage

import vapoursynth as vs
from qpmbdeblock import open_h264_source, av2deblock

core = vs.core

clip_src, qpmap, clip_nodeblock = open_h264_source("input.mkv", high_bitdepth=False)

# Apply AV2 deblocking guided by QP map
deblocked_8x8, deblocked_4x4, debug_clip = av2deblock(
    clip=clip_nodeblock,
    qpmap=qpmap,
    mbmap=..., # macroblock mode map
    qpmap_offset=0,
)

Building from Source

Requirements:

• Python ≥ 3.12
• CMake ≥ 3.15
• C++17 compatible compiler (MSVC 2019+, GCC 9+, Clang 10+)
• FFmpeg shared development libraries (libavcodec, libavformat, libavutil)

# Windows (specify FFmpeg directory if not in PATH):
$env:FFMPEG_ROOT = "C:\path\to\ffmpeg-full_build-shared"
pip install .

# Linux (Debian / Ubuntu):
sudo apt-get install -y libavcodec-dev libavformat-dev libavutil-dev
pip install .

License

This project is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0). FFmpeg dependencies are dynamically linked under the terms of the GNU LGPL v2.1.