Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 42 additions & 13 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -418,10 +418,20 @@ Adding a filter touches many files. Missing any step causes silent failures (fil
doesn't list). If the table shows it refusing a depth or subsampling a pass
can be handed, add a `Contract` to `worker/templates/plugin_formats.py` and
call it through `_pf.run_within(clip, '<ns.Fn>', fn, label='<Pass>')`
(test_252 fails on a contracted plugin called any other way); a refusal no
contract expresses (a field flag, a frame size) is handled in the pass and
(test_252 fails on a contracted plugin called any other way). A frame
size the plugin refuses is a Contract's `width_step` / `height_step`
(luma samples, or `CHROMA`): `run_within` pads to it with `pad_around`
and crops back (tasks #56, #57). A refusal no contract expresses (a field
flag) is handled in the pass and
explained in `plugin_formats.HANDLED`, or filed as a task and listed in
`plugin_formats.KNOWN` until it is. Check on a fixture with real low
`plugin_formats.KNOWN` until it is. **Anything that reaches MVTools'
Compensate, Degrain or BlockFPS with an overlap** (directly or through
havsfunc / a vendored module) goes through `_pf.mvtools_blocks(clip, fn)`
(test_256): MVTools picks the overlap window with
`(by + nBlkY - 3) / (nBlkY - 2)`, so a picture two block rows tall is
SIGFPE on x86 and silently 100+ levels off on arm64, and one block row or
column is that far off everywhere; the helper pads a picture under 64x96
(task #56 F9). Check on a fixture with real low
bits that the plugin leaves the samples it doesn't change exact — see
"High Bit Depth Sources"
- If any parameter is a **level, threshold or offset expressed in 8-bit units**
Expand Down Expand Up @@ -1509,12 +1519,19 @@ A >8-bit source is read natively off the pipe. Two ways this breaks after that:
saturation/hue are ratios and must **not** be scaled). Both scalings are
computed **in the script from `clip.format`**, since a preceding pass may
have changed the depth.
3. **A limit counted per histogram bin scales with the CONTENT's depth, not
the container's.** `vszip.CLAHE` (8/16-bit only before vszip 23; the template still runs deeper clips at
16-bit) needs `limit << (16 - content_depth)`: 8-bit content in a 16-bit
histogram fills every 256th bin, genuine 10-bit every 64th, and ProRes 4444
decodes as 12-bit whatever it holds. The template measures the content depth
per frame; container-depth scaling was 9.85 levels off in the parity test.
3. **A limit counted per histogram bin can't be scaled to a deeper
histogram.** `vszip.CLAHE`'s clip limit is a whole count per bin
(`limit x tile pixels / bins`, at least 1). The per-bin limit that matches
an 8-bit picture's is a fraction at 16-bit, so genuinely deep content was
barely clipped. So Local Contrast **decides on an 8-bit copy at every
depth and adds only its change at the clip's depth**
(`plugin_formats.change_at`, task #56 F7): genuine 10–16-bit content lands
~1 level from the 8-bit result at 720x480 (it was 3–22 with the old
`limit << (16 - content_depth)` scaling, which assumed each 8-bit level's
samples fill its sub-bins evenly), and 8-bit content in a deeper
container is exactly the 8-bit result. The cost: samples of one 8-bit
level get the same change, so a smooth deep ramp steps about as the
8-bit result does (docs/reports/task-56-format-sweep-findings).

**Test this class of bug with a reference, not an expected value** — a
correctly-scaled filter produces the same picture at 10-bit as at 8-bit, to
Expand Down Expand Up @@ -1555,7 +1572,7 @@ does, and decides bit depth as well as chroma:

| Option | Output | For |
|---|---|---|
| `original` (default) | source format, depth included (a 9-bit source comes out 10-bit, a 14-bit one 16-bit, see "Source Pixel Formats") | archival; a 10-bit source stays 10-bit |
| `original` (default) | source format, depth included (a 9-bit source comes out 10-bit, a 14-bit one 16-bit, see "Source Pixel Formats"); a pass that changed the depth (Deband's Working Depth) is dithered back to the source's after the passes (`{{#DEPTH_RESTORE}}`, task #56) | archival; a 10-bit source stays 10-bit |
| `yuv420` | `vs.YUV420P8` | compatibility — the only one every player opens |
| `yuv420p10` | `vs.YUV420P10` | the only 10-bit layout NVENC/QSV/AMF encode (issue #74) |
| `yuv422` | `vs.YUV422P8` | more chroma detail, 8-bit |
Expand Down Expand Up @@ -2788,8 +2805,9 @@ evidence for every rule here is docs/reports/2026-11-v210-field-order.
unflagged (these codecs, or a container-only codec in AVI). Said, never
refused.
- **A pass that makes a still-interlaced clip progressive must be taught to
`output_field_order`** (today: Stabilize pitch, Deblock mpeg2stinx, the
Frame Rate pass). `test_221` counts every `SetFieldBased(` in the template
`output_field_order`** (today: Stabilize pitch, Deblock mpeg2stinx, a
quarter turn in Rotate / Flip, the Frame Rate pass; a vertical flip or half
turn swaps the order). `test_221` counts every `SetFieldBased(` in the template
and fails on one it doesn't know.
- **The stored format comes from the script, never from ffmpeg's
`-pix_fmt`**, which blends interlaced 4:2:0 chroma across the fields; zimg
Expand Down Expand Up @@ -2912,6 +2930,14 @@ derivation both the encode and preview paths must use.
interlaced"; Deblock uses it to run every method per field
(`{{#DEBLOCK_PER_FIELD}}`) — DCTFilter on the woven frame scored 1.5–3.7 dB
*below no filtering* (docs/reports/2026-11-deblock-order).
- **After Rotate / Flip, the field order is `ScriptGenerator::field_order_at_framing`**
(task #56 F3): a quarter turn makes the picture progressive (its "fields"
would be columns) and a vertical flip or half turn swaps TFF and BFF; the
geometry block stamps it (`{{#GEOM_SET_FIELD_BASED}}`) before its format
restore. Everything after it reads that, not `still_interlaced_tff`: the
border alignment, the crop step and the resize height step
(`framing_steps`: a still-interlaced 4:2:0 picture is resized to a height
that is a multiple of 4, F5), and `output_field_order`.

### Deinterlace Working Format (issue #49)

Expand Down Expand Up @@ -3320,7 +3346,10 @@ bundle at 1.16.0 or older, the known skew.
Bisect a crash by generating the script (`--config`, keep the `.vpy`) and
running it under vspipe with passes commented out; on Windows `0xC0000005`
= access violation, `0xC000001D` = illegal instruction (CPU feature the
machine lacks) — both decoded by `format_exit_status`, as are SIGILL/SIGSEGV.
machine lacks), `0xC0000094` = integer divide by zero (SIGFPE elsewhere:
exit 136) — decoded by `format_exit_status`, as are SIGILL/SIGSEGV/SIGFPE.
The preview reports a failure the same way (task #56 F9b: it used to quote
vspipe's first stderr line, a plugin warning, instead of the crash).
`Header too large` in a job error now means vspipe exited cleanly (or by
SIGPIPE) with nothing to send.
**If it happens with every pass disabled, it is load-time, not a filter**:
Expand Down
82 changes: 68 additions & 14 deletions Scripts/probe-plugin-formats.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,12 @@
(Tests/TestResources/plugin_format_table.json is the committed one);
--check compares every cell measured with that table and exits 1 on any
difference. --quick measures the reachable set for the calls with a
contract or a known limit (plugin_formats.CONTRACTS / HANDLED), and one
format per depth for every other call: the push gate's subset.
contract or a known limit (plugin_formats.CONTRACTS / HANDLED), plus 4:2:0 at
720x486 for a contract with a frame-size step, and one format per depth for
every other call: the push gate's subset. A contracted call's cells are also
run through plugin_formats.run_within() (the `within` result, task #57): the
plugin may refuse a size its contract pads. --quick does that only for a
contract with a frame-size step.
"""
import argparse
import concurrent.futures
Expand Down Expand Up @@ -163,6 +167,10 @@ def call(key, covers, run):

# Deinterlace, IVTC
call('havsfunc.QTGMC', ['havsfunc.QTGMC'], lambda c: haf.QTGMC(c, Preset='Fast', TFF=True))
# Super Fast halves the frame for its motion search (SrchClipPP 1), which
# Fast doesn't: the only presets that refuse a 4:2:x width 2 mod 4 (task
# #56 F2). The template picks this contract for SrchClipPP 1.
call('havsfunc.QTGMC[SrchClipPP=1]', ['havsfunc.QTGMC'], lambda c: haf.QTGMC(c, Preset='Super Fast', TFF=True))
call('bwdif.Bwdif', ['bwdif.Bwdif'], lambda c: core.bwdif.Bwdif(c, field=3, edeint=nnedi3(c, field=3)))
call('nnedi3.nnedi3', ['nnedi3.nnedi3', 'znedi3.nnedi3'], lambda c: nnedi3(c, field=1))
call('vivtc.VFM', ['vivtc.VFM'], lambda c: core.vivtc.VFM(c, order=1, mode=1, cthresh=9, mi=80, blockx=16, blocky=16))
Expand Down Expand Up @@ -300,17 +308,21 @@ def size_grid():
for b in (8, 16) for f in (0, 2)]


def quick_grid(limited):
def quick_grid(limited, padded=False):
if limited:
return base_grid()
grid = base_grid()
if padded:
# A contract with a frame-size step: the size it pads (task #57).
grid += [cell('420', 8, f, 720, 486) for f in (0, 2)]
return grid
return [cell('420', b, 0, *BASE) for b in DEPTHS]


# ---------------------------------------------------------------------------
# Child: run one call's cells, one JSON line per cell as it finishes
# ---------------------------------------------------------------------------

def child(key, cells, fixtures):
def child(key, cells, fixtures, within=True):
import ctypes
import vapoursynth as vs
core = vs.core
Expand Down Expand Up @@ -344,6 +356,9 @@ def fill(n, f):
return c

fmts = {'420': (1, 1), '422': (1, 0), '444': (0, 0), '411': (2, 0)}
sys.path.insert(0, TEMPLATES)
import plugin_formats
contracted = within and key in plugin_formats.CONTRACTS
for cl in cells:
try:
sw, sh = fmts[cl['ss']]
Expand All @@ -356,12 +371,30 @@ def fill(n, f):
out.get_frame(min(FRAMES // 2, out.num_frames - 1))
res = {'ok': True}
except Exception as e: # noqa: BLE001 -- the error is the measurement
msg = (str(e).strip().splitlines() or [type(e).__name__])[0]
res = {'ok': False, 'error': msg[:300]}
res = {'ok': False, 'error': _first_line(e)}
if contracted and cl['reachable']:
# The call as the template makes it: through run_within(), which
# converts and pads to the contract (task #57). delta_only=False:
# only whether it runs is measured, and some calls retime.
try:
c = core.resize.Bicubic(source(cl['w'], cl['h']), format=fmt.id, dither_type='none')
c = core.std.SetFieldBased(core.std.SetFrameProps(
c, _Matrix=6, _Primaries=6, _Transfer=6, _Range=0, _ChromaLocation=0), cl['field'])
out = plugin_formats.run_within(c, key, run, delta_only=False)
out.get_frame(min(FRAMES // 2, out.num_frames - 1))
if (out.width, out.height) != (cl['w'], cl['h']):
raise RuntimeError('run_within returned %dx%d' % (out.width, out.height))
res['within'] = 'ok'
except Exception as e: # noqa: BLE001
res['within'] = _first_line(e)
sys.stdout.write(json.dumps({'key': cell_key(cl), **res}) + '\n')
sys.stdout.flush()


def _first_line(e):
return ((str(e).strip().splitlines() or [type(e).__name__])[0])[:300]


# ---------------------------------------------------------------------------
# Parent
# ---------------------------------------------------------------------------
Expand All @@ -375,15 +408,15 @@ def exit_status(code):
return 'exit code %d' % code


def run_cells(key, cells, fixtures):
def run_cells(key, cells, fixtures, within=True):
"""{cell key: {'ok', 'error'?}} for every cell, through as many child
processes as crashes need."""
processes as crashes need. within=False skips the run_within() pass."""
results = {}
todo = list(cells)
while todo:
p = subprocess.run(
[sys.executable, os.path.abspath(__file__), '--child', key],
input=json.dumps({'cells': todo, 'fixtures': fixtures}),
input=json.dumps({'cells': todo, 'fixtures': fixtures, 'within': within}),
capture_output=True, text=True, timeout=3600)
for line in p.stdout.splitlines():
if line.startswith('{'):
Expand All @@ -398,7 +431,7 @@ def run_cells(key, cells, fixtures):
first = todo.pop(0)
q = subprocess.run(
[sys.executable, os.path.abspath(__file__), '--child', key],
input=json.dumps({'cells': [first], 'fixtures': fixtures}),
input=json.dumps({'cells': [first], 'fixtures': fixtures, 'within': within}),
capture_output=True, text=True, timeout=3600)
got = [json.loads(l) for l in q.stdout.splitlines() if l.startswith('{')]
if got:
Expand Down Expand Up @@ -442,6 +475,9 @@ def summarise(cells, results):
refused = [cell_key(c) for c in sized if not ok(c)]
if sized:
s['sizes_refused'] = refused
within = [cell_key(c) for c in cells if c['reachable'] and results[cell_key(c)].get('within', 'ok') != 'ok']
if any('within' in results[cell_key(c)] for c in cells):
s['within_refused'] = within
crashes = sorted(cell_key(c) for c in cells if results[cell_key(c)].get('error', '').startswith('crash'))
if crashes:
s['crashes'] = crashes
Expand All @@ -454,6 +490,12 @@ def limited_calls():
return set(plugin_formats.CONTRACTS) | set(plugin_formats.HANDLED)


def padded_calls():
sys.path.insert(0, TEMPLATES)
import plugin_formats
return {k for k, c in plugin_formats.CONTRACTS.items() if (c.width_step, c.height_step) != (1, 1)}


def main():
ap = argparse.ArgumentParser()
ap.add_argument('--child')
Expand All @@ -470,7 +512,7 @@ def main():

if a.child:
req = json.loads(sys.stdin.read())
child(a.child, req['cells'], req['fixtures'])
child(a.child, req['cells'], req['fixtures'], req.get('within', True))
return 0

calls = _calls()
Expand All @@ -481,10 +523,11 @@ def main():

keys = a.calls.split(',') if a.calls else list(calls)
limited = limited_calls() if a.quick else set()
padded = padded_calls() if a.quick else set()
grids = {}
for k in keys:
if a.quick:
grids[k] = quick_grid(k in limited)
grids[k] = quick_grid(k in limited, k in padded)
else:
grids[k] = base_grid() + doc_grid() + size_grid()
sizes = sorted({(c['w'], c['h']) for g in grids.values() for c in g})
Expand All @@ -493,7 +536,14 @@ def main():
with tempfile.TemporaryDirectory() as tmp:
fixtures = make_fixtures(tmp, sizes, a.ffmpeg)
with concurrent.futures.ThreadPoolExecutor(a.jobs) as ex:
futs = {k: ex.submit(run_cells, k, grids[k], fixtures) for k in keys}
# --quick runs the run_within() pass only for a contract with a
# frame-size step, the one thing it adds over the plugin's own
# cells: a depth-only contract's conversion is checked on real
# frames by plugin_format_contracts_test, and running every
# LUTDeCrawl/LUTDeRainbow cell again at 10-bit doubled their cost
# (task #56: macOS x64 passed the push gate's 30 minutes).
futs = {k: ex.submit(run_cells, k, grids[k], fixtures, not a.quick or k in padded)
for k in keys}
for k in keys:
res = futs[k].result()
cells = grids[k]
Expand All @@ -520,6 +570,10 @@ def main():
exp = override.get(ck, want['cells'].get(ck))
if exp is None:
diffs.append('%s %s: not in the committed table' % (k, ck))
elif 'within' in got and exp.get('within') != got['within'] and \
(exp.get('within') == 'ok') != (got['within'] == 'ok'):
diffs.append('%s %s: table says run_within %s, the bundle says %s' % (
k, ck, exp.get('within'), got['within']))
elif exp['ok'] != got['ok']:
diffs.append('%s %s: table says %s, the bundle says %s' % (
k, ck, 'ok' if exp['ok'] else 'refused (%s)' % exp.get('error'),
Expand Down
Loading
Loading