Metadata-Version: 2.2
Name: QPMBDeblock
Version: 0.3.0
Summary: Fast native H.264 QP and macroblock map extractor using FFmpeg
Author: PingWer, Mhanz3500
License: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License
         
         By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
         
         Section 1 – Definitions.
         [... The standard CC BY-NC-SA 4.0 legal code applies. See https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode for the full text ...]
         
         You are free to:
         - Share — copy and redistribute the material in any medium or format
         - Adapt — remix, transform, and build upon the material
         
         Under the following terms:
         - Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
         - NonCommercial — You may not use the material for commercial purposes.
         - ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
         
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.12
Requires-Dist: numpy>=1.20.0
Description-Content-Type: text/markdown

# 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

```bash
pip install QPMBDeblock
```

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

## Python API

```python
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

```python
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.

```bash
# 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:
```bash
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.
