render: add --height and --crf; resolution-independent per-segment zoom

[shoaib90]

The problem

render.py encodes the video twice — once per segment in extract_segment, then again in build_final_composite to composite overlays and burn in subtitles. The concat and the loudness pass are both -c copy, so those are lossless.

Both CRFs were hardcoded (extract 20/22/28, composite a literal 18), and the scale was an unconditional scale=1920:-2. So there was no way to deliver a 4K source at anything above 1080p, and no way to raise the extract CRF — which, being the first generation, is the quality ceiling the composite can only add loss on top of.

I hit this on a 4K talking-head edit that came out visibly soft. The diagnostic that isolated it was bits per pixel, not bitrate:

	resolution	bitrate	bits/px
source	3840×2160	50.4 Mbps	0.253
render (before)	1920×1080	12.7 Mbps	0.255

Per-pixel quality was already matched — the loss was discarded pixels plus a second generation, not bitrate starvation. No flag could fix that.

Changes

--height — output height, default 1080 (720 with --draft). Width follows the source aspect. --height 2160 delivers at the source resolution and skips the downscale generation entirely. Re-rendering the same EDL that way gave 0.451 bits/px.

--crf — CRF for the extract, i.e. the ceiling. Defaults 16 final / 22 preview / 28 draft. The composite encode is now derived as crf - 2 rather than a hardcoded 18, so the second generation adds minimal further loss. Final also moves from fast/20 to slow/16.

ranges[].zoom (plus zoom_x, a 0–1 horizontal crop bias) — an optional per-segment push-in, for disguising jump cuts on a static single-camera shot.

It is deliberately a number, not a filter string. A hardcoded crop=1812:1018,scale=1920:1080 is only correct at one output height, and any per-segment dimension mismatch breaks the -c copy concat (Hard Rule 2). Relative ffmpeg expressions do not rescue it either: rounding to even dimensions stops crop round-tripping to the exact original size — 1920 comes back as 1918, while segments with no filter stay 1920, and the concat fails. Instead probe_scaled_dims() mirrors the scale expression, so the crop is computed from the real post-scale dimensions. Verified with 13 mixed 1.00×/1.06×/1.12× segments all landing at exactly 3840×2160.

audio_filter — an optional global audio chain applied per segment before the 30ms fades, so the fades stay on the true segment edges (Hard Rule 3). Intended for denoise/EQ on noisy location audio; I needed it for car-interior road noise.

display_dims() factors out the rotation-aware probe that is_portrait_source() was already doing inline.

Compatibility

All flags and EDL fields are optional. The only behaviour change without them is the final-mode default moving to slow/CRF 16 — better output, slower encode. Happy to leave the old fast/20 default and make the improvement strictly opt-in if you'd rather.

tests/ passes (16 tests, 15 subtests), including the existing fps and orientation suites.

Note

Touches build_final_composite's signature and main(), so it overlaps slightly with #(the subtitle PR) if both land — whichever merges second needs a trivial rebase.

---

Summary by cubic

Adds --height and --crf to render.py plus per-segment zoom and global audio_filter EDL fields. Previously every render was downscaled to 1080p with hardcoded CRFs; now 4K sources can be delivered at native resolution and the extract CRF, the quality ceiling, is configurable.

New Features

• --height sets output height; default stays 1080 (720 with --draft) and width follows source aspect. It must be a positive even number since yuv420p requires it.
• --crf sets the extract CRF (defaults 16 final, 22 preview, 28 draft; fractional values like 16.5 are valid); the composite CRF is derived as crf - 2 instead of hardcoded 18.
• ranges[].zoom and zoom_x add an optional per-segment push-in expressed as a number, not a filter string, so one EDL stays correct at any output height. The crop is computed from the source's measured post-scale dimensions, so zoomed and unzoomed segments always match and the lossless concat is preserved.
• audio_filter applies a global audio chain per segment before the 30ms fades, keeping fades on true segment edges.

Compatibility

• All new flags and EDL fields are optional; without them, the only behavior change is final mode defaulting to slow/CRF 16 instead of fast/20, which means better output but slower encodes.

^{Written for commit 764f007. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 2 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>