Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
feat(cut): edit-list copies, --keep-hevc, --vfr-guard and a checked join (takeover of #306) (#313)
Shogo Kajiyama3b04a9cb1c1c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex bb13f31..44f6bc6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,18 @@## Unreleased-(nothing yet)+- feat(cut): `--vfr-guard average|sampled|off` chooses what keeps a variable-frame-rate source from a stream copy. `average` (the default) is the guard every 2.x release had, unchanged: a source whose nominal and average frame rates differ (`variable_frame_rate_suspected`) re-encodes as `--accurate` (now reason `vfr`); its packet timestamps are then sampled in up to five 6 s windows (no decoding) and reported in `vfr_check` (`measured`: `sampled_cfr` / `vfr` / `inconclusive`, `guard`, `windows`, `deltas`), with a note naming `--vfr-guard sampled` when the sample is constant, as on an iPhone clip at 29.98 against a nominal 30. `sampled` decides on the sample instead: `sampled_cfr` copies, `vfr` re-encodes with reason `vfr` and `inconclusive` (too few frames, or ffprobe failed) with `vfr_inconclusive`; `off` samples and keeps the copy, with a note. Variable timing between the sampled windows is not seen. The sample runs under `--dry-run` and is skipped when nothing would copy (audio-only, `--accurate`, `--codec`). `probe.py`'s `variable_frame_rate_suspected` keeps its meaning.+- fix(cut): a `--segments` segment that runs past the end of the video no longer opens a hole at its join. A segment (not the last) that runs past the end of the video left a gap before the next one: 0.355 s for 0.3 s of sound with no picture, reported as `mode: copy`. It now ends with the video when it runs less than a frame past it, and otherwise holds the last frame for its sound, which re-cuts the join from the source (`concat_fallback`, with a note). Also, `--accurate` joins went through per-part encodes and a copy join, leaving a 23 ms hole (one AAC frame) at every join; they now re-cut every segment in one encode, as the fallback does, reported only as `requested`. The video's end is measured from the file's own start, so offset timestamps do not move it.+- fix(cut): a `--segments` stream-copy join is exact, or it is not a copy. On B-frame video each part carried the next GOP's keyframe and first P-frame (an input `-t` stops in decode order) and its `make_zero` start shifted it by the reorder delay: 186 frames for 180, holes in the picture and the sound drifting 67 then 133 ms, reported as `mode: copy` (287 frames for 224 on iPhone HEVC). `.mp4`/`.mov` parts of B-frame video now keep their edit list and end at their end keyframe's decode time; an end is snapped to the first keyframe at or after it, never an earlier one, within `--tolerance` (each end judged on its own; past it, the join is re-cut from the source), a part that reaches the end of the video keeps its length, and a later segment that starts between keyframes is re-cut (the concat demuxer crushes its hidden pre-roll into the join). A source with no B-frames (iPhone "Most Compatible" H.264) cuts its parts as 2.5.1 did, which was already frame-exact (`0-1.8,4-6` is 114 frames, as before). A source with open GOPs (x265's default; iPhone "High Efficiency" HEVC at every keyframe) cannot be cut exactly by stream copy, so its joins are re-cut from the source (`concat_fallback`, with a note), keeping HEVC, 10 bits and HDR tags. Every copy join is then measured by demuxing: `join_check` (`packets`, `expected_packets` counted in the source, `max_step_seconds`, `audio_offset_ms`, `audio_parts_checked`, `ok`); each step at a join must be the one its parts predict (within 1 ms), and each part's sound is matched to the source's audio packets and must sit within 5 ms of its picture (a B-frame H.264 + PCM `.mov` join copied every frame exactly with its sound 16 and 53 ms late); a failed check re-cuts the join. Only windows around the segments are read from the source (±10 s, widened up to three times, then the whole file), so a long source costs what its segments do: 0.5 s for three 1-minute segments of a 25-minute source. Matroska/MPEG-TS parts keep the old cut and rely on that check. New key `segment_end_snap_seconds`. A join whose parts would re-encode is re-cut in one encode instead of copy-joining separately encoded parts. `duration_error_ms` on an exact AAC copy join reads about +21 ms: one AAC frame of priming. A checked join is written to a hidden file beside the output and renamed into place only once it passes, so a failed check never costs an `--overwrite` target; placing a finished file (this, and `render.py`'s last step) now holds the output's lock like any ffmpeg write.+- feat(cut): `--keep-hevc` (opt-in) re-encodes an SDR HEVC source as HEVC (x265 8-bit, BT.709-tagged, on VideoToolbox under `--hw`) instead of H.264; it covers `--accurate`, the tolerance fallback and the `--segments` re-cut join. Without it every SDR re-encode stays x264, as before; HDR and BT.2020 sources keep their HEVC Main10 line either way, and `--codec` still overrides. The contract's `cut` x265 capability adds "with `--keep-hevc` on an HEVC source".+- feat(cut): `--edit-list` keeps the MP4 edit list on a single-segment `.mp4`/`.mov` stream copy instead of `-avoid_negative_ts make_zero`, which shows the keyframe's pre-roll (on Core Media HEVC, 3.7 s of sound with no picture from a run that exited 0): the pre-roll is stored but hidden, so the picture starts at `--start`. The default is unchanged (`make_zero`). New keys on every cut: `edit_list` (`false` without the flag), `stored_preroll_seconds` (the hidden pre-roll, from the keyframe the demuxer really seeks to; `null` without the flag), `av_start_skew_seconds` (audio start minus video start; past max(2 frames, 0.1 s) a note names `--accurate`, and `--edit-list` for an `.mp4`/`.mov` copy cut without it: the skew is reported, not repaired) and `notes`. Under `--edit-list` a copy is judged by its video's length, not the container's, and one that starts where asked but ends past `--tolerance` re-encodes without offering another `--start`. `keyframe_snapped` keeps its meaning (a stream copy end to end); the new `start_snapped` is measured: `true` when a copied picture starts more than a frame from `--start` (an `--edit-list` copy whose edit list hides the pre-roll is not; reading a source's keyframes no longer seeks to its start, which skipped an edit-listed file's negative-pts keyframe and reported its start as snapped), `null` under `--dry-run`. The compact probe gains per-stream `start_time` (`video.start_time`, `audio.start_time`).+- fix(cut): `-ss`/`-t` are passed to the microsecond (they were rounded to the millisecond): `--start 00:00:02:01@30` on a keyframe at 2.0333 s seeked to 2.033, before it, and snapped back to the keyframe at 0 (a `tolerance` re-encode); it now copies from that keyframe.+- fix(cut): `--accurate` on video seeks a second early and drops the margin on the output side. Seeking straight to `--start` landed, by decode time, on a keyframe after it when the start was a few frames before a keyframe on B-frame video, losing those frames.+- fix(cut): a `--segments` join of mismatched parts no longer goes through the concat demuxer, which takes the first part's parameters for all of them: a copied HEVC segment next to a re-encoded H.264 one decoded with errors from a run that exited 0. Parts are joined by stream copy only when their codec parameters, rotation, colour tags and extradata match; otherwise every segment is re-cut from the source through the concat filter (at most 32 per ffmpeg call), keeping an audio track's offset from the video, on the source's frame grid and at its stated frame rate (FFmpeg 7.0 otherwise wrote 25 fps). Each segment is seeked a second early and trimmed to its start, because the MP4 demuxer seeks by decode time and a start inside the B-frame reorder delay before a keyframe would land on that keyframe. A join into `.mp4`/`.mov` keeps HEVC's `hvc1` tag (an HDR source's re-cut is HEVC by default), including when more than 32 segments are encoded as Matroska chunks and copied together. Subtitle and data streams are dropped from that re-cut and reported (`dropped_non_av_streams`).+- fix(cut): a video cut or `--segments` segment shorter than one frame is refused (`kind: input`) before ffmpeg runs; 2.5.1 wrote a whole frame for it and reported success (`--start 1 --end 1.01` on 30 fps video wrote one frame, 44 ms longer than asked). A cut to an audio output is not affected.+- feat(cut): `reencode_reason` says why anything was re-encoded: a list of `requested`, `codec`, `vfr`, `vfr_inconclusive`, `pcm_container`, `copy_failed`, `tolerance`, `concat_fallback` in first-seen order, `[]` for a clean copy. `--segments` cuts add `segment_precision`, and every cut adds `least_exact_precision`, the least exact segment's; `precision` keeps its formula. `requested_segments`/`requested_duration` still report the request clamped to the media's duration; a segment ended with the video shows its trim in `duration_delta_seconds` and a note. `batch.py` rows gain `cut_reencode_reasons`, its top level counts them in `cut_reencode_reasons` (`cut_stream_copy` is unchanged), and its log no longer calls every re-encode a "hybrid tolerance fallback".+- fix(cut): a `--segments` cut whose parts copied losslessly but whose join had to re-encode reported `mode: "copy"`, `reencoded: false` and `precision: "packet"`; it now reports `hybrid`, `reencoded: true`, the re-encode's precision and `concat_fallback`.+- The `cut.py` work above, from `reencode_reason` and the `concat_fallback` report to the edit-list, HEVC and frame-timing paths and the exact `--segments` copy joins with their `join_check`, was built by [@rymalia](https://github.com/rymalia) in #306, measured frame by frame on fixtures and iPhone footage. The maintainers' takeover kept 2.x's defaults behind `--edit-list`, `--keep-hevc` and `--vfr-guard`, and added the no-B-frame path, the audio check and the bounded packet read.## 2.7.0diff --git a/README.md b/README.mdindex 6ae843b..cfe69c3 100644--- a/README.md+++ b/README.md@@ -202,7 +202,7 @@ These are the rules the skill file gives the agent and the code enforces.| Tool | What it does ||---|---|-| `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact video and sample-exact audio; reports `precision`; `--snap beats` moves the in/out points onto a measured beat, or refuses when there is no measurable pulse |+| `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact video and sample-exact audio, `--keep-hevc` to re-encode an HEVC source as HEVC, `--edit-list` to keep an `.mp4` copy's start exact, `--vfr-guard` to choose the VFR check; reports `precision`; `--snap beats` moves the in/out points onto a measured beat, or refuses when there is no measurable pulse || `join.py` | Concatenate clips with xfade transitions, normalising size, fps, sample rate and channel layout (the widest clip's, or `--channels`); audio-only inputs are joined as audio; `--list parts.txt` reads generated segments (TTS lines) and checks every one first — missing, empty or unreadable parts are all named in one refusal, or skipped and reported with `--on-missing skip` || `silence.py` | Detect and remove dead air (jump cuts) with a margin around speech; list or export the cut list; `--filler` also removes filler words, but only where a speech engine timed them; `--speech-aware` keeps a breath inside a sentence and cuts only at sentence-boundary pauses, composing with `--filler` through the same `keep_ranges()` || `fit.py` | Fit to a duration (pitch-preserving speed change or trim, smooth slow-mo) and/or aspect ratio (pad, crop or `--fit blur`'s blurred, darkened fill, with `--crop-x`/`--crop-y` to keep an off-centre subject) and/or exact `--width`/`--height`; rotate 90/180/270, flip h/v; force constant fps |@@ -362,8 +362,8 @@ npx ffmpeg-skill doctor --json # available / missing / missing_optional / unknThe short list for humans. The agent-facing version, with the reasoning, is the "Things that look right but are wrong" and "Gotchas" sections of [SKILL.md](SKILL.md).-- **Variable frame rate (phone and screen recordings).** `probe.py` flags it; every re-encoding tool conforms to a constant rate automatically, and `cut.py` switches to frame-accurate mode on its own because copy-cuts on VFR land on the wrong frame. Choose the rate yourself with `fit.py input.mp4 --fps 30` when the measured average is odd.-- **Lossless cuts snap to keyframes.** A stream-copy cut can start up to one GOP earlier than asked. `cut.py` re-encodes when the snap exceeds 0.5 s (`--tolerance` changes the limit). For a strictly lossless file pass `--tolerance -1`, and expect the cut to land on the nearest earlier keyframe; the JSON result lists them under `nearest_keyframes`.+- **Variable frame rate (phone and screen recordings).** `probe.py` flags it; every re-encoding tool conforms to a constant rate automatically. `cut.py` switches to frame-accurate mode on it, because copy-cuts on VFR land on the wrong frame, and samples the frame timing to say whether that was needed (`--vfr-guard sampled` decides on the sample instead; `--vfr-guard off` keeps the copy). Choose the rate yourself with `fit.py input.mp4 --fps 30` when the measured average is odd.+- **Lossless cuts snap to keyframes.** A stream-copy cut can start up to one GOP earlier than asked. `cut.py` re-encodes when the snap exceeds 0.5 s (`--tolerance` changes the limit). For a strictly lossless file pass `--tolerance -1` (plus `--vfr-guard off` on a variable-frame-rate source), and expect the cut to land on the nearest earlier keyframe; the JSON result lists them under `nearest_keyframes`. A `--segments` join can still be re-cut: open-GOP video, a later segment of B-frame `.mp4`/`.mov` video that starts between keyframes (start it on a keyframe, or write `.mkv`), or a join that fails its check. For a single `.mp4`/`.mov` cut, `--edit-list` keeps the copy and starts the picture where asked: the keyframe's pre-roll is stored but hidden by an MP4 edit list, which a player that ignores edit lists shows.- **HDR stays HDR.** When the probe reports HDR (HDR10, HLG, Dolby Vision, BT.2020), the tools keep it rather than flatten it. Convert deliberately with `color.py --to-sdr` before H.264 deliverables or LUT work. `export.py` platform presets are SDR and warn on HDR input.- **Loudness targets.** −14 LUFS / −1 dBTP for YouTube and social platforms (the `loudness.py` default), `-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast. A clip measured at −40 LUFS or below is room tone, not content; raising it raises the noise. Check true peak as well as LUFS: `check.py file --platform podcast` measures both.- **Frame changes first, text second.** Captions and overlays burned before a crop or resize end up off-frame. Reframe, then caption.diff --git a/SKILL.md b/SKILL.mdindex e858d2a..a884650 100644--- a/SKILL.md+++ b/SKILL.md@@ -7,7 +7,7 @@ description: 'Edit video and audio with local FFmpeg from natural-language requeScripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`, and delivery templates in `templates/`. This file is enough to do a job: the table below routes the request, and `--help` on the script about to run is the cheapest full flag list. A reference file costs as much as this one; open one only for a question you have: `references/scripts.md` (every flag of all 42 scripts), `references/devices.md` (iPhone HDR, GoPro, DJI, screen recordings, Zoom), `references/gotchas.md` (the long form of the one-line rules at the end). MCP: `tools/list` shows only the core 12 by default; the other 30 (per this table) stay callable by name via `tools/call`, described by `contract --json`; set `FFMPEG_SKILL_MCP_FULL=1` for all 42.-Shared flags (every script): `--dry-run`; `--json` (output path, its probe, the commands run); `--json-brief` (status/output/verified + a `summary`; prefer on writing steps); `--fast` (preview quality); `--progress` (percent/ETA); `--timeout SECONDS` (`kind: timeout`, default 1800); `--overwrite` (step 7); `--plan FILE` (a dry run `render.py FILE` runs later; refuses if an input changed). Re-encoding tools also take `--hw` (Apple Silicon GPU, big files; `FFMPEG_SKILL_HW=1` = default, not export), `--codec h264|hevc|av1|prores` and `--quality N`: unset, SDR is x264, HDR is x265 Main10; `prores` needs `-o NAME.mov`, `h264` refuses HDR (`color.py --to-sdr` first).+Shared flags (every script): `--dry-run`; `--json` (output path, its probe, the commands run); `--json-brief` (status/output/verified + a `summary`; prefer on writing steps); `--fast` (preview quality); `--progress` (percent/ETA); `--timeout SECONDS` (`kind: timeout`, default 1800); `--overwrite` (step 7); `--plan FILE` (a dry run `render.py FILE` runs later; refuses if an input changed). Re-encoding tools also take `--hw` (Apple Silicon GPU, big files; `FFMPEG_SKILL_HW=1` = default, not export), `--codec h264|hevc|av1|prores` and `--quality N`: unset, SDR is x264 (`cut.py --keep-hevc`: HEVC source stays HEVC), HDR is x265 Main10; `prores` needs `-o NAME.mov`, `h264` refuses HDR (`color.py --to-sdr` first).Writing tools run nothing under `--dry-run`; the measuring tools (`probe`, `check`, `sync`, `multicam`, `scenes`, `cropdetect`, `report`, `silence`, `loudness`, `stabilize`) may still run ffmpeg/ffprobe, skipping artifacts/side files (`--edl`, `--sheet`, a generated `.ass`); `verify` ignores the flag. Per tool: `contract --json` `dry_run`.@@ -52,7 +52,7 @@ This skill cuts, joins, measures, syncs, exports and checks files — it executeThe line: same input + same explicit parameters always producing the same verifiable output belongs here; anything depending on taste, understanding or what looks or sounds good belongs to whoever makes that judgement.-If a request needs an FFmpeg feature none of the 42 scripts expose, say so and name the closest built-in option — never guess a raw `ffmpeg`/`ffprobe` invocation outside `scripts/*.py`. It bypasses every guarantee this skill makes, so never a fallback when a script's flag doesn't cover something.+If a request needs an FFmpeg feature none of the 42 scripts expose, say so and name the closest built-in option — never guess a raw `ffmpeg`/`ffprobe` invocation outside `scripts/*.py`. It bypasses every guarantee this skill makes, so it is never a fallback.## Request → script@@ -65,7 +65,7 @@ Timestamp flags (`--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`,| "cut from 1:20 to 2:05", "trim the first 10 s" | `cut.py input.mp4 --start 1:20 --end 2:05` || "keep only these parts", "remove the middle" | `cut.py input.mp4 --segments 0-1:00,1:30-2:00` || "make it exactly 60 seconds" | `fit.py input.mp4 --duration 60` (speed) or `--method trim` |-| "cut this and make it HEVC / AV1 / ProRes" (output codec named) | `cut.py input.mp4 --start 0:10 --end 0:40 --codec hevc` (`--codec`/`--quality` on any re-encoding tool; ProRes needs `-o NAME.mov`) |+| "cut this and make it HEVC / AV1 / ProRes" (output codec named) | `cut.py input.mp4 --start 0:10 --end 0:40 --codec hevc` (ProRes needs `-o NAME.mov`) || "cut out the pauses", "jump cuts" | `silence.py input.mp4 [--threshold -40 --min-silence 0.8]` || "cut the ums and uhs", "remove the filler words" | `silence.py input.mp4 --filler --words words.json` (measured word timings; `--transcribe` makes them) || "don't cut inside a sentence, just the real pauses" | `silence.py input.mp4 --speech-aware` — a breath under `--min-silence` inside a sentence is kept, only sentence-boundary pauses cut; composes with `--filler` into one list |@@ -206,8 +206,8 @@ One line each; open the linked `references/gotchas.md` section when the job is i- HDR (iPhone, HDR10) re-encoded through an SDR path goes flat; the scripts keep HDR; `hdr: true` is a real PQ/HLG/DV signal, `bt2020_or_hdr: true` also BT.2020 SDR. -> [#hdr-and-colour](references/gotchas.md#hdr-and-colour)- Log footage (S-Log/V-Log/C-Log) is tagged SDR and looks grey: `probe.py --analyze`, then `color.py --lut` first. -> [#log-footage](references/gotchas.md#log-footage)-- A `-c copy` cut can start on a wrong or frozen frame; `cut.py` re-encodes past a 0.5 s snap, respect it. -> [#keyframe-cuts](references/gotchas.md#keyframe-cuts)-- VFR phone/screen recordings: re-encodes conform to CFR, `cut.py` switches to `--accurate`; pick the rate with `fit.py --fps` when odd. -> [#variable-frame-rate](references/gotchas.md#variable-frame-rate)+- A `-c copy` cut can start on a wrong/frozen frame; `cut.py` re-encodes past a 0.5 s snap, respect it; `--edit-list` hides an .mp4's pre-roll. -> [#keyframe-cuts](references/gotchas.md#keyframe-cuts)+- VFR phone/screen clips: re-encodes go CFR; `cut.py` re-encodes (`--vfr-guard sampled`: only measured VFR); odd rate: `fit.py --fps`. -> [#variable-frame-rate](references/gotchas.md#variable-frame-rate)- Sync/multicam `confidence` under 0.3 (or a huge offset) is suspect — check every camera; these align audio, never lip sync. -> [#sync-multicam-and-drift](references/gotchas.md#sync-multicam-and-drift)- "Normalised" audio can still clip (check true peak); ambience at -40 LUFS or below must never be raised to a speech target. -> [#loudness-and-ambience](references/gotchas.md#loudness-and-ambience)- Captions burned before a crop/resize land off-frame; burned small then upscaled by `export.py` come out soft. -> [#captions-fonts-and-text-order](references/gotchas.md#captions-fonts-and-text-order)diff --git a/demos/build.py b/demos/build.pyindex cb76158..3a6d083 100644--- a/demos/build.py+++ b/demos/build.py@@ -803,6 +803,26 @@ def demo_cut_accurate(ctx):return before, after+def demo_cut_edit_list(ctx):+ """Two lossless copies of the same request: the default one shifts its timestamps to zero and+ shows the keyframe's pre-roll, the --edit-list one keeps the MP4 edit list that hides it, so+ its picture starts where asked. Both are stream copies; neither re-encodes."""+ src = FIX / "mandel.mp4"+ before = ctx.path("before.mp4")+ after = ctx.path("after.mp4")+ # --tolerance 5 keeps both on the stream copy, which is what this demo compares+ plain = ctx.script("cut.py", src, "--start", "2.05", "--duration", "3", "--tolerance", "5",+ "--json", "-o", before, capture=True)+ listed = ctx.script("cut.py", src, "--start", "2.05", "--duration", "3", "--tolerance", "5",+ "--edit-list", "--json", "-o", after, capture=True)+ if plain and listed:+ a, b = json.loads(plain), json.loads(listed)+ ctx.note("default: mode=%s, start_snapped=%s; --edit-list: mode=%s, start_snapped=%s, "+ "stored_preroll_seconds=%s" % (a.get("mode"), a.get("start_snapped"), b.get("mode"),+ b.get("start_snapped"), b.get("stored_preroll_seconds")))+ return before, after++def demo_crop_rect(ctx):before = FIX / "mandel.mp4"after = ctx.path("after.mp4")@@ -1462,6 +1482,9 @@ _ROWS = [("cut_accurate", PICTURE, "Lossless cut vs. accurate cut","Both sides asked for the same 2.05 s start. The stream copy could only snap to the nearest keyframe, so its first frame is from earlier in the clip; --accurate re-encodes and starts on the frame that was asked for.",demo_cut_accurate, "video", None, ("LOSSLESS", "--ACCURATE")),+ ("cut_edit_list", PICTURE, "Lossless cut that starts where asked",+ "Both sides are stream copies of the same 2.05 s request. The default shifts the copy's timestamps to zero, so the keyframe's pre-roll plays first (start_snapped: true); --edit-list keeps the MP4 edit list that hides it, so the picture starts at 2.05 s (start_snapped: false, stored_preroll_seconds says how much is hidden). A player that ignores edit lists shows the pre-roll.",+ demo_cut_edit_list, "video", None, ("DEFAULT COPY", "--EDIT-LIST")),("beats_snap", PICTURE, "Cuts that land on the beat","Both cuts asked for 2.03 s. The right one moved 30 ms to the nearest measured onset, so its first frame lands on a click instead of just after one; the waveform is the evidence. The tempo, the beat list and the confidence are in the JSON -- nothing is snapped to a grid the audio does not support, and below --min-confidence the cut refuses rather than inventing one.",demo_beats_snap, "wave", None, ("--snap none", "--snap beats")),diff --git a/docs/contract.md b/docs/contract.mdindex ee9d9c8..9f8791b 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -216,7 +216,9 @@ BT.709 for SDR; av1 is SVT-AV1 with libaom as the fallback; prores is 422 HQ and`.mov`/`.mkv` output; h264 refuses an HDR source (`kind: input`). `--quality` is the CRF scale;its default is the tool's own (18, `proxy.py` 30). 1.x also accepted `--crf` as an alias; 2.0removed it (`export.py` keeps its own `--crf`). Without `--codec` the encoder is what it always was (x264 for SDR, x265-Main10 for HDR), so the flags add no behaviour to a caller that does not pass them. The+Main10 for HDR), so the flags add no behaviour to a caller that does not pass them.+`cut.py --keep-hevc` (opt-in) re-encodes an SDR HEVC source as x265 8-bit BT.709 instead of x264; an HDR or+BT.2020 source keeps the Main10 line with its own colour tags, with or without the flag. Theencoder each value needs is listed under the tool's optional capabilities (`--codec hevc` andso on). `export.py` refuses `--codec`: its presets decide the codec.@@ -573,6 +575,12 @@ Per-tool keys added after 2.2.2, all additive:| `encoder`, `hw`, `notes` | every re-encoding tool, `export.py`, `render.py`, `batch.py` (and its rows), `waveform.py` | `encoder`: the video encoder the last command ran (after any GPU→CPU fallback; under `--dry-run`, the planned one), `copy` for a stream copy; absent when no command encoded video. A tool that runs other tools reports its stages': `render.py` its stages and an executed plan's tool, `waveform.py` the title/caption stage that writes its file (its `commands` include that stage's). `hw` is present when VideoToolbox was asked for (`--hw`, `FFMPEG_SKILL_HW=1`, or a stage or `batch.py` item that reported it) and on `export.py` when `FFMPEG_SKILL_HW=1` is set but its delivery preset does not take it: `{requested, source: flag\|env, used, fallback, notes}`. `requested` says whether this run's encodes were asked onto VideoToolbox (`false` for that export), `used` whether the encoder that ran last is VideoToolbox (`null` under `--dry-run`, which ran nothing, and when the tool encoded nothing itself: `batch.py`, whose top-level `hw` gathers its items' `requested`/`source`/`fallback`/`notes` while each `results` row carries the item's own `encoder`, and `hw`/`notes` when VideoToolbox was asked for), `fallback` whether a job VideoToolbox refused was re-encoded on the CPU, and `notes` why. Only a VideoToolbox failure (the encoder could not open, or its compression session failed) is retried on the CPU; any other failure is reported as it happened, once. Every VideoToolbox encode adds a top-level `notes` line: its quality is not CRF-equivalent (`--quality` / a preset's CRF maps to `-q:v` approximately), and `verified` stays what it is for every tool, the measured properties of the output. A `kind: ffmpeg` failure under `--hw` / `FFMPEG_SKILL_HW` carries `encoder` and `hw` for the command that ran last (a stage's, when `render.py`/`waveform.py` re-raise it); when the command itself failed inside the run (not a tool's own check afterwards, such as `cut.py`'s), its message also names that encoder || `transcription` | `caption.py --transcribe` (every `--mode`); inside `filler` for `silence.py --filler --transcribe` | `{routing, detected_language?, engine, model, language}`: the engine and model that made the transcript; `language` is the language the engine was told -- the one named (`--language`, `--filler-lang`), else the one auto's detector named -- and `null` when the engine identified it itself; `detected_language` is present when auto's whisper.cpp detector named one; `routing` says why `--engine auto` chose the engine (`"requested"` for a named engine), ending `, no Parakeet engine transcribed it` when auto chose Parakeet and a Whisper engine made the transcript after every Parakeet engine failed || `notes` | `silence.py --filler --transcribe` (new for `silence.py`; `caption.py` already had it) | present when `--engine auto` ran the English-only Parakeet model on English *assumed* (no language given or detectable, and no Whisper engine installed or none that succeeded): the transcript is wrong if the speech is not English. `caption.py --transcribe` puts the same line in its `notes` |+| `reencode_reason`, `segment_precision`, `least_exact_precision`, `start_snapped` | `cut.py` (every run) | `reencode_reason`: why anything was re-encoded, distinct values in first-seen order, `[]` for a clean copy: `requested` (`--accurate`), `codec` (`--codec`), `vfr`, `vfr_inconclusive`, `pcm_container`, `copy_failed`, `tolerance`, `concat_fallback` (a `--segments` join that could not stay a stream copy, which now also sets `reencoded: true` and `mode: hybrid`; it reported `copy` before). `segment_precision`: each `--segments` segment's precision (`null` for one segment); `least_exact_precision`: the least exact of them, on every run. `precision` and `keyframe_snapped` keep their meaning (`keyframe_snapped` is `precision == "packet"`, a stream copy end to end); `least_exact_precision` differs from `precision` only for an audio-only join of copied and re-encoded parts. `start_snapped`: measured, `true` when a copied segment's picture starts more than one frame from its requested start (or its start could not be measured: an unknown start is never claimed exact), `false` when every start is where asked or everything re-encoded, `null` under `--dry-run`. `requested_segments`/`requested_duration` keep their meaning, the request clamped to the media's duration: a segment ended with the video (less than a frame of sound trimmed) shows in `duration_delta_seconds` and a `notes` line |+| `edit_list`, `stored_preroll_seconds`, `av_start_skew_seconds`, `notes` | `cut.py` (every run) | `edit_list`: `true` only for a single-segment `.mp4`/`.m4v`/`.mov` stream copy run with `--edit-list`, which keeps the MP4 edit list the copy writes instead of `-avoid_negative_ts make_zero` (the default, unchanged): the keyframe's pre-roll is stored but hidden, so the picture starts at `--start`. `stored_preroll_seconds`: with `edit_list`, the seconds decoded from the keyframe the copy's seek lands on (measured with the seek ffmpeg makes) up to the first presented frame; `null` otherwise. Under `--edit-list` a copy is judged by its video's length (a `notes` line says so when the container is longer), and one that starts where asked but ends past `--tolerance` re-encodes (`tolerance`) without a `lossless_alternative`. `av_start_skew_seconds`: the output's audio start minus its video start (`null` when either is missing or under `--dry-run`); on a stream copy, when it is more than max(2 frames, 0.1 s) away from the source's own audio/video offset where the copy's picture starts (the keyframe it began from; `--start` under `--edit-list`), a `notes` line names `--accurate`, and `--edit-list` for a single `.mp4`/`.mov` copy whose start snapped. A re-encode carries no such note. The skew is reported, never repaired. `notes`: what the run did that a caller should know, in plain sentences (`[]` when nothing) |+| `video.start_time`, `audio.start_time` | `probe.py` (and every `probe` block a tool returns) | where each stream starts, in seconds on the file's own clock (ffprobe's stream `start_time`; `null` when unknown). A video stream that starts after its audio, or the reverse, is how a lossless cut's A/V skew shows; `cut.py` reads them for `av_start_skew_seconds` |+| `cut_reencode_reasons` | `batch.py` (and its `results` rows) | a row whose recipe ran `cut.py` lists each `reencode_reason` its `cut.py` calls named, once per call, beside `cut_reencoded`; the top level counts them across the folder (`{}` when no call re-encoded, `null` when no `cut.py` step ran) on a completed batch, as `cut_stream_copy` does: a failure document carries `results`, whose rows hold each row's reasons; a re-encoded call in a row served from a cache an earlier 2.x batch wrote, which recorded no reasons, counts as `unknown`. `cut_stream_copy` is unchanged |+| `vfr_check` | `cut.py` (a video input that could still stream-copy) | the sampled frame timing, `{heuristic: true, measured, method: "sampled", guard, windows, deltas}`; `measured` is `sampled_cfr`, `vfr` or `inconclusive`. `--vfr-guard average` (the default) keeps the 2.x guard: a source whose nominal and average frame rates differ (`variable_frame_rate_suspected`) re-encodes as `--accurate` (reason `vfr`, stderr says "variable-frame-rate"), and only then is the timing sampled and reported, with a `notes` line naming `--vfr-guard sampled` when it measured `sampled_cfr`; the key is absent otherwise. `--vfr-guard sampled` samples before every copy and re-encodes on `vfr` (reason `vfr`) or `inconclusive` (fewer than 20 intervals; `vfr_inconclusive`); `--vfr-guard off` samples and keeps the copy, with a `notes` line. Absent for audio-only input or output, `--accurate`, `--codec` and a pending `--dry-run` input |+| `join_check`, `segment_end_snap_seconds` | `cut.py --segments` | `join_check`: a video stream-copy join measured by demuxing, `{packets, expected_packets, max_step_seconds, audio_offset_ms, audio_parts_checked, ok}`. `expected_packets` counts the source's video packets from each part's start keyframe to its end (or the end of the video); `max_step_seconds` is the largest presentation step, `null` when `vfr_check` measured anything but `sampled_cfr` (a `--vfr-guard off` join of variable timing: count only), and each step at a join must be the step its parts predict within 1 ms. `audio_offset_ms`: per part, its sound's shift minus its picture's in ms (+ = sound late), from audio packets matched by CRC32 to the source stream shaped like the joined audio (FFmpeg's default selection may copy one other than `a:0`; an MPEG-TS source's AAC is hashed without its ADTS headers); `null` for a part with no unique match (digital silence, a periodic tone), and as a whole when the source has no audio or the video check failed. `audio_parts_checked` counts the measured parts. `ok` is the conjunction (count, steps, every measured part within 5 ms); `ok: false` means the join was re-cut (`concat_fallback`) and this is the failed measurement. `null` for a single segment, audio, `--dry-run`, any re-encode forced for every segment, a segment that re-encoded, or a join re-cut before a copy was tried (open GOPs, a later B-frame segment starting between keyframes, parts that differ, a concat error). `segment_end_snap_seconds`: per segment, the signed seconds its end moved to the keyframe the copied part stops at, the first at or after the requested end (`null` for a part that reaches the end of the video, a part of a source with no B-frames, cut to its requested end as in 2.5.1, or a Matroska/MPEG-TS part, which is not snapped); `null` as a whole unless the output is those copied parts |`caption.py --transcribe` and `silence.py --filler --transcribe`: when a local speech engine ranand produced no cue, the refusal is `"<engine> found no speech in <input>"` with `kind: input`,diff --git a/docs/demos.md b/docs/demos.mdindex 8086763..95799b9 100644--- a/docs/demos.md+++ b/docs/demos.md@@ -261,6 +261,17 @@ python3 scripts/cut.py demos/out/fixtures/mandel.mp4 --start 2.05 --duration 3 -**Look for:** Both sides asked for the same 2.05 s start. The stream copy could only snap to the nearest keyframe, so its first frame is from earlier in the clip; --accurate re-encodes and starts on the frame that was asked for.+### Lossless cut that starts where asked++++```bash+python3 scripts/cut.py demos/out/fixtures/mandel.mp4 --start 2.05 --duration 3 --tolerance 5 --json -o demos/out/cut_edit_list_before.mp4+python3 scripts/cut.py demos/out/fixtures/mandel.mp4 --start 2.05 --duration 3 --tolerance 5 --edit-list --json -o demos/out/cut_edit_list_after.mp4+```++**Look for:** Both sides are stream copies of the same 2.05 s request. The default shifts the copy's timestamps to zero, so the keyframe's pre-roll plays first (start_snapped: true); --edit-list keeps the MP4 edit list that hides it, so the picture starts at 2.05 s (start_snapped: false, stored_preroll_seconds says how much is hidden). A player that ignores edit lists shows the pre-roll.+### Cuts that land on the beatdiff --git a/docs/demos/cut_edit_list.gif b/docs/demos/cut_edit_list.gifnew file mode 100644index 0000000..134ae81Binary files /dev/null and b/docs/demos/cut_edit_list.gif differdiff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex e76c106..aca277e 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -1006,3 +1006,353 @@ not a new file format this tool would have to maintain.each engine's source and process, so `network: false` cannot be read as "a first`--transcribe` is network-free". Tests: `InstallHintTests`,`test_the_network_claim_matches_where_each_engine_runs`.++## Unreleased — cuts that say what they did++- **`precision`, `keyframe_snapped` and `requested_*` keep their 2.x meanings; what is measured+ per segment gets new keys.** No 2.x key changes meaning. `precision` stays `precision_of()` for+ the whole run and `keyframe_snapped` stays `precision == "packet"` (a stream copy end to end):+ `demos/build.py`'s `demo_cut_accurate` and `docs/demos.md` read it that way. What #306 measured+ goes beside them. `start_snapped` is true when a copied picture starts more than a frame from+ its requested start (the keyframe the copy's seek lands on, measured: see the entry on where a+ copy begins) or when that start could not be measured (no packet at or after it in the probed+ window): an unknown start is never claimed exact, and the copy is not re-encoded for it, because+ 2.x copied without measuring at all. Test: `test_an_unmeasured_start_is_never_reported_as_exact`.+ It is `null` under+ `--dry-run`, because a planned copy has not landed anywhere yet. `least_exact_precision` is the+ least exact segment's precision, and `segment_precision` lists them all. The two precisions+ differ only for an audio-only join of copied and re-encoded parts, because a video join re-cuts+ every segment when one part re-encodes. `requested_segments`/`requested_duration` and+ `expected_duration` stay the request clamped to the media's duration. A segment that ends with+ the video (less than a frame of sound trimmed) shows in `duration_delta_seconds` and a note,+ not in a changed request. Tests (main's, restored verbatim):+ `test_cut_json_reports_requested_vs_actual_and_mode`,+ `test_cut_copy_keyframe_snap_reports_a_real_nonzero_delta`, `test_eval6_followups`; new:+ `test_cut_precision_keeps_its_formula_and_least_exact_precision_is_beside_it`,+ `test_cut_start_snapped_is_measured_and_null_under_dry_run`,+ `test_a_sound_tail_under_a_frame_ends_the_segment_with_its_picture`.+- **A join that re-encoded is not reported as a copy (defect fix, on by default).** When the+ concat demuxer's stream copy failed, 2.x re-encoded the join and still reported `mode: copy`,+ `reencoded: false` and `precision: packet`. The join now counts toward `reencoded`, so such a+ run reports `hybrid` and `concat_fallback`. `reencode_reason` lists every cause, and `--codec`+ is named even when `--accurate` already forced the re-encode. Tests:+ `test_a_failed_concat_copy_is_reported_as_the_reencode_it_became`,+ `test_cut_json_says_why_it_reencoded_and_how_exact_each_segment_is`.+- **`batch.py`'s `cut_stream_copy` keeps its shape; the reasons are a sibling key.** Callers+ compare that object whole: main's test does, with `assertEqual`. Each row gains+ `cut_reencode_reasons` (each reason once per `cut.py` call that named it), and the top level+ gains `cut_reencode_reasons` counts. They are `{}` when no call re-encoded and `null` when no+ `cut.py` step ran. A row served from a cache an earlier 2.x batch wrote has `cut_reencoded`+ but no reasons; its re-encoded calls count as `unknown`, so the counts never read "none+ re-encoded" beside `cut_stream_copy.reencoded: 1`. Tests: `test_batch_reports_cuts_stream_copy_vs_hybrid_rate_across_the_folder`+ (main's, verbatim), `test_batch_counts_cut_reencode_reasons_beside_the_stream_copy_rate`.++- **A `--segments` join copies only identical parts, and otherwise re-cuts from the source.**+ The concat demuxer takes the first part's parameters for every part, so a copied HEVC segment+ next to a re-encoded H.264 one decoded with errors from a run that exited 0. The copy join now+ needs matching per-stream signatures (codec parameters, rotation, colour tags, extradata hash;+ a hash missing on both sides only counts for PCM/MP3/MP2 or an MPEG-TS output). No sum of the+ parts' durations predicts the join (each carries its own start offset, which the concat+ demuxer drops: it missed by 0.03–1.3 s across five ordinary sources), so the result is+ measured instead (next entry). The fallback does not join the parts at all: a copied part carries keyframe+ pre-roll and an audio tail, and the concat filter starts each segment where its longest stream+ ended, which left a 0.1 s hole even after a `PTS-STARTPTS` rebase. Re-cutting every segment+ from the source (per-segment input seek, `trim`/`atrim`, concat filter) measured 120/120+ frames with no gap. Code: `cut.signatures_match`, `cut.join_from_source`. Tests:+ `tests/test_cut_copy.py`.+- **A copy join of B-frame video snaps both ends of every part to keyframes, and verifies by+ demuxing.** Measured on lavfi fixtures, frame by frame with `framemd5`, then on real iPhone+ footage. An input `-t` stops in decode order, so a part ended at a keyframe's pts carried that+ keyframe and the P-frame after it; `make_zero` parts started at the reorder delay. Of five+ designs only one was exact: `.mp4`/`.m4v`/`.mov` parts that keep their edit list (the concat demuxer+ ignores where it starts, so the pre-roll is shown, but places the next part by its length) and+ end at the end keyframe's **dts**. Each end is judged against `--tolerance` on its own. **Open+ GOPs** cannot be cut this way: the frames just before a keyframe decode after it, so they are+ lost (144/150 in every design). An open end keyframe, or an open start keyframe after the first+ part, re-cuts the join. iPhone "High Efficiency" HEVC is open at every keyframe, so its joins+ re-encode. Smart rendering (copy the interior, re-encode the joins) was deferred. The check is+ the backstop for what the design does not model: Matroska parts (still the old cut), unusual GOP+ shapes. Only copied parts are copy-joined; parts encoded one by one leave an AAC frame's hole at+ every join. Code: `cut.plan_part`, `cut.gop_is_open`, `cut.check_join`. Tests:+ `CopyJoinPlanTests`, `CutJoinTests` in `tests/test_cut_copy.py`.+- **A source whose frames do not reorder cuts its parts as 2.5.1 did.** #306's keyframe plan was+ written for B-frames, and on H.264 with no B-frames (`-g 60`, AAC; iPhone "Most Compatible") it+ regressed joins 2.5.1 copied frame-exactly: `0-1.0,4-6` re-encoded (`tolerance`,+ `concat_fallback`) where 2.5.1 copied 90 frames; `0-1.8,4-6` gave 120 frames (end moved+ +0.2 s) for 2.5.1's 114; `0-2.4,4-6` gave 120 (end moved −0.4 s: requested frames dropped under+ `mode: copy`) for 132; and `0.3-2,4.4-6`, which 2.5.1 copied as 120 frames, failed the check+ and re-encoded. Without reordering a cut in decode order is already exact, so+ `cut.reorders(packets)` (a packet presented before one decoded ahead of it) decides: when+ nothing reorders, each part is cut as in every 2.x release (`make_zero`, `-t end-start`, no end+ snap, judged against `--tolerance` by its length) and the join is still checked. All four came+ out bit-identical to 2.5.1's outputs. Tests:+ `test_a_source_without_bframes_cuts_its_parts_as_2x_did`,+ `test_a_60fps_source_without_bframes_stays_an_exact_copy`,+ `test_reorders_is_true_only_when_a_frame_is_presented_before_one_decoded_ahead`.+- **An end snaps to the keyframe at or after it, never earlier.** #306 took the keyframe nearest+ the requested end, so `0-2.4` ended at 2.0 and dropped requested frames under `mode: copy`. A+ start snap only ever adds material, and so does an end snap now: the part runs to the first+ keyframe at or after the end, and if that one is past `--tolerance` the join is re-cut. An end in+ the video's last GOP has no keyframe after it; it stays where asked and the join check judges it+ (#306's rule, not a tolerance miss, even under `--tolerance -1`). Tests:+ `test_an_end_snaps_to_the_keyframe_after_it_never_before`,+ `test_an_end_snaps_to_the_first_keyframe_at_or_after_it`,+ `test_a_segment_in_the_last_gop_is_not_a_tolerance_reencode`.+- **A later B-frame segment that starts between keyframes is re-cut without trying the copy.**+ Its edit-listed part stores the frames from the keyframe to the start as hidden pre-roll, and the+ concat demuxer crushes them into steps of about 0.07 ms at the join, so the copy failed its check+ on every source shape tried (`0.3-2,4.4-6`, `0-2,4.1-6`, `0-2,4.4-12` on H.264, `0-2,4.2-6` on+ closed-GOP HEVC). Only edit-listed parts hide pre-roll; the first part's is not at a join. It+ holds under `--tolerance -1` too, so `--tolerance -1` is "never for a keyframe snap", not "never":+ README, `references/gotchas.md`, `references/scripts.md` and `cut.py --help` say so, and advise a+ keyframe start or an `.mkv` output. Code: `cut.hidden_preroll_start`. Tests:+ `test_a_later_start_between_bframe_keyframes_is_recut_without_a_copy`,+ `test_only_a_later_edit_listed_part_starting_between_keyframes_hides_pre_roll`.+- **The step at a join is the one its parts predict, within 1 ms.** #306 allowed a frame plus+ `max(frame/2, one audio frame)` at every step. That rejected exact joins (no-B `0-1.8,4-6` steps+ 56.7 ms at the join, past its 54.7 ms bound) and let through a hole of up to one audio packet,+ which grows without limit with large PCM packets. The concat demuxer places each part where the+ previous part's container ends, so the step is (that container's end − its last picture) + (the+ next part's first picture − its container start), read from each part's format and video+ packets (Matroska stores no stream durations): 33.3 + 13.3 + 10.0 = 56.7 ms there, what the+ joined file showed, and within 1 ms on every MP4, MOV, Matroska and MPEG-TS join measured.+ Steps inside a part stay within (frame/2, 1.5 × frame). Code: `cut.predicted_join_steps`,+ `cut.check_join`. Tests: `test_each_join_step_is_held_to_the_step_its_parts_predict`,+ `test_a_join_step_is_predicted_from_the_parts_containers_and_pictures`,+ `test_a_no_bframe_join_one_frame_plus_its_gap_long_passes_the_check`.+- **A copy join's sound is checked against its picture, part by part.** Matching audio packet+ hashes to the source on keyframe-aligned `0-2,4-6,8-10` copy joins, each part's sound minus+ picture shift measured 0.3 ms (B-frame H.264, AAC; closed-GOP HEVC), 0–0.64 ms (no-B H.264),+ 0 (audio 0.379 s late; audio leading by 0.2 s), and 0 / +16.0 / +53.3 ms for B-frame H.264 with+ `pcm_s16le` in a `.mov`, which #306 passed as `ok: true` with 180/180 frames. `check_join_audio`+ reads `a:0` packets with `-show_data_hash CRC32` for the join and for source windows around each+ part's start keyframe; for each part, the first run of 8 packets from 0.25 s into it that+ appears exactly once in the source within ±0.5 s of where the video's shift puts it gives the+ audio shift. More than 5 ms from the video's shift fails the check and re-cuts the join. A part+ with no unique run (digital silence, a periodic tone, a part too short) is unmeasured+ (`null`), not failed, so silence makes the check blind there. The source stream hashed is the+ one the join copied: FFmpeg's default selection copies the audio stream with the most channels,+ not always `a:0` (a 6-channel PCM `a:1` beside a stereo AAC `a:0` was copied, every part went+ unmeasured, and a join 16 and 53 ms off passed), so the check hashes the source streams with+ the joined audio's codec, channels and sample rate, in turn, until one measures a part. An+ MPEG-TS source's AAC carries an ADTS header that the copy into MP4/MOV/Matroska strips, so no+ hash matched; its packets are hashed without it (from `-show_data`; zlib's CRC32 is ffprobe's).+ `ok` is the conjunction, and `join_check` carries only its documented keys. Cost: about 0.5 s+ on a 3-minute join. Code: `cut.check_join_audio`, `cut.copied_audio_streams`,+ `cut.audio_packet_hashes`. Tests: `test_the_audio_check_hashes_the_stream_the_join_copied`,+ `test_the_audio_check_measures_aac_out_of_mpeg_ts`,+ `test_an_adts_header_is_left_out_of_the_hashed_payload`,+ `test_a_matroska_join_is_checked_and_recut_when_it_is_wrong` (the key set),+ `test_a_join_whose_sound_drifts_off_its_picture_fails_the_check_and_is_recut`,+ `test_a_clean_join_passes_the_audio_check_part_by_part`,+ `test_the_audio_check_measures_each_parts_sound_against_its_picture`,+ `test_a_part_whose_packets_repeat_is_unmeasured_not_failed`.+- **The join reads the source's packets only around the segments.** #306 read every video packet+ of the source for each `--segments` run, so the cost followed the source's length: on a+ 25-minute 720p30 H.264 source (`-g 60 -bf 3`, AAC, 954 MB, 45,000 video packets, 4 vCPU,+ FFmpeg 6.1) the whole read took 2.9 s with the page cache dropped and 1.1 s warm. Now one ffprobe+ per merged window `[start − M, end + M]`, M = max(10 s, 2 × `--tolerance`), absolute times; for+ `60-120,600-660,1200-1260` the three windows read 7,200 packets in 0.5 s cold or warm; the+ whole join took 4.9–5.1 s against 5.2–5.7 s (it now also checks the audio), and its `--dry-run`+ 0.7 s against 1.4 s. A window that lacks the landing keyframe, a whole GOP after it, or the first+ keyframe at or after the end with a whole GOP after that is widened ×4, up to three times, and+ then the whole file is read. The window at the file's start does not seek (a seek there skips an+ edit-listed MP4's negative-pts keyframe, as `measure_frame_timing` found); packets a later+ window's seek reads again are dropped; `gop_is_open` and `reorders` do not take a window's end+ for the file's end or the next packet; the cache key is (source, windows). Code:+ `cut.video_packets`, `cut.packet_windows`, `cut._windows_cover`. Tests:+ `test_the_packets_read_around_segments_plan_as_the_whole_file_does`,+ `test_packets_are_read_in_windows_widened_until_the_plan_has_its_gops`,+ `test_a_gop_longer_than_every_window_reads_the_whole_file`,+ `test_the_first_window_never_seeks_and_windows_merge`,+ `test_a_gop_cut_off_by_a_read_window_is_not_judged_closed`,+ `test_reorders_is_judged_within_each_read_window`.+- **A checked join is written beside the output and renamed into place.** #306 wrote it in the+ temp directory and copied it (about 2 s for a 240 MB join). It is now a hidden sibling of the+ output (`.<name>.ffskill-join-<pid>.<ext>`), renamed with `os.replace` under the output's lock+ by `place_output(..., move=True)` (a rename that fails falls back to the copy), and removed+ whatever happens. A failed check still never costs an `--overwrite` target. Code:+ `runner.place_output`, `runner.sibling_temp`. Tests:+ `test_a_checked_join_is_renamed_into_place_under_the_outputs_lock`,+ `test_a_checked_join_is_placed_under_the_outputs_lock`,+ `test_a_checked_join_is_renamed_into_place_not_copied`.+- **The re-cut cuts on the source's frame grid and states its frame rate.** Each segment runs, for+ both streams, from the first frame at or after its start to the first at or after its end (the+ frames it holds); the video trim sits half a frame before those points, so no FFmpeg version+ rounds a boundary frame in or out. A start between frames placed the segment's pictures half a+ frame off the output's grid, and FFmpeg 6.1's constant-rate output duplicated one (65 frames for+ 64). `-r` is the source's `r_frame_rate`: FFmpeg 7.0 encoded the trimmed, concatenated pictures+ at 25 fps and dropped frames (98 for 117). Both streams still shift by one constant. Tests:+ `test_a_short_segment_across_a_bframe_keyframe_never_cuts_a_negative_length`,+ `test_the_recut_cuts_on_the_frame_grid_and_states_the_sources_rate`,+ `test_mismatched_parts_are_recut_from_the_source_with_exact_boundaries` (on 7.0).+- **Both streams of a segment shift by one constant.** A per-stream `PTS-STARTPTS` moved an+ audio track that starts 0.379 s after its video 0.379 s early. The re-cut shifts video and+ audio by the same seek margin and pads the audio to the segment origin+ (`aresample=async=1:first_pts=0`). Test: `test_a_delayed_audio_track_keeps_its_offset_through_the_fallback`.+- **The re-cut seeks a second early.** The MP4 demuxer seeks over its raw decode times, so on a keyint-60+ HEVC file with 4 B-frames `-ss 9.9` began at the keyframe at 10.0 and lost three frames; an+ input `-t` likewise stops reading before late-stored B-frames. Test:+ `test_more_segments_than_one_call_takes_are_joined_in_chunks` (it crosses that boundary).+- **At most 32 segments per ffmpeg call, chunked through Matroska with PCM audio.** Each segment+ is its own input (a file handle, demuxer and decoder), and macOS shells default to 256 open+ files. MP4/AAC chunks copy-joined put the video 23 ms behind the audio (encoder priming per+ chunk); PCM chunks carry none, and the audio is encoded once for the final file.+- **A video cut or segment shorter than one frame is refused (defect fix, on by default).** There+ is no picture to cut: on 2.5.1 `--start 1 --end 1.01` on 30 fps video wrote one whole frame+ (44 ms longer than asked) and `--segments 1-1.01,3-4` wrote 31 frames, both reported+ `completed`. A copy lands on a whole GOP and a re-encode on one frame or none, so neither is what+ was asked; the refusal (`kind: input`, before ffmpeg runs) follows 2.x's refusals of a caption+ burn that draws nothing and of blank graphics text. A cut to an audio output is not refused: sound has no frame.+ Code: `cut.main()`. Tests: `test_a_segment_shorter_than_a_frame_is_refused`,+ `test_a_single_cut_shorter_than_a_frame_is_refused_but_not_to_audio`.+- **A single MP4/MOV copy keeps its edit list only with `--edit-list`; its report comes from the+ source's packets.** `make_zero` shows the keyframe's pre-roll. The plain copy writes an edit+ list that hides it, and its first presented frame was bit-identical to the source frame at or+ after `--start`. #306 made that the default. It is opt-in in 2.x because the default decides+ what a caller gets, measured against main: `nob.mp4 --start 1.13 --end 5.71 --tolerance 2`+ copied 172 frames (+1.153 s) and now 138 with the pre-roll hidden; `hevc_sdr --start 1.1 --end 4+ --tolerance 0.3` re-encoded (`hybrid`) and now copies; a 25-minute source `--start 601 --end 661`+ wrote 74.7 s and now 1.95 s. A player or tool that ignores edit lists also shows the stored+ pre-roll, so an edit-listed copy is not what every 2.x caller expects. So the default stays+ `-avoid_negative_ts make_zero` and is judged by the container's length, as in every 2.x+ release; `edit_list` is `false` and `stored_preroll_seconds` `null`. Two rules apply only under+ `--edit-list`: the copy is judged by its video (the container also counts a longer track), and+ a copy that starts where asked but ends past `--tolerance` re-encodes without offering another+ `--start`. What a copy stored is read from the source, not the output: `stored_preroll_seconds`+ is the first presented frame minus the presentation time of the keyframe the copy's seek lands+ on (measured: next entry), and a keyframe presented *after* the start (10.0, asked for 9.9 on+ the HEVC fixture) is a snap. Comparing the output's durations with and without the edit list+ was tried and does not work: a B-frame composition offset makes them differ even on a keyframe+ start. Code: `cut.seek_keyframe`, `cut.copy_presentation`. Tests:+ `test_an_mp4_copy_shifts_to_zero_unless_the_edit_list_is_asked_for` (the default),+ `test_an_mp4_copy_starts_its_picture_at_the_requested_time`,+ `test_an_edit_listed_source_cut_again_starts_where_asked`,+ `test_judging_a_copy_by_its_video_is_noted_even_when_it_then_reencodes`; main's+ `test_cut_json_reports_requested_vs_actual_and_mode` and `test_eval6_followups`, verbatim.+- **Where a stream copy begins is measured with the seek ffmpeg makes, not modelled.** #306+ predicted the landing as the keyframe with the largest ffprobe dts at or before the start. The+ MP4 demuxer seeks over its raw decode times, which are ffprobe's dts plus the reorder delay, so+ on B-frame H.264 (FFmpeg 6.1.1 and 7.0.2) `-ss 3.99` landed on the keyframe at 2.0, not on the+ one at 4.0 (dts 3.933), and only `-ss 4.0` reached 4.0; on the HEVC fixture `-ss 9.85` landed on+ 8.0 and `-ss 9.9` on 10.0. The model got the second right and the first wrong: a single copy+ from 3.97 reported `start_snapped: false` with its picture 1.97 s early, its `--edit-list`+ variant reported no stored pre-roll, and a join from 3.95 failed its check (180 packets for 120)+ and was re-encoded after the copy was tried. `seek_keyframe` now runs `ffprobe -read_intervals`+ from the file's start_time + t, the same `avformat_seek_file` call as ffmpeg's input `-ss`, and+ takes the first keyframe it reads (ffmpeg's copy drops what comes before it). For a demuxer+ without `AVFMT_SEEK_TO_PTS` (Matroska, MPEG-TS) ffmpeg seeks 3/23 s earlier when a stream has+ a decode delay (`fftools` `ffmpeg_demux.c`), and so does the probe (`cut.seek_shift`): on a+ B-frame `.mkv` `-ss 4.05` lands on 2.0 and `-ss 4.2` on 4.0, as the probe says. A `--segments`+ plan starts each part at its measured landing, so a later start in the reorder delay is+ planned (a tolerance re-cut, or the hidden pre-roll re-cut) instead of failing its check. One+ ffprobe per segment start; the read never seeks earlier than ffmpeg does (a seek before the+ file's start skipped an edit-listed MP4's negative-pts keyframe). Code: `cut.seek_keyframe`,+ `cut.seek_shift`, `cut.plan_part`. Tests:+ `test_a_start_inside_the_reorder_delay_lands_where_ffmpeg_seeks`,+ `test_a_later_start_inside_the_reorder_delay_is_planned_not_tried`,+ `test_an_edit_listed_source_cut_again_starts_where_asked`.+- **A `--segments` tolerance re-cut names the nearest keyframes, as in 2.x.** 2.5.1 cut every part+ and the part that missed `--tolerance` filled `nearest_keyframes`. #306 judges every start in+ `plan_part` before any part is cut and re-cuts without `cut_one`, so the key was `null` for+ those runs (67 harness cases). The re-cut branch now lists `keyframes_near` each such segment's+ start, the same values 2.5.1 gave. `lossless_alternative` stays single-segment, as in 2.x.+ Test: `test_a_segments_tolerance_reencode_names_the_nearest_keyframes`.+- **Microsecond `-ss`/`-t` and the `--accurate` seek margin are defect fixes, on by default.**+ Both change what the default writes, and both only make it what was asked. `-ss` rounded to the+ millisecond missed a keyframe at 61/30 = 2.0333 s: `--start 00:00:02:01@30` seeked to 2.033,+ snapped back to the keyframe at 0 and re-encoded; it now copies from that keyframe. A video+ `--accurate` cut seeks a second early and drops the margin on the output side, because a seek+ straight to a start a few frames before a keyframe could land (the MP4 demuxer seeks over its raw+ decode times) on that keyframe and+ lost those frames. Tests: `test_a_millisecond_off_keyframe_start_is_seeked_to_the_microsecond`,+ `test_accurate_keeps_the_frames_before_a_keyframe`.+- **An A/V start skew on the default path is reported, not repaired.** Without `--edit-list` a+ copy keeps main's `make_zero` behaviour, including the Core Media HEVC case (3.7 s of sound+ with no picture) and the B-frame reorder delay (0.12 s on the HEVC fixture). Re-copying with+ the edit list when the skew is large was considered and rejected for 2.x: it would change the+ default output's timestamps, the thing `--edit-list` is opt-in to avoid. `av_start_skew_seconds`+ is always reported. On a stream copy only, a `notes` line names `--accurate` (and `--edit-list`+ for a single `.mp4`/`.mov` copy whose start snapped) when the skew is more than max(2 frames,+ 0.1 s) away from the source's own skew where the copy's picture starts: at the keyframe the copy+ began from, or at `--start` under `--edit-list`. A track that starts late by design (the 0.355 s+ late-audio fixture cut from 0, or from 0.3, which snaps back to the same keyframe and writes the+ same copy) is what was asked for, not a copy that began on packets the streams do not share. A+ re-encode gets no note: it starts both streams where the source has them (the re-cut pads the+ audio to each segment's origin), and the note told `--accurate` runs to re-run with+ `--accurate`. Code: `cut.av_skew`, `cut.source_skew`. Tests:+ `test_an_mp4_copy_shifts_to_zero_unless_the_edit_list_is_asked_for`,+ `test_a_source_whose_audio_starts_late_is_not_reported_as_a_skewed_cut`,+ `test_a_snapped_copy_is_compared_with_the_source_where_it_landed`,+ `test_a_reencode_never_carries_the_copy_skew_note`,+ `test_av_skew_names_the_edit_list_only_where_it_would_help`.+- **A re-encoded cut keeps an SDR HEVC source HEVC only with `--keep-hevc`.** A cut is a trim, so+ a re-encoded segment could come out in the codec of the source and of any copied segment beside+ it; x264 for every SDR source turns an iPhone clip into H.264. #306 made HEVC the default, which+ changed what an existing call writes (`hevc_sdr --start 2 --end 4 --accurate` gave h264 on 2.5.1+ and hevc with #306), so within 2.x it is opt-in: `source_codec_video_args(..., keep_hevc)` calls+ `encoder_args("hevc")` (x265 8-bit BT.709, VideoToolbox under `--hw` with the CPU line recorded+ for the fallback) only when the flag is set, the source is HEVC and not `bt2020_or_hdr`;+ everything else takes `video_args`, the line every editing tool uses. An HDR, HLG or BT.2020-SDR+ source gets the same Main10 line either way, and `--codec` always wins. The contract's `cut`+ capabilities keep 2.5.1's x264 and HDR x265 entries, the x265 one extended by "with+ `--keep-hevc` on an HEVC source". Tests:+ `test_a_reencoded_cut_of_an_sdr_hevc_source_is_h264_unless_keep_hevc_is_asked_for` (the default+ pin), `test_a_reencoded_cut_of_an_sdr_hevc_source_stays_hevc`,+ `test_codec_h264_still_overrides_the_source_codec`, `SourceCodecArgsTests` (including+ `test_cut_passes_keep_hevc_to_the_encoder_and_composes_with_hw`).+- **A chunked join restates `hvc1`, by default.** A `--segments` re-cut of more than 32 segments+ encodes Matroska chunks and copies them into the output; out of Matroska into MP4 that copy+ writes `hev1`, which Apple players refuse. 2.5.1 had no chunks (its re-encodes wrote `hvc1`+ directly), so this is a defect in #306's chunking, not in a release; it is fixed by default+ because every HDR source's re-cut is HEVC Main10 with no flag, and a chunked join of it would+ otherwise be the first 2.x output tagged `hev1`: `_join_chunk` returns its codec arguments and+ the final copy into `.mp4`/`.mov`/`.m4v` repeats their `-tag:v`. Tests:+ `test_a_chunked_hdr_join_keeps_the_hvc1_tag_by_default` (HLG, no flag),+ `test_more_segments_than_one_call_takes_are_joined_in_chunks` (`--keep-hevc`).+- **The VFR guard stays the average check by default; the sampled measurement is `--vfr-guard+ sampled`.** `r_frame_rate` against `avg_frame_rate` is a whole-file average: a phone clip at+ 29.98 against a nominal 30 trips it, and one long last frame does too. #306 replaced it with+ `measure_frame_timing`, which reads packet timestamps (no decoding) in up to five 6 s windows+ and requires every interval within a tick (1 ms at least, half a frame at most) of its window's+ median; the half-frame cap is there because a 1/fps time base makes one tick a whole frame.+ As the default that changed what existing calls write in both directions: a 0.5 s+ constant-rate clip that 2.5.1 copied re-encoded (`vfr_inconclusive`, 11 intervals where 20 are+ needed), and the suspected-but-constant `vfr_false_positive.mp4` that 2.5.1 re-encoded copied.+ So within 2.x the guard is a choice. `average` (default) is 2.5.1's guard: the suspected source+ re-encodes as `--accurate`, reason `vfr`, and stderr still says "variable-frame-rate"; only+ then is the timing sampled, and reported in `vfr_check` with `guard`, plus a `notes` line naming+ `--vfr-guard sampled` when the sample is constant. A source the average check passes is not+ sampled, so the default costs what it did, and a copy join of it checks its steps as constant+ timing. `sampled` is #306's guard (re-encode on `vfr` or `inconclusive`), and `off` is #306's+ unreleased `--vfr-copy` (which never shipped and is gone): for an eligible copy cut it samples the+ timing but keeps the stream copy. VFR confined to the unsampled+ stretches is missed by `sampled`; that was accepted because a copy is lossless and `--accurate`+ is always available. The reads are shaped by how `-read_intervals` behaves: it resolves a+ seek, and a relative end, against the keyframe it lands on, so windows name an absolute end and+ keep only frames from their own start, and the first window does not seek (a seek to 0 on an+ edit-listed MP4 skipped its negative-pts keyframe). Code: `cut.main()` (the guard),+ `_common/probe.py` `classify_frame_timing`, `measure_frame_timing`. Tests:+ `test_vfr_is_conformed_to_cfr_on_cut_and_fit` (2.5.1's, verbatim),+ `test_a_short_constant_clip_copies_by_default`,+ `test_a_suspected_but_constant_source_reencodes_by_default_and_says_sampled_would_copy`,+ `FrameTimingTests`, `VfrGuardTests` (`--vfr-guard sampled` / `off`).+- **A segment past the video's end is held or trimmed, like a join.py clip; `--accurate` joins in one+ encode.** Both concat routes start the next segment after the longer stream of this one, so a+ segment whose sound outruns its picture opened a hole (0.355 s; and one AAC frame at every+ `--accurate` join, because each part was encoded on its own). `clip_length`'s rule decides: under a+ frame past the video's end, the segment ends with the video; more, its last frame is held for the+ sound, which only the re-cut can do. The last segment keeps the source's tail. The video's end is+ on the cut's clock: stream start + duration − the file's start_time. Its test source starts both+ streams at 10 s with PCM audio: a copied AAC track's priming started the file 21 ms before its+ video on FFmpeg 6.1 and not on later versions, which changed the frame count. Tests:+ `test_a_segment_past_the_video_end_holds_its_last_frame_in_a_copy_join` and siblings,+ `test_an_accurate_join_has_no_hole_at_its_joins`.+- **Decided for 3.0: the defaults #306 measured better, and the meanings it wanted.** 2.x keeps+ every key's meaning and every default's behaviour, so these wait for the next major, where+ each is a documented breaking change: `--edit-list` becomes the default for a single+ `.mp4`/`.mov` copy; `--keep-hevc` becomes the default, so a re-encoded cut of an SDR HEVC+ source stays HEVC; `--vfr-guard sampled` becomes the default, so a stream copy is refused on+ measured frame timing rather than on the whole-file average; `keyframe_snapped` takes+ `start_snapped`'s meaning (the presented start moved) and `precision` takes+ `least_exact_precision`'s (the least exact segment).diff --git a/references/gotchas.md b/references/gotchas.mdindex 9b4a126..a23c0a1 100644--- a/references/gotchas.md+++ b/references/gotchas.md@@ -37,17 +37,39 @@ S-Log, V-Log and C-Log look grey and low-contrast but are tagged SDR. Run### Keyframe cutsA lossless `cut.py` result may start up to one GOP (often 1–10 s) earlier than-requested; the script re-encodes automatically when the deviation exceeds 0.5 s.-If the user insists on lossless output, pass `--tolerance -1` and tell them the-cut lands on the nearest earlier keyframe. A `-c copy` cut on VFR or a+requested (`start_snapped: true`); the script re-encodes automatically when the+deviation exceeds 0.5 s. With `--edit-list`, a single-segment `.mp4`/`.m4v`/`.mov` copy+keeps the MP4 edit list instead: the pre-roll back to the keyframe is stored but+hidden, so the picture starts at the requested time (`edit_list`,+`stored_preroll_seconds`). A player or tool that ignores edit lists shows that+pre-roll. The **end** still lands on a packet boundary, a few frames long, and+those extra frames can skip. `.mkv` output has no edit list, and a `--segments`+join shows each part from its keyframe. On B-frame video an `.mp4`/`.mov`+`--segments` part's end moves to the first keyframe at or after it, within the+same tolerance (`segment_end_snap_seconds`); no-B-frame and `.mkv`/`.ts` parts+are not snapped. Every copy join is checked (frames, steps, each part's sound+against its picture) and re-cut when wrong. Open-GOP HEVC (iPhone "High Efficiency")+always re-encodes a `--segments` join, even with `--tolerance -1`, and so does a B-frame `.mp4`/`.mov`+join whose later segment starts between keyframes (start it on a keyframe, or write `.mkv`). If the user insists on lossless output, pass+`--tolerance -1` and tell them the cut lands on the nearest earlier keyframe.+Where a copy begins is measured with the seek ffmpeg makes: on B-frame `.mp4`/`.mov`+a start a few frames before a keyframe can begin at that keyframe or one GOP+earlier (`start_snapped: true` either way).+`av_start_skew_seconds` warns when a copy's sound and picture start apart+(Core Media HEVC once gave 3.7 s of sound with no picture); it is reported, not+repaired: `--accurate` is the fix, or `--edit-list` for a lossless `.mp4`/`.m4v`/`.mov`. A `-c copy` cut on VFR or anon-keyframe boundary produces a file that "works" but starts on a frozen orwrong frame — respect the automatic re-encode rather than forcing the copy.### Variable frame rate`probe.py` sets `variable_frame_rate_suspected` when `r_frame_rate` and`avg_frame_rate` disagree (phone and screen recordings). Every re-encoding-script then adds `-fps_mode cfr` at the source's average rate, and `cut.py`-switches itself to `--accurate` (copy-cuts on VFR are unreliable). Pick the rate+script then adds `-fps_mode cfr` at the source's average rate. That flag is a+whole-file average, and a phone clip at 29.98 against a nominal 30 trips it, so+`cut.py` re-encodes on it by default and reports packet timestamps sampled in up+to five windows (`vfr_check`), with a note when they are constant;+`--vfr-guard sampled` switches to `--accurate` only when they are irregular or too+few to judge, and `--vfr-guard off` keeps the copy anyway. Pick the rateexplicitly with `fit.py --fps 30|60` when the average is odd (e.g. 23.4 fps fromdropped frames).diff --git a/references/scripts.md b/references/scripts.mdindex 18abcb5..093df35 100644--- a/references/scripts.md+++ b/references/scripts.md@@ -56,24 +56,91 @@ between tools.```probe.py INPUT... [--compact] [--field duration|video.fps|...]```-JSON with `duration`, `video{codec,width,height,fps,pix_fmt,color_space,rotation,variable_frame_rate_suspected,hdr,hdr_signal,bt2020_or_hdr,hdr_format}`+JSON with `duration`, `video{codec,width,height,fps,pix_fmt,color_space,rotation,variable_frame_rate_suspected,hdr,hdr_signal,bt2020_or_hdr,hdr_format,start_time}`(`hdr`, and `hdr_signal` equal to it, is true only for a PQ / HLG transfer or Dolby Vision -- since 2.0;`bt2020_or_hdr` also counts BT.2020 primaries on an SDR transfer, which `hdr_format` names "BT.2020 SDR"),-`audio{codec,channels,sample_rate}`. `--compact` gives one line per file.+`audio{codec,channels,sample_rate,start_time}` (`start_time`: where the stream starts on the file's+own clock, `null` when unknown). `--compact` gives one line per file.### cut.py — cut / join segments```-cut.py INPUT [--start T] [--end T | --duration T] [--segments A-B,C-D,...] [--accurate] [-o OUT]+cut.py INPUT [--start T] [--end T | --duration T] [--segments A-B,C-D,...] [--accurate] [--edit-list] [--keep-hevc] [--vfr-guard average|sampled|off] [-o OUT]cut.py INPUT --start T --end T --snap beats [--snap-tolerance 0.12] [--snap-source FILE] [--min-confidence 0.5]```Times accept `12.5`, `1:30`, `00:01:30.250`. Default is `-c copy` (snaps tokeyframes, instant, lossless); if the snapped result deviates more than`--tolerance` (0.5 s) from the request, that segment is re-encoded automatically-(x264 CRF 18). `--accurate` always re-encodes; `--tolerance -1` never does.+(CRF 18: x264, or x265 Main10 with the source's own tags for an HDR or BT.2020 source;+`--keep-hevc` re-encodes an SDR HEVC source (not BT.2020: that keeps its Main10 line and colour tags) as x265 8-bit BT.709, on VideoToolbox under `--hw`;+`--codec` overrides all of them). `--accurate` always re-encodes; `--tolerance -1` never does for a keyframe snap+(a `--segments` join of open-GOP video, one whose later B-frame `.mp4`/`.mov` segment starts+between keyframes, or one that fails its check, still re-cuts).Multiple segments are concatenated in the order given. stderr reports whetherthe result was "lossless stream copy" or "re-encoded"; when the snap forced are-encode, the result's `lossless_alternative` names the nearest keyframe`--start` that would stream-copy instead, so the trade can be offered.+A single `.mp4`/`.mov` stream copy shifts its timestamps to zero+(`-avoid_negative_ts make_zero`), so the picture starts at the keyframe.+`--edit-list` keeps its MP4 edit list instead, so the picture starts at+`--start`: `edit_list` and `stored_preroll_seconds` say so, `notes` warns that a+player which ignores edit lists shows the pre-roll, and the copy's length is+judged by its video (a copy that starts where asked but ends past `--tolerance`+re-encodes without offering another `--start`). `av_start_skew_seconds` is+audio start minus video start; a stream copy gets a note when it is more than+max(2 frames, 0.1 s) away from the source's own offset where the picture starts+(the keyframe the copy began from; `--start` under `--edit-list`). It is+reported, not repaired. `-ss`/`-t` are passed to the microsecond; `--accurate`+seeks a second early and trims on the output side, so frames just before a+keyframe are kept. `keyframe_snapped` is true for every stream copy (`precision`+`packet`); `start_snapped` is measured: true when a copied picture starts more+than a frame from `--start`, or when its start could not be measured (an unknown start is+never claimed exact); `null` under `--dry-run`.+`reencode_reason` lists every cause of a re-encode (`requested`, `codec`, `vfr`,+`vfr_inconclusive`, `pcm_container`, `copy_failed`, `tolerance`, `concat_fallback`);+`--segments` adds `segment_precision`, and `least_exact_precision` is the least exact one.+A `--segments` video copy join adds `join_check` (`packets`, `expected_packets`,+`max_step_seconds`, `audio_offset_ms` per part, `audio_parts_checked`, `ok`: the+written file measured against the source) and `segment_end_snap_seconds` (where+each part's end moved to its keyframe).++**VFR guard (`--vfr-guard`).** `average` (default): a source whose nominal and+average frame rates differ (`variable_frame_rate_suspected`) re-encodes as+`--accurate` (reason `vfr`), and `cut.py` then samples its packet timestamps (up+to five 6 s windows; no decoding) into `vfr_check` (`measured`: `sampled_cfr`,+`vfr` or `inconclusive`, plus `guard`); a `sampled_cfr` there adds a note naming+`--vfr-guard sampled`. `sampled` samples before every copy and re-encodes only on+`vfr` / `inconclusive` (reasons `vfr` / `vfr_inconclusive`), so a phone clip at+29.98 against a nominal 30 copies; `off` samples and keeps the copy with a note.+Irregular timing between the windows is not seen; `--accurate` is always available.++A source with no B-frames (iPhone "Most Compatible" H.264) cuts its parts as+every 2.x release did: from the keyframe at (or before) each start to the end+asked for, each part within `--tolerance`. On B-frame video a copied+`.mp4`/`.mov` part runs from the keyframe at (or before) its start to the first+keyframe at or after its end (never an earlier one), each end within+`--tolerance`, so the join is the source's own frames with no gaps; a later+segment that starts between keyframes there is re-cut (its hidden pre-roll+cannot cross a join). A source with **open GOPs** (x265's default, iPhone "High+Efficiency" HEVC) cannot be copied exactly across a join and is re-cut+(`concat_fallback`, named in `notes`). Every copy join is measured after it is+written (`join_check`): the frame count, each step at a join against the step+its parts predict, and each part's sound against its picture (audio packets+matched to the source; more than 5 ms off fails, a part with no unique match+is unmeasured). One that fails is re-cut. Only windows around the segments+(about 10 s each side, widened as needed) are read from the source, so a long+source costs what its segments do.+The parts are joined by stream copy only when they all copied and match: the+same streams with the same codec parameters, rotation, colour tags and+extradata. Otherwise every segment is **re-cut from+the source** into one re-encode (`concat_fallback`): frame-exact boundaries, the+audio's offset from the video kept, subtitles dropped and reported, and at most+32 segments per ffmpeg call. A segment shorter than one video frame is refused.+With `--accurate` the segments are always cut that way, in one encode (a part+encoded on its own ran an AAC frame past its picture, leaving a hole at every+join). A segment other than the last that runs past the end of the video is+ended with the video when it runs less than a frame past it, and otherwise keeps+its sound with the last frame held -- which forces the re-cut (`concat_fallback`,+named in `notes`). The last segment keeps the source's own sound-only tail.**`--snap beats` (1.17)** moves each in/out point to the nearest *measured*beat within `--snap-tolerance` seconds (default 0.12, about a quarter of a beat@@ -905,6 +972,13 @@ batch.py FOLDER --recipe batch.json [--force] [--watch SECONDS] [--jobs N|auto]placeholders, chained) or `project` (a render project applied per file).Outputs land in `output_dir` with `suffix`; a content-hash cache skips filesalready done with the same recipe. Use `--dry-run` to preview the plan.+A recipe that runs `cut.py` rolls its calls up: each of those `results` rows carries+`cut_reencoded` (each call's `reencoded`) and `cut_reencode_reasons` (each+`reencode_reason` its calls named, once per call),+and the top level `cut_stream_copy` (`{calls, stream_copy, reencoded,+stream_copy_rate}`) and `cut_reencode_reasons` (counts per reason; `unknown` for a+re-encoded call cached by an earlier 2.x batch); both are `null`+when no `cut.py` step ran.**`--jobs N` (1.17)** processes N files at once (threads: the work issubprocess waiting). Capped at `min(N, cpu_count, 8)` — every item is itself andiff --git a/scripts/_common/__init__.py b/scripts/_common/__init__.pyindex 8a924db..66f9ecf 100644--- a/scripts/_common/__init__.py+++ b/scripts/_common/__init__.py@@ -59,7 +59,7 @@ from _common.runner import (ffmpeg_version, flush_drawtext_textfiles, INSTALL_HINTS, install_signal_handlers, _is_ffmpeg, _limit_for,_odd_dimension_retry, _on_signal, _OutputLock, _pid_dead, place_output, PROBE_TIMEOUT, _progress_line,read_text_or_die, refuse_output_is_input, _remember_output, require_tool, run, run_analysis, _run_captured,- run_keeping_subtitles, run_tool, _run_with_progress, shell_quote, _SIGNALS_INSTALLED, _stage_existing_output,+ run_keeping_subtitles, run_tool, _run_with_progress, shell_quote, sibling_temp, _SIGNALS_INSTALLED, _stage_existing_output,STATE, _timed_out, _unwatch, _watch, X264_PRESETS)from _common.emit import (@@ -68,7 +68,7 @@ from _common.emit import ()from _common.probe import (analyze_levels, _aspect_string, _bit_depth, decode_pcm_mono, detect_scenes, detect_silences, fingerprint,- _fraction, keyframes_near, SCORE_RE, SIL_RE, decode_gray_frames,+ _fraction, keyframes_near, classify_frame_timing, measure_frame_timing, SCORE_RE, SIL_RE, decode_gray_frames,measured_level_dbfs, AUDIO_MEDIA_EXT, MEDIA_EXT, _output_failed, probe, rms_envelope, _to_float, _to_int, verify_output)from _common.decision import (@@ -83,7 +83,7 @@ from _common.decision import (_onset_strength, _pick_onsets, _autocorrelation_peak, _grid_score,brand_states_font, cfr_args, concat_list_line, db_to_linear, default_output, encoder_args, escape_filter_path,fmt_secs, fmt_smpte_time, fmt_srt_time, frame_size, is_audio_output, load_brand, MissingFpsError, pad_filters, parse_time,- signed_time_arg, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw+ signed_time_arg, source_codec_video_args, SVT_PRESET, time_arg, video_args, x264_args, _x264_raw)from _common.asr import (ASR_ENGINES, ASR_INSTALL_HINT, _asr_run, die_no_engine, parse_srt, transcribe, _transcribe_in,@@ -200,7 +200,7 @@ __all__ = ["font_family_for_script", "font_family_of_file", "FONT_FLAG_HINT", "font_for_script", "FONT_INSTALL_HINT","fonts_dir_covers_script", "_fraction", "has_emoji", "info", "INSTALL_HINTS", "install_signal_handlers","is_audio_output", "_is_emoji_base", "_is_emoji_char", "_is_ffmpeg", "_is_mark", "_KEYCAP", "_KEYCAP_BASES",- "keyframes_near", "LANGUAGE_NAMES", "LATIN_EM", "LEADING_VOWELS", "_libass_color_probe", "_limit_for",+ "keyframes_near", "classify_frame_timing", "measure_frame_timing", "LANGUAGE_NAMES", "LATIN_EM", "LEADING_VOWELS", "_libass_color_probe", "_limit_for","load_brand", "measured_level_dbfs", "AUDIO_MEDIA_EXT", "MEDIA_EXT", "MissingFpsError", "needs_shaping", "NO_SPACE_SCRIPTS","_odd_dimension_retry", "_on_signal", "_output_failed", "_OutputLock", "pad_filters", "parse_time", "_pid_dead","place_output", "_plan_at_exit", "_plan_inputs", "_PLAN_STRIP", "PLAN_VERSION", "PREFERRED_FAMILIES",@@ -209,10 +209,10 @@ __all__ = ["decode_gray_frames", "frame_flow", "label_shot_flow", "MOTION_GRID", "MOTION_SEARCH", "MOTION_STATIC_PX", "MOTION_PAN_SPREAD","_run_captured", "run_keeping_subtitles", "run_tool", "_run_with_progress", "_SCRIPT_FONT_CACHE","_script_font_entry", "script_font_for_text", "script_font_status", "_script_font_uncached", "_SCRIPT_RANGES",- "SCRIPTS", "_sdr_bt709", "_set_current_ctx", "_SHAPING_BUILD_CACHE", "SHAPING_SCRIPTS", "shell_quote",+ "SCRIPTS", "_sdr_bt709", "_set_current_ctx", "_SHAPING_BUILD_CACHE", "SHAPING_SCRIPTS", "shell_quote", "sibling_temp","_SIGNALS_INSTALLED", "signed_time_arg", "_stage_existing_output", "STATE", "SVT_PRESET", "text_width_em","time_arg", "_timed_out", "_to_float", "_to_int", "_unwatch", "validate_color", "verify_output",- "video_args", "_VS15", "_VS16", "_watch", "WINDOWS_FONTS", "write_plan", "x264_args", "X264_PRESETS",+ "source_codec_video_args", "video_args", "_VS15", "_VS16", "_watch", "WINDOWS_FONTS", "write_plan", "x264_args", "X264_PRESETS","_x264_raw", "_ZWJ","ASR_ENGINES", "ASR_INSTALL_HINT", "_asr_run", "die_no_engine", "parse_srt", "transcribe","_transcribe_in", "transcribe_words", "_words_from_openai_whisper_json",diff --git a/scripts/_common/decision.py b/scripts/_common/decision.pyindex cb6e6c7..69e4dae 100644--- a/scripts/_common/decision.py+++ b/scripts/_common/decision.py@@ -478,6 +478,19 @@ def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medreturn _maybe_hw("hevc", crf, meta, True, _x265_hdr_default(v, crf, preset))+def source_codec_video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium",+ keep_hevc: bool = False) -> List[str]:+ """video_args(), except that with `keep_hevc` (cut.py --keep-hevc) an SDR HEVC source re-encodes+ to HEVC (8-bit, BT.709-tagged, on VideoToolbox when --hw asks) instead of H.264: a cut is a trim,+ so a re-encoded segment can come out in the codec the source (and any copied segment beside it)+ is in. Opt-in within 2.x, where an SDR re-encode stays x264 unless asked. An HDR or BT.2020+ source always takes video_args()'s Main10 line, and --codec always wins."""+ v = (meta or {}).get("video") or {}+ if keep_hevc and not STATE.codec and v.get("codec") == "hevc" and not v.get("bt2020_or_hdr"):+ return encoder_args("hevc", crf, preset, meta)+ return video_args(meta, crf, preset)++def _x265_hdr_default(v: Dict[str, Any], crf: int, preset: str) -> List[str]:cs = v.get("color_space") or "bt2020nc"prim = v.get("color_primaries") or "bt2020"diff --git a/scripts/_common/probe.py b/scripts/_common/probe.pyindex cb10c41..68707a4 100644--- a/scripts/_common/probe.py+++ b/scripts/_common/probe.py@@ -9,6 +9,7 @@ import jsonimport mathimport osimport re+import statisticsfrom fractions import Fractionfrom typing import Any, Dict, List, Optional, Sequence, Tuplefrom _common.emit import die@@ -285,6 +286,9 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:"nb_frames": _to_int(video.get("nb_frames")),# the stream's own length (a container's also counts audio priming and a longer track)"duration": _to_float(video.get("duration")),+ # where the stream starts; a video stream that starts after its audio (or the reverse)+ # is how a lossless cut's A/V skew shows up+ "start_time": _to_float(video.get("start_time")),"bitrate": _to_int(video.get("bit_rate")),}if audio:@@ -295,6 +299,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:"sample_rate": _to_int(audio.get("sample_rate")),"bitrate": _to_int(audio.get("bit_rate")),"duration": _to_float(audio.get("duration")),+ "start_time": _to_float(audio.get("start_time")),}# every audio stream in file order: index n here is `-map 0:a:n` (audio.py --audio-stream n)out["audio_streams"] = [{@@ -343,6 +348,93 @@ def keyframes_near(path: str, t: float, window: float = 5.0) -> List[float]:return sorted(set(out))+# frame timing: is a stream's frame rate really variable? (cut.py's VFR guard)+TIMING_WINDOWS = 5 # sampled windows per file, fewer on a short one+TIMING_WINDOW_SECONDS = 6+TIMING_MIN_DELTAS = 20 # fewer measured intervals than this is no evidence either way+++def complete_pts(packets: Sequence[Dict[str, Any]]) -> List[Any]:+ """The pts of `packets` (as read, in decode order) whose frames are all there: those at or+ before the last dts read. A read that stops just after a frame stored ahead of the B-frames+ shown before it has missed those B-frames, and their gap would read as a dropped frame; every+ frame shown by the last dts was decoded by then, so it was read. (FFmpeg 9.0's interval reads+ measured whole on MP4; this keeps a demuxer that stops elsewhere from faking VFR.)"""+ dts = [p["dts"] for p in packets if isinstance(p.get("dts"), int)]+ pts = [p.get("pts") for p in packets]+ return pts if not dts else [t for t in pts if isinstance(t, int) and t <= max(dts)]+++def classify_frame_timing(windows: Sequence[Sequence[Any]], time_base: Any) -> Dict[str, Any]:+ """Whether the frame timing in sampled windows is constant. `windows` are lists of pts in+ `time_base` ticks, the first starting at the file's first packet.++ Each window's pts are sorted (decode order stores B-frames out of sequence) and differenced,+ with repeats and missing values dropped. The file-start window also drops its first interval:+ an edit list or encoder priming can stretch it without the frame rate being variable.+ `sampled_cfr` needs every interval within one tick (at least 1 ms) of its window's median and+ the window medians to agree, so a single dropped or irregular frame is `vfr`. The tolerance+ never exceeds half a frame: a tick that coarse (AVI's 1/fps) cannot round an interval, and one+ tick of slack there would pass a dropped frame. Fewer than+ TIMING_MIN_DELTAS intervals is `inconclusive`. What happens between the windows is not seen."""+ result: Dict[str, Any] = {"measured": "inconclusive", "windows": len(windows), "deltas": 0}+ tick = _fraction(str(time_base)) if time_base else None+ if not tick or tick <= 0:+ return result+ per_window: List[List[float]] = []+ for i, pts in enumerate(windows):+ vals = sorted(float(p) for p in pts if isinstance(p, (int, float)) and math.isfinite(p))+ deltas = [(b - a) * float(tick) for a, b in zip(vals, vals[1:]) if b != a]+ per_window.append(deltas[1:] if i == 0 else deltas)+ per_window = [d for d in per_window if d]+ result["deltas"] = sum(len(d) for d in per_window)+ if result["deltas"] < TIMING_MIN_DELTAS:+ return result+ medians = [statistics.median(d) for d in per_window]+ tol = min(max(0.001, float(tick) + 1e-6), min(medians) / 2)+ steady = all(abs(x - m) <= tol for d, m in zip(per_window, medians) for x in d)+ result["measured"] = "sampled_cfr" if steady and max(medians) - min(medians) <= tol else "vfr"+ return result+++def timing_window_starts(duration: float, start: float = 0.0) -> List[float]:+ """Up to TIMING_WINDOWS non-overlapping window starts spread over the file, the first on its+ first packet. -read_intervals takes timestamps, so a file that starts at 10 s is read from 10."""+ n = max(1, min(TIMING_WINDOWS, int((duration or 0.0) // TIMING_WINDOW_SECONDS)))+ span = (duration or 0.0) - TIMING_WINDOW_SECONDS+ return [round(start + (span * i / (n - 1) if n > 1 else 0.0), 3) for i in range(n)]+++def measure_frame_timing(path: str, duration: Optional[float], start: float = 0.0) -> Dict[str, Any]:+ """classify_frame_timing over sampled windows of `path`'s first video stream that is not cover+ art (probe()'s choice): one packet-only ffprobe per window, no decoding. An interval read seeks+ back to the keyframe before its start and, given a relative end, ends that far past the+ keyframe -- on a long GOP every window read the file's first seconds -- so each window names+ its absolute end and keeps only the frames from its start. The first window does not seek at+ all: a seek to the start of an edit-listed MP4 skips its keyframe, stored before the start+ with a negative pts, and loses the frames that depend on it (seeks near the start behave+ erratically, so no margin is safe). The cost: a file whose video begins long after its first+ packet is demuxed, not decoded, up to the video start. An ffprobe failure is `inconclusive`."""+ ffprobe = require_tool("ffprobe")+ windows: List[List[Any]] = []+ time_base = None+ for i, t in enumerate(timing_window_starts(duration or 0.0, start)):+ proc = run([ffprobe, "-v", "error", "-select_streams", "V:0", "-show_packets",+ "-show_entries", "packet=pts,dts:stream=time_base", "-of", "json",+ "-read_intervals", f"{t if i else ''}%{t + TIMING_WINDOW_SECONDS:.3f}", path], quiet=True, check=False)+ try:+ doc = json.loads(proc.stdout) if proc.returncode == 0 else None+ except ValueError:+ doc = None+ if not isinstance(doc, dict):+ return {"measured": "inconclusive", "windows": len(windows), "deltas": 0}+ time_base = time_base or ((doc.get("streams") or [{}])[0] or {}).get("time_base")+ tick = float(_fraction(str(time_base)) or 0) if time_base else 0.0+ windows.append([p for p in complete_pts(doc.get("packets") or [])+ if isinstance(p, int) and p * tick >= t - 1e-6])+ return classify_frame_timing(windows, time_base)++def measured_level_dbfs(path: str, seconds: Optional[float] = 120.0,audio_stream: Optional[int] = None) -> Optional[Dict[str, float]]:"""Mean and peak level of the first `seconds` of audio (volumedetect), in dBFS; None if unmeasurable.diff --git a/scripts/_common/runner.py b/scripts/_common/runner.pyindex 0edc5d4..3862f53 100644--- a/scripts/_common/runner.py+++ b/scripts/_common/runner.py@@ -1158,11 +1158,17 @@ def ffmpeg_base(overwrite: bool = True) -> List[str]:return cmd-def place_output(src: str, dst: str) -> None:+def place_output(src: str, dst: str, move: bool = False) -> None:"""Deliver an already-rendered file to `dst` under the same rules as an ffmpeg output:- the path is checked, an existing file is only replaced through a sibling temp so a- failed copy never costs the caller what was there, and the result is remembered as ours.- render.py's final `copyfile()` used to bypass all three."""+ the path is checked, the output's lock is held (as run() holds it for an ffmpeg write), an+ existing file is only replaced through a sibling temp so a failed copy never costs the+ caller what was there, and the result is remembered as ours. render.py's final+ `copyfile()` used to bypass all of them.++ `move`: `src` is a temp file the caller wrote next to `dst` (sibling_temp), renamed into place+ with os.replace() under the lock instead of copied -- a checked `cut.py --segments` join was+ copied whole, about 2 s for 240 MB. A rename that fails (another filesystem) falls back to+ the copy."""import shutilcmd = ["ffmpeg", dst]_check_output_path(cmd)@@ -1170,18 +1176,35 @@ def place_output(src: str, dst: str) -> None:d, base = os.path.split(dst)stem, ext = os.path.splitext(base)tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")- try:- shutil.copyfile(src, tmp)- os.replace(tmp, dst)- except OSError as e:+ with _OutputLock(dst):+ if move:+ try:+ os.replace(src, dst)+ _remember_output(cmd)+ return+ except OSError:+ passtry:- os.remove(tmp)- except OSError:- pass- die(f"could not place {dst}: {e}", kind="output")+ shutil.copyfile(src, tmp)+ os.replace(tmp, dst)+ except OSError as e:+ try:+ os.remove(tmp)+ except OSError:+ pass+ die(f"could not place {dst}: {e}", kind="output")_remember_output(cmd)+def sibling_temp(dst: str, tag: str) -> str:+ """A hidden path next to `dst`, with its extension (the muxer is chosen by it), for a file+ place_output(..., move=True) renames into place: same directory, so the rename never+ crosses a filesystem."""+ d, base = os.path.split(dst)+ stem, ext = os.path.splitext(base)+ return os.path.join(d, f".{stem}.ffskill-{tag}-{os.getpid()}{ext}")++_DRAWTEXT_TMPDIR: "Optional[str]" = Nonediff --git a/scripts/_contract.py b/scripts/_contract.pyindex f90ab43..4a4c33c 100644--- a/scripts/_contract.py+++ b/scripts/_contract.py@@ -78,7 +78,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {required=["ffprobe"], optional=[{"capability": "ffmpeg", "when": "--analyze"}, {"capability": "filter:signalstats", "when": "--analyze"}],video_required=False, audio_only=True, visual=False, verify=[], produces_artifact=False, idempotency="bit_exact", deterministic=True),"cut": dict(role="execution", inputs=["video or audio asset"], outputs=["cut video/audio artifact (same container family, or audio extracted when -o has an audio extension)"],- required=FF, optional=[{"capability": X264, "when": "re-encode: --accurate, VFR source, or a keyframe farther than --tolerance"}, HDR_X265, {"capability": AAC, "when": "re-encode of a video container"}] + AUDIO_OUT,+ required=FF, optional=[{"capability": X264, "when": "re-encode: --accurate, VFR source, or a keyframe farther than --tolerance"},+ dict(HDR_X265, when=HDR_X265["when"] + "; with --keep-hevc on an HEVC source"), {"capability": AAC, "when": "re-encode of a video container"}] + AUDIO_OUT,video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),"fit": dict(role="execution", inputs=["video asset"], outputs=["video artifact at the requested duration / aspect / fps"],required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:minterpolate", "when": "--smooth interpolate"},@@ -254,7 +255,7 @@ DRY_RUN_NOTES = {# of the original audio codec never happens on those tools.REENCODE_META: Dict[str, Dict[str, str]] = {"probe": dict(video="never", audio="never", note="analysis only, no artifact"),- "cut": dict(video="conditional", audio="conditional", note="lossless -c copy preferred; re-encodes on --accurate, a VFR source, or a keyframe snap past --tolerance (see cut.py --json: mode, keyframe_snapped)"),+ "cut": dict(video="conditional", audio="conditional", note="lossless -c copy preferred; re-encodes on --accurate, --codec, a VFR source (--vfr-guard), a keyframe snap past --tolerance, or a --segments join the parts cannot stream-copy (see cut.py --json: mode, reencode_reason, keyframe_snapped)"),"fit": dict(video="always", audio="always", note="always re-encodes to AAC when audio is present, even if only --fps or --aspect was asked for"),"crop": dict(video="always", audio="always", note="the crop filter always forces a re-encode of both streams"),"deinterlace": dict(video="always", audio="always", note="the yadif filter always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),@@ -453,7 +454,10 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[strelif name == "verify":extra = {"report": {"type": ["string", "null"]}, "files": {"type": "array"}, "failed": {"type": "integer"}, "total": {"type": "integer"}}elif name == "batch":- extra = {"results": {"type": "array"}, "processed": {"type": "integer"}, "total": {"type": "integer"}}+ extra = {"results": {"type": "array", "description": "one row per input; a row whose recipe ran cut.py carries cut_reencoded (each cut.py call's reencoded) and cut_reencode_reasons (each reason those calls named, once per call)"},+ "processed": {"type": "integer"}, "total": {"type": "integer"},+ "cut_stream_copy": {"type": ["object", "null"], "description": "cut.py calls across the folder: {calls, stream_copy, reencoded, stream_copy_rate}; null when no cut.py step ran"},+ "cut_reencode_reasons": {"type": ["object", "null"], "description": "how many cut.py calls named each reencode_reason ({} when none re-encoded); a re-encoded call whose row came from a cache an earlier 2.x batch wrote, which recorded no reasons, counts as unknown; null when no cut.py step ran"}}elif name == "report":extra = {"report": {"type": "string"}, "check": {"type": ["object", "null"]}}elif name == "export":@@ -475,9 +479,24 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[strextra = {"expected_duration": {"type": "number", "description": "seconds requested"},"duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},"precision": {"enum": ["packet", "sample", "codec_frame", "frame"],- "description": "packet: stream copy on a packet/keyframe boundary; sample: decoded audio trimmed to the sample, lossless output; codec_frame: sample-trimmed then framed by a lossy encoder (priming delay adds to the length); frame: re-encoded video"},+ "description": "the whole run's: packet only when nothing re-encoded, the --segments join included (stream copy on a packet/keyframe boundary); sample: decoded audio trimmed to the sample, lossless output; codec_frame: sample-trimmed then framed by a lossy encoder (priming delay adds to the length); frame: re-encoded video"},+ "least_exact_precision": {"enum": ["packet", "sample", "codec_frame", "frame"],+ "description": "the least exact segment's precision (the order packet, codec_frame, frame, sample); differs from precision only for an audio-only --segments join of copied and re-encoded parts"},+ "keyframe_snapped": {"type": "boolean", "description": "precision is packet: the run is a stream copy end to end, which lands on keyframes and packets. Whether a copied start really moved is start_snapped"},+ "start_snapped": {"type": ["boolean", "null"], "description": "measured: true when a copied segment's picture starts more than one frame from its requested start (the keyframe the copy's seek lands on, measured with the seek ffmpeg makes); false when every start is where asked (an MP4 edit list hides the pre-roll, the start is a keyframe, an audio-only copy, or everything re-encoded); null when a copied start was not measured (--dry-run)"},"reencoded": {"type": "boolean"},- "lossless_alternative": {"type": ["string", "null"], "description": "when a lossless cut re-encoded because of the keyframe snap: the --start that would stream-copy instead, and how far it is from the request"}}+ "reencode_reason": {"type": "array", "items": {"enum": ["requested", "codec", "vfr", "vfr_inconclusive", "pcm_container", "copy_failed", "tolerance", "concat_fallback"]},+ "description": "why anything was re-encoded, distinct values in first-seen order ([] when nothing was): requested (--accurate), codec (--codec), vfr (a variable-frame-rate source forced --accurate), vfr_inconclusive (its frame timing could not be measured), pcm_container (compressed audio into a .wav), copy_failed (the stream copy errored), tolerance (a keyframe snap past --tolerance), concat_fallback (--segments parts could not be joined by stream copy)"},+ "segment_precision": {"type": ["array", "null"], "items": {"enum": ["packet", "sample", "codec_frame", "frame"]},+ "description": "--segments only: each segment's precision in order; least_exact_precision is the least exact of them (null for a single segment)"},+ "edit_list": {"type": "boolean", "description": "--edit-list on a single MP4/MOV stream copy: it kept the edit list it wrote instead of -avoid_negative_ts make_zero, so the keyframe's pre-roll is stored but hidden and the picture and the sound start at the requested time (false for every other path, the default included)"},+ "stored_preroll_seconds": {"type": ["number", "null"], "description": "with edit_list: seconds decoded from the keyframe the copy's seek lands on up to the requested start and hidden by the edit list (a player that ignores edit lists shows them); null otherwise"},+ "av_start_skew_seconds": {"type": ["number", "null"], "description": "the output's audio start minus its video start (null when either is missing or under --dry-run); reported, never repaired: on a stream copy only, a warning in notes when it is more than max(2 frames, 0.1 s) away from the source's own skew where the copy's picture starts (the keyframe it began from; the requested start under --edit-list), naming --accurate (and --edit-list for a single MP4/MOV copy whose start snapped)"},+ "notes": {"type": "array", "items": {"type": "string"}, "description": "stored pre-roll behind an --edit-list edit list, or an --edit-list copy judged by its video; an A/V start skew with its remedies; a source the default --vfr-guard average took for VFR whose sampled timing is constant (naming --vfr-guard sampled), or a sampled measurement that forced or (--vfr-guard off) skipped a re-encode; a --segments segment ended with the video, or held on its last frame for its sound; a --segments join re-cut because the source uses open GOPs, because a later B-frame .mp4/.mov segment starts between keyframes, or because its join check failed"},+ "vfr_check": {"type": "object", "description": "the sampled frame timing of a video input that could still stream-copy: under --vfr-guard average (the default) only when its nominal and average frame rates differ, which re-encodes it (reason vfr) whatever the sample says; under sampled or off on every such input (absent for audio-only input or output, --accurate, --codec, or a --dry-run input a plan has not written yet): {heuristic: true, measured, method: \"sampled\", guard, windows, deltas}. measured is sampled_cfr (every packet interval in up to five 6 s windows within a tick, at least 1 ms and at most half a frame, of its window's median, and the windows agree; the file-start window's first interval is ignored), vfr (under sampled, forces a re-encode, reason vfr) or inconclusive (fewer than 20 intervals or ffprobe failed; under sampled, reason vfr_inconclusive). --vfr-guard off keeps the copy either way, with a note. Variable timing between the windows is not seen"},+ "lossless_alternative": {"type": ["string", "null"], "description": "when a lossless cut re-encoded because of the keyframe snap: the --start that would stream-copy instead, and how far it is from the request"},+ "join_check": {"type": ["object", "null"], "description": "--segments video stream-copy join: the written file measured by demuxing, {packets, expected_packets, max_step_seconds, audio_offset_ms, audio_parts_checked, ok}. expected_packets counts the source's video packets from each part's start keyframe to its end (or the end of the video); max_step_seconds is the largest presentation step (null when vfr_check measured anything but sampled_cfr, e.g. a --vfr-guard off join of variable timing, which checks the count only), and each step at a join must be the step its parts predict within 1 ms; audio_offset_ms is, per part, its sound's shift minus its picture's (+ = sound late) from audio packets matched by CRC32 to the source stream shaped like the joined audio (FFmpeg's default selection may copy one other than a:0; an MPEG-TS source's AAC is hashed without its ADTS headers) (null for a part with no unique match, e.g. digital silence; null as a whole when the source has no audio or the video check failed), and audio_parts_checked counts the measured parts; ok is the conjunction (counts, steps, every measured part within 5 ms), and false means the join was re-cut from the source (concat_fallback) and this is the failed measurement. null for a single segment, audio, --dry-run, --accurate/--codec/a forced re-encode, a segment that re-encoded, or a join that fell back before a copy join was attempted (open GOPs, a later B-frame segment starting between keyframes, parts that differ, a concat error)"},+ "segment_end_snap_seconds": {"type": ["array", "null"], "items": {"type": ["number", "null"]}, "description": "--segments stream-copy join: per segment, the signed seconds its end moved to the keyframe the copied part stops at (the first keyframe at or after the requested end, never an earlier one; null for a part that runs to the end of the video, a part of a source with no B-frames, which is cut to its requested end as in every 2.x release, or a Matroska/MPEG-TS part, which is not snapped). null as a whole unless the output is those copied parts: a single segment, audio, --dry-run, or any re-encode or fallback"}}elif name == "join":extra = {"mode": {"enum": ["video", "audio"]}, "clips": {"type": "integer"}, "transition": {"type": "string"},"expected_duration": {"type": ["number", "null"], "description": "clip lengths minus the transitions; null under --dry-run while an input is pending (its length is unknown)"},diff --git a/scripts/batch.py b/scripts/batch.pyindex 3a254c7..81117e2 100755--- a/scripts/batch.py+++ b/scripts/batch.py@@ -173,6 +173,7 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,ok, _doc = run_step(["render.py", str(pj)], budget())step_docs = [("render", _doc)]cut_reencoded: List[bool] = []+ cut_reasons: List[str] = []else:steps = recipe.get("steps") or []if not steps:@@ -181,18 +182,20 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,ok = Truecut_reencoded = []step_docs = []+ cut_reasons = []for i, step in enumerate(steps):last = i == len(steps) - 1out = str(final) if last else str(work / f"{src.stem}_step{i}.{'mp4' if src.suffix.lower() not in ('.wav', '.mp3', '.m4a', '.flac') else src.suffix.lstrip('.')}")argv = [str(a).replace("{in}", cur).replace("{out}", out) for a in step]step_ok, doc = run_step(argv, budget())step_docs.append((Path(str(argv[0])).stem if argv else "step", doc))- # only cut.py's own doc carries `reencoded` -- true if ANY range this call cut needed- # the tolerance-triggered hybrid re-encode fallback (cut.py ORs its per-segment results- # into one top-level field; it doesn't report which range, so this is per cut.py call,- # not per --segments range).+ # only cut.py's own doc carries `reencoded` -- true if ANY range this call cut (or its+ # --segments join) re-encoded, for the reasons in its `reencode_reason` (distinct per+ # call, so cut_reencode_reasons lists each reason once per cut.py call that named it).+ # Per cut.py call, not per --segments range.if step_ok and argv and argv[0] == "cut.py" and isinstance(doc, dict) and "reencoded" in doc:cut_reencoded.append(bool(doc["reencoded"]))+ cut_reasons.extend(r for r in (doc.get("reencode_reason") or []) if isinstance(r, str))if not step_ok:ok = Falsebreak@@ -200,6 +203,7 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,result: Dict[str, Any] = {"file": str(src), "output": str(final), "ok": ok, "seconds": round(time.time() - t0, 1)}if cut_reencoded:result["cut_reencoded"] = cut_reencoded+ result["cut_reencode_reasons"] = cut_reasons# the encoder each item really ran and its GPU facts (--hw / FFMPEG_SKILL_HW: on VideoToolbox,# fell back and why): this process encodes nothing itself, so its top-level hw.used is nullresult.update(steps_encoder_report(step_docs))@@ -563,23 +567,36 @@ def main() -> int:die(f"{len(results) - done} of {len(results)} items failed: {', '.join(failed_files[:5])}" + (" ..." if len(failed_files) > 5 else ""),kind="verification", output=None, dry_run=STATE.dry_run, results=results, processed=done, total=len(results))# cut.py's own `reencoded`, rolled up across every cut.py step this batch ran: how much of the- # folder landed on the fast lossless path (mode "copy") vs fell back to the tolerance-triggered- # hybrid re-encode on at least one range -- purely a function of the sources' keyframe placement- # relative to each cut point, not something a single run can predict, so it's worth reporting- # after the fact rather than not at all. Per cut.py call, not per --segments range: cut.py ORs- # its own per-segment results into one top-level field and doesn't say which range needed it.+ # folder landed on the fast lossless path (mode "copy") vs re-encoded on at least one range.+ # Keyframe placement, VFR sources, --accurate/--codec in the recipe and --segments joins all+ # cause it, so the summary counts cut.py's own `reencode_reason` values rather than guessing+ # one cause. Per cut.py call, not per --segments range.all_cuts = [r for res in results for r in (res.get("cut_reencoded") or [])]cut_summary = None+ # how many cut.py calls named each reason, beside cut_stream_copy (whose shape is 2.x's,+ # unchanged); null when no cut.py step ran+ reasons: Optional[Dict[str, int]] = Noneif all_cuts:copied = sum(1 for r in all_cuts if not r)cut_summary = {"calls": len(all_cuts), "stream_copy": copied, "reencoded": len(all_cuts) - copied,"stream_copy_rate": round(copied / len(all_cuts), 3)}+ reasons = {}+ for res in results:+ if "cut_reencode_reasons" not in res:+ # a row from a cache an earlier 2.x batch wrote: it says which calls re-encoded,+ # not why, so they count as "unknown" rather than leaving {} ("none re-encoded")+ unknown = sum(1 for r in res.get("cut_reencoded") or [] if r)+ if unknown:+ reasons["unknown"] = reasons.get("unknown", 0) + unknown+ for r in res.get("cut_reencode_reasons") or []:+ reasons[r] = reasons.get(r, 0) + 1+ why = (" (reencode_reason: " + ", ".join(f"{k} x{v}" for k, v in reasons.items()) + ")") if reasons else ""info(f"cut.py: {copied}/{len(all_cuts)} call(s) stayed fully lossless stream-copy "- f"({cut_summary['stream_copy_rate']:.0%}), {len(all_cuts) - copied} fell back to hybrid re-encode on at least one range")+ f"({cut_summary['stream_copy_rate']:.0%}), {len(all_cuts) - copied} re-encoded a range or its --segments join{why}")emit(None, results=results, processed=done, total=len(results),jobs=jobs, jobs_requested=requested, wall_seconds=round(time.time() - started, 1),item_seconds_total=round(sum(float(r.get("seconds") or 0) for r in results), 1),- timed_out=timed_out["hit"], cut_stream_copy=cut_summary)+ timed_out=timed_out["hit"], cut_stream_copy=cut_summary, cut_reencode_reasons=reasons)return 0diff --git a/scripts/cut.py b/scripts/cut.pyindex cbaf517..13fffd2 100755--- a/scripts/cut.py+++ b/scripts/cut.py@@ -3,7 +3,8 @@Lossless stream copy (-c copy) is preferred. Cuts snap to keyframes in thatmode, so if frame accuracy matters pass --accurate to re-encode. Multiple-segments are cut individually and concatenated with the concat demuxer.+segments are cut individually and joined by stream copy when the parts match in their codec+parameters; otherwise every segment is re-cut from the source into one re-encode.Audio: a stream copy lands on a packet boundary (about 21 ms for AAC, onedemuxer block for WAV); --accurate decodes and trims to the sample. The output@@ -12,11 +13,25 @@ WAV), -o out.m4a writes AAC; an audio extension on a video input drops thepicture (mp4 -> wav extraction). The result reports `precision`(packet / sample / codec_frame / frame) and the measured duration error, plus`mode` (copy / accurate / hybrid -- "hybrid" means a lossless cut silently-re-encoded because the keyframe snap exceeded --tolerance), `keyframe_snapped`,-`requested_start`/`requested_end` (or `requested_segments` for --segments),+re-encoded because the keyframe snap exceeded --tolerance), `keyframe_snapped`+(a stream copy end to end), `start_snapped` (measured: a copied start moved past a frame),+`reencode_reason`, `requested_start`/`requested_end` (or `requested_segments` for --segments),`requested_duration`, `output_duration` and `duration_delta_seconds` -- so acaller never has to trust "it probably cut where I asked" on faith.+A single-segment .mp4/.mov copy shifts its timestamps to zero (-avoid_negative_ts+make_zero), so the picture starts at the keyframe; --edit-list keeps the MP4 edit+list instead, which hides the keyframe's pre-roll so the picture starts at --start.++A re-encode uses x264 for an SDR source and x265 Main10 for an HDR or BT.2020 one, as every+editing tool does; --keep-hevc re-encodes an SDR HEVC source as HEVC (x265 8-bit BT.709, or+VideoToolbox under --hw), so a trimmed phone clip keeps its codec. --codec overrides both.++A source whose nominal and average frame rates differ is taken for variable-frame-rate and+re-encoded, as --accurate (--vfr-guard average, the default); its sampled packet timing is+reported in `vfr_check`. --vfr-guard sampled re-encodes only when that sampled timing is+variable or too short to judge, and --vfr-guard off keeps the copy with a note.+Examples:python3 cut.py input.mp4 --start 00:00:10 --end 00:00:25python3 cut.py input.mp4 --segments 0:05-0:12,1:00-1:20 -o highlights.mp4@@ -25,20 +40,25 @@ Examples:python3 cut.py talk.mp4 --start 1:00 --end 2:00 -o part.wav # audio extraction"""import argparse+import contextlibimport jsonimport osimport sysimport tempfile+import zlibfrom typing import List, Tuplefrom _common import (beat_grid, snap_points, decode_pcm_mono, rms_envelope, BEAT_MIN_CONFIDENCE)-from _common import video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, time_arg, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, refuse_output_is_input, fmt_secs+from _common import require_tool+from _common import sibling_temp, source_codec_video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, time_arg, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, place_output, refuse_output_is_input, fmt_secs, measure_frame_timing, dry_run_input_pending# outputs whose re-encode dropped a subtitle/data stream (reported as dropped_non_av_streams)DROPPED_STREAMS: List[str] = []# keyframe timestamps found next to a requested cut that the tolerance turned into a re-encode# (reported so the caller can choose a lossless cut at one of them next time)NEAREST_KEYFRAMES: list = []+# --keep-hevc: an SDR HEVC source re-encodes as HEVC instead of H.264 (set by main())+KEEP_HEVC = Falsedef _t(value: str, fps, flag: str = "--segments") -> float:@@ -71,7 +91,11 @@ def encode_args(meta: dict, dst: str, crf: int, preset: str) -> List[str]:the audio extension names (PCM for .wav, FLAC, MP3, AAC...) with no video stream."""if is_audio_output(dst) or not meta.get("video"):return ["-vn"] + audio_codec_for(dst)- return video_args(meta, crf, preset) + cfr_args(meta) + aac_args()+ return video_encode_args(meta, crf, preset) + aac_args()+++def video_encode_args(meta: dict, crf: int, preset: str) -> List[str]:+ return source_codec_video_args(meta, crf, preset, keep_hevc=KEEP_HEVC) + cfr_args(meta)def copy_args(meta: dict, dst: str) -> List[str]:@@ -104,20 +128,695 @@ def precision_of(meta: dict, dst: str, reencoded: bool) -> str:return "frame"-def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: int, preset: str, tolerance: float = 0.5, meta: dict = None) -> bool:- """Cut one segment. Returns True if the result was re-encoded."""+# The order `precision` values rank in, least exact first. It is a conservative order for this+# tool's segments (all cut from one source into one container), not a universal scale.+PRECISION_ORDER = ("packet", "codec_frame", "frame", "sample")+++def least_exact(precisions: List[str]) -> str:+ return min(precisions, key=PRECISION_ORDER.index)+++def report_precision(meta: dict, dst: str, reencoded: bool, outcomes: List[dict]) -> dict:+ """The run's precision keys from its segments' outcomes.++ precision main's formula, unchanged: precision_of() for the whole run, so `packet` only+ when nothing re-encoded (the join included)+ keyframe_snapped precision == "packet": the run is a stream copy end to end, which lands on+ keyframes and packets. Kept with its 2.x meaning; whether a copied START+ really moved is start_snapped+ start_snapped measured: true when a copied segment's picture starts more than a frame from+ its requested start; false when every start is where asked (an edit list, a+ start on a keyframe, an audio-only copy's packet seek) or everything+ re-encoded; null when a copied start was not measured (--dry-run)+ least_exact_precision the least exact segment's precision; differs from `precision` only for+ an audio-only --segments join of copied and re-encoded parts (a video join+ re-cuts every segment when any part re-encodes)+ segment_precision each segment's, for --segments (null for one segment)"""+ precision = precision_of(meta, dst, reencoded)+ snaps = [o.get("start_snapped") for o in outcomes]+ if any(s is True for s in snaps):+ start_snapped = True+ elif any(s is None for s in snaps):+ start_snapped = None+ else:+ start_snapped = False+ return {"precision": precision, "keyframe_snapped": precision == "packet", "start_snapped": start_snapped,+ "least_exact_precision": least_exact([o["precision"] for o in outcomes]),+ "segment_precision": [o["precision"] for o in outcomes] if len(outcomes) > 1 else None}+++def _outcome(meta: dict, dst: str, reencoded: bool, reasons: List[str], **copy) -> dict:+ """One segment's outcome. start_snapped defaults to false: a re-encode starts where asked, and+ an audio-only copy seeks on the output side, to the packet; a video copy passes the measured+ value (copy_presentation), a --dry-run copy None."""+ out = {"reencoded": reencoded, "reasons": reasons, "precision": precision_of(meta, dst, reencoded),+ "start_snapped": False, "edit_list": False, "stored_preroll_seconds": None}+ out.update(copy)+ return out+++EDIT_LIST_EXTS = (".mp4", ".mov", ".m4v")+++def _with_notes(outcome: dict, notes: List[str]) -> dict:+ """An outcome with the notes of the attempt that led to it put first."""+ outcome["notes"] = list(notes) + list(outcome.get("notes") or [])+ return outcome+++_ORIGINS: dict = {}+++def file_origin(src: str) -> float:+ """The file's format start_time: the zero that -ss and segment times count from. Stream+ start_times are absolute, so subtract this to put them on the cut's clock. One probe per source."""+ if src not in _ORIGINS:+ proc = run([require_tool("ffprobe"), "-v", "error", "-show_entries", "format=start_time", "-of", "csv=p=0", src],+ quiet=True, check=False)+ try:+ _ORIGINS[src] = float((proc.stdout or "").strip() or 0.0)+ except ValueError:+ _ORIGINS[src] = 0.0+ return _ORIGINS[src]+++def source_skew(src: str, meta: dict, t: float) -> float:+ """How far the source's audio starts after its video at `t` on the cut's clock: a cut from+ `t` that keeps both streams where they were starts them this far apart (0 once both run)."""+ v, a = meta.get("video") or {}, meta.get("audio") or {}+ if v.get("start_time") is None or a.get("start_time") is None:+ return 0.0+ origin = file_origin(src)+ return max(a["start_time"] - origin, t) - max(v["start_time"] - origin, t)+++def video_end(src: str, meta: dict):+ """Where the video stream ends on the cut's clock (seconds from the file's start), or None when+ the stream's length is unknown."""+ v = meta.get("video") or {}+ if not v.get("duration"):+ return None+ return (v.get("start_time") or 0.0) + v["duration"] - file_origin(src)+++_SEEK_SHIFTS: dict = {}+# ffmpeg's dts heuristic: before a demuxer that does not seek by presentation time, an input -ss+# seeks this much earlier when a stream has a decode delay (B-frames); fftools ffmpeg_demux.c+DTS_HEURISTIC = 3.0 / 23+++def seek_shift(src: str) -> float:+ """How much earlier than `-ss t` ffmpeg's input seek asks the demuxer for: DTS_HEURISTIC for a+ demuxer that does not seek by pts (Matroska, MPEG-TS...) when a stream has a decode delay, 0+ for MP4/MOV (AVFMT_SEEK_TO_PTS) or a source with no delay. One probe per source."""+ if src not in _SEEK_SHIFTS:+ proc = run([require_tool("ffprobe"), "-v", "error", "-show_entries", "format=format_name:stream=has_b_frames",+ "-of", "json", src], quiet=True, check=False)+ try:+ doc = json.loads(proc.stdout or "") if proc.returncode == 0 else {}+ name = str((doc.get("format") or {}).get("format_name") or "")+ delay = any(int(st.get("has_b_frames") or 0) > 0 for st in doc.get("streams") or [])+ except (ValueError, TypeError, AttributeError):+ name, delay = "", False+ _SEEK_SHIFTS[src] = 0.0 if ("mov" in name.split(",") or not delay) else DTS_HEURISTIC+ return _SEEK_SHIFTS[src]+++_LANDINGS: dict = {}+++def seek_keyframe(src: str, t: float):+ """The keyframe a stream copy starting at `-ss t` begins from, as (pts, dts, first presented+ pts at or after t) in seconds on the cut's clock, or None when it cannot be read.++ Measured, not modelled: ffprobe -read_intervals seeks with the same avformat_seek_file call as+ ffmpeg's input -ss (to the file's start_time + t, less seek_shift()), and the copy starts at+ the first keyframe read after it, as ffmpeg drops the packets before it. A model ("the+ keyframe with the largest dts at or before t") was wrong both ways: the MP4 demuxer seeks+ over its raw decode times, ffprobe's dts plus the reorder delay, so on B-frame H.264 -ss 3.99+ landed on the keyframe at 2.0, not on the one at 4.0 (dts 3.933), while on a keyint-60 HEVC+ file -ss 9.9 began at the keyframe at 10.0 (dts 9.833). The read does not seek earlier than+ ffmpeg does: a seek before the file's start skips an edit-listed MP4's negative-pts keyframe.+ Cached on (src, t)."""+ key = (src, round(t, 6))+ if key in _LANDINGS:+ return _LANDINGS[key]+ origin = file_origin(src)+ target = origin + t - seek_shift(src)+ proc = run([require_tool("ffprobe"), "-v", "error", "-select_streams", "v:0", "-show_entries",+ "packet=pts_time,dts_time,flags", "-of", "json", "-read_intervals",+ f"{target:.6f}%{origin + t + 1.0:.6f}", src], quiet=True, check=False)+ try:+ packets = json.loads(proc.stdout or "")["packets"] if proc.returncode == 0 else []+ except (ValueError, KeyError, TypeError):+ packets = []+ landed, pts_all = None, []+ for p in packets if isinstance(packets, list) else []:+ try:+ pts = float(p["pts_time"]) - origin+ except (KeyError, TypeError, ValueError):+ continue+ if landed is None:+ if "K" not in str(p.get("flags", "")):+ continue # ffmpeg's copy drops what comes before the first keyframe+ try:+ landed = (pts, float(p.get("dts_time", p["pts_time"])) - origin)+ except (TypeError, ValueError):+ landed = (pts, pts)+ pts_all.append(pts)+ if landed is None:+ _LANDINGS[key] = None+ return None+ # the first picture an edit list starting at t presents: the first frame at or after t+ later = [x for x in pts_all if x >= t - 1e-6]+ _LANDINGS[key] = (landed[0], landed[1], min(later) if later else None)+ return _LANDINGS[key]+++def copy_presentation(t: float, key, edit_list: bool, fps) -> dict:+ """What a stream copy starting at `t` presents, from the keyframe it began at (seek_keyframe).+ With an MP4 edit list a keyframe at or before t is decoded but hidden (stored pre-roll) and the+ picture starts at t; a keyframe after t starts the picture late. Without one (Matroska, or a+ concat part cut with make_zero) the picture starts at the keyframe. start_snapped: the+ presented start is more than a frame from t (an unmeasured start counts as snapped)."""+ frame = 1.0 / fps if fps else 0.0+ if key is None:+ return {"start_snapped": True, "stored_preroll_seconds": None}+ k_pts, first = key[0], key[2]+ if first is None:+ # no packet at or after t in the probed window: where the picture starts is unmeasured+ return {"start_snapped": True, "stored_preroll_seconds": None}+ if edit_list and k_pts <= t + 1e-6:+ # hidden: the pictures decoded from the keyframe up to the first one presented+ return {"start_snapped": False, "stored_preroll_seconds": round(max(0.0, first - k_pts), 6)}+ return {"start_snapped": abs(k_pts - t) > frame + 1e-6, "stored_preroll_seconds": None}+++def av_skew(out_meta: dict, edit_list_remedy: bool = False, expected: float = 0.0):+ """(seconds audio starts after video, warning note or None); None when either is missing.+ A lossless cut can start its streams apart -- Core Media HEVC once gave 3.7 s of sound with no+ picture from a run that exited 0 -- so a skew more than max(2 frames, 0.1 s) away from+ `expected` (the source's own skew at the cut's start: a track that starts late there, by+ design, is not a defect of the cut) is named. It is reported, not repaired:+ `edit_list_remedy` (a single MP4/MOV copy whose start snapped, cut without --edit-list)+ names --edit-list as the lossless way to start both streams at --start."""+ v, a = out_meta.get("video") or {}, out_meta.get("audio") or {}+ if v.get("start_time") is None or a.get("start_time") is None:+ return None, None+ skew = round(a["start_time"] - v["start_time"], 6)+ fps = v.get("fps") or 0+ limit = max(2.0 / fps if fps else 0.0, 0.1)+ if abs(skew - expected) <= limit:+ return skew, None+ first = "audio" if skew > 0 else "video"+ return skew, (f"the {'video' if first == 'audio' else 'audio'} starts {abs(skew):.3f}s before the {first}"+ + (f" ({abs(expected):.3f}s in the source there)" if abs(expected) > 1e-3 else "")+ + ": a stream copy began on packets the two streams do not share; re-run with --accurate "+ "for a cut whose picture and sound start together"+ + (", or with --edit-list to keep the lossless copy and hide the keyframe's pre-roll"+ if edit_list_remedy else ""))+++_PACKETS: dict = {}+++def _packet_time(value):+ try:+ return float(value)+ except (TypeError, ValueError):+ return None+++class _Packets(list):+ """video_packets' result: (pts, dts, keyframe) in decode order, plus `breaks`, the indices of+ packets after which a read window ended before the end of the file (what follows is a later+ window, not the next packet), and `spans`, each window's (lo, hi) with the range of packets+ read in it."""+ breaks: frozenset = frozenset()+ spans: tuple = ()+++# video_packets reads [start - M, end + M] around each segment, M = max(PACKET_MARGIN, 2 x+# --tolerance), and widens M x4 up to PACKET_WIDENINGS times before reading the whole file+PACKET_MARGIN = 10.0+PACKET_WIDENINGS = 3+++def packet_windows(segments, margin: float, total=None) -> tuple:+ """The merged read windows around `segments`, as (lo, hi) on the cut's clock: lo None from the+ file's start (never a seek: a seek to it skips an edit-listed MP4's negative-pts keyframe, as+ measure_frame_timing found), hi None to its end (`total`, the media duration)."""+ spans = sorted((s - margin, e + margin) for s, e in segments)+ merged = []+ for lo, hi in spans:+ if merged and lo <= merged[-1][1]:+ merged[-1][1] = max(merged[-1][1], hi)+ else:+ merged.append([lo, hi])+ return tuple((None if lo <= 0 else round(lo, 6), None if total and hi >= total else round(hi, 6))+ for lo, hi in merged)+++def _read_packets(src: str, windows: tuple):+ """The video packets of `src` in `windows` (packet_windows; ((None, None),) is the whole file),+ one ffprobe per window, or None when ffprobe fails. A window's seek lands on the keyframe+ before its start, so packets a previous window already read (dts not after its last) are+ dropped. Cached on (src, windows)."""+ key = (src, windows)+ if key in _PACKETS:+ return _PACKETS[key]+ origin = file_origin(src)+ packets, breaks, spans, last_dts = _Packets(), set(), [], None+ for lo, hi in windows:+ first, before = len(packets), last_dts+ cmd = [require_tool("ffprobe"), "-v", "error", "-select_streams", "v:0", "-show_entries",+ "packet=pts_time,dts_time,flags", "-of", "csv=p=0"]+ if lo is not None or hi is not None:+ cmd += ["-read_intervals", ("" if lo is None else f"{origin + lo:.6f}") + "%"+ + ("" if hi is None else f"{origin + hi:.6f}")]+ proc = run(cmd + [src], quiet=True, check=False)+ if proc.returncode != 0:+ _PACKETS[key] = None+ return None+ for line in (proc.stdout or "").split():+ fields = line.split(",")+ if len(fields) < 3:+ continue+ pts, dts = _packet_time(fields[0]), _packet_time(fields[1])+ pts, dts = (None if pts is None else pts - origin), (None if dts is None else dts - origin)+ if before is not None and dts is not None and dts <= before + 1e-9:+ continue+ packets.append((pts, dts, "K" in fields[2]))+ if dts is not None:+ last_dts = dts+ if hi is not None and len(packets) > first:+ breaks.add(len(packets) - 1)+ spans.append((lo, hi, first, len(packets)))+ packets.breaks, packets.spans = frozenset(breaks), tuple(spans)+ _PACKETS[key] = packets or None+ return _PACKETS[key]+++def _windows_cover(packets, segments) -> bool:+ """True when the packets read around each segment hold what the plan needs from them: the+ keyframe the copy lands on (the largest dts at or before the start; none at all only counts+ from the file's start), a whole GOP after it, and the first keyframe at or after the end+ with a whole GOP after that too (gop_is_open judges both) -- or the end of the file."""+ runs = [(lo, hi, packets[i0:i1]) for lo, hi, i0, i1 in packets.spans]+ for s, e in segments:+ run_ = next(((lo, hi, p) for lo, hi, p in runs if (lo is None or lo <= s) and (hi is None or hi >= e)), None)+ if run_ is None:+ return False+ lo, hi, part = run_+ keys = [(p[0], p[1]) for p in part if p[2] and p[0] is not None and p[1] is not None]+ landed = [k for k in keys if k[1] <= s + 1e-6]+ if not landed:+ if lo is None:+ continue+ return False+ k_dts = max(k[1] for k in landed)+ later = [k for k in keys if k[1] > k_dts + 1e-9]+ if not later:+ if hi is None:+ continue+ return False+ after = [k for k in later if k[0] >= e - 1e-6]+ if hi is None:+ continue+ if not after or not [k for k in after if k[1] > min(after)[1] + 1e-9]:+ return False+ return True+++def video_packets(src: str, segments=None, tolerance: float = 0.5, total=None):+ """The video packets of `src` a --segments copy join is planned and checked against, in decode+ order, as (pts, dts, keyframe) on the cut's clock (a missing timestamp is None), or None+ when ffprobe cannot read them. Only windows around the segments are read (packet_windows),+ widened x4 up to PACKET_WIDENINGS times while one lacks what the plan needs (_windows_cover),+ and the whole file after that, so the cost follows the segments asked for, not the source's+ length; with no `segments`, the whole file."""+ if segments:+ margin = max(PACKET_MARGIN, 2 * tolerance)+ for _ in range(PACKET_WIDENINGS + 1):+ windows = packet_windows(segments, margin, total)+ if windows == ((None, None),):+ break+ packets = _read_packets(src, windows)+ if packets is None:+ return None+ if _windows_cover(packets, segments):+ return packets+ margin *= 4+ return _read_packets(src, ((None, None),))+++def gop_is_open(packets, i: int) -> bool:+ """True when keyframe packets[i] starts an open GOP: a packet decoded after it, before the next+ keyframe, is presented before it (a leading picture, which needs the GOP before to decode). A+ missing timestamp there counts as open, and so does a GOP whose read window ended before its+ next keyframe (video_packets widens its windows so that the GOPs a plan judges are whole). A+ GOP the file ends in has been read to its last packet and is judged on those."""+ key = packets[i][0]+ breaks = getattr(packets, "breaks", ())+ if key is None or i in breaks:+ return True+ for j in range(i + 1, len(packets)):+ pts, dts, is_key = packets[j]+ if is_key:+ return False+ if pts is None or dts is None or pts < key - 1e-6 or j in breaks:+ return True+ return False+++# a copied part stops before its end keyframe's packet by this much: -t compares decode+# timestamps, and ffprobe prints them rounded to the microsecond+_DTS_MARGIN = 1e-4+++def reorders(packets) -> bool:+ """True when the source's frames reorder: some packet is presented before one decoded ahead of+ it (B-frames). A source that never reorders cuts exactly in decode order, so its --segments+ parts are cut as in every 2.x release (main()). Judged within each window video_packets read:+ the gap between two windows is not a reorder."""+ breaks = getattr(packets, "breaks", ())+ top = None+ for i, (pts, _dts, _key) in enumerate(packets):+ if pts is not None:+ if top is not None and pts < top - 1e-6:+ return True+ top = pts if top is None else max(top, pts)+ if i in breaks:+ top = None+ return False+++def plan_part(packets, start: float, end: float, tolerance: float, vend, fps, snap_end: bool = True,+ landing=None) -> dict:+ """How the --segments part start-end is stream-copied for a concat-demuxer join.++ The copy begins at the keyframe `-ss start` lands on: `landing`, seek_keyframe()'s measurement,+ when it is one of `packets`' keyframes, otherwise the one with the largest dts at or before+ `start` (which the MP4 demuxer's seek over raw decode times does not always take: the join+ check is the backstop). The join presents from that keyframe: the concat demuxer does not apply the part's edit+ list start. The part ends at its end keyframe's DTS: an input -t stops in decode order, so+ ending at the keyframe's pts would carry that keyframe and the P-frame after it into the part.+ The end keyframe is the first one presented at or after `end` among those decoded after the+ landing (an earlier one would drop requested frames, and any decoded before the landing would+ give -t <= 0); one past `tolerance` re-encodes, reason "tolerance". With no keyframe after+ `end` (the end is in the video's last GOP) the end stays where asked and check_join judges+ the copy. A part that reaches the end of the video keeps -t end-start: nothing follows it to+ leak in. Without `snap_end` (a source whose frames do not reorder, or Matroska/MPEG-TS+ parts) the end is left where asked, as in every 2.x release; only the start is judged."""+ frame = 1.0 / fps if fps else 0.001+ keys = [(i, p[0], p[1]) for i, p in enumerate(packets) if p[2] and p[0] is not None and p[1] is not None]+ measured = ([k for k in keys if abs(k[1] - landing[0]) < 1e-5] if landing else [])+ landed = measured[:1] or [k for k in keys if k[2] <= start + 1e-6]+ if not landed and keys and (not getattr(packets, "spans", None) or packets.spans[0][0] is None):+ # a video stream that starts after `start` (its sound leads it): the seek lands on its+ # first keyframe, which the tolerance judges like any other+ landed = keys[:1]+ plan = {"reason": None, "start": start, "t": end - start, "start_index": None, "start_pts": None,+ "end_index": None, "end_pts": None, "end_bound": end}+ if not landed:+ plan["reason"] = "tolerance"+ return plan+ si, s_pts, s_dts = max(landed, key=lambda k: k[2])+ plan.update(start_index=si, start_pts=s_pts)+ within = (lambda off: True) if tolerance < 0 else (lambda off: off < tolerance)+ if not within(abs(s_pts - start)):+ plan["reason"] = "tolerance"+ return plan+ if vend is not None and end >= vend - frame / 2:+ plan["end_bound"] = None+ return plan+ if not snap_end:+ return plan+ after = [k for k in keys if k[2] > s_dts + 1e-9 and k[1] >= end - 1e-6]+ if not after:+ # the end is in the video's last GOP: no keyframe to snap it to, so the end stays where+ # asked and check_join judges the copy (a B-frame part cut mid-GOP in decode order usually+ # fails it, and the join is re-cut) -- not a tolerance miss, even under --tolerance -1+ return plan+ ei, e_pts, e_dts = min(after, key=lambda k: k[1])+ if not within(e_pts - end):+ plan["reason"] = "tolerance"+ return plan+ t = e_dts - start - _DTS_MARGIN+ if t < 0.001:+ # the start sits within a millisecond of the end keyframe's dts: no packet to copy+ plan["reason"] = "tolerance"+ return plan+ plan.update(t=t, end_index=ei, end_pts=e_pts, end_bound=e_pts)+ return plan+++def hidden_preroll_start(packets, plans, edit_listed: bool):+ """The 1-based number of the first part after the first whose start is not on a keyframe+ presented at or before it, for edit-listed (.mp4/.mov) parts of a source whose frames reorder;+ None otherwise. Such a part stores the frames from its keyframe to its start as hidden+ pre-roll, which the concat demuxer crushes into sub-millisecond steps at the join (measured on+ every source shape tried), so the join is re-cut without trying the copy."""+ if not edit_listed:+ return None+ for i, plan in enumerate(plans):+ if i and not plan["reason"] and plan["start_pts"] is not None and plan["start_pts"] < plan["start"] - _DTS_MARGIN:+ return i + 1+ return None+++def open_join_key(packets, plans):+ """The pts of the first keyframe a stream-copy join of the planned parts cannot cross, or None.+ An open END keyframe: its leading pictures belong to the part but decode after the keyframe,+ so a part cut in decode order loses them. An open START keyframe after the first part: the+ decoder drops leading pictures only at the start of a stream, so after a join they would decode+ against the previous part's frames. Parts that re-encode anyway are skipped."""+ for i, plan in enumerate(plans):+ if plan["reason"]:+ continue+ if i and gop_is_open(packets, plan["start_index"]):+ return plan["start_pts"]+ if plan["end_index"] is not None and gop_is_open(packets, plan["end_index"]):+ return plan["end_pts"]+ return None+++def stream_packet_times(path: str, stream: str, entry: str, limit: int = None) -> list:+ """One timestamp field (pts_time, duration_time) of every packet of the first `stream` ("v" or+ "a") in `path`, or of its first `limit` packets; a missing value is None. [] when there is no+ such stream or ffprobe fails."""+ cmd = [require_tool("ffprobe"), "-v", "error", "-select_streams", f"{stream}:0", "-show_entries", f"packet={entry}",+ "-of", "csv=p=0"] + (["-read_intervals", f"%+#{limit}"] if limit else []) + [path]+ proc = run(cmd, quiet=True, check=False)+ if proc.returncode != 0:+ return []+ return [_packet_time(line.split(",")[0]) for line in (proc.stdout or "").split()]+++def expected_packets(packets, ranges) -> int:+ """How many source video packets the join's parts present: those with lo <= pts < hi in each+ (lo, hi) range, hi None for a part that runs to the end of the video."""+ return sum(1 for lo, hi in ranges for pts, _, _ in packets+ if pts is not None and pts >= lo - 1e-6 and (hi is None or pts < hi - 1e-6))+++def check_join(out_pts, counts, fps, cfr: bool, predicted=None) -> dict:+ """The joined file measured, not predicted: its video packet count against the source's+ (`counts`, one per part, from expected_packets), and with constant frame timing every+ presentation step. A step inside a part is a frame (more than half, less than one and a half).+ The step at a join is the one `predicted` from the parts (predicted_join_steps), within a+ millisecond: the frame before a join is shown for its frame plus the time the concat+ demuxer leaves between the parts' pictures, which is not a fixed bound -- 56.7 ms at 30 fps+ for an exact no-B-frame join, one audio frame or more past a frame for PCM -- and a bound+ loose enough for every source let a hole of one audio packet through. Without a prediction+ a join step is held to the interior bound."""+ expected = sum(counts)+ pts = sorted(p for p in out_pts if p is not None)+ ok = len(out_pts) == expected and len(pts) == len(out_pts)+ max_step = None+ if cfr and fps:+ frame = 1.0 / fps+ gaps = [b - a for a, b in zip(pts, pts[1:])]+ if gaps:+ max_step = round(max(gaps), 6)+ joins = {}+ if ok and predicted:+ at = 0+ for j, n in enumerate(counts[:-1]):+ at += n+ if 0 < at < len(pts) and j < len(predicted) and predicted[j] is not None:+ joins[at - 1] = predicted[j]+ ok = ok and all(abs(g - joins[i]) <= JOIN_STEP_SLACK and g > frame / 2 if i in joins+ else frame / 2 < g < 1.5 * frame for i, g in enumerate(gaps))+ return {"packets": len(out_pts), "expected_packets": expected, "max_step_seconds": max_step, "ok": ok}+++def _adts_payload(data: str) -> bytes:+ """A packet's bytes from ffprobe's -show_data hex dump, without the ADTS header an MPEG-TS AAC+ packet carries (7 bytes, 9 with a CRC): what aac_adtstoasc leaves when the packet is copied+ into MP4, MOV or Matroska."""+ raw = bytearray()+ for line in str(data or "").strip().splitlines():+ _, _, rest = line.partition(":")+ raw += bytes.fromhex(rest.strip().split(" ")[0].replace(" ", ""))+ if len(raw) >= 7 and raw[0] == 0xFF and (raw[1] & 0xF6) == 0xF0:+ return bytes(raw[7 if raw[1] & 1 else 9:])+ return bytes(raw)+++def audio_packet_hashes(path: str, lo=None, hi=None, stream: str = "a:0", strip_adts: bool = False) -> list:+ """(pts, CRC32) of the `stream` audio packets of `path`, on its own raw clock, from `lo` to `hi`+ (absolute seconds; None = the file's start or end: a read from the start never seeks). With+ `strip_adts` each packet is hashed without its ADTS header (_adts_payload; zlib's CRC32 is+ ffprobe's), so an MPEG-TS source's AAC matches the same packets copied out of it. [] when+ there is no such stream or ffprobe fails."""+ cmd = [require_tool("ffprobe"), "-v", "error", "-select_streams", stream]+ if strip_adts:+ cmd += ["-show_entries", "packet=pts_time,data", "-show_data", "-of", "json"]+ else:+ cmd += ["-show_entries", "packet=pts_time,data_hash", "-show_data_hash", "CRC32", "-of", "csv=p=0"]+ if lo is not None or hi is not None:+ cmd += ["-read_intervals", ("" if lo is None else f"{lo:.6f}") + "%" + ("" if hi is None else f"{hi:.6f}")]+ proc = run(cmd + [path], quiet=True, check=False)+ out = []+ if proc.returncode != 0:+ return out+ if strip_adts:+ try:+ packets = json.loads(proc.stdout or "").get("packets") or []+ except (ValueError, AttributeError):+ return out+ for p in packets:+ pts = _packet_time(p.get("pts_time")) if isinstance(p, dict) else None+ if pts is not None and p.get("data"):+ out.append((pts, "CRC32:%08x" % zlib.crc32(_adts_payload(p["data"]))))+ return out+ for line in (proc.stdout or "").split():+ fields = line.split(",")+ pts = _packet_time(fields[0])+ crc = next((f for f in fields[1:] if f.startswith("CRC32:")), None)+ if pts is not None and crc:+ out.append((pts, crc))+ return out+++def copied_audio_streams(meta: dict, joined: str) -> List[str]:+ """The source audio streams (`a:N`) a join's sound may have been copied from: those with the+ codec, channel count and sample rate of the joined file's audio. FFmpeg's default selection+ copies the stream with the most channels, which need not be a:0 (a stereo AAC a:0 beside a+ 6-channel PCM a:1 copied a:1), so the check must hash the stream that was copied."""+ proc = run([require_tool("ffprobe"), "-v", "error", "-select_streams", "a:0", "-show_entries",+ "stream=codec_name,channels,sample_rate", "-of", "json", joined], quiet=True, check=False)+ try:+ st = (json.loads(proc.stdout or "").get("streams") or [{}])[0] if proc.returncode == 0 else {}+ shape = (st.get("codec_name"), int(st.get("channels") or 0), int(st.get("sample_rate") or 0))+ except (ValueError, TypeError, AttributeError, IndexError):+ return ["a:0"]+ found = [f"a:{a['index']}" for a in meta.get("audio_streams") or []+ if (a.get("codec"), a.get("channels") or 0, a.get("sample_rate") or 0) == shape]+ return found or ["a:0"]+++# check_join_audio: a run of AUDIO_RUN packets, from AUDIO_SKIP seconds into a part and starting+# within AUDIO_REACH of it, is looked for within AUDIO_SEARCH of where it belongs in the source; a+# part whose sound is more than AUDIO_SYNC_LIMIT off its picture fails the join+AUDIO_RUN, AUDIO_SKIP, AUDIO_REACH, AUDIO_SEARCH, AUDIO_SYNC_LIMIT = 8, 0.25, 2.0, 0.5, 0.005+++def check_join_audio(src: str, joined: str, starts, counts, out_pts=None, streams=("a:0",),+ strip_adts: bool = False) -> dict:+ """Each copied part's sound against its picture in the joined file, by matching audio packets+ with the source's (CRC32). A part's video moved by (its first frame in the join - its start+ keyframe in the source), and its sound by (an audio packet's time in the join - the same+ packet's time in the source); the two must agree within AUDIO_SYNC_LIMIT. The packet is the+ first of AUDIO_RUN consecutive ones, from AUDIO_SKIP into the part, whose run appears exactly+ once within AUDIO_SEARCH of where the video's move puts it. A part with no such run (digital+ silence, a periodic tone, a part too short) is unmeasured, not failed. `starts` are the+ parts' start keyframes (pts on the cut's clock), `counts` their video packets in the join,+ `out_pts` the join's video packet times when the caller has read them. `streams` are the+ source streams the sound may have come from (copied_audio_streams), tried in turn until one+ measures a part; `strip_adts` hashes the source's packets without their ADTS headers.+ Returns {audio_offset_ms: per part, sound minus picture (+ = sound late, null = unmeasured),+ audio_parts_checked, audio_ok}. A B-frame H.264 + PCM .mov join measured 0 / +16.0 / +53.3 ms+ and passed the video check; clean joins measure under 1 ms."""+ out_a = audio_packet_hashes(joined)+ if out_pts is None:+ out_pts = stream_packet_times(joined, "v", "pts_time")+ vpts = sorted(p for p in out_pts if p is not None)+ if not out_a or len(vpts) != sum(counts):+ return {"audio_offset_ms": None, "audio_parts_checked": 0, "audio_ok": True}+ origin = file_origin(src)+ offsets: list = []+ for stream in streams:+ offsets, first = [], 0+ for k, n in zip(starts, counts):+ v_out = vpts[first]+ nxt = vpts[first + n] if first + n < len(vpts) else float("inf")+ first += n+ vshift = v_out - (k + origin)+ lo = k + origin - 1.0+ src_a = audio_packet_hashes(src, None if lo <= origin else lo, k + origin + AUDIO_REACH + 2 * AUDIO_SEARCH,+ stream=stream, strip_adts=strip_adts)+ by_hash: dict = {}+ for j, (_, crc) in enumerate(src_a):+ by_hash.setdefault(crc, []).append(j)+ found = None+ for m, (p, crc) in enumerate(out_a):+ if p < v_out + AUDIO_SKIP:+ continue+ if p > v_out + AUDIO_REACH or m + AUDIO_RUN > len(out_a) or out_a[m + AUDIO_RUN - 1][0] >= nxt:+ break+ run_ = [h for _, h in out_a[m:m + AUDIO_RUN]]+ hits = [j for j in by_hash.get(crc, ()) if abs(src_a[j][0] - (p - vshift)) <= AUDIO_SEARCH+ and [h for _, h in src_a[j:j + AUDIO_RUN]] == run_]+ if len(hits) == 1:+ found = (p - src_a[hits[0]][0]) - vshift+ break+ offsets.append(None if found is None else round(found * 1000, 2) + 0.0)+ if any(o is not None for o in offsets):+ break+ measured = [o for o in offsets if o is not None]+ return {"audio_offset_ms": offsets, "audio_parts_checked": len(measured),+ "audio_ok": all(abs(o) <= AUDIO_SYNC_LIMIT * 1000 for o in measured)}+++def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: int, preset: str, tolerance: float = 0.5, meta: dict = None,+ _reasons: List[str] = None, edit_list_ok: bool = False, copy_t: float = None) -> dict:+ """Cut one segment. Returns its outcome: {reencoded, reasons, precision, start_snapped, ...}, where+ `reasons` lists why THIS segment re-encoded on its own (pcm_container / copy_failed / tolerance);+ the caller adds the reasons that forced every segment (requested, codec, vfr).++ `edit_list_ok` (--edit-list) keeps the edit list a single MP4/MOV copy writes instead of+ -avoid_negative_ts make_zero; off, the copy is cut and judged as in every 2.x release.++ `copy_t` is a --segments part planned by plan_part: copied for -t copy_t (to its end+ keyframe's dts), keeping the edit list an MP4/MOV copy writes, and not judged by its length+ here, since plan_part judged each of its ends."""+ reasons = list(_reasons or [])dur = end - startmeta = meta or probe(src)audio_only = is_audio_output(dst) or not meta.get("video")if not reencode and audio_only and audio_codec_for(dst)[1].startswith("pcm") and not str((meta.get("audio") or {}).get("codec", "")).startswith("pcm"):info(f"{(meta.get('audio') or {}).get('codec')} packets cannot be copied into a PCM container; decoding to PCM")reencode = True+ reasons.append("pcm_container")+ edit_list = False+ notes: List[str] = []if reencode:- # -ss before -i seeks, then decoding discards samples up to the exact start (accurate_seek);- # atrim bounds the decoded stream to the requested length at sample resolution.- cmd = ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur:.6f}"]if is_audio_output(dst) or not meta.get("video"):+ # -ss before -i seeks, then decoding discards samples up to the exact start+ # (accurate_seek); atrim bounds the decoded stream to the requested length at sample+ # resolution.+ cmd = ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur:.6f}"]cmd += ["-af", f"atrim=end={dur:.6f},asetpts=PTS-STARTPTS"]+ else:+ # Seek SEEK_MARGIN early, then drop the margin on the output side, which decodes and+ # discards it from both streams alike. An input seek straight to `start` can land (the+ # MP4 demuxer seeks over its raw decode times) on a keyframe whose picture comes after+ # `start` and lose the frames before it (-ss 9.9 on a B-frame HEVC file began at 10.0).+ m = min(SEEK_MARGIN, start)+ cmd = ffmpeg_base() + ["-ss", f"{start - m:.6f}", "-i", src, "-ss", f"{m:.6f}", "-t", f"{dur:.6f}"]# ffmpeg's default stream selection also picks one subtitle stream; a re-encode cannot# trim it (the cues kept their timestamps and the container grew to 2 s for a 1 s cut,# sweep F2), so the re-encode carries video/audio only and the result says so@@ -130,15 +829,40 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i# FLAC/MP3 on a coarse index; reading from the start and dropping packets is exact to the packetcmd = ffmpeg_base() + ["-i", src, "-ss", f"{start:.6f}", "-t", f"{dur:.6f}"] + copy_args(meta, dst) + ["-avoid_negative_ts", "make_zero", dst]else:- cmd = ffmpeg_base() + ["-ss", f"{start:.3f}", "-i", src, "-t", f"{dur:.3f}"] + copy_args(meta, dst) + ["-avoid_negative_ts", "make_zero", dst]+ # With --edit-list a single MP4/MOV output keeps the edit list the plain copy writes: the+ # keyframe's pre-roll is stored but hidden, so the picture and the sound start at `start`.+ # make_zero (the default, as in every 2.x release) shifts the timestamps instead and shows+ # the pre-roll -- on Core Media HEVC, 3.7 s of sound with no picture from a run that exited+ # 0, which av_start_skew_seconds and a note report. A planned concat part keeps it: the concat+ # demuxer ignores where the edit list starts (it shows the pre-roll) but places the next+ # part by its length, which make_zero parts got wrong by the B-frame reorder delay.+ # Other concat parts (Matroska, MPEG-TS) keep make_zero.+ edit_list = (edit_list_ok or copy_t is not None) and os.path.splitext(dst)[1].lower() in EDIT_LIST_EXTS+ cmd = (ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur if copy_t is None else copy_t:.6f}"]+ + copy_args(meta, dst) + ([] if edit_list else ["-avoid_negative_ts", "make_zero"]) + [dst])proc = run(cmd, check=False)if proc.returncode != 0:if not reencode:info("stream copy failed, falling back to re-encode")- return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta)+ return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta, reasons + ["copy_failed"], edit_list_ok)die(f"ffmpeg failed:\n{proc.stderr.strip()}", kind="ffmpeg")- if not reencode and tolerance >= 0 and not STATE.dry_run:- got = probe(dst).get("duration") or 0.0+ if not reencode and tolerance >= 0 and not STATE.dry_run and copy_t is None:+ out_meta = probe(dst)+ got = out_meta.get("duration") or 0.0+ vdur, fps = (out_meta.get("video") or {}).get("duration"), (meta.get("video") or {}).get("fps")+ if edit_list and not audio_only and vdur and fps and abs(got - vdur) > 1.0 / fps:+ # the container's length counts the longer track; the tolerance is about the picture.+ # Only under --edit-list: the default judges the container, as every 2.x release did+ msg = f"the container is {got:.3f}s but its video {vdur:.3f}s; the cut was judged by the video"+ info(msg)+ notes.append(msg)+ got = vdur+ if abs(got - dur) >= tolerance and edit_list and (copy_presentation(start, seek_keyframe(src, start), True, fps)["stored_preroll_seconds"] is not None):+ # the edit list started the picture at `start`: only the END is off (it lands on a+ # packet boundary), and no other --start would change that+ info(f"the stream copy starts where asked but its end landed {got - dur:+.2f}s from the requested "+ f"length (> {tolerance:.2f}s tolerance); re-encoding this segment for accuracy")+ return _with_notes(cut_one(src, start, end, dst, True, crf, preset, tolerance, meta, reasons + ["tolerance"], edit_list_ok), notes)if abs(got - dur) >= tolerance: # a snap of exactly the tolerance is not "within" it (sweep F20)near = keyframes_near(src, start)alt = ""@@ -149,8 +873,260 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: iNEAREST_KEYFRAMES.extend(k for k in near if k not in NEAREST_KEYFRAMES)info(f"stream copy landed on a keyframe {abs(got - dur):.2f}s away from the requested cut "f"(> {tolerance:.2f}s tolerance); re-encoding this segment for accuracy{alt}")- return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta)- return reencode+ return _with_notes(cut_one(src, start, end, dst, True, crf, preset, tolerance, meta, reasons + ["tolerance"], edit_list_ok), notes)+ if reencode or audio_only:+ return _outcome(meta, dst, reencode, reasons)+ if STATE.dry_run:+ # the planned copy: whether it keeps an edit list is known; where it lands is not+ return _outcome(meta, dst, False, reasons, edit_list=edit_list and edit_list_ok, start_snapped=None)+ fps = (meta.get("video") or {}).get("fps")+ # a concat part's edit list does not hide its pre-roll in the join, so it presents from the keyframe+ shown = edit_list and edit_list_ok+ key = seek_keyframe(src, start)+ return _outcome(meta, dst, False, reasons, edit_list=shown, notes=notes, landed_pts=key[0] if key else None,+ **copy_presentation(start, key, shown, fps))+++# The most segments one fallback ffmpeg call opens: every segment is its own input (a file handle,+# a demuxer and a decoder each), and macOS shells default to 256 open files.+JOIN_CHUNK = 32+# how far before a segment the fallback seeks, so a start inside the B-frame reorder delay before a+# keyframe still decodes from the keyframe BEFORE it+SEEK_MARGIN = 1.0+# codecs whose configuration travels in the packets, so a part with no extradata is not missing any+IN_BAND_CONFIG = ("mp3", "mp2")+TS_EXTS = (".ts", ".m2ts", ".mts")+_SIG_FIELDS = {"video": ("codec_name", "profile", "pix_fmt", "width", "height", "r_frame_rate", "time_base",+ "sample_aspect_ratio", "color_transfer", "color_primaries"),+ "audio": ("codec_name", "profile", "sample_rate", "channels", "time_base")}+++_PARTS: dict = {}+++def _part_probe(path: str):+ """ffprobe's streams and format of a cut part, with extradata hashes; None when it cannot be+ read. One probe per part serves join_signature and predicted_join_steps."""+ if path not in _PARTS:+ proc = run([require_tool("ffprobe"), "-v", "error", "-show_data_hash", "sha256", "-show_streams", "-show_format",+ "-of", "json", path], quiet=True, check=False)+ try:+ doc = json.loads(proc.stdout or "") if proc.returncode == 0 else None+ except ValueError:+ doc = None+ _PARTS[path] = doc if isinstance(doc, dict) and isinstance(doc.get("streams"), list) else None+ return _PARTS[path]+++def join_signature(path: str):+ """What a stream-copy join needs to be identical across parts: each stream's type, codec+ parameters, rotation and extradata hash. None when ffprobe cannot read the part."""+ doc = _part_probe(path)+ if doc is None:+ return None+ sig = []+ for st in doc["streams"]:+ kind = st.get("codec_type")+ entry = {"type": kind, "extradata_hash": st.get("extradata_hash")}+ entry.update({f: st.get(f) for f in _SIG_FIELDS.get(kind, ("codec_name",))})+ if kind == "video":+ entry["rotation"] = next((sd.get("rotation") for sd in st.get("side_data_list") or []+ if "rotation" in sd), None)+ sig.append(entry)+ return sig+++# how far a measured join step may be from the predicted one: ffprobe prints the parts' times+# to the microsecond, and a time base coarser than that (Matroska's 1 ms) rounds each of them+JOIN_STEP_SLACK = 0.001+++def predicted_join_steps(parts) -> list:+ """For each join of `parts`, the presentation step from the last frame of one part to the+ first of the next, as the concat demuxer places them: the next part starts where this one's+ container ends, so the step is (this part's container end - its last frame's pts) + (the next+ part's first frame's pts - its container start), read from the parts' own packets (Matroska+ stores no stream durations). None for a join whose parts' times are unknown. On an exact+ no-B-frame join (0-1.8,4-6 at 30 fps) that is 33.3 + 13.3 + 10.0 = 56.7 ms, what the joined+ file showed."""+ def times(path):+ doc = _part_probe(path)+ pts = [p for p in stream_packet_times(path, "v", "pts_time") if p is not None]+ try:+ fmt = (doc or {}).get("format") or {}+ c_start, c_dur = float(fmt["start_time"]), float(fmt["duration"])+ except (KeyError, TypeError, ValueError):+ return None+ return (c_start, c_start + c_dur, min(pts), max(pts)) if pts else None+ spans = [times(p) for p in parts]+ return [None if a is None or b is None else (a[1] - a[3]) + (b[2] - b[0]) for a, b in zip(spans, spans[1:])]+++def signatures_match(sigs: list, ext: str) -> bool:+ """True when every part can be joined by stream copy: same streams in the same order with the+ same parameters. A missing extradata hash only matches another missing one where the codec (or+ an MPEG-TS output) carries its configuration in-band -- PCM has none at all."""+ if not sigs or any(sig is None for sig in sigs):+ return False+ first = sigs[0]+ for sig in sigs[1:]:+ if len(sig) != len(first):+ return False+ for a, b in zip(first, sig):+ if {k: v for k, v in a.items() if k != "extradata_hash"} != {k: v for k, v in b.items() if k != "extradata_hash"}:+ return False+ ha, hb = a.get("extradata_hash"), b.get("extradata_hash")+ if ha or hb:+ if ha != hb:+ return False+ else:+ codec = str(a.get("codec_name") or "")+ if not (codec.startswith("pcm_") or codec in IN_BAND_CONFIG or ext in TS_EXTS):+ return False+ return True+++def _fraction_rate(text: str) -> float:+ """"30000/1001" or "30" as a number."""+ num, _, den = str(text).partition("/")+ return float(num) / float(den or 1)+++def _grid_at_or_after(t: float, v0: float, rate: float) -> float:+ """The time of the first frame at or after `t` on a constant-rate grid starting at `v0`."""+ import math+ return v0 + math.ceil((t - v0) * rate - 1e-6) / rate+++def _join_chunk(src: str, segments: List[Tuple[float, float]], dst: str, meta: dict, crf: int, preset: str,+ has_v: bool, intermediate: bool = False, vend=None, hold=frozenset(), first: int = 0) -> List[str]:+ """Re-cut `segments` from the source into one file through the concat filter, returning the codec+ arguments it encoded with. Each segment is+ its own seeked input, so both of its streams start at the segment's origin (0); neither is+ rebased on its own, which would drop a real A/V offset -- the audio is padded to the origin+ instead. Both streams are cut to the same length so the next segment starts where this ends.++ An `intermediate` chunk keeps its audio as PCM, so the chunks join with no encoder priming+ between them and the audio is encoded once, for the final file."""+ has_a = bool(meta.get("audio"))+ cmd = ffmpeg_base()+ graph, pads = [], ""+ video = meta.get("video") or {}+ rate_arg = video.get("r_frame_rate") if has_v else None+ try:+ rate = _fraction_rate(rate_arg) if rate_arg else (video.get("fps") or 0.0)+ except (ValueError, ZeroDivisionError):+ rate = video.get("fps") or 0.0+ v0 = (video.get("start_time") or 0.0) - file_origin(src) if has_v and rate else 0.0+ for i, (s, e) in enumerate(segments):+ d = e - s+ # Seek SEEK_MARGIN early and trim to the exact start. The MP4 demuxer seeks over its raw+ # decode times, so a start just before a keyframe (within the B-frame reorder delay) can+ # land on that keyframe and lose its leading frames -- measured: -ss 9.9 on a keyint-60+ # HEVC file began at 10.0 (seek_keyframe measures where a copy lands). Likewise an input -t stops reading at s+d in decode order and would drop+ # B-frames that display inside the segment, so it reads a second past the end.+ m = min(SEEK_MARGIN, s)+ cmd += ["-ss", f"{s - m:.6f}", "-t", f"{m + d + 1.0:.6f}", "-i", src]+ a, b, half = m, m + d, 0.0+ if has_v and rate:+ # Both streams are cut on the source's frame grid: from the first frame at or after the+ # start to the first at or after the end, which are the frames the segment holds. A+ # segment starting between frames otherwise placed its pictures half a frame off the+ # output's grid, and the constant-rate output duplicated one (65 frames for 64 on+ # FFmpeg 6.1). The video trim sits half a frame before each grid point, so no FFmpeg+ # version rounds a frame on the boundary in or out.+ a = m + (_grid_at_or_after(s, v0, rate) - s)+ b = m + (_grid_at_or_after(e, v0, rate) - s)+ half = 0.5 / rate+ # both streams shift by the same constant, so an offset between them (audio that starts+ # late) survives; the audio is then padded to the segment's origin+ if has_v:+ # a segment that runs past the video's end holds its last frame for the sound (main()+ # has already ended one that ran less than a frame past it at the video's end): the+ # concat filter starts the next segment after the longer stream, so a short picture+ # would leave a hole in the video there+ pad = f"tpad=stop_mode=clone:stop_duration={e - vend + 1.0:.6f}," if first + i in hold else ""+ graph.append(f"[{i}:v:0]{pad}trim=start={a - half:.6f}:end={b - half:.6f},setpts=PTS-{a:.6f}/TB[v{i}]")+ pads += f"[v{i}]"+ if has_a:+ graph.append(f"[{i}:a:0]atrim=start={a:.6f}:end={b:.6f},asetpts=PTS-{a:.6f}/TB,"+ f"aresample=async=1:first_pts=0[a{i}]")+ pads += f"[a{i}]"+ outs = ("[v]" if has_v else "") + ("[a]" if has_a else "")+ graph.append(f"{pads}concat=n={len(segments)}:v={int(has_v)}:a={int(has_a)}{outs}")+ cmd += ["-filter_complex", ";".join(graph)]+ for pad in ("[v]" if has_v else None, "[a]" if has_a else None):+ if pad:+ cmd += ["-map", pad]+ if intermediate:+ codec = (video_encode_args(meta, crf, preset) if has_v else ["-vn"]) + ["-c:a", "pcm_s24le"]+ else:+ codec = encode_args(meta, dst, crf, preset)+ # the source's rate, stated: FFmpeg 7.0 encoded the trimmed, concatenated pictures at 25 fps+ # and dropped frames to fit (98 frames for 117 at 30 fps)+ rate_out = ["-r", rate_arg] if has_v and rate_arg and rate and "-r" not in codec else []+ cmd += ["-sn", "-dn"] + codec + rate_out + [dst]+ run(cmd)+ return codec+++def join_from_source(src: str, segments: List[Tuple[float, float]], dst: str, meta: dict, crf: int, preset: str, tmp: str) -> None:+ """The join fallback: every segment re-cut from the source and encoded once. The parts are not+ reused -- a copied part carries keyframe pre-roll and an audio tail the concat filter would+ turn into a gap, and a re-encode keeps nothing lossless anyway."""+ if meta.get("subtitle_streams") or meta.get("data_streams"):+ DROPPED_STREAMS.append(dst)+ has_v = bool(meta.get("video")) and not is_audio_output(dst)+ vend = video_end(src, meta) if has_v else None+ # the segments whose picture ends before their sound; the last one is left as the source had it,+ # since no join follows it+ # (by position: a repeat of a held segment in last place is still the last one)+ hold = frozenset(k for k, (_, e) in enumerate(segments[:-1]) if vend is not None and e > vend + 1e-6)+ if len(segments) <= JOIN_CHUNK:+ _join_chunk(src, segments, dst, meta, crf, preset, has_v, vend=vend, hold=hold)+ return+ ext = os.path.splitext(dst)[1] or ".mp4"+ # Matroska chunks with PCM audio: no edit lists and no AAC priming to carry into the join (MP4+ # chunks measured the video 23 ms late against the audio after a copy concat)+ # the chunks' codec tag (hvc1), which a stream copy out of Matroska does not carry into an MP4+ # (it writes hev1, which Apple players refuse)+ tag: List[str] = []++ def encode_chunks() -> List[str]:+ out = []+ for k in range(0, len(segments), JOIN_CHUNK):+ chunk = os.path.join(tmp, f"chunk{k // JOIN_CHUNK:03d}.mkv")+ args = _join_chunk(src, segments[k:k + JOIN_CHUNK], chunk, meta, crf, preset, has_v, intermediate=True,+ vend=vend, hold=hold, first=k) or []+ if "-tag:v" in args:+ tag[:] = args[args.index("-tag:v"):args.index("-tag:v") + 2]+ out.append(chunk)+ return out++ chunks = encode_chunks()+ if not STATE.dry_run and STATE.hw and not signatures_match([join_signature(c) for c in chunks], ".mkv"):+ # VideoToolbox refused some chunk and run() re-encoded that one on the CPU, so the chunks+ # no longer match: encode them all on the CPU rather than refuse a join that can be made+ info("the GPU refused part of this join and the chunks came out mixed; re-encoding every chunk on the CPU")+ STATE.hw_notes.append("the --segments join fell back to the CPU for every chunk after VideoToolbox refused one")+ # off for these encodes only: the result still reports that the GPU was asked for+ STATE.hw = False+ try:+ chunks = encode_chunks()+ finally:+ STATE.hw = True+ if not STATE.dry_run and not signatures_match([join_signature(c) for c in chunks], ".mkv"):+ die("the re-encoded chunks of this join came out with different stream parameters, so they "+ f"cannot be joined safely; cut at most {JOIN_CHUNK} segments per run and join the results "+ "with join.py", kind="ffmpeg")+ listfile = os.path.join(tmp, "chunks.txt")+ with open(listfile, "w", encoding="utf-8") as fh:+ for c in chunks:+ fh.write(concat_list_line(c) + "\n")+ audio = [] if not meta.get("audio") else (aac_args() if has_v else audio_codec_for(dst))+ run(ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile]+ + (["-c:v", "copy"] + (tag if ext in (".mp4", ".mov", ".m4v") else []) if has_v else ["-vn"]) + audio+ + (["-movflags", "+faststart"] if ext in (".mp4", ".mov", ".m4v") and has_v else []) + [dst])BEAT_RATE = 22050 # the decode rate the onset pass uses, matching scenes.py --beats@@ -270,6 +1246,23 @@ def snap_segments(args, segments, meta, total):out_segments)+def _join_workspace():+ """A --segments copy join's workspace: a temp directory for its parts, and a list of the files+ it writes beside the output (the checked join, renamed into place when it passes), removed+ whatever happens."""+ temps: List[str] = []+ try:+ with tempfile.TemporaryDirectory(prefix="ffskill_cut_") as tmp:+ yield tmp, temps+ finally:+ for path in temps:+ try:+ os.remove(path)+ except OSError:+ pass++def main() -> int:ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)ap.add_argument("input")@@ -280,7 +1273,16 @@ def main() -> int:g.add_argument("--duration", help="duration instead of --end")ap.add_argument("--segments", help="comma separated START-END list, e.g. '0:05-0:12,1:00-1:20' (joined in order)")ap.add_argument("--accurate", action="store_true", help="always re-encode for frame-accurate (video) / sample-accurate (audio) cuts (default: lossless -c copy, re-encoding only when the keyframe snap exceeds --tolerance)")- ap.add_argument("--tolerance", type=float, default=0.5, help="max seconds a lossless cut may deviate before re-encoding kicks in (default 0.5, -1 = never)")+ ap.add_argument("--edit-list", action="store_true", help="a single-segment .mp4/.mov stream copy keeps the MP4 edit list that hides the keyframe's pre-roll, so the picture starts at --start (default: -avoid_negative_ts make_zero, the picture starts at the keyframe); a player that ignores edit lists shows the pre-roll")+ ap.add_argument("--keep-hevc", action="store_true", help="a re-encode of an SDR HEVC source stays HEVC (x265 8-bit BT.709; VideoToolbox under --hw) instead of x264 (default: x264 for SDR, x265 Main10 for HDR); --codec overrides it")+ ap.add_argument("--vfr-guard", choices=["average", "sampled", "off"], default="average",+ help="what keeps a variable-frame-rate source from a stream copy (default average: a nominal rate "+ "that differs from the average re-encodes, as --accurate, and the sampled frame timing is "+ "reported; sampled: re-encode only when sampled packet timestamps are variable or too few "+ "to judge; off: measure and keep the copy, with a note)")+ ap.add_argument("--tolerance", type=float, default=0.5, help="max seconds a lossless cut may deviate before re-encoding kicks in (default 0.5, -1 = never for a "+ "keyframe snap; a --segments join is still re-cut for open GOPs, a later B-frame .mp4/.mov "+ "segment starting between keyframes, or a failed join check)")snap = ap.add_argument_group("beat snapping")snap.add_argument("--snap", choices=["none", "beats"], default="none",help="move each in/out point to the nearest measured beat (default none)")@@ -297,16 +1299,21 @@ def main() -> int:add_common(ap)args = ap.parse_args()apply_common(args)+ global KEEP_HEVC+ KEEP_HEVC = args.keep_hevcmeta = probe(args.input)total = meta.get("duration") or 0.0- if meta.get("video", {}) and meta["video"].get("variable_frame_rate_suspected") and not args.accurate:- info("source looks variable-frame-rate; lossless cuts on VFR are unreliable, switching to --accurate")- args.accurate = True- if STATE.codec and not args.accurate:- # "cut this and make it HEVC": a stream copy keeps the source codec, so the request is a re-encode- info(f"--codec {STATE.codec} asks for a re-encode; the lossless copy path keeps the source codec, switching to --accurate")+ # why every segment re-encodes, if one of these forces it; `requested` is read before the+ # guards below overwrite args.accurate, so a forced re-encode is never reported as asked for+ forced: List[str] = ["requested"] if args.accurate else []+ if STATE.codec:+ # "cut this and make it HEVC": a stream copy keeps the source codec, so the request is a+ # re-encode -- and a cause of it even when --accurate or the VFR guard already forced one+ if not args.accurate:+ info(f"--codec {STATE.codec} asks for a re-encode; the lossless copy path keeps the source codec, switching to --accurate")args.accurate = True+ forced.append("codec")fps = (meta.get("video") or {}).get("fps")if args.segments:@@ -337,54 +1344,305 @@ def main() -> int:if total and s >= total:die(f"segment start {s:.3f}s is beyond the media duration {total:.3f}s")segments = [(s, min(e, total) if total else e) for s, e in segments]+ # what was asked for, clamped to the media duration as in every 2.x release: requested_* and+ # expected_duration report this, and a segment the join below ends with the video (less than a+ # frame of sound trimmed) shows that trim in duration_delta_seconds and a note instead+ requested = list(segments)+ video = meta.get("video") or {}+ if video.get("fps") and not is_audio_output(args.output or ""):+ # a video segment shorter than one frame has no picture to cut: a copy lands on a whole+ # GOP and a re-encode on one frame or none, so the result would not be what was asked+ frame = 1.0 / video["fps"]+ # where the video ends on the cut's clock (video_end), not the stream's length: video that+ # starts after the container does (MPEG-TS) ends later than its length says. A pending+ # --dry-run input has nothing to probe, so it falls back to the media duration.+ vend = (None if dry_run_input_pending(args.input) else video_end(args.input, meta)) or total+ for s, e in segments:+ if (min(e, vend) if vend else e) - s < frame - 1e-6:+ die(f"segment {s:.3f}-{e:.3f}s is shorter than one frame ({frame:.4f}s at {video['fps']:g} fps)"+ + (" inside the video stream" if vend and e > vend else "")+ + "; give every segment at least one frame", kind="input")output = args.output or default_output(args.input, "cut")refuse_output_is_input(output, args.input)ext = os.path.splitext(output)[1] or ".mp4"- reencoded = False+ # A segment that runs past the end of the video, with a join after it: whatever joins it (the+ # concat demuxer or the concat filter) starts the next segment after its LONGER stream, so the+ # sound with no picture left a hole in the video (0.355 s for 0.3 s of sound, reported as a+ # clean copy). clip_length's rule, as join.py uses it: less than a frame past -> end the+ # segment with its picture; more -> hold the last frame for the sound, which only a re-cut+ # can do. The last segment is left as the source had it: nothing is placed after it.+ join_notes: List[str] = []+ hold_needed = False+ vend = (video_end(args.input, meta) if len(segments) > 1 and video.get("fps") and not is_audio_output(output)+ and not dry_run_input_pending(args.input) else None)+ if vend is not None:+ frame = 1.0 / video["fps"]+ for i, (s, e) in enumerate(segments[:-1]):+ if e <= vend + 1e-6:+ continue+ if e - vend <= frame + 1e-6:+ segments[i] = (s, vend)+ join_notes.append(f"segment {i + 1} ends with the video at {vend:.3f}s: the {(e - vend) * 1000:.0f} ms of "+ "sound after its last frame is trimmed")+ else:+ hold_needed = True+ join_notes.append(f"segment {i + 1} runs {e - vend:.3f}s past the end of the video; its last frame is held "+ "for the sound, which a stream-copy join cannot do, so every segment was re-cut")+ for n in join_notes:+ info(n)++ # the VFR guard: a stream copy of variable-frame-rate video cuts unreliably. --vfr-guard average+ # (the default, as in every 2.x release) trusts probe's nominal-vs-average rate check and+ # re-encodes on it; the sampled packet timing is then measured only to report whether that+ # check was right. sampled re-encodes on the sampled timing instead (an iPhone's 30 vs 29.98+ # fps is not taken for VFR), and off measures and keeps the copy.+ vfr_check = None+ vfr_notes: List[str] = []+ could_copy = (bool(video) and not args.accurate and not hold_needed and not is_audio_output(output)+ and not dry_run_input_pending(args.input))++ def sample_timing() -> dict:+ return {"heuristic": True, **measure_frame_timing(args.input, total, video.get("start_time") or 0.0),+ "method": "sampled", "guard": args.vfr_guard}++ if args.vfr_guard == "average":+ if video.get("variable_frame_rate_suspected") and not args.accurate:+ info("source looks variable-frame-rate; lossless cuts on VFR are unreliable, switching to --accurate")+ if could_copy:+ vfr_check = sample_timing()+ if vfr_check["measured"] == "sampled_cfr":+ vfr_notes.append("the nominal and average frame rates differ, so the source was taken for VFR and "+ "re-encoded, but its sampled frame timing is constant: --vfr-guard sampled keeps "+ "the lossless copy")+ info(vfr_notes[-1])+ args.accurate = True+ forced.append("vfr")+ elif could_copy:+ vfr_check = sample_timing()+ measured = vfr_check["measured"]+ what = ("the sampled frame timing is variable" if measured == "vfr"+ else "the frame timing could not be measured")+ if measured != "sampled_cfr" and args.vfr_guard == "off":+ vfr_notes.append(f"{what}; --vfr-guard off skipped the re-encode that forces, so a stream copy of this "+ "source may land off its frames")+ info(vfr_notes[-1])+ elif measured != "sampled_cfr":+ info(f"{what}; lossless cuts on VFR are unreliable, switching to --accurate (--vfr-guard off keeps the copy)")+ args.accurate = True+ forced.append("vfr" if measured == "vfr" else "vfr_inconclusive")++ outcomes: List[dict] = []+ join_reencoded = False+ join_check = Noneif len(segments) == 1:- reencoded = cut_one(args.input, segments[0][0], segments[0][1], output, args.accurate, args.crf, args.preset, args.tolerance, meta)- else:+ outcomes.append(cut_one(args.input, segments[0][0], segments[0][1], output, args.accurate, args.crf, args.preset, args.tolerance, meta,+ edit_list_ok=args.edit_list))+ elif hold_needed or args.accurate:+ # Straight to one encode through the concat filter. A held frame needs the re-cut (no part+ # can carry it into a copy join); and when every part re-encodes anyway, encoding each on+ # its own and copy-joining them left a hole of one AAC frame at every join (each part's+ # audio runs an encoder frame past its picture, and the concat demuxer places the next+ # part after it: measured 23 ms per join).with tempfile.TemporaryDirectory(prefix="ffskill_cut_") as tmp:- parts = []- for i, (s, e) in enumerate(segments):- part = os.path.join(tmp, f"part{i:03d}{ext}")- reencoded |= cut_one(args.input, s, e, part, args.accurate, args.crf, args.preset, args.tolerance, meta)- parts.append(part)- listfile = os.path.join(tmp, "list.txt")- with open(listfile, "w", encoding="utf-8") as fh:- for p in parts:- fh.write(concat_list_line(p) + "\n")- cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile, "-c", "copy"]- if ext in (".mp4", ".mov", ".m4v"):- cmd += ["-movflags", "+faststart"]- cmd += [output]- proc = run(cmd, check=False)- if proc.returncode != 0:- info("concat with stream copy failed, re-encoding the join")- cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile] + encode_args(meta, output, args.crf, args.preset) + [output]- run(cmd)+ join_from_source(args.input, segments, output, meta, args.crf, args.preset, tmp)+ join_reencoded = hold_needed # only the hold is a fallback; --accurate asked for this+ outcomes = [_outcome(meta, output, True, []) for _ in segments]+ else:+ with _join_workspace() as (tmp, temps):+ # A video join is planned from the source's own packets and measured against them once+ # written (check_join). A source whose frames do not reorder (no B-frames) cuts its+ # parts as every 2.x release did (make_zero, -t end-start, each part judged against+ # --tolerance by its length): in decode order that is already exact. One whose frames+ # reorder keeps .mp4/.mov parts' edit lists and cuts each from its start keyframe to+ # its end keyframe's dts (plan_part). An audio-only join keeps the plain cut.+ join_video = bool(video) and not is_audio_output(output) and not dry_run_input_pending(args.input)+ # where each part's -ss lands, measured (seek_keyframe); the packets read around the+ # segments reach back to it+ landings = [seek_keyframe(args.input, s) for s, _ in segments] if join_video else None+ packets = (video_packets(args.input, [(min(s, k[0]) if k else s, e) for (s, e), k in zip(segments, landings)],+ args.tolerance, total) if join_video else None)+ snap_end = bool(packets) and reorders(packets) and ext.lower() in EDIT_LIST_EXTS+ plans = ([plan_part(packets, s, e, args.tolerance, video_end(args.input, meta), fps, snap_end, k)+ for (s, e), k in zip(segments, landings)] if packets else None)+ open_key = open_join_key(packets, plans) if plans else None+ preroll = hidden_preroll_start(packets, plans, snap_end) if plans else None+ recut = None # why the parts are not joined by stream copy, when that is known before cutting them+ if join_video and not packets:+ recut = ("the source's video packets could not be read, so a stream-copy join could not be checked; "+ "every segment was re-cut from the source")+ elif open_key is not None:+ recut = (f"the source uses open GOPs: frames before the keyframe at {open_key:.3f}s decode after it, so a "+ "stream-copy join would drop them; every segment was re-cut from the source")+ elif preroll is not None and not any(p["reason"] for p in plans):+ recut = (f"segment {preroll} starts between keyframes of a source whose frames reorder: its copy would "+ "hide the frames before its start, which a stream-copy join cannot do; every segment was re-cut "+ "from the source")+ compatible = False+ if recut:+ info(recut)+ join_notes.append(recut)+ elif plans and any(p["reason"] for p in plans):+ # a segment with no keyframe near its start or end re-encodes, and only copied parts are+ # joined by copy (parts encoded one by one leave an AAC frame's hole at every join), so+ # every segment is re-cut into one encode, without encoding the parts first+ late = [str(i + 1) for i, p in enumerate(plans) if p["reason"]]+ # the keyframes near each such segment's start, as a part judged on its own named them+ # in every 2.x release, so the caller can move the cut instead+ for (s, _), p in zip(segments, plans):+ if p["reason"]:+ NEAREST_KEYFRAMES.extend(k for k in keyframes_near(args.input, s) if k not in NEAREST_KEYFRAMES)+ info(f"segment{'s' if len(late) > 1 else ''} {', '.join(late)} {'have' if len(late) > 1 else 'has'} no keyframe "+ f"within {args.tolerance:.2f}s of {'their' if len(late) > 1 else 'its'} start or end to copy from; "+ "re-cutting every segment from the source into one re-encode")+ recut = "tolerance"+ if recut:+ outcomes = [_outcome(meta, output, True, ["tolerance"] if plans and plans[i]["reason"] else [])+ for i in range(len(segments))]+ else:+ parts = []+ for i, (s, e) in enumerate(segments):+ part = os.path.join(tmp, f"part{i:03d}{ext}")+ plan = plans[i] if plans else None+ outcomes.append(cut_one(args.input, s, e, part, False, args.crf, args.preset, args.tolerance, meta,+ edit_list_ok=False, copy_t=plan["t"] if plan and snap_end else None))+ parts.append(part)+ # a stream-copy join is only safe between identical copied parts: the concat demuxer+ # takes the first part's parameters for all of them, and a mismatch (a copied HEVC part+ # next to a re-encoded one, or H.264 next to HEVC) decodes with errors from a run that+ # exited 0; video parts that all re-encoded match, but leave an AAC frame's hole at each+ # join (audio decoded to PCM has no encoder priming, so those parts still join)+ compatible = (not (join_video and any(o["reencoded"] for o in outcomes))+ and (STATE.dry_run or signatures_match([join_signature(p) for p in parts], ext)))+ if compatible:+ listfile = os.path.join(tmp, "list.txt")+ with open(listfile, "w", encoding="utf-8") as fh:+ for p in parts:+ fh.write(concat_list_line(p) + "\n")+ # a join that is checked is written to a hidden file beside the output and renamed+ # into place only once it passes (copying it out of the temp directory cost about 2 s+ # for 240 MB): a failed check re-cuts, and a re-cut that then failed must not cost+ # the caller the file --overwrite would have replaced+ checked = bool(plans) and not STATE.dry_run+ joined = sibling_temp(output, "join") if checked else output+ if checked:+ temps.append(joined)+ cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile, "-c", "copy"]+ if ext in (".mp4", ".mov", ".m4v"):+ cmd += ["-movflags", "+faststart"]+ cmd += [joined]+ proc = run(cmd, check=False)+ if proc.returncode != 0:+ info("concat with stream copy failed; re-cutting every segment from the source into one re-encode")+ compatible = False+ elif checked:+ # measured, not predicted: the joined file against the source packets its parts hold+ # constant frame timing: measured by the sampled guards, and under the default+ # average guard a copy is only reached when probe's rate check found it constant+ cfr = (vfr_check.get("measured") == "sampled_cfr" if vfr_check+ else args.vfr_guard == "average")+ counts = [expected_packets(packets, [(p["start_pts"], p["end_bound"])]) for p in plans]+ out_pts = stream_packet_times(joined, "v", "pts_time")+ join_check = check_join(out_pts, counts, fps, cfr, predicted_join_steps(parts))+ # the sound of each part against its picture (only once the pictures are right: the+ # parts are located in the join by their packet counts)+ video_ok = join_check["ok"]+ audio = (check_join_audio(args.input, joined, [p["start_pts"] for p in plans], counts, out_pts,+ copied_audio_streams(meta, joined),+ strip_adts=("mpegts" in str(meta.get("format") or "").split(",")+ and ext.lower() not in TS_EXTS))+ if video_ok and meta.get("audio") else+ {"audio_offset_ms": None, "audio_parts_checked": 0, "audio_ok": True})+ audio_ok = audio.pop("audio_ok")+ join_check["ok"] = video_ok and audio_ok+ join_check.update(audio)+ if not join_check["ok"]:+ step = join_check["max_step_seconds"]+ if video_ok:+ off = max((o for o in join_check["audio_offset_ms"] if o is not None), key=abs)+ why = (f"segment {join_check['audio_offset_ms'].index(off) + 1}'s sound is {abs(off):.1f} ms "+ f"{'late' if off > 0 else 'early'} against its picture")+ else:+ why = (f"{join_check['packets']} video packets where the segments hold "+ f"{join_check['expected_packets']} in the source"+ + (f", largest step {step:.3f}s" if step is not None else ""))+ msg = f"the stream-copy join was checked and failed: {why}; every segment was re-cut from the source"+ info(msg)+ join_notes.append(msg)+ compatible = False+ else:+ place_output(joined, output, move=True)+ else:+ info("the cut parts cannot be joined by stream copy (a segment re-encoded, or the parts differ in "+ "codec parameters); re-cutting every segment from the source into one re-encode")+ if not compatible:+ join_from_source(args.input, segments, output, meta, args.crf, args.preset, tmp)+ join_reencoded = True+ # every segment was re-cut and re-encoded: none of them keeps its copy precision+ outcomes = [_outcome(meta, output, True, o["reasons"]) for o in outcomes]result = probe(output, role="output")- expected = sum(e - s for s, e in segments)- precision = precision_of(meta, output, reencoded)+ expected = sum(e - s for s, e in requested)+ # the join counts: a copy join that fell back to a re-encode is not a stream copy (2.x reported+ # it as mode copy, precision packet)+ reencoded = join_reencoded or any(o["reencoded"] for o in outcomes)+ report = report_precision(meta, output, reencoded, outcomes)+ precision = report["precision"]+ reencode_reason: List[str] = []+ if reencoded:+ for r in forced + [r for o in outcomes for r in o["reasons"]] + (["concat_fallback"] if join_reencoded else []):+ if r not in reencode_reason:+ reencode_reason.append(r)got = result.get("duration")error_ms = round((got - expected) * 1000, 3) if got is not None and not STATE.dry_run else None- # mode: "copy" (untouched lossless), "accurate" (--accurate was asked for), "hybrid" (asked for- # lossless but the keyframe snap exceeded --tolerance so this segment silently re-encoded instead)+ # mode: "copy" (nothing re-encoded at any stage, the join included), "accurate" (--accurate was+ # asked for or forced), "hybrid" (asked for lossless but a segment or the join re-encoded anyway;+ # reencode_reason says why)mode = "copy" if not reencoded else ("accurate" if args.accurate else "hybrid")- keyframe_snapped = precision == "packet"+ notes: List[str] = vfr_notes + join_notes + [n for o in outcomes for n in o.get("notes") or []]+ single = outcomes[0] if len(outcomes) == 1 else {}+ stored = single.get("stored_preroll_seconds")+ if single.get("edit_list") and stored:+ notes.append(f"{stored:.3f}s of pre-roll is stored, hidden by the MP4 edit list; a player or "+ "tool that ignores edit lists will show it")+ # where each copied part's end moved to its keyframe; only for a join that is those parts+ end_snaps = None+ if join_check and join_check["ok"] and not join_reencoded:+ end_snaps = [None if o["reencoded"] or p["end_pts"] is None else round(p["end_pts"] - e, 3) + 0.0+ for o, p, (_, e) in zip(outcomes, plans, segments)]+ # a single MP4/MOV copy without --edit-list shows the pre-roll the edit list would hide+ remedy = (len(outcomes) == 1 and not reencoded and not single.get("edit_list") and single.get("start_snapped")+ and ext.lower() in EDIT_LIST_EXTS and not is_audio_output(output))+ # the source's own skew where the output's picture starts: at the keyframe the first copy+ # landed on, or at the start when an edit list hides the pre-roll (or a re-encode starts there)+ first = outcomes[0] if outcomes else {}+ at = (first["landed_pts"] if not reencoded and not first.get("edit_list") and first.get("landed_pts") is not None+ else segments[0][0])+ skew, skew_note = ((None, None) if STATE.dry_run+ else av_skew(result, bool(remedy), source_skew(args.input, meta, at)))+ if reencoded:+ # a re-encode starts both streams where the source had them at the start (the re-cut pads the+ # audio to each segment's origin): the skew is reported, but no copy began on unshared packets+ skew_note = None+ if skew_note:+ info(skew_note)+ notes.append(skew_note)info(f"wrote {output} ({fmt_secs(got)}, expected ~{expected:.3f}s, "+ ("re-encoded" if reencoded else "lossless stream copy") + f", {precision} precision)")emit(output, expected_duration=round(expected, 6), duration_error_ms=error_ms, precision=precision, reencoded=reencoded,dropped_non_av_streams=bool(DROPPED_STREAMS),- requested_start=round(segments[0][0], 6) if len(segments) == 1 else None,- requested_end=round(segments[0][1], 6) if len(segments) == 1 else None,- requested_segments=[[round(s, 6), round(e, 6)] for s, e in segments] if len(segments) > 1 else None,+ requested_start=round(requested[0][0], 6) if len(requested) == 1 else None,+ requested_end=round(requested[0][1], 6) if len(requested) == 1 else None,+ requested_segments=[[round(s, 6), round(e, 6)] for s, e in requested] if len(requested) > 1 else None,requested_duration=round(expected, 6), output_duration=round(got, 6) if got is not None else None,duration_delta_seconds=round(error_ms / 1000, 6) if error_ms is not None else None,- mode=mode, keyframe_snapped=keyframe_snapped,+ mode=mode, keyframe_snapped=report["keyframe_snapped"], start_snapped=report["start_snapped"],+ reencode_reason=reencode_reason, least_exact_precision=report["least_exact_precision"],+ segment_precision=report["segment_precision"],+ edit_list=bool(single.get("edit_list")), stored_preroll_seconds=stored, av_start_skew_seconds=skew,+ join_check=join_check, segment_end_snap_seconds=end_snaps,+ notes=notes, **({"vfr_check": vfr_check} if vfr_check else {}),nearest_keyframes=sorted(NEAREST_KEYFRAMES) if NEAREST_KEYFRAMES else None,# the trade the caller can offer instead of a re-encode (eval e02: "without losing quality")lossless_alternative=(f"--start {min(NEAREST_KEYFRAMES, key=lambda k: abs(k - segments[0][0])):.3f} lands on a keyframe: "diff --git a/tests/fixtures/mcp_tools.json b/tests/fixtures/mcp_tools.jsonindex 3b43a28..c58ad25 100644--- a/tests/fixtures/mcp_tools.json+++ b/tests/fixtures/mcp_tools.json@@ -317,11 +317,13 @@"codec","dry_run","duration",+ "edit_list","end","fast","hw","input","json_brief",+ "keep_hevc","min_confidence","no_hw","output",@@ -335,7 +337,8 @@"snap_tolerance","start","timeout",- "tolerance"+ "tolerance",+ "vfr_guard"],"required": []},diff --git a/tests/test_all.py b/tests/test_all.pyindex 4c37d00..c6b82a6 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -4,8 +4,8 @@python3 tests/test_all.py # or: python3 -m unittest tests/test_all.pyThe cases themselves live one module per tool group -- test_analysis, test_editing, test_audio,-test_picture, test_delivery, test_orchestration, test_accel, test_asr -- over the fixtures in _fixtures.py. This file-imports all seven so that the entry point every CI job, npm test and release_check.sh already runs+test_picture, test_delivery, test_orchestration, test_accel, test_asr, test_cut_copy -- over the fixtures in _fixtures.py.+This file imports all nine so that the entry point every CI job, npm test and release_check.sh already runskeeps running exactly the same set; each group module is also runnable on its own."""import sys@@ -18,16 +18,18 @@ import test_accel # noqa: E402import test_analysis # noqa: E402import test_asr # noqa: E402import test_audio # noqa: E402+import test_cut_copy # noqa: E402import test_delivery # noqa: E402import test_editing # noqa: E402import test_orchestration # noqa: E402import test_picture # noqa: E402-MODULES = (test_analysis, test_editing, test_audio, test_picture, test_delivery, test_orchestration, test_accel, test_asr)+MODULES = (test_analysis, test_editing, test_cut_copy, test_audio, test_picture, test_delivery, test_orchestration, test_accel,+ test_asr)def load_tests(loader, tests, pattern):- """unittest calls this instead of scanning this module: the cases are in the seven group+ """unittest calls this instead of scanning this module: the cases are in the nine groupmodules, and naming them here keeps the set (and the order groups run in) explicit."""suite = unittest.TestSuite()for module in MODULES:diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 3b15252..d869758 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -2199,6 +2199,18 @@ class ContractTests(unittest.TestCase):doc = json.loads(tool("cut", self.src, "--start", "0", "--end", "2", "--json", "-o", self.out("e6_cut0.mp4")).stdout)self.assertIsNone(doc["lossless_alternative"])+ def test_cut_names_the_lossless_alternative_in_matroska_and_mp4_keeps_its_edit_list(self):+ """.mkv has no edit list, so the copy snaps back to the keyframe at 0 and the lossless+ alternative is offered; an .mp4 copy that keeps its edit list (--edit-list) starts at 2 s+ losslessly."""+ doc = json.loads(tool("cut", self.src, "--start", "2", "--end", "4", "--fast", "--json", "-o", self.out("e6_cut.mkv")).stdout)+ self.assertEqual(doc["mode"], "hybrid")+ self.assertIn("--start 0.000", doc["lossless_alternative"])+ doc = json.loads(tool("cut", self.src, "--start", "2", "--end", "4", "--fast", "--edit-list", "--json",+ "-o", self.out("e6_cut_el.mp4")).stdout)+ self.assertEqual(doc["mode"], "copy")+ self.assertTrue(doc["edit_list"])+def test_verified_reports_what_the_tool_measured(self):"""#189 C: every success document carries `verified` and `verification`. cut: probe only;loudness: probe + its own after-write measurement; export on a raw source: loudness stepdiff --git a/tests/test_cut_copy.py b/tests/test_cut_copy.pynew file mode 100644index 0000000..544901b--- /dev/null+++ b/tests/test_cut_copy.py@@ -0,0 +1,1929 @@+#!/usr/bin/env python3+"""cut.py's stream-copy and --segments join paths, checked on the decoded frames they produce.++ python3 tests/test_cut_copy.py # this group alone+ python3 tests/test_all.py # every group++The fixtures are small and built once here: an HEVC source with B-frames (the Core Media shape+the carry-forward fixes are about), an H.264 source whose audio starts 0.379 s after its video,+and a WAV. Frames are identified by PSNR against the source's own frames rather than by hash,+because a re-encoded join cannot reproduce a frame bit for bit; testsrc2 changes on every frame,+so the right frame and its neighbours are tens of dB apart.+"""+import importlib+import json+import math+import os+import re+import subprocess+import sys+import tempfile+import unittest+from pathlib import Path+from unittest import mock++sys.path.insert(0, str(Path(__file__).resolve().parent))+from _fixtures import OUT, SCRIPTS, script, sh # noqa: E402+from _common import decision, probe # noqa: E402+probe_mod = sys.modules["_common.probe"] # the module (the package re-exports probe() under its name)++sys.path.insert(0, str(SCRIPTS))+import cut # noqa: E402++DIR = OUT / "cut_copy"+FPS = 30+W, H = 64, 36+++def gray_frames(path):+ """Every frame of `path`, decoded and scaled to a 64x36 grey thumbnail."""+ raw = subprocess.run(["ffmpeg", "-v", "error", "-i", str(path), "-fps_mode", "passthrough", "-vf", f"scale={W}:{H},format=yuv420p,extractplanes=y",+ "-f", "rawvideo", "-"], stdout=subprocess.PIPE, check=True).stdout+ n = W * H+ return [raw[i:i + n] for i in range(0, len(raw), n)]+++def psnr(a, b):+ mse = sum((x - y) ** 2 for x, y in zip(a, b)) / len(a)+ return 99.0 if mse == 0 else 10 * math.log10(255 * 255 / mse)+++def frame_pts(path):+ out = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "frame=pts_time",+ "-of", "csv=p=0", str(path)], stdout=subprocess.PIPE, text=True, check=True).stdout+ return [float(x.split(",")[0]) for x in out.split()]+++def md5_frames(path):+ """Every decoded frame's MD5, in presentation order: a stream copy reproduces them exactly."""+ raw = subprocess.run(["ffmpeg", "-v", "error", "-i", str(path), "-map", "0:v:0", "-fps_mode", "passthrough",+ "-f", "framemd5", "-"], stdout=subprocess.PIPE, text=True, check=True).stdout+ return [line.split(",")[-1].strip() for line in raw.splitlines() if line and not line.startswith("#")]+++def steps(path):+ pts = sorted(frame_pts(path))+ return {round(b - a, 4) for a, b in zip(pts, pts[1:])}+++def stderr_of_decode(path):+ return subprocess.run(["ffmpeg", "-v", "error", "-i", str(path), "-f", "null", "-"],+ stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True).stderr.strip()+++def cut_json(*args):+ return json.loads(script("cut.py", *args, "--json").stdout)+++class CutJoinTests(unittest.TestCase):+ @classmethod+ def setUpClass(cls):+ DIR.mkdir(parents=True, exist_ok=True)+ cls.hevc = DIR / "hevc.mp4"+ if not cls.hevc.exists():+ # keyframes every 2 s (keyint 60), 4 B-frames, hvc1 as Core Media writes it+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"testsrc2=s=320x180:r={FPS}:d=12",+ "-f", "lavfi", "-i", "sine=f=440:d=12", "-c:v", "libx265",+ "-x265-params", "bframes=4:b-pyramid=1:keyint=60:min-keyint=60:scenecut=0:log-level=error",+ "-tag:v", "hvc1", "-c:a", "aac", "-shortest", cls.hevc)+ cls.hevc25 = DIR / "hevc25.mp4"+ if not cls.hevc25.exists():+ # the shape a join-length check misjudged: 25 fps, keyint 50, 4 B-frames, 48 kHz AAC+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "testsrc2=s=320x180:r=25:d=12",+ "-f", "lavfi", "-i", "sine=f=440:d=12:sample_rate=48000", "-c:v", "libx265",+ "-x265-params", "bframes=4:keyint=50:min-keyint=50:scenecut=0:log-level=error",+ "-tag:v", "hvc1", "-c:a", "aac", "-shortest", cls.hevc25)+ cls.late = DIR / "late_audio.mp4"+ if not cls.late.exists():+ # baseline profile, so a re-encoded part (x264 high) can never match a copied one+ base = DIR / "late_base.mp4"+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"testsrc2=s=320x180:r={FPS}:d=8",+ "-f", "lavfi", "-i", "sine=f=440:d=8", "-c:v", "libx264", "-profile:v", "baseline", "-g", str(FPS),+ "-c:a", "aac", base)+ sh("ffmpeg", "-y", "-v", "error", "-i", base, "-itsoffset", "0.379", "-i", base,+ "-map", "0:v", "-map", "1:a", "-c", "copy", cls.late)+ cls.wav = DIR / "tone.wav"+ if not cls.wav.exists():+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "sine=f=300:d=6:sample_rate=44100",+ "-c:a", "pcm_s16le", cls.wav)+ cls.rot = DIR / "rot.mp4"+ if not cls.rot.exists():+ # -display_rotation arrived in FFmpeg 6.0; 5.x writes the rotation as the stream's+ # rotate tag, which every probe reads the same (tests/_fixtures.py does the same)+ if subprocess.run(["ffmpeg", "-hide_banner", "-loglevel", "error", "-display_rotation", "90", "-f", "lavfi",+ "-i", "color=c=black:s=16x16:d=0.1", "-f", "null", "-"],+ stdout=subprocess.PIPE, stderr=subprocess.PIPE).returncode == 0:+ sh("ffmpeg", "-y", "-v", "error", "-display_rotation", "90", "-i", cls.hevc, "-c", "copy", cls.rot)+ else:+ sh("ffmpeg", "-y", "-v", "error", "-i", cls.hevc, "-c", "copy", "-metadata:s:v:0", "rotate=90", cls.rot)+ cls.subs = DIR / "subs.mp4"+ if not cls.subs.exists():+ srt = DIR / "subs.srt"+ srt.write_text("1\n00:00:00,500 --> 00:00:09,000\nhello\n", encoding="utf-8")+ sh("ffmpeg", "-y", "-v", "error", "-i", cls.hevc, "-i", srt, "-map", "0", "-map", "1",+ "-c", "copy", "-c:s", "mov_text", cls.subs)+ cls.noise = DIR / "hevc_noise.mp4"+ if not cls.noise.exists():+ # the same pictures with a non-periodic audio track, so a cross-correlation has one peak+ sh("ffmpeg", "-y", "-v", "error", "-i", cls.hevc, "-f", "lavfi", "-i", "anoisesrc=seed=7:d=12:a=0.3:r=48000",+ "-map", "0:v", "-map", "1:a", "-c:v", "copy", "-c:a", "aac", "-shortest", cls.noise)+ cls.offset = DIR / "hevc_offset.mp4"+ if not cls.offset.exists():+ # a source whose timestamps start at 10 s+ sh("ffmpeg", "-y", "-v", "error", "-i", cls.hevc, "-c", "copy", "-output_ts_offset", "10", cls.offset)+ cls.long = DIR / "long_audio.mp4"+ if not cls.long.exists():+ # sound that outlasts the picture by 0.3 s (a music bed padded to the container), g30+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"testsrc2=s=320x180:r={FPS}:d=6",+ "-f", "lavfi", "-i", "sine=f=440:d=6.3:sample_rate=48000", "-c:v", "libx264", "-g", "30",+ "-c:a", "aac", cls.long)+ cls.tail = DIR / "tail_audio.mp4"+ if not cls.tail.exists():+ # the same, by 20 ms: an ordinary AAC tail, under one frame+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"testsrc2=s=320x180:r={FPS}:d=6",+ "-f", "lavfi", "-i", "sine=f=440:d=6.02:sample_rate=48000", "-c:v", "libx264", "-g", "30",+ "-c:a", "aac", cls.tail)+ cls.long_offset = DIR / "long_audio_offset.mov"+ if not cls.long_offset.exists():+ # PCM, so both streams start at 10 s on every FFmpeg: a copied AAC track's priming+ # starts the file 21 ms before its video on 6.1 and not on later versions+ sh("ffmpeg", "-y", "-v", "error", "-i", cls.long, "-c:v", "copy", "-c:a", "pcm_s16le",+ "-output_ts_offset", "10", cls.long_offset)+ # the copy-join sources:+ # x264 B-frames (a closed GOP), x265 with open-gop=0, and x265's default open GOP in HLG+ x264bf = ("-c:v", "libx264", "-g", "60", "-bf", "3", "-x264-params", "scenecut=0")+ cls.h264bf = DIR / "h264bf.mp4"+ if not cls.h264bf.exists():+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"testsrc2=s=320x180:r={FPS}:d=12",+ "-f", "lavfi", "-i", "sine=f=440:d=12:sample_rate=48000", *x264bf, "-c:a", "aac", "-shortest", cls.h264bf)+ cls.hevc25c = DIR / "hevc25c.mp4"+ if not cls.hevc25c.exists():+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "testsrc2=s=320x180:r=25:d=12",+ "-f", "lavfi", "-i", "sine=f=440:d=12:sample_rate=48000", "-c:v", "libx265",+ "-x265-params", "bframes=4:keyint=50:min-keyint=50:scenecut=0:open-gop=0:log-level=error",+ "-tag:v", "hvc1", "-c:a", "aac", "-shortest", cls.hevc25c)+ cls.beep = DIR / "beep_bf.mp4"+ if not cls.beep.exists():+ # a 40 ms beep at every k + 0.5 s, so every onset has silence before it to measure from+ beep = "aevalsrc='if(between(mod(t\\,1)\\,0.5\\,0.54)\\,0.8*sin(2*PI*1000*t)\\,0)':s=48000:d=12"+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"testsrc2=s=320x180:r={FPS}:d=12",+ "-f", "lavfi", "-i", beep, *x264bf, "-c:a", "aac", "-shortest", cls.beep)+ cls.beep_pcm = DIR / "beep_pcm.mov"+ if not cls.beep_pcm.exists():+ # the same pictures with the beeps as PCM in a .mov: a copy join of it put the sound of+ # each later part off its picture (16 and 53 ms) with every frame exact+ sh("ffmpeg", "-y", "-v", "error", "-i", cls.beep, "-c:v", "copy", "-c:a", "pcm_s16le", cls.beep_pcm)+ cls.long60 = DIR / "long60.mp4"+ if not cls.long60.exists():+ # a minute of B-frame H.264, so the packet reads around a segment seek+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"testsrc2=s=64x36:r={FPS}:d=60",+ "-f", "lavfi", "-i", "sine=f=440:d=60:sample_rate=48000", *x264bf, "-c:a", "aac", "-shortest", cls.long60)+ cls.hlg = DIR / "hlg_open.mp4"+ if not cls.hlg.exists():+ # the iPhone "High Efficiency" shape: 10-bit HLG HEVC with an open GOP at every keyframe+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"testsrc2=s=320x180:r={FPS}:d=6",+ "-f", "lavfi", "-i", "sine=f=440:d=6:sample_rate=48000", "-pix_fmt", "yuv420p10le", "-c:v", "libx265",+ "-x265-params", "bframes=4:keyint=60:min-keyint=60:scenecut=0:log-level=error:"+ "colorprim=bt2020:transfer=arib-std-b67:colormatrix=bt2020nc",+ "-color_primaries", "bt2020", "-color_trc", "arib-std-b67", "-colorspace", "bt2020nc",+ "-tag:v", "hvc1", "-c:a", "aac", "-shortest", cls.hlg)+ cls.nob = DIR / "nob.mp4"+ if not cls.nob.exists():+ # H.264 with no B-frames at 30 fps, keyframes every 2 s: a copy cut in decode order is exact+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"testsrc2=s=320x180:r={FPS}:d=12",+ "-f", "lavfi", "-i", "sine=f=440:d=12:sample_rate=48000", "-c:v", "libx264", "-bf", "0", "-g", "60",+ "-x264-params", "scenecut=0", "-c:a", "aac", "-shortest", cls.nob)+ cls.nob60 = DIR / "nob60.mp4"+ if not cls.nob60.exists():+ # the iPhone "Most Compatible" shape: H.264 with no B-frames, here at 60 fps and 44.1 kHz+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "testsrc2=s=320x180:r=60:d=12",+ "-f", "lavfi", "-i", "sine=f=440:d=12:sample_rate=44100", "-c:v", "libx264", "-bf", "0", "-g", "120",+ "-x264-params", "scenecut=0", "-c:a", "aac", "-shortest", cls.nob60)+ cls.src_frames = gray_frames(cls.hevc)+ cls.long_frames = gray_frames(cls.long)++ def assertFrameIs(self, frame, expected, msg="", src_frames=None):+ """`frame` is source frame `expected`: its best match within 5 frames, at 40 dB or more,+ and 10 dB clear of the next best."""+ src_frames = self.src_frames if src_frames is None else src_frames+ lo, hi = max(0, expected - 5), min(len(src_frames), expected + 6)+ scores = sorted(((psnr(frame, src_frames[i]), i) for i in range(lo, hi)), reverse=True)+ (best, idx), (second, _) = scores[0], scores[1]+ self.assertEqual(idx, expected, f"{msg}: best match {idx} at {best:.1f} dB")+ self.assertGreaterEqual(best, 40.0, msg)+ self.assertGreaterEqual(best - second, 10.0, msg)++ def assertFrameExact(self, frame, expected, msg=""):+ """A stream copy decodes bit-identically: `frame` is source frame `expected` exactly."""+ self.assertEqual(psnr(frame, self.src_frames[expected]), 99.0, msg)++ # ------------------------------------------------------------------ single-segment copies+ def test_an_mp4_copy_starts_its_picture_at_the_requested_time(self):+ """Core Media HEVC once gave 3.7 s of sound with no picture: make_zero showed the keyframe's+ pre-roll. With --edit-list the copy keeps its edit list, which hides it."""+ out = DIR / "copy_4.3.mp4"+ data = cut_json(self.hevc, "--start", "4.3", "--duration", "3", "--tolerance", "-1", "--edit-list", "-o", out)+ self.assertEqual(data["mode"], "copy")+ self.assertEqual(data["reencode_reason"], [])+ self.assertTrue(data["edit_list"])+ self.assertTrue(data["keyframe_snapped"], "a stream copy end to end")+ self.assertFalse(data["start_snapped"])+ self.assertAlmostEqual(data["stored_preroll_seconds"], 0.3, places=3, msg="4.3 s back to the keyframe at 4.0")+ self.assertIn("edit list", " ".join(data["notes"]))+ self.assertLessEqual(abs(data["av_start_skew_seconds"]), 1 / FPS)+ frames = gray_frames(out)+ self.assertFrameExact(frames[0], 129, "first presented frame is the source frame at 4.3 s")+ # the end still lands on a packet boundary: bounded, and the last frame is the source's own+ over = probe(str(out))["video"]["duration"] - 3.0+ self.assertGreaterEqual(over, -1e-6)+ self.assertLessEqual(over, 6 / FPS)+ # the frames past the requested end are not contiguous (B-frames whose references were not+ # copied are dropped: measured 218, 221, 223), so the last one is located by its own pts+ last_pts = frame_pts(out)[-1]+ self.assertFrameExact(frames[-1], 129 + round(last_pts * FPS), "last frame, at its own presented time")++ def test_a_dry_run_mp4_copy_reports_the_edit_list_it_plans(self):+ data = cut_json(self.hevc, "--start", "4.3", "--duration", "2", "--dry-run", "--edit-list", "-o", DIR / "never.mp4")+ self.assertTrue(data["edit_list"])+ self.assertIsNone(data["start_snapped"], "a planned copy has not landed anywhere yet")+ self.assertEqual(data["commands"][0].count("-avoid_negative_ts"), 0)++ def test_an_mp4_copy_shifts_to_zero_unless_the_edit_list_is_asked_for(self):+ """The default is every 2.x release's: -avoid_negative_ts make_zero, no edit list, so the+ picture starts at the keyframe and the report says the start moved. The A/V start skew+ this can leave is reported, not repaired, and the note names both remedies."""+ data = cut_json(self.hevc, "--start", "4.3", "--duration", "2", "--dry-run", "-o", DIR / "never.mp4")+ self.assertIn("-avoid_negative_ts make_zero", data["commands"][0])+ self.assertFalse(data["edit_list"])+ self.assertIsNone(data["stored_preroll_seconds"])+ out = DIR / "copy_4.3_default.mp4"+ data = cut_json(self.hevc, "--start", "4.3", "--duration", "3", "--tolerance", "-1", "-o", out)+ self.assertEqual((data["mode"], data["edit_list"], data["stored_preroll_seconds"]), ("copy", False, None))+ self.assertTrue(data["start_snapped"], "the picture starts at the keyframe at 4.0, 0.3 s early")+ self.assertFalse(any("pre-roll is stored" in n for n in data["notes"]), data["notes"])+ self.assertFrameExact(gray_frames(out)[0], 120, "make_zero shows the keyframe's pre-roll")+ skew = data["av_start_skew_seconds"]+ self.assertIsNotNone(skew)+ if abs(skew) > 0.1:+ self.assertTrue(any("--edit-list" in n and "--accurate" in n for n in data["notes"]), data["notes"])++ def test_an_edit_listed_copy_past_tolerance_blames_the_end_not_the_start(self):+ """The start is exact, so offering another --start as the lossless alternative would be+ wrong: only the end overshoots (+4 to +5 frames on this fixture)."""+ out = DIR / "copy_tight.mp4"+ proc = script("cut.py", self.hevc, "--start", "4.3", "--duration", "3", "--tolerance", "0.05", "--edit-list", "-o", out, "--json")+ data = json.loads(proc.stdout)+ self.assertEqual(data["reencode_reason"], ["tolerance"])+ self.assertIsNone(data["lossless_alternative"])+ self.assertIsNone(data["nearest_keyframes"])+ self.assertIn("starts where asked", proc.stderr)++ def test_an_off_grid_start_presents_the_next_source_frame(self):+ out = DIR / "copy_4.31.mp4"+ data = cut_json(self.hevc, "--start", "4.31", "--duration", "2", "--tolerance", "-1", "--edit-list", "-o", out)+ self.assertFalse(data["start_snapped"])+ self.assertFrameExact(gray_frames(out)[0], 130, "the first frame at or after 4.31 s is 4.333 s")++ def test_a_start_just_before_a_keyframe_is_reported_as_snapped(self):+ """The demuxer seeks by decode time: the keyframe at 10.0 (dts 9.833) is taken for 9.9, so+ the copy's picture starts three frames late. That is a snap, and it says so."""+ out = DIR / "copy_9.9.mp4"+ data = cut_json(self.hevc, "--start", "9.9", "--duration", "1", "--tolerance", "-1", "--edit-list", "-o", out)+ self.assertEqual(data["mode"], "copy")+ self.assertTrue(data["start_snapped"])+ self.assertIsNone(data["stored_preroll_seconds"])+ self.assertFrameExact(gray_frames(out)[0], 300)++ def test_a_source_that_starts_at_ten_seconds_cuts_the_same_frame(self):+ out = DIR / "copy_offset.mp4"+ data = cut_json(self.offset, "--start", "4.3", "--duration", "2", "--tolerance", "-1", "--edit-list", "-o", out)+ self.assertTrue(data["edit_list"])+ # --start is relative to the file's start and packet times are absolute: the report must+ # still find the keyframe at 4.0 (14.0 in the file)+ self.assertFalse(data["start_snapped"])+ self.assertAlmostEqual(data["stored_preroll_seconds"], 0.3, places=3)+ self.assertFrameExact(gray_frames(out)[0], 129)+ # cutting that result again: the VFR sampler must read its stored pre-roll, or a seek to its+ # start skips the keyframe (negative pts) and finds too few frames to judge+ again = cut_json(out, "--start", "0.5", "--duration", "1", "--vfr-guard", "sampled", "--dry-run",+ "-o", DIR / "never_again.mp4")+ self.assertEqual(again["vfr_check"]["measured"], "sampled_cfr")++ def test_an_edit_listed_source_cut_again_starts_where_asked(self):+ first = DIR / "copy_again_1.mp4"+ cut_json(self.hevc, "--start", "4.3", "--duration", "4", "--tolerance", "-1", "--edit-list", "-o", first)+ out = DIR / "copy_again_2.mp4"+ data = cut_json(first, "--start", "1", "--duration", "2", "--tolerance", "-1", "--edit-list",+ "--vfr-guard", "sampled", "-o", out)+ # the VFR sampler reads the stored pre-roll too (a seek to 0 skipped its keyframe and found+ # too few frames to judge, forcing a re-encode)+ self.assertEqual((data["vfr_check"]["measured"], data["mode"]), ("sampled_cfr", "copy"))+ self.assertFalse(data["start_snapped"])+ self.assertFrameExact(gray_frames(out)[0], 159, "1 s into a cut that starts at 4.3 s")++ def test_the_copy_keeps_audio_in_step_with_the_picture(self):+ out = DIR / "copy_noise.mp4"+ cut_json(self.noise, "--start", "4.3", "--duration", "2", "--tolerance", "-1", "--edit-list", "-o", out)+ rate = 8000++ def pcm(path, *pre):+ raw = subprocess.run(["ffmpeg", "-v", "error", *pre, "-i", str(path), "-t", "0.5", "-ac", "1", "-ar", str(rate),+ "-f", "s16le", "-"], stdout=subprocess.PIPE, check=True).stdout+ return [int.from_bytes(raw[i:i + 2], "little", signed=True) for i in range(0, len(raw) - 1, 2)]+ # the source from 0.1 s before the cut, decoded the same way; the output's first 0.2 s+ # should sit 0.1 s (800 samples) into it+ ref = pcm(self.noise, "-ss", "4.2")+ got = pcm(out)[:int(0.2 * rate)]++ def corr(lag):+ return sum(a * b for a, b in zip(got, ref[lag:lag + len(got)]))+ lag = max(range(700, 901), key=corr)+ self.assertLessEqual(abs(lag - 800), 8, f"audio is {lag - 800} samples off the picture (±1 ms allowed)")++ def test_an_m4v_copy_keeps_its_edit_list_like_mp4_and_mov(self):+ """CodeRabbit on #313 read .m4v as outside the edit-list contract. It is the same MP4 family+ as .mp4/.mov everywhere else in the repo, and its copy keeps the edit list too (H.264;+ the ipod muxer behind .m4v takes no HEVC)."""+ src = DIR / "h264_bf_for_m4v.mp4"+ if not src.exists():+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "testsrc2=s=320x180:r=30:d=8",+ "-f", "lavfi", "-i", "sine=f=440:d=8", "-c:v", "libx264", "-bf", "3", "-g", "60", "-c:a", "aac",+ "-shortest", src)+ seen = {}+ for ext in ("mp4", "m4v", "mov"):+ data = cut_json(src, "--start", "3.3", "--end", "5.3", "--edit-list", "-o", DIR / f"el_family.{ext}")+ seen[ext] = (data["mode"], data["edit_list"], data["stored_preroll_seconds"], data["start_snapped"])+ self.assertEqual(seen["mp4"][:2], ("copy", True), seen)+ self.assertEqual(seen["m4v"], seen["mp4"], seen)+ self.assertEqual(seen["mov"], seen["mp4"], seen)+ self.assertGreater(seen["m4v"][2], 0.5, "the keyframe's pre-roll is stored behind the edit list")++ def test_an_unmeasured_start_is_never_reported_as_exact(self):+ """No packet at or after the start in the probed window: the start is unknown, so it is+ not claimed exact and no pre-roll is reported."""+ self.assertEqual(cut.copy_presentation(4.3, (4.0, 3.9, None), True, 30.0),+ {"start_snapped": True, "stored_preroll_seconds": None})+ self.assertEqual(cut.copy_presentation(4.3, (4.0, 3.9, 4.3), True, 30.0),+ {"start_snapped": False, "stored_preroll_seconds": 0.3})++ def test_judging_a_copy_by_its_video_is_noted_even_when_it_then_reencodes(self):+ """The late-audio source's container outlasts its video by 0.379 s, so an edit-listed copy+ is judged by the video; that explanation survives the tolerance re-encode that follows+ (--tolerance 0 re-encodes every copy, since abs(delta) >= 0). Without --edit-list the copy+ is judged by the container, as in every 2.x release."""+ # to the end of the file, where the late audio runs 0.379 s past the video+ data = cut_json(self.late, "--start", "0.5", "--tolerance", "0", "--edit-list",+ "-o", DIR / "late_judged.mp4")+ self.assertIn("tolerance", data["reencode_reason"])+ self.assertTrue(any("judged by the video" in n for n in data["notes"]), data["notes"])+ data = cut_json(self.late, "--start", "0.5", "--tolerance", "0", "-o", DIR / "late_judged_default.mp4")+ self.assertIn("tolerance", data["reencode_reason"])+ self.assertFalse(any("judged by the video" in n for n in data["notes"]), data["notes"])++ def test_a_millisecond_off_keyframe_start_is_seeked_to_the_microsecond(self):+ """A keyframe at 61/30 = 2.0333 s: --start 00:00:02:01@30 is that frame, but -ss rounded+ to the millisecond (2.033) fell before it, so the copy snapped back to the keyframe at 0+ and re-encoded. -ss and -t now carry six decimals, and the copy starts on the keyframe."""+ src = DIR / "g61.mp4"+ if not src.exists():+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"testsrc2=s=320x180:r={FPS}:d=8",+ "-f", "lavfi", "-i", "sine=f=440:d=8:sample_rate=48000", "-c:v", "libx264", "-g", "61", "-bf", "0",+ "-x264-params", "scenecut=0", "-c:a", "aac", "-shortest", src)+ dry = cut_json(src, "--start", "00:00:02:01@30", "--end", "4", "--dry-run", "-o", DIR / "never_g61.mkv")+ self.assertIn("-ss 2.033333", dry["commands"][0])+ out = DIR / "copy_g61.mkv"+ data = cut_json(src, "--start", "00:00:02:01@30", "--end", "4", "-o", out)+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ self.assertFalse(data["start_snapped"], "the start is the keyframe at 2.0333 s")+ self.assertEqual(md5_frames(out)[0], md5_frames(src)[61])++ def test_av_skew_names_the_edit_list_only_where_it_would_help(self):+ meta = {"video": {"start_time": 0.0, "fps": 30.0}, "audio": {"start_time": -0.122}}+ self.assertNotIn("--edit-list", cut.av_skew(meta)[1])+ self.assertIn("--edit-list", cut.av_skew(meta, True)[1])+ self.assertEqual(cut.av_skew(meta, True)[0], -0.122)++ def test_a_source_whose_audio_starts_late_is_not_reported_as_a_skewed_cut(self):+ """The late-audio source's sound starts 0.355 s after its picture by design: a cut from 0+ keeps that, and is not a stream copy that began on packets the streams do not share. The+ skew is still reported; the warning compares it with the source's own at the start."""+ for extra in ((), ("--accurate",)):+ data = cut_json(self.late, "--start", "0", "--end", "2", "--tolerance", "-1", *extra,+ "-o", DIR / f"late_skew{len(extra)}.mp4")+ self.assertGreater(data["av_start_skew_seconds"], 0.3, extra)+ self.assertFalse(any("do not share" in n for n in data["notes"]), (extra, data["notes"]))+ self.assertAlmostEqual(cut.source_skew(str(self.late), probe(str(self.late)), 0.0), 0.355, delta=0.03)+ self.assertEqual(cut.source_skew(str(self.late), probe(str(self.late)), 4.3), 0.0)+ skew, note = cut.av_skew({"video": {"start_time": 0.0, "fps": 30.0}, "audio": {"start_time": 0.5}}, expected=0.5)+ self.assertEqual((skew, note), (0.5, None))+ self.assertIn("in the source there", cut.av_skew({"video": {"start_time": 0.0, "fps": 30.0},+ "audio": {"start_time": 0.0}}, expected=0.5)[1])++ def test_a_reencode_never_carries_the_copy_skew_note(self):+ """The note is about a stream copy that began on packets the two streams do not share. A+ re-encode starts both streams where the source has them (the re-cut pads the audio to each+ segment's origin), so its skew is reported without the note -- which told an --accurate+ run to re-run with --accurate."""+ data = cut_json(self.late, "--segments", "0-2,4-6", "--accurate", "-o", DIR / "late_accurate_join.mp4")+ self.assertEqual(data["mode"], "accurate")+ self.assertIsNotNone(data["av_start_skew_seconds"])+ self.assertFalse(any("do not share" in n for n in data["notes"]), data["notes"])++ def test_a_snapped_copy_is_compared_with_the_source_where_it_landed(self):+ """--start 0.3 snaps back to the keyframe at 0 and writes the copy --start 0 writes, sound+ 0.379 s after the picture as in the source there: no note. It was compared with the source+ at 0.3 s and told it began on packets the streams do not share."""+ a = cut_json(self.late, "--start", "0", "--end", "4", "-o", DIR / "late_from0.mp4")+ b = cut_json(self.late, "--start", "0.3", "--end", "4", "-o", DIR / "late_from03.mp4")+ self.assertEqual((b["mode"], b["start_snapped"]), ("copy", True))+ self.assertAlmostEqual(a["av_start_skew_seconds"], b["av_start_skew_seconds"], delta=0.001)+ self.assertFalse(any("do not share" in n for n in a["notes"] + b["notes"]), (a["notes"], b["notes"]))++ def test_av_skew_is_measured_and_named_past_the_threshold(self):+ skew, note = cut.av_skew({"video": {"start_time": 0.0, "fps": 30.0}, "audio": {"start_time": 0.5}})+ self.assertEqual(skew, 0.5)+ self.assertIn("--accurate", note)+ self.assertEqual(cut.av_skew({"video": {"start_time": 0.0, "fps": 30.0}, "audio": {"start_time": 0.02}}), (0.02, None))+ self.assertEqual(cut.av_skew({"video": {"start_time": 0.0, "fps": 30.0}}), (None, None))++ def test_accurate_keeps_the_frames_before_a_keyframe(self):+ """--accurate seeked straight to the start, and by decode time -ss 9.9 lands on the+ keyframe at 10.0; the three frames before it were lost."""+ out = DIR / "accurate_9.9.mp4"+ data = cut_json(self.hevc, "--start", "9.9", "--end", "10.1", "--accurate", "-o", out)+ self.assertEqual(data["mode"], "accurate")+ frames = gray_frames(out)+ self.assertEqual(len(frames), 6)+ self.assertFrameIs(frames[0], 297, "first frame of 9.9-10.1")+ self.assertFrameIs(frames[-1], 302, "last frame of 9.9-10.1")++ # ------------------------------------------------------------------ the source codec+ def test_a_reencoded_cut_of_an_sdr_hevc_source_stays_hevc(self):+ """A re-encode goes through x264 whatever the SDR source, so trimming an iPhone HEVC+ clip with --accurate hands back H.264. With --keep-hevc it keeps HEVC, 8-bit and tagged BT.709."""+ out = DIR / "accurate_hevc.mp4"+ data = cut_json(self.hevc, "--start", "4.3", "--duration", "1", "--accurate", "--keep-hevc", "--preset", "ultrafast",+ "-o", out)+ self.assertTrue(data["reencoded"])+ v = probe(str(out))["video"]+ self.assertEqual(v["codec"], "hevc")+ self.assertEqual(v["pix_fmt"], "yuv420p")+ self.assertEqual((v["color_primaries"], v["color_transfer"], v["color_space"]), ("bt709", "bt709", "bt709"))+ self.assertEqual(stderr_of_decode(out), "")++ def test_codec_h264_still_overrides_the_source_codec(self):+ out = DIR / "accurate_h264.mp4"+ data = cut_json(self.hevc, "--start", "4.3", "--duration", "1", "--codec", "h264", "--keep-hevc",+ "--preset", "ultrafast", "-o", out)+ self.assertIn("codec", data["reencode_reason"])+ self.assertEqual(probe(str(out))["video"]["codec"], "h264")++ def test_a_reencoded_cut_of_an_sdr_hevc_source_is_h264_unless_keep_hevc_is_asked_for(self):+ """The 2.x default, pinned: a re-encode of an SDR source is x264 whatever its codec (as on+ main); --keep-hevc is opt-in. The dry run plans the same encoders the real runs use."""+ out = DIR / "accurate_hevc_default.mp4"+ data = cut_json(self.hevc, "--start", "4.3", "--duration", "1", "--accurate", "--preset", "ultrafast", "-o", out)+ self.assertEqual(data["reencode_reason"], ["requested"])+ self.assertEqual(probe(str(out))["video"]["codec"], "h264")+ self.assertEqual(stderr_of_decode(out), "")+ plan = cut_json(self.hevc, "--start", "4.3", "--duration", "1", "--accurate", "--dry-run", "-o", DIR / "plan_hevc.mp4")+ self.assertIn("libx264", " ".join(plan["commands"]))+ self.assertNotIn("libx265", " ".join(plan["commands"]))+ plan = cut_json(self.hevc, "--start", "4.3", "--duration", "1", "--accurate", "--keep-hevc", "--dry-run",+ "-o", DIR / "plan_hevc.mp4")+ self.assertIn("libx265", " ".join(plan["commands"]))++ # ------------------------------------------------------------------ the join fallback+ def test_mismatched_parts_are_recut_from_the_source_with_exact_boundaries(self):+ """The live bug: a copied HEVC segment next to a re-encoded one used to be joined by the+ concat demuxer -- H.264 after HEVC decoded with errors from a run that exited 0. The join+ now re-cuts both segments from the source in one encode."""+ out = DIR / "mixed.mp4"+ # 0-2 starts on the keyframe at 0 and copies; 5.1 snaps back to the keyframe at 4, 1.1 s+ # past the 0.3 s tolerance, so it re-encodes+ data = cut_json(self.hevc, "--segments", "0-2,5.1-7", "--tolerance", "0.3", "-o", out)+ self.assertEqual(data["reencode_reason"], ["tolerance", "concat_fallback"])+ self.assertTrue(data["reencoded"])+ self.assertEqual(data["mode"], "hybrid")+ self.assertEqual(data["segment_precision"], ["frame", "frame"])+ self.assertEqual((data["precision"], data["least_exact_precision"]), ("frame", "frame"))+ self.assertFalse(data["keyframe_snapped"])+ self.assertFalse(data["start_snapped"], "every segment was re-cut, so every start is where asked")+ self.assertEqual(stderr_of_decode(out), "")+ self.assertEqual(probe(str(out))["video"]["codec"], "h264", "the re-cut join is x264 unless --keep-hevc asks")+ pts = frame_pts(out)+ self.assertEqual(len(pts), 60 + 57)+ deltas = [round(b - a, 4) for a, b in zip(pts, pts[1:])]+ self.assertEqual(set(deltas), {round(1 / FPS, 4)}, "no pts gap at the join")+ m = probe(str(out))+ self.assertLessEqual(abs(m["video"]["duration"] - m["audio"]["duration"]), 1 / FPS + 0.03)+ frames = gray_frames(out)+ self.assertFrameIs(frames[0], 0, "first frame of segment 0")+ self.assertFrameIs(frames[59], 59, "last frame of segment 0")+ self.assertFrameIs(frames[60], 153, "first frame of segment 1 (5.1 s)")+ self.assertFrameIs(frames[116], 209, "last frame of segment 1")++ def test_a_delayed_audio_track_keeps_its_offset_through_the_fallback(self):+ out = DIR / "late_join.mp4"+ data = cut_json(self.late, "--segments", "0-2,4.5-6", "--tolerance", "0.3", "-o", out)+ self.assertIn("concat_fallback", data["reencode_reason"], "the premise: the parts must not match")+ log = subprocess.run(["ffmpeg", "-v", "info", "-i", str(out), "-af", "silencedetect=n=-40dB:d=0.05",+ "-f", "null", "-"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True).stderr+ starts = [float(v) for v in re.findall(r"silence_start: (-?[0-9.]+)", log)]+ ends = [float(v) for v in re.findall(r"silence_end: (-?[0-9.]+)", log)]+ self.assertTrue(starts and ends, log)+ self.assertAlmostEqual(starts[0], 0.0, delta=0.02)+ self.assertAlmostEqual(ends[0], 0.379, delta=0.02)+ m = probe(str(out))+ self.assertLessEqual(abs(m["video"]["duration"] - m["audio"]["duration"]), 1 / FPS + 0.03)++ # ------------------------------------------------------------------ a segment past the video's end+ def assertHeldJoin(self, out, data):+ """`--segments 4-6.3,0-2` of long_audio: 2.3 s then 2 s, with no hole. Output frames 0-59+ are source 120-179, 60-68 hold source frame 179 for the sound that runs on, and 69-128 are+ source 0-59."""+ pts = frame_pts(out)+ self.assertEqual(len(pts), 69 + 60, data.get("notes"))+ self.assertEqual({round(b - a, 4) for a, b in zip(pts, pts[1:])}, {round(1 / FPS, 4)}, "no hole in the video")+ frames = gray_frames(out)++ def best(frame, candidates):+ return max(candidates, key=lambda i: psnr(frame, self.long_frames[i]))+ self.assertEqual(best(frames[0], range(115, 126)), 120)+ for i in (59, 60, 64, 68):+ self.assertEqual(best(frames[i], range(170, 180)), 179, f"output frame {i} holds the last picture")+ self.assertGreaterEqual(psnr(frames[i], self.long_frames[179]), 35.0)+ self.assertEqual(best(frames[69], range(0, 6)), 0, "the next segment starts on its own first frame")+ self.assertEqual(best(frames[128], range(54, 60)), 59)+ self.assertIn("concat_fallback", data["reencode_reason"])++ def test_a_segment_past_the_video_end_holds_its_last_frame_in_a_copy_join(self):+ """The copy join placed the next segment after the 0.3 s of sound with no picture, leaving a+ 0.355 s hole in the video, and reported mode copy. A copy cannot add a frame, so the join+ is re-cut from the source with the last frame held for the sound."""+ out = DIR / "held_copy.mp4"+ data = cut_json(self.long, "--segments", "4-6.3,0-2", "--vfr-guard", "sampled", "-o", out)+ self.assertEqual(data["mode"], "hybrid")+ self.assertTrue(any("past the end of the video" in n for n in data["notes"]), data["notes"])+ self.assertNotIn("vfr_check", data, "a held join cannot copy, so the frame timing is not sampled")+ self.assertHeldJoin(out, data)++ def test_a_repeat_of_a_held_segment_in_last_place_is_not_held(self):+ """The hold is decided by position: the same range twice, first and last, holds only the+ first. 69 + 60 + 60 frames, not 69 + 60 + 69."""+ out = DIR / "held_repeat.mp4"+ cut_json(self.long, "--segments", "4-6.3,0-2,4-6.3", "--accurate", "-o", out)+ self.assertEqual(len(frame_pts(out)), 69 + 60 + 60)++ def test_a_segment_past_the_video_end_holds_its_last_frame_when_accurate(self):+ """--accurate re-encoded each part and then copy-joined them, with the same hole."""+ out = DIR / "held_accurate.mp4"+ data = cut_json(self.long, "--segments", "4-6.3,0-2", "--accurate", "-o", out)+ self.assertEqual(data["mode"], "accurate")+ self.assertHeldJoin(out, data)++ def test_the_video_end_is_measured_from_the_files_own_start(self):+ """A source whose timestamps start at 10 s: stream start_time is raw, segment times are+ relative to the file, so the video's end is 6.0 here, not 16.0."""+ out = DIR / "held_offset.mp4"+ data = cut_json(self.long_offset, "--segments", "4-6.3,0-2", "--accurate", "-o", out)+ self.assertHeldJoin(out, data)++ def test_a_sound_tail_under_a_frame_ends_the_segment_with_its_picture(self):+ """20 ms of sound past the picture is trimmed, not held for: a 60 + 60 frame join with no+ fractional hole, and the trim is named. requested_segments keeps what was asked (clamped+ to the media's duration, as in every 2.x release); duration_delta_seconds shows the trim."""+ out = DIR / "tail_trim.mp4"+ data = cut_json(self.tail, "--segments", "4-6.02,0-2", "--accurate", "-o", out)+ pts = frame_pts(out)+ self.assertEqual(len(pts), 120)+ self.assertEqual({round(b - a, 4) for a, b in zip(pts, pts[1:])}, {round(1 / FPS, 4)})+ self.assertEqual(data["requested_segments"][0], [4.0, 6.02])+ self.assertAlmostEqual(data["requested_duration"], 4.02, places=6)+ self.assertAlmostEqual(data["expected_duration"], 4.02, places=6)+ # the trim shows in the delta against the request (120 frames are 4.0 s against 4.02 s+ # asked), give or take an AAC frame of the joined sound, which FFmpeg versions pad differently+ self.assertAlmostEqual(data["duration_delta_seconds"], data["output_duration"] - 4.02, places=6)+ self.assertLess(abs(data["duration_delta_seconds"]), 1 / FPS + 1024 / 48000)+ self.assertTrue(any("ends with the video" in n for n in data["notes"]), data["notes"])++ def test_an_accurate_join_has_no_hole_at_its_joins(self):+ """--accurate used to re-encode each part on its own and copy-join them: each part's AAC ran+ an encoder frame past its picture and the concat demuxer placed the next part after it, a+ 23 ms hole at every join of every --accurate --segments run. One encode through the concat+ filter has none, and it is what was asked for, not a fallback."""+ out = DIR / "accurate_join.mp4"+ data = cut_json(self.hevc, "--segments", "0-2,4-6", "--accurate", "-o", out)+ self.assertEqual(data["reencode_reason"], ["requested"])+ self.assertEqual(data["mode"], "accurate")+ pts = frame_pts(out)+ self.assertEqual(len(pts), 120)+ self.assertEqual({round(b - a, 4) for a, b in zip(pts, pts[1:])}, {round(1 / FPS, 4)})+ frames = gray_frames(out)+ self.assertFrameIs(frames[59], 59, "last frame of segment 0")+ self.assertFrameIs(frames[60], 120, "first frame of segment 1 (4.0 s)")++ def test_the_last_segment_past_the_video_end_is_left_alone(self):+ """No join follows the last segment, so its sound-only tail is what the source had: no hold,+ no pre-check fallback."""+ out = DIR / "held_last.mp4"+ data = cut_json(self.long, "--segments", "0-2,4-6.3", "--accurate", "-o", out)+ self.assertNotIn("concat_fallback", data["reencode_reason"])+ self.assertFalse(any("past the end of the video" in n for n in data["notes"]))+ self.assertEqual(data["requested_segments"][1], [4.0, 6.3])+ self.assertEqual(len(frame_pts(out)), 60 + 60, "the picture ends where the source's does; no frame is held")++ def test_a_rotated_source_joins_in_display_orientation(self):+ out = DIR / "rot_join.mp4"+ data = cut_json(self.rot, "--segments", "0-2,5.1-7", "--tolerance", "0.3", "-o", out)+ self.assertIn("concat_fallback", data["reencode_reason"])+ m = probe(str(out))+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (180, 320))+ self.assertEqual(m["video"]["rotation"], 0)+ self.assertEqual(len(frame_pts(out)), 60 + 57)+ self.assertEqual(stderr_of_decode(out), "")++ def test_subtitles_are_dropped_by_the_fallback_and_reported(self):+ out = DIR / "subs_join.mp4"+ data = cut_json(self.subs, "--segments", "0-2,5.1-7", "--tolerance", "0.3", "-o", out)+ self.assertIn("concat_fallback", data["reencode_reason"])+ self.assertTrue(data["dropped_non_av_streams"])+ self.assertEqual(probe(str(out))["subtitle_streams"], 0)++ def test_more_segments_than_one_call_takes_are_joined_in_chunks(self):+ out = DIR / "many.mp4"+ # 40 segments of 0.2 s; those not on a keyframe re-encode, so the parts are mixed+ segs = ",".join(f"{i * 0.3:.1f}-{i * 0.3 + 0.2:.1f}" for i in range(40))+ data = cut_json(self.hevc, "--segments", segs, "--tolerance", "0.1", "--keep-hevc", "--preset", "ultrafast", "-o", out)+ self.assertIn("concat_fallback", data["reencode_reason"])+ self.assertEqual(sum("concat=n=32:" in c for c in data["commands"]), 1)+ self.assertEqual(sum("concat=n=8:" in c for c in data["commands"]), 1)+ self.assertEqual(stderr_of_decode(out), "")+ self.assertEqual(len(frame_pts(out)), 40 * 6)+ starts = dict(line.split(",")[:2] for line in subprocess.run(+ ["ffprobe", "-v", "error", "-show_entries", "stream=codec_type,start_time", "-of", "csv=p=0", str(out)],+ stdout=subprocess.PIPE, text=True, check=True).stdout.split())+ self.assertLessEqual(abs(float(starts["video"]) - float(starts["audio"])), 0.005, "chunking adds no A/V offset")+ tag = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "stream=codec_tag_string",+ "-of", "csv=p=0", str(out)], stdout=subprocess.PIPE, text=True, check=True).stdout.strip()+ self.assertEqual(tag, "hvc1", "the Matroska chunks' HEVC keeps the tag Apple players need")++ def test_a_chunked_hdr_join_keeps_the_hvc1_tag_by_default(self):+ """A defect fix on by default: an HDR source re-cuts as HEVC Main10 with no flag, and a join+ of more than 32 segments copied its Matroska chunks into the MP4 as hev1, which Apple+ players refuse. The final copy restates the chunks' hvc1."""+ out = DIR / "many_hlg.mp4"+ segs = ",".join(f"{i * 0.15:.2f}-{i * 0.15 + 0.1:.2f}" for i in range(36))+ data = cut_json(self.hlg, "--segments", segs, "--preset", "ultrafast", "-o", out)+ self.assertIn("concat_fallback", data["reencode_reason"])+ self.assertEqual(sum("concat=n=32:" in c for c in data["commands"]), 1, "the join was chunked")+ self.assertEqual(stderr_of_decode(out), "")+ stream = json.loads(subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",+ "stream=codec_name,codec_tag_string,pix_fmt,color_transfer", "-of", "json",+ str(out)], stdout=subprocess.PIPE, text=True, check=True).stdout)["streams"][0]+ self.assertEqual((stream["codec_name"], stream["codec_tag_string"], stream["pix_fmt"], stream["color_transfer"]),+ ("hevc", "hvc1", "yuv420p10le", "arib-std-b67"))++ # ------------------------------------------------------------------ an exact stream-copy join+ def test_keyframe_aligned_bframe_segments_join_frame_exact(self):+ """The copy join used to add the next GOP's keyframe and P-frame to every part (an+ input -t stops in decode order) and show them: 186 frames for 180, with holes, reported as+ mode copy. Each part now ends at its end keyframe's dts and keeps its edit list."""+ out = DIR / "keyframe_join.mp4"+ data = cut_json(self.h264bf, "--segments", "0-2,4-6,8-10", "-o", out)+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ self.assertEqual(data["segment_precision"], ["packet", "packet", "packet"])+ src = md5_frames(self.h264bf)+ self.assertEqual(md5_frames(out), src[0:60] + src[120:180] + src[240:300])+ self.assertEqual(steps(out), {round(1 / FPS, 4)})+ self.assertEqual((data["join_check"]["packets"], data["join_check"]["expected_packets"]), (180, 180))+ self.assertTrue(data["join_check"]["ok"])+ self.assertEqual(data["segment_end_snap_seconds"], [0.0, 0.0, 0.0])++ def test_closed_gop_hevc_segments_join_frame_exact(self):+ """The same on HEVC with a closed GOP: 150 frames, each the source's own."""+ out = DIR / "keyframe_join_hevc.mp4"+ data = cut_json(self.hevc25c, "--segments", "0-2,4-6,8-10", "-o", out)+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ self.assertEqual(probe(str(out))["video"]["codec"], "hevc")+ src = md5_frames(self.hevc25c)+ self.assertEqual(md5_frames(out), src[0:50] + src[100:150] + src[200:250])+ self.assertEqual(steps(out), {0.04})+ self.assertTrue(data["join_check"]["ok"])++ def test_a_60fps_source_without_bframes_stays_an_exact_copy(self):+ """With no B-frames each part's AAC runs up to one audio frame (23 ms at 44.1 kHz) past its+ picture, and the concat demuxer places the next part after it, so the frame before a join+ shows longer than 1/60 s -- past half a frame, which a stricter check would have sent to a+ re-encode. The frames are the source's own, as a copy join of this footage always was."""+ out = DIR / "nob60_join.mp4"+ data = cut_json(self.nob60, "--segments", "0-2,4-6,8-10", "-o", out)+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ src = md5_frames(self.nob60)+ self.assertEqual(md5_frames(out), src[0:120] + src[240:360] + src[480:600])+ self.assertTrue(data["join_check"]["ok"])+ self.assertGreater(data["join_check"]["max_step_seconds"], 1.5 / 60, "the premise: a step past half a frame")++ def test_a_matroska_join_is_checked_and_recut_when_it_is_wrong(self):+ """Matroska parts keep the old cut (make_zero, -t end-start, no end snap), which carries the+ next GOP's keyframe and P-frame into each part. Nothing predicts that; the join check+ measures it, and the join is re-cut, keeping the failed measurement."""+ out = DIR / "mkv_join.mkv"+ data = cut_json(self.h264bf, "--segments", "0-2,4-6,8-10", "-o", out)+ self.assertIn("concat_fallback", data["reencode_reason"])+ self.assertFalse(data["join_check"]["ok"])+ self.assertEqual(data["join_check"]["expected_packets"], 180)+ # the documented keys only: no internal audio_ok left behind when the audio was not checked+ self.assertEqual(set(data["join_check"]), {"packets", "expected_packets", "max_step_seconds", "audio_offset_ms",+ "audio_parts_checked", "ok"})+ self.assertIsNone(data["join_check"]["audio_offset_ms"])+ self.assertTrue(any("checked and failed" in n for n in data["notes"]), data["notes"])+ self.assertIsNone(data["segment_end_snap_seconds"])+ self.assertEqual(len(frame_pts(out)), 180)+ for step in steps(out): # Matroska stores whole milliseconds: 33 or 34+ self.assertAlmostEqual(step, 1 / FPS, delta=0.001)++ def test_an_open_gop_source_is_joined_by_one_reencode(self):+ """In an open GOP the frames just before a keyframe decode after it, so a part cut in+ decode order loses them (144 frames for 150). The join was 672 ms long and said mode+ copy; it is now re-cut from the source, with the right frames and no gaps."""+ out = DIR / "open_gop_join.mp4"+ data = cut_json(self.hevc25, "--segments", "0-2,4-6,8-10", "-o", out)+ self.assertTrue(data["reencoded"])+ self.assertIn("concat_fallback", data["reencode_reason"])+ self.assertTrue(any("open GOP" in n for n in data["notes"]), data["notes"])+ self.assertIsNone(data["segment_end_snap_seconds"])+ self.assertEqual(len(frame_pts(out)), 150)+ self.assertEqual(steps(out), {0.04})+ frames, src = gray_frames(out), gray_frames(self.hevc25)+ for got, want in ((0, 0), (49, 49), (50, 100), (99, 149), (100, 200), (149, 249)):+ self.assertFrameIs(frames[got], want, f"output frame {got}", src_frames=src)++ def test_an_exact_copy_join_keeps_every_beep_on_its_picture(self):+ """The old join put the beep 67 ms, then 133 ms, after its picture in the second and+ third segments. Each beep (at k + 0.5 s) now starts on the pts of output frame+ (k + 0.5) * 30."""+ out = DIR / "beep_join.mp4"+ data = cut_json(self.beep, "--segments", "0-2,4-6,8-10", "-o", out)+ self.assertEqual(data["mode"], "copy")+ log = subprocess.run(["ffmpeg", "-v", "info", "-i", str(out), "-af", "silencedetect=n=-30dB:d=0.3",+ "-f", "null", "-"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True).stderr+ onsets = [float(v) for v in re.findall(r"silence_end: (-?[0-9.]+)", log)][:6]+ pts = sorted(frame_pts(out))+ self.assertEqual(len(onsets), 6, log)+ for onset, frame in zip(onsets, (15, 45, 75, 105, 135, 165)):+ self.assertAlmostEqual(onset, pts[frame], delta=0.005, msg=f"beep at frame {frame}")++ def test_a_join_whose_sound_drifts_off_its_picture_fails_the_check_and_is_recut(self):+ """B-frame H.264 with PCM in a .mov: every frame of the copy join was the source's own and+ the video check passed, but the sound of the second and third parts landed 16 and 53 ms+ after their pictures (reported mode copy). The audio check matches each part's audio+ packets to the source's and fails the join; the re-cut keeps every beep on its picture."""+ out = DIR / "beep_pcm_join.mov"+ data = cut_json(self.beep_pcm, "--segments", "0-2,4-6,8-10", "-o", out)+ check = data["join_check"]+ self.assertEqual((check["packets"], check["expected_packets"]), (180, 180), "the pictures were right")+ self.assertFalse(check["ok"])+ self.assertEqual(check["audio_parts_checked"], 3)+ self.assertLess(abs(check["audio_offset_ms"][0]), 1.0)+ self.assertGreater(max(abs(o) for o in check["audio_offset_ms"]), 10.0)+ self.assertEqual(data["reencode_reason"], ["concat_fallback"])+ self.assertTrue(any("sound is" in n and "against its picture" in n for n in data["notes"]), data["notes"])+ log = subprocess.run(["ffmpeg", "-v", "info", "-i", str(out), "-af", "silencedetect=n=-30dB:d=0.3",+ "-f", "null", "-"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True).stderr+ onsets = [float(v) for v in re.findall(r"silence_end: (-?[0-9.]+)", log)][:6]+ pts = sorted(frame_pts(out))+ self.assertEqual(len(onsets), 6, log)+ for onset, frame in zip(onsets, (15, 45, 75, 105, 135, 165)):+ self.assertAlmostEqual(onset, pts[frame], delta=0.005, msg=f"beep at frame {frame}")++ def test_a_clean_join_passes_the_audio_check_part_by_part(self):+ """The same pictures with AAC: each part's sound is within a millisecond of its picture+ (0.3 ms of AAC framing), so the copy stands, and every part was measured."""+ out = DIR / "beep_join_audio.mp4"+ data = cut_json(self.beep, "--segments", "0-2,4-6,8-10", "-o", out)+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ self.assertTrue(data["join_check"]["ok"])+ self.assertEqual(data["join_check"]["audio_parts_checked"], 3)+ for off in data["join_check"]["audio_offset_ms"]:+ self.assertLess(abs(off), 1.0)++ def test_the_audio_check_hashes_the_stream_the_join_copied(self):+ """FFmpeg's default selection copies the audio stream with the most channels: here a+ 6-channel PCM a:1 beside a stereo AAC a:0. The check hashed a:0, matched nothing, and+ passed a join whose sound drifted (16 and 53 ms in the PCM .mov) as an exact copy. It now+ hashes the source stream shaped like the joined file's audio, so every part is measured."""+ src = DIR / "beep_two_audio.mov"+ if not src.exists():+ sh("ffmpeg", "-y", "-v", "error", "-i", self.beep, "-map", "0:v", "-map", "0:a", "-map", "0:a", "-c:v", "copy",+ "-c:a:0", "aac", "-ac:a:0", "2", "-c:a:1", "pcm_s16le", "-ac:a:1", "6", src)+ data = cut_json(src, "--segments", "0-2,4-6,8-10", "-o", DIR / "beep_two_audio_join.mov")+ check = data["join_check"]+ self.assertEqual(check["audio_parts_checked"], 3, check)+ self.assertEqual(check["ok"], data["mode"] == "copy")++ def test_the_audio_check_measures_aac_out_of_mpeg_ts(self):+ """MPEG-TS carries AAC with a 7-byte ADTS header that the copy into MP4 strips, so no source+ packet hash ever matched and every part was silently unmeasured. The source's packets are+ hashed without the header."""+ mp4, ts = DIR / "bf_noise.mp4", DIR / "bf_noise.ts"+ if not ts.exists():+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"testsrc2=s=320x180:r={FPS}:d=12", "-f", "lavfi",+ "-i", "anoisesrc=seed=7:d=12:a=0.3:r=48000", "-c:v", "libx264", "-g", "60", "-bf", "3",+ "-x264-params", "scenecut=0", "-c:a", "aac", "-shortest", mp4)+ sh("ffmpeg", "-y", "-v", "error", "-i", mp4, "-c", "copy", ts)+ if subprocess.run(["ffprobe", "-v", "error", "-show_format", str(ts)], stdout=subprocess.PIPE,+ stderr=subprocess.PIPE).returncode != 0:+ # the johnvansickle static ffprobe builds (5.1.1, 7.0.2) segfault on any MPEG-TS file+ self.skipTest("this ffprobe cannot read MPEG-TS")+ data = cut_json(ts, "--segments", "0-2,4-6,8-10", "-o", DIR / "bf_noise_ts_join.mp4")+ check = data["join_check"]+ self.assertIsNotNone(check, data["notes"])+ self.assertEqual(check["audio_parts_checked"], 3, check)+ self.assertTrue(all(abs(o) < 1.0 for o in check["audio_offset_ms"]), check)++ def test_an_adts_header_is_left_out_of_the_hashed_payload(self):+ dump = "\n00000000: fff1 5080 2a5f fc21 0a0b 0c ...\n"+ self.assertEqual(cut._adts_payload(dump), bytes([0x21, 0x0A, 0x0B, 0x0C]))+ with_crc = "\n00000000: fff0 5080 2a5f fc00 0021 0a ...\n"+ self.assertEqual(cut._adts_payload(with_crc), bytes([0x21, 0x0A]))+ self.assertEqual(cut._adts_payload("\n00000000: 2111 0a0b ..\n"), bytes([0x21, 0x11, 0x0A, 0x0B]))++ def test_a_start_inside_the_reorder_delay_lands_where_ffmpeg_seeks(self):+ """The MP4 demuxer seeks over raw decode times (ffprobe's dts plus the reorder delay), so+ -ss 3.99 on B-frame H.264 began at the keyframe at 2.0, not at the one at 4.0 (dts 3.933)+ that "the largest dts at or before the start" predicted: the copy was reported unsnapped+ with its picture 2 s early. seek_keyframe measures the landing with the seek ffmpeg makes."""+ landing = cut.seek_keyframe(str(self.h264bf), 3.99)+ self.assertEqual(landing[0], 2.0, "the premise: the seek lands a GOP early")+ self.assertEqual(cut.seek_keyframe(str(self.h264bf), 4.0)[0], 4.0)+ src = md5_frames(self.h264bf)+ out = DIR / "bf_3.99.mp4"+ data = cut_json(self.h264bf, "--start", "3.99", "--end", "8", "--tolerance", "3", "-o", out)+ self.assertEqual(data["mode"], "copy")+ self.assertEqual(md5_frames(out)[0], src[60], "the copy begins at the keyframe at 2.0")+ self.assertTrue(data["start_snapped"])+ out = DIR / "bf_3.99_el.mp4"+ data = cut_json(self.h264bf, "--start", "3.99", "--end", "8", "--tolerance", "3", "--edit-list", "-o", out)+ self.assertEqual(data["mode"], "copy")+ self.assertFalse(data["start_snapped"])+ self.assertAlmostEqual(data["stored_preroll_seconds"], 2.0, delta=0.001)+ self.assertTrue(any("pre-roll is stored" in n for n in data["notes"]), data["notes"])++ def test_a_later_start_inside_the_reorder_delay_is_planned_not_tried(self):+ """The same landing in a join: 3.95 lands on the keyframe at 2.0, which the plan now knows,+ so the join is re-cut before a copy is tried (the copy failed its check with 180 packets+ for 120), and a tolerance re-cut names the keyframes it could have used."""+ data = cut_json(self.h264bf, "--segments", "0-2,3.95-6", "-o", DIR / "bf_join_3.95.mp4")+ self.assertEqual((data["mode"], data["join_check"]), ("hybrid", None))+ self.assertEqual(data["reencode_reason"], ["tolerance", "concat_fallback"])+ self.assertIn(4.0, data["nearest_keyframes"])+ data = cut_json(self.h264bf, "--segments", "0-2,3.95-6", "--tolerance", "3", "-o", DIR / "bf_join_3.95t.mp4")+ self.assertEqual((data["mode"], data["join_check"]), ("hybrid", None))+ self.assertTrue(any("segment 2 starts between keyframes" in n for n in data["notes"]), data["notes"])++ def test_a_segments_tolerance_reencode_names_the_nearest_keyframes(self):+ """As every 2.x release did, a --segments cut that re-encodes because a keyframe was too far+ lists the keyframes near each such segment's start (nearest_keyframes), so the caller can+ move the cut; the plan judged the starts before any part was cut, and listed none."""+ data = cut_json(self.nob, "--segments", "1-3.5,5-7.2", "-o", DIR / "nob_far.mp4")+ self.assertEqual(data["mode"], "hybrid")+ self.assertIn("tolerance", data["reencode_reason"])+ for k in (0.0, 2.0, 4.0, 6.0):+ self.assertIn(k, data["nearest_keyframes"])+ self.assertIsNone(data["lossless_alternative"], "a single cut's key, as in 2.x")++ def test_the_packets_read_around_segments_plan_as_the_whole_file_does(self):+ """A minute of B-frame video, segments in its middle: video_packets reads one window+ around them (seeking to it), and every plan it gives is the whole-file read's."""+ segs = [(30.0, 32.0), (40.0, 41.9)]+ src = str(self.long60)+ windowed = cut.video_packets(src, segs, 0.5, 60.0)+ whole = cut.video_packets(src)+ self.assertEqual(windowed.spans[0][:2], (20.0, 51.9), "one merged window, [start - 10, end + 10]")+ self.assertLess(len(windowed), len(whole) * 0.6)+ self.assertTrue(set(windowed) <= set(whole), "the window's packets are the file's")+ fps = probe(src)["video"]["fps"]+ for s, e in segs:+ want = cut.plan_part(whole, s, e, 0.5, 60.0, fps)+ got = cut.plan_part(windowed, s, e, 0.5, 60.0, fps)+ for key in ("reason", "start_pts", "end_pts", "t"):+ self.assertEqual(got[key], want[key], key)+ out = DIR / "long60_join.mp4"+ data = cut_json(self.long60, "--segments", "30-32,40-41.9", "-o", out)+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ frames = md5_frames(self.long60)+ self.assertEqual(md5_frames(out), frames[900:960] + frames[1200:1260])+ self.assertEqual(data["segment_end_snap_seconds"], [0.0, 0.1])+ self.assertEqual([p.name for p in DIR.iterdir() if ".ffskill-" in p.name], [],+ "the checked join was renamed into place, nothing left beside it")++ def test_a_checked_join_is_renamed_into_place_not_copied(self):+ """cut.py run with shutil.copyfile failing: the checked join is renamed into place, so the+ run still writes the source's own frames and leaves nothing beside the output."""+ no_copy = (+ "import shutil, sys\n"+ "sys.path.insert(0, sys.argv[1])\n"+ "def refuse(*a, **k):\n"+ " raise OSError('copied')\n"+ "shutil.copyfile = refuse\n"+ "import cut\n"+ "sys.argv = ['cut.py'] + sys.argv[2:]\n"+ "sys.exit(cut.main())\n")+ out = DIR / "renamed_join.mp4"+ proc = sh(sys.executable, "-c", no_copy, SCRIPTS, self.h264bf, "--segments", "0-2,4-6", "-o", out,+ "--overwrite", "--json")+ data = json.loads(proc.stdout)+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ src = md5_frames(self.h264bf)+ self.assertEqual(md5_frames(out), src[0:60] + src[120:180])+ self.assertEqual([p.name for p in DIR.iterdir() if p.name.startswith(".renamed_join")], [])++ def test_an_end_within_tolerance_snaps_to_the_keyframe_after_it(self):+ """0-1.8 ends 0.2 s before the keyframe at 2.0: the part runs to that keyframe, so the+ join is 60 + 60 of the source's frames. start_snapped describes the starts only; the+ end's move is reported per segment."""+ out = DIR / "end_snap_join.mp4"+ data = cut_json(self.h264bf, "--segments", "0-1.8,4-6", "-o", out)+ self.assertEqual(data["mode"], "copy")+ self.assertFalse(data["start_snapped"])+ self.assertEqual(data["segment_end_snap_seconds"], [0.2, 0.0])+ src = md5_frames(self.h264bf)+ self.assertEqual(md5_frames(out), src[0:60] + src[120:180])++ def test_an_end_past_tolerance_reencodes_and_the_join_falls_back(self):+ """0-1.0 is 1.0 s from the next keyframe, past a 0.3 s tolerance: that part+ re-encodes, the parts differ, and the join is re-cut with exact boundaries."""+ out = DIR / "end_far_join.mp4"+ data = cut_json(self.h264bf, "--segments", "0-1.0,4-6", "--tolerance", "0.3", "-o", out)+ self.assertEqual(data["reencode_reason"], ["tolerance", "concat_fallback"])+ self.assertIsNone(data["segment_end_snap_seconds"])+ self.assertEqual(len(frame_pts(out)), 30 + 60)+ self.assertEqual(steps(out), {round(1 / FPS, 4)})+ frames, src = gray_frames(out), gray_frames(self.h264bf)+ for got, want in ((29, 29), (30, 120), (89, 179)):+ self.assertFrameIs(frames[got], want, f"output frame {got}", src_frames=src)++ def test_a_segment_in_the_last_gop_is_not_a_tolerance_reencode(self):+ """10-11 starts on the last keyframe (10.0) and ends before the video does: no+ keyframe follows it to snap the end to. That is not a tolerance miss (it was reported as+ one, even under --tolerance -1, "no keyframe within -1.00s"): the end stays where asked+ and the join check judges the copy. On B-frame video a part cut mid-GOP in decode order+ is not exact (main's copy showed 82 frames for 78), so the join is re-cut from source."""+ for extra in ((), ("--tolerance", "-1")):+ with self.subTest(tolerance=extra):+ out = DIR / f"last_gop_join{len(extra)}.mp4"+ data = cut_json(self.h264bf, "--segments", "0-2,10-11", *extra, "-o", out)+ self.assertEqual(data["reencode_reason"], ["concat_fallback"])+ self.assertEqual(len(frame_pts(out)), 60 + 30)+ self.assertEqual(steps(out), {round(1 / FPS, 4)})++ def test_a_short_segment_across_a_bframe_keyframe_never_cuts_a_negative_length(self):+ """-ss 1.95 lands on the keyframe at 2.0 (its dts, 1.933, is before 1.95). That+ keyframe cannot also end the part: its dts is before the start, so -t would be negative.+ The end is snapped among keyframes decoded after the landing, and none is near 2.085.+ The re-cut starts between frames: cut off the frame grid, its pictures sat half a frame+ off the output's and FFmpeg 6.1 duplicated one (65 frames); FFmpeg 7.0 encoded at 25 fps."""+ out = DIR / "short_across_key.mp4"+ data = cut_json(self.h264bf, "--segments", "1.95-2.085,3.985-5.985", "-o", out)+ self.assertEqual(data["reencode_reason"], ["tolerance", "concat_fallback"])+ self.assertEqual(stderr_of_decode(out), "")+ frames = gray_frames(out)+ self.assertEqual(len(frames), 4 + 60)+ self.assertFrameIs(frames[0], 59, "the first frame at or after 1.95", src_frames=gray_frames(self.h264bf))++ def test_a_source_without_bframes_cuts_its_parts_as_2x_did(self):+ """No-B-frame H.264 cuts exactly in decode order, so its parts are cut as in every 2.x+ release (make_zero, -t end-start, no end snap) and the join is the frames 2.5.1 wrote:+ #306's keyframe plan re-encoded 0-1.0, moved the end of 0-1.8 to 2.0 and of 0-2.4 back+ to 2.0, and re-cut a mid-GOP second start. Each part starts at the keyframe at or before+ its start; each end is where asked (ends half a frame off the frame grid)."""+ src = md5_frames(self.nob)+ for segs, want in (("0-0.985,4-5.985", src[0:30] + src[120:180]),+ ("0-1.785,4-5.985", src[0:54] + src[120:180]),+ ("0-2.385,4-5.985", src[0:72] + src[120:180]),+ ("0.315-1.985,4.415-5.985", src[0:60] + src[120:180])):+ with self.subTest(segments=segs):+ out = DIR / f"nob_{segs}.mp4"+ data = cut_json(self.nob, "--segments", segs, "-o", out)+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []), data["notes"])+ self.assertEqual(md5_frames(out), want)+ self.assertTrue(data["join_check"]["ok"])+ self.assertEqual(data["join_check"]["expected_packets"], len(want))+ self.assertEqual(data["segment_end_snap_seconds"], [None, None], "a no-B part's end is not snapped")++ def test_a_no_bframe_join_one_frame_plus_its_gap_long_passes_the_check(self):+ """0-1.795: the part's sound runs past its last frame and the next part's picture starts+ after its sound, so the step at the join is 56.7 ms at 30 fps -- past #306's fixed bound+ (a frame + one AAC frame, 54.7 ms), which re-encoded a join 2.5.1 copied exactly. The+ step predicted from the parts is what the joined file shows."""+ out = DIR / "nob_step_join.mp4"+ data = cut_json(self.nob, "--segments", "0-1.795,4-5.985", "-o", out)+ self.assertEqual(data["mode"], "copy")+ self.assertGreater(data["join_check"]["max_step_seconds"], 1 / FPS + 1024 / 48000, "the premise")+ self.assertTrue(data["join_check"]["ok"])++ def test_an_end_snaps_to_the_keyframe_after_it_never_before(self):+ """B-frame H.264: 0-2.385 ends 0.385 s past the keyframe at 2.0 and 1.615 s before the+ one at 4.0. #306 snapped it back to 2.0, dropping requested frames under mode copy; an end+ only moves forward, so with the default 0.5 s tolerance the join is re-cut, and with+ --tolerance 2 the part runs to 4.0."""+ out = DIR / "end_forward_recut.mp4"+ data = cut_json(self.h264bf, "--segments", "0-2.385,6-7.985", "-o", out)+ self.assertEqual(data["reencode_reason"], ["tolerance", "concat_fallback"])+ self.assertEqual(len(frame_pts(out)), 72 + 60)+ out = DIR / "end_forward_copy.mp4"+ data = cut_json(self.h264bf, "--segments", "0-2.385,6-7.985", "--tolerance", "2", "-o", out)+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ self.assertEqual(data["segment_end_snap_seconds"], [1.615, 0.015])+ src = md5_frames(self.h264bf)+ self.assertEqual(md5_frames(out), src[0:120] + src[180:240])++ def test_a_later_start_between_bframe_keyframes_is_recut_without_a_copy(self):+ """An edit-listed part that starts between keyframes stores the frames before its start as+ hidden pre-roll, and the concat demuxer crushes them into sub-millisecond steps at the+ join: the copy always failed its check. It is re-cut directly, with exact boundaries."""+ out = DIR / "mid_gop_second_start.mp4"+ data = cut_json(self.h264bf, "--segments", "0-1.985,4.415-5.985", "-o", out)+ self.assertEqual(data["reencode_reason"], ["concat_fallback"])+ self.assertTrue(any("starts between keyframes" in n for n in data["notes"]), data["notes"])+ self.assertIsNone(data["join_check"], "no copy join was tried")+ self.assertEqual(len(frame_pts(out)), 60 + 47)+ frames, src = gray_frames(out), gray_frames(self.h264bf)+ for got, want in ((59, 59), (60, 133), (106, 179)):+ self.assertFrameIs(frames[got], want, f"output frame {got}", src_frames=src)++ def test_an_hdr_open_gop_join_is_reencoded_as_hdr(self):+ """iPhone HEVC is open-GOP HLG. A detector that let it through would+ stream-copy it, so the re-encode is asserted first; then that it kept HEVC, 10 bits and+ the HLG transfer rather than flattening the picture."""+ out = DIR / "hlg_join.mp4"+ data = cut_json(self.hlg, "--segments", "0-2,4-6", "-o", out)+ self.assertTrue(data["reencoded"])+ self.assertIn("concat_fallback", data["reencode_reason"])+ stream = json.loads(subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",+ "stream=codec_name,pix_fmt,color_transfer", "-of", "json", str(out)],+ stdout=subprocess.PIPE, text=True, check=True).stdout)["streams"][0]+ self.assertEqual((stream["codec_name"], stream["pix_fmt"], stream["color_transfer"]),+ ("hevc", "yuv420p10le", "arib-std-b67"))++ def test_the_last_segment_past_the_video_end_stays_an_exact_copy(self):+ """On the copy path, the last part runs to the end of the file (-t e-s, nothing after it+ to leak), and the join is the source's own 60 + 60 frames."""+ out = DIR / "held_last_copy.mp4"+ data = cut_json(self.long, "--segments", "0-2,4-6.3", "-o", out)+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ src = md5_frames(self.long)+ self.assertEqual(md5_frames(out), src[0:60] + src[120:180])+ self.assertAlmostEqual(probe(str(out))["video"]["duration"], 4.0, delta=0.001)+ self.assertEqual(data["segment_end_snap_seconds"], [0.0, None])++ def test_a_sound_tail_under_a_frame_stays_an_exact_copy(self):+ """On the copy path, the first part ends at the end of the file with its sound one AAC+ frame at most past its picture; the concat demuxer places the next part after the sound,+ so its last frame shows up to that long. The frames are exact and the check accepts it."""+ out = DIR / "tail_copy.mp4"+ data = cut_json(self.tail, "--segments", "4-6.02,0-2", "-o", out)+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ src = md5_frames(self.tail)+ self.assertEqual(md5_frames(out), src[120:180] + src[0:60])+ self.assertTrue(data["join_check"]["ok"])+ self.assertLess(data["join_check"]["max_step_seconds"], 1 / FPS + 1024 / 48000)++ def test_a_failed_concat_copy_is_reported_as_the_reencode_it_became(self):+ """2.x re-encoded the join when the concat demuxer's stream copy failed but still reported+ mode copy, reencoded false and packet precision. The failure is simulated (cut.py run+ with its concat-copy command failing): a keyframe-aligned video join and a WAV join, both+ of which copy when nothing fails."""+ mock_concat = (+ "import subprocess, sys\n"+ "sys.path.insert(0, sys.argv[1])\n"+ "import cut\n"+ "real = cut.run\n"+ "def run(cmd, *a, **k):\n"+ " cmd = [str(c) for c in cmd]\n"+ " if '-f' in cmd and cmd[cmd.index('-f') + 1] == 'concat' and '-c' in cmd and cmd[cmd.index('-c') + 1] == 'copy':\n"+ " return subprocess.CompletedProcess(cmd, 1, '', 'simulated concat failure')\n"+ " return real(cmd, *a, **k)\n"+ "cut.run = run\n"+ "sys.argv = ['cut.py'] + sys.argv[2:]\n"+ "sys.exit(cut.main())\n")+ for src, segs, out, precision in ((self.h264bf, "0-2,4-6", DIR / "concat_failed.mp4", "frame"),+ (self.wav, "1-2,3-4.5", DIR / "concat_failed.wav", "sample")):+ with self.subTest(out=out.name):+ proc = sh(sys.executable, "-c", mock_concat, SCRIPTS, src, "--segments", segs, "-o", out,+ "--overwrite", "--json")+ data = json.loads(proc.stdout)+ self.assertIn("concat with stream copy failed", proc.stderr, "the premise: the copy join failed")+ self.assertEqual((data["mode"], data["reencoded"]), ("hybrid", True))+ self.assertEqual(data["reencode_reason"], ["concat_fallback"])+ self.assertEqual(data["precision"], precision)+ self.assertFalse(data["keyframe_snapped"])+ self.assertFalse(data["start_snapped"])++ def test_the_recut_cuts_on_the_frame_grid_and_states_the_sources_rate(self):+ """Each segment of the re-cut runs from the first frame at or after its start to the first+ at or after its end, for both streams; the video trim sits half a frame before those+ points; and the output rate is the source's r_frame_rate (FFmpeg 7.0 otherwise wrote 25+ fps). No encode runs: the command is read."""+ cmds = []+ meta = {"video": {"fps": 29.97, "r_frame_rate": "30000/1001", "start_time": 0.0}, "audio": {"codec": "aac"}}+ with mock.patch.object(cut, "run", lambda cmd, **kw: cmds.append([str(c) for c in cmd])), \+ mock.patch.object(cut, "file_origin", lambda src: 0.0), tempfile.TemporaryDirectory() as tmp:+ cut.join_from_source("src.mp4", [(1.0, 2.0)], os.path.join(tmp, "out.mp4"), meta, 18, "medium", tmp)+ (cmd,) = cmds+ graph = cmd[cmd.index("-filter_complex") + 1]+ # seeked to 0 with a 1 s margin: frame 30 (1.001 s) starts it, frame 60 (2.002 s) ends it+ a, b = 30 * 1001 / 30000, 60 * 1001 / 30000+ half = 0.5 * 1001 / 30000+ self.assertIn(f"trim=start={a - half:.6f}:end={b - half:.6f},setpts=PTS-{a:.6f}/TB", graph)+ self.assertIn(f"atrim=start={a:.6f}:end={b:.6f},asetpts=PTS-{a:.6f}/TB", graph)+ self.assertEqual(cmd[cmd.index("-r") + 1], "30000/1001")++ def test_a_wav_join_stays_a_lossless_copy(self):+ """PCM has no extradata at all; a "missing means incompatible" rule would have sent every+ multi-segment WAV cut to a re-encode."""+ out = DIR / "tone_join.wav"+ data = cut_json(self.wav, "--segments", "1-2,3-4.5", "-o", out)+ self.assertEqual(data["mode"], "copy")+ self.assertEqual(data["reencode_reason"], [])++ def test_the_audio_only_fallback_writes_one_pcm_stream_of_the_exact_length(self):+ out = DIR / "tone_recut.wav"+ if out.exists():+ out.unlink() # called in-process, without the CLI's --overwrite+ with tempfile.TemporaryDirectory() as tmp:+ cut.join_from_source(str(self.wav), [(1.0, 2.0), (3.0, 4.5)], str(out), probe(str(self.wav)), 18, "medium", tmp)+ streams = json.loads(subprocess.run(["ffprobe", "-v", "error", "-show_entries", "stream=codec_type,codec_name,duration_ts",+ "-of", "json", str(out)], stdout=subprocess.PIPE, text=True, check=True).stdout)["streams"]+ self.assertEqual([s["codec_type"] for s in streams], ["audio"])+ self.assertEqual(streams[0]["codec_name"], "pcm_s16le")+ self.assertEqual(int(streams[0]["duration_ts"]), 44100 + 66150)++ def test_a_segment_shorter_than_a_frame_is_refused(self):+ out = DIR / "subframe.mp4"+ proc = script("cut.py", self.hevc, "--segments", "1-1.01,3-4", "-o", out, expect_fail=True)+ self.assertIn("shorter than one frame", proc.stderr)+ self.assertFalse(out.exists())++ def test_the_one_frame_refusal_measures_the_video_end_on_the_cut_clock(self):+ """CodeRabbit on #313: the check took the video stream's length as its end. A source whose video+ starts after the container does (MPEG-TS, here 0.54 s) ends later than that length says, so+ a real last 0.2 s was refused as "shorter than one frame inside the video stream"."""+ src = DIR / "video_starts_late.ts"+ if not src.exists():+ sh("ffmpeg", "-y", "-v", "error", "-itsoffset", "0.5", "-f", "lavfi", "-i", "testsrc2=s=320x180:r=25:d=5.5",+ "-f", "lavfi", "-i", "sine=f=440:d=6", "-c:v", "libx264", "-g", "25", "-pix_fmt", "yuv420p",+ "-c:a", "aac", "-t", "6.5", src)+ if subprocess.run(["ffprobe", "-v", "error", "-show_format", str(src)], stdout=subprocess.PIPE,+ stderr=subprocess.PIPE).returncode != 0:+ # the johnvansickle static ffprobe builds (5.1.1, 7.0.2) segfault on any MPEG-TS file+ self.skipTest("this ffprobe cannot read MPEG-TS")+ meta = probe(str(src))+ v = meta["video"]+ end = cut.video_end(str(src), meta)+ # the premise: the stream's own length falls short of where the video ends on the cut clock+ self.assertGreater(end - v["duration"], 0.3, (end, v["duration"]))+ last = (meta["duration"] - 0.2, meta["duration"] - 0.01)+ out = DIR / "video_starts_late_tail.ts"+ proc = script("cut.py", src, "--start", f"{last[0]:.3f}", "--end", f"{last[1]:.3f}", "--dry-run", "--json", "-o", out)+ self.assertNotIn("shorter than one frame", proc.stderr)+ self.assertEqual(json.loads(proc.stdout)["status"], "completed")+ # less than a frame of picture left before the video's end is still refused+ short = script("cut.py", src, "--start", f"{end - 0.02:.3f}", "--end", f"{end:.3f}", "--dry-run", "--json", "-o", out,+ expect_fail=True)+ self.assertIn("shorter than one frame", short.stderr)++ def test_a_single_cut_shorter_than_a_frame_is_refused_but_not_to_audio(self):+ """2.5.1 wrote one whole frame for --start 1 --end 1.01 and reported success. The refusal+ is a kind: input before ffmpeg runs; sound has no frame, so an audio output still cuts."""+ out = DIR / "subframe_single.mp4"+ if out.exists():+ out.unlink()+ proc = script("cut.py", self.hevc, "--start", "1", "--end", "1.01", "-o", out, "--json", expect_fail=True)+ self.assertIn("shorter than one frame", proc.stderr)+ doc = json.loads(proc.stdout)+ self.assertEqual(doc["error"]["kind"], "input")+ self.assertEqual(doc["commands"], [])+ self.assertFalse(out.exists())+ data = cut_json(self.hevc, "--start", "1", "--end", "1.01", "-o", DIR / "subframe_single.wav")+ self.assertEqual(data["status"], "completed")+ self.assertAlmostEqual(data["expected_duration"], 0.01, places=3)++ def test_a_gpu_chunk_refusal_reencodes_every_chunk_on_the_cpu(self):+ """Under --hw, run() retries a chunk VideoToolbox refused on the CPU; the chunks then differ,+ and the join encodes them all on the CPU rather than refusing (no real encode here)."""+ encodes, hw_seen = [], []++ def fake_chunk(src, segs, dst, meta, crf, preset, has_v, intermediate=False, **_hold):+ encodes.append(dst)+ hw_seen.append(cut.STATE.hw)++ # first round mixed (one chunk fell back to the CPU), second round all CPU+ sigs = iter([[{"type": "video", "codec_name": "hevc", "extradata_hash": "A"}],+ [{"type": "video", "codec_name": "hevc", "extradata_hash": "B"}],+ [{"type": "video", "codec_name": "hevc", "extradata_hash": "C"}],+ [{"type": "video", "codec_name": "hevc", "extradata_hash": "C"}]])+ segs = [(i * 0.3, i * 0.3 + 0.2) for i in range(40)]+ meta = {"video": {"fps": 30.0}, "audio": None}+ with mock.patch.object(cut, "_join_chunk", fake_chunk), \+ mock.patch.object(cut, "join_signature", lambda p: next(sigs)), \+ mock.patch.object(cut, "run", lambda cmd, **kw: None), \+ mock.patch.object(cut.STATE, "hw", True), \+ mock.patch.object(cut.STATE, "hw_notes", []), \+ mock.patch.object(cut.STATE, "hw_source", "flag"), \+ mock.patch.object(cut.STATE, "commands", ["ffmpeg -i src.mp4 -c:v libx265 -crf 18 chunk.mkv"]), \+ tempfile.TemporaryDirectory() as tmp:+ cut.join_from_source("src.mp4", segs, os.path.join(tmp, "out.mp4"), meta, 18, "medium", tmp)+ self.assertEqual(hw_seen, [True, True, False, False], "two chunks on the GPU, then both again on the CPU")+ self.assertEqual(len(cut.STATE.hw_notes), 1)+ # the result still says the GPU was asked for and why it was not used+ rep = importlib.import_module("_common.emit")._encoder_report(cut.STATE)+ self.assertEqual((rep["hw"]["requested"], rep["hw"]["used"]), (True, False), rep)+ self.assertIn("fell back to the CPU", " ".join(rep["hw"]["notes"]))++ # ------------------------------------------------------------------ signatures (unit, prepared parts)+ def _part(self, name, *args):+ path = DIR / name+ if not path.exists():+ sh("ffmpeg", "-y", "-v", "error", *args, path)+ return str(path)++ def test_part_signatures_tell_joinable_parts_apart(self):+ copy_a = self._part("sig_copy_a.mp4", "-ss", "0", "-i", self.hevc, "-t", "1", "-c", "copy")+ copy_b = self._part("sig_copy_b.mp4", "-ss", "4", "-i", self.hevc, "-t", "1", "-c", "copy")+ h264 = self._part("sig_h264.mp4", "-ss", "4", "-i", self.hevc, "-t", "1", "-c:v", "libx264", "-c:a", "aac")+ hevc_re = self._part("sig_hevc_re.mp4", "-ss", "4", "-i", self.hevc, "-t", "1", "-c:v", "libx265",+ "-x265-params", "log-level=error", "-tag:v", "hvc1", "-c:a", "aac")+ rot_copy = self._part("sig_rot_copy.mp4", "-ss", "0", "-i", self.rot, "-t", "1", "-c", "copy")+ rot_re = self._part("sig_rot_re.mp4", "-ss", "0", "-i", self.rot, "-t", "1", "-c:v", "libx265",+ "-x265-params", "log-level=error", "-tag:v", "hvc1", "-c:a", "aac")+ wav_a = self._part("sig_a.wav", "-i", self.wav, "-t", "1", "-c", "copy")+ wav_b = self._part("sig_b.wav", "-ss", "2", "-i", self.wav, "-t", "1", "-c", "copy")+ sig = {p: cut.join_signature(p) for p in (copy_a, copy_b, h264, hevc_re, rot_copy, rot_re, wav_a, wav_b)}+ self.assertTrue(cut.signatures_match([sig[copy_a], sig[copy_b]], ".mp4"), "two copies of one source join")+ self.assertFalse(cut.signatures_match([sig[copy_a], sig[h264]], ".mp4"), "HEVC then H.264")+ # the premise of the same-codec case: the re-encode really carries different extradata+ self.assertNotEqual(sig[copy_a][0]["extradata_hash"], sig[hevc_re][0]["extradata_hash"])+ self.assertFalse(cut.signatures_match([sig[copy_a], sig[hevc_re]], ".mp4"), "a copy and a re-encode of one codec")+ self.assertFalse(cut.signatures_match([sig[rot_copy], sig[rot_re]], ".mp4"), "rotated copy vs rotated re-encode")+ self.assertIsNone(sig[wav_a][0]["extradata_hash"])+ self.assertTrue(cut.signatures_match([sig[wav_a], sig[wav_b]], ".wav"), "PCM parts join without extradata")+ self.assertIsNone(cut.join_signature(str(DIR / "no_such_part.mp4")))++ def test_a_missing_extradata_hash_only_matches_where_the_config_is_in_band(self):+ def sig(codec):+ return [{"type": "audio", "codec_name": codec, "profile": None, "sample_rate": "48000", "channels": 2,+ "time_base": "1/48000", "extradata_hash": None}]+ self.assertFalse(cut.signatures_match([sig("aac"), sig("aac")], ".mp4"))+ self.assertTrue(cut.signatures_match([sig("aac"), sig("aac")], ".ts"))+ self.assertTrue(cut.signatures_match([sig("pcm_s16le"), sig("pcm_s16le")], ".wav"))+ self.assertTrue(cut.signatures_match([sig("mp3"), sig("mp3")], ".mp3"))+ one = sig("aac")+ other = sig("aac")+ other[0]["extradata_hash"] = "SHA256:ab"+ self.assertFalse(cut.signatures_match([one, other], ".ts"), "a hash on one side only is a mismatch")+++class SourceCodecArgsTests(unittest.TestCase):+ """source_codec_video_args routes by the source (pure: no encode runs)."""+ SDR_HEVC = {"video": {"codec": "hevc", "bt2020_or_hdr": False}}+ HDR_HEVC = {"video": {"codec": "hevc", "bt2020_or_hdr": True, "color_space": "bt2020nc",+ "color_primaries": "bt2020", "color_transfer": "smpte2084"}}+ SDR_H264 = {"video": {"codec": "h264", "bt2020_or_hdr": False}}+ # BT.2020 primaries on an SDR curve: routed through the HDR (Main10, tags kept) path+ BT2020_SDR_HEVC = {"video": {"codec": "hevc", "bt2020_or_hdr": True, "color_space": "bt2020nc",+ "color_primaries": "bt2020", "color_transfer": "bt709"}}++ def encoder(self, meta, codec=None, hw=False, swaps=None, keep_hevc=True):+ """The encoder line, run through the real VideoToolbox routing with this machine's platform+ and encoder list mocked, so the test means the same on any host."""+ with mock.patch.object(decision.STATE, "codec", codec), mock.patch.object(decision.STATE, "hw", hw), \+ mock.patch.object(decision.STATE, "hw_swaps", [] if swaps is None else swaps), \+ mock.patch.object(decision.STATE, "hw_notes", []), \+ mock.patch.object(decision, "hw_platform_reason", lambda: None), \+ mock.patch.object(decision, "ffmpeg_encoders", lambda: {"libx264", "libx265", "hevc_videotoolbox", "h264_videotoolbox"}):+ args = decision.source_codec_video_args(meta, 18, "ultrafast", keep_hevc=keep_hevc)+ return args[args.index("-c:v") + 1], args++ def test_sdr_hevc_is_encoded_as_h264_without_keep_hevc(self):+ """The 2.x default: video_args()'s x264 line, on the CPU and on VideoToolbox."""+ enc, args = self.encoder(self.SDR_HEVC, keep_hevc=False)+ self.assertEqual(enc, "libx264")+ self.assertNotIn("-tag:v", args)+ enc, _ = self.encoder(self.SDR_HEVC, hw=True, keep_hevc=False)+ self.assertEqual(enc, "h264_videotoolbox")++ def test_an_hdr_or_bt2020_source_gets_video_args_line_with_or_without_keep_hevc(self):+ for meta in (self.HDR_HEVC, self.BT2020_SDR_HEVC):+ for hw in (False, True):+ with mock.patch.object(decision.STATE, "codec", None), mock.patch.object(decision.STATE, "hw", hw), \+ mock.patch.object(decision.STATE, "hw_swaps", []), mock.patch.object(decision.STATE, "hw_notes", []), \+ mock.patch.object(decision, "hw_platform_reason", lambda: None), \+ mock.patch.object(decision, "ffmpeg_encoders", lambda: {"libx264", "libx265", "hevc_videotoolbox", "h264_videotoolbox"}):+ plain = decision.video_args(meta, 18, "ultrafast")+ self.assertEqual(self.encoder(meta, hw=hw, keep_hevc=True)[1], plain, (meta, hw))+ self.assertEqual(self.encoder(meta, hw=hw, keep_hevc=False)[1], plain, (meta, hw))++ def test_cut_passes_keep_hevc_to_the_encoder_and_composes_with_hw(self):+ """cut.py's own re-encode line: --keep-hevc with --hw gives VideoToolbox HEVC with its CPU+ fallback recorded; without the flag, --hw gives VideoToolbox H.264."""+ for keep, expected in ((True, "hevc_videotoolbox"), (False, "h264_videotoolbox")):+ swaps = []+ with mock.patch.object(cut, "KEEP_HEVC", keep), mock.patch.object(decision.STATE, "codec", None), \+ mock.patch.object(decision.STATE, "hw", True), mock.patch.object(decision.STATE, "hw_swaps", swaps), \+ mock.patch.object(decision.STATE, "hw_notes", []), \+ mock.patch.object(decision, "hw_platform_reason", lambda: None), \+ mock.patch.object(decision, "ffmpeg_encoders", lambda: {"libx264", "libx265", "hevc_videotoolbox", "h264_videotoolbox"}):+ args = cut.video_encode_args({"video": dict(self.SDR_HEVC["video"], fps=30.0)}, 18, "ultrafast")+ self.assertEqual(args[args.index("-c:v") + 1], expected)+ self.assertEqual(len(swaps), 1, "run() can put the CPU line back if the GPU refuses")+ cpu = swaps[0][1]+ self.assertEqual(cpu[cpu.index("-c:v") + 1], "libx265" if keep else "libx264")++ def test_sdr_hevc_is_encoded_as_hevc_8bit_bt709(self):+ enc, args = self.encoder(self.SDR_HEVC)+ self.assertEqual(enc, "libx265")+ self.assertEqual(args[args.index("-pix_fmt") + 1], "yuv420p")+ self.assertEqual(args[args.index("-tag:v") + 1], "hvc1")++ def test_sdr_hevc_goes_to_videotoolbox_with_a_cpu_fallback_when_hw_is_on(self):+ swaps = []+ enc, args = self.encoder(self.SDR_HEVC, hw=True, swaps=swaps)+ self.assertEqual(enc, "hevc_videotoolbox")+ self.assertEqual(args[args.index("-bsf:v") + 1],+ "hevc_metadata=colour_primaries=1:transfer_characteristics=1:matrix_coefficients=1")+ self.assertEqual(len(swaps), 1, "run() can put the CPU line back if the GPU refuses")+ gpu, cpu = swaps[0]+ self.assertEqual(gpu, args)+ self.assertEqual(cpu[cpu.index("-c:v") + 1], "libx265")++ def test_a_codec_flag_wins_over_the_source(self):+ enc, _ = self.encoder(self.SDR_HEVC, codec="h264")+ self.assertEqual(enc, "libx264")++ def test_sdr_h264_is_still_encoded_as_h264(self):+ enc, args = self.encoder(self.SDR_H264)+ self.assertEqual(enc, "libx264")+ self.assertNotIn("-tag:v", args)++ def test_hdr_hevc_stays_main10_with_its_own_tags(self):+ enc, args = self.encoder(self.HDR_HEVC)+ self.assertEqual(enc, "libx265")+ self.assertEqual(args[args.index("-pix_fmt") + 1], "yuv420p10le")+ self.assertEqual(args[args.index("-color_trc") + 1], "smpte2084")+ self.assertIn("hdr10-opt=1", args[args.index("-x265-params") + 1])+++def ramp(n, step, start=0):+ return [start + i * step for i in range(n)]+++class FrameTimingTests(unittest.TestCase):+ """classify_frame_timing on fixed timestamps: no encodes, the rules one at a time."""++ def classify(self, windows, tb="1/30"):+ return probe_mod.classify_frame_timing(windows, tb)["measured"]++ def test_exact_thirtieths_are_constant(self):+ self.assertEqual(self.classify([ramp(60, 1), ramp(60, 1, 300)]), "sampled_cfr")++ def test_ntsc_rounding_to_a_600_timescale_is_constant(self):+ """29.97 fps in 1/600 ticks is 20.02 ticks a frame: mostly 20-tick intervals with a 21+ about every 50 frames. That rounding is not variable timing."""+ pts = [round(n * 600 * 1001 / 30000) for n in range(180)]+ deltas = [b - a for a, b in zip(pts, pts[1:])]+ self.assertEqual(set(deltas), {20, 21})+ self.assertEqual(deltas.count(21), 4)+ self.assertEqual(self.classify([pts[:90], pts[90:]], "1/600"), "sampled_cfr")++ def test_a_stretched_first_interval_at_the_file_start_is_not_evidence(self):+ first = [0] + ramp(59, 1, 3) # the first frame held for three frame times+ self.assertEqual(self.classify([first, ramp(60, 1, 300)]), "sampled_cfr")++ def test_the_same_interval_second_in_the_file_is_vfr(self):+ second = [0, 1] + ramp(58, 1, 4)+ self.assertEqual(self.classify([second, ramp(60, 1, 300)]), "vfr")++ def test_a_stretched_first_interval_in_a_later_window_is_vfr(self):+ later = [300] + ramp(59, 1, 303)+ self.assertEqual(self.classify([ramp(60, 1), later]), "vfr")++ def test_one_dropped_frame_in_one_window_is_vfr(self):+ dropped = ramp(30, 1, 300) + ramp(30, 1, 331)+ self.assertEqual(self.classify([ramp(60, 1), dropped]), "vfr")++ def test_one_dropped_frame_at_a_fine_time_base_is_vfr(self):+ dropped = ramp(30, 512, 153600) + ramp(30, 512, 153600 + 31 * 512) # 1/15360, as MP4 writes 30 fps+ self.assertEqual(self.classify([ramp(60, 512), dropped], "1/15360"), "vfr")++ def test_jitter_is_vfr(self):+ jitter = [n * 33 + (0 if n % 2 else 7) for n in range(60)] # 1/1000 s ticks: 26 and 40 ms+ self.assertEqual(self.classify([jitter], "1/1000"), "vfr")++ def test_windows_at_different_rates_are_vfr(self):+ self.assertEqual(self.classify([ramp(60, 2), ramp(60, 1, 300)], "1/60"), "vfr")++ def test_variable_timing_between_the_windows_is_not_seen(self):+ """The documented limit: the clean windows are all the classifier gets."""+ self.assertEqual(self.classify([ramp(60, 1), ramp(60, 1, 900)]), "sampled_cfr")++ def test_bframe_decode_order_classifies_like_presentation_order(self):+ shown = ramp(60, 1)+ stored = [shown[0]] + [shown[i + d] for i in range(1, 57, 3) for d in (2, 0, 1)] + shown[58:]+ self.assertEqual(sorted(stored), shown, "the premise: the same frames, out of order")+ self.assertEqual(self.classify([stored, ramp(60, 1, 300)]), self.classify([shown, ramp(60, 1, 300)]))+ self.assertEqual(self.classify([stored, ramp(60, 1, 300)]), "sampled_cfr")++ def test_fewer_than_twenty_intervals_is_inconclusive(self):+ result = probe_mod.classify_frame_timing([ramp(20, 1)], "1/30")+ self.assertEqual((result["measured"], result["deltas"]), ("inconclusive", 18))++ def test_missing_and_repeated_timestamps_are_skipped(self):+ pts = ramp(60, 1)+ pts[10:10] = [None, float("nan"), 10]+ self.assertEqual(self.classify([pts, ramp(60, 1, 300)]), "sampled_cfr")++ def test_a_read_that_stops_mid_reorder_keeps_only_complete_frames(self):+ """Decode order I0 P3 B1 B2 P6 (stop): frames 4 and 5 were never read. Only the pts up to+ the last dts read are all present."""+ packets = [{"pts": 0, "dts": -2}, {"pts": 3, "dts": -1}, {"pts": 1, "dts": 0}, {"pts": 2, "dts": 1},+ {"pts": 6, "dts": 2}]+ self.assertEqual(sorted(probe_mod.complete_pts(packets)), [0, 1, 2])++ def test_windows_are_spread_over_the_file_from_its_first_packet(self):+ self.assertEqual(probe_mod.timing_window_starts(60.0, 0.0), [0.0, 13.5, 27.0, 40.5, 54.0])+ self.assertEqual(probe_mod.timing_window_starts(60.0, 10.0), [10.0, 23.5, 37.0, 50.5, 64.0])+ self.assertEqual(probe_mod.timing_window_starts(13.0, 0.0), [0.0, 7.0])+ self.assertEqual(probe_mod.timing_window_starts(4.0, 0.0), [0.0])++ def test_a_window_that_seeks_back_reads_only_from_its_start(self):+ """A long GOP: every read seeks back to the keyframe at 0, whose first interval is stretched+ (an edit-list start). Only the file-start window may ignore that interval, so the later+ windows must drop what precedes their own start."""+ pts = [0] + ramp(599, 1, 3) # 1/30 ticks: 20 s, the first frame held 3x+ doc = json.dumps({"packets": [{"pts": p, "dts": p} for p in pts], "streams": [{"time_base": "1/30"}]})+ ran = subprocess.CompletedProcess([], 0, doc, "")+ with mock.patch.object(probe_mod, "run", lambda cmd, **kw: ran):+ result = probe_mod.measure_frame_timing("x.mp4", 20.0, 0.0)+ self.assertEqual((result["measured"], result["windows"]), ("sampled_cfr", 3))++ def test_an_ffprobe_failure_is_inconclusive(self):+ failed = subprocess.CompletedProcess([], 1, "", "boom")+ with mock.patch.object(probe_mod, "run", lambda cmd, **kw: failed):+ self.assertEqual(probe_mod.measure_frame_timing("x.mp4", 30.0, 0.0)["measured"], "inconclusive")+++def gop_packets(fps=30, keyint=60, gops=6, delay=2, leading=0):+ """Synthetic packets in decode order, as (pts, dts, key): each GOP's keyframe first, then its+ other frames by pts; dts runs `delay` frames behind. `leading` frames before each keyframe+ after the first decode after it (an open GOP's leading pictures)."""+ order = []+ for g in range(gops):+ k = g * keyint+ order.append((k, True))+ if g and leading:+ order += [(k - leading + j, False) for j in range(leading)]+ last = k + keyint - (leading if g < gops - 1 else 0)+ order += [(n, False) for n in range(k + 1, last)]+ return [(n / fps, (i - delay) / fps, key) for i, (n, key) in enumerate(order)]+++class CopyJoinPlanTests(unittest.TestCase):+ """The copy-join helpers on synthetic packet lists: where a copied part ends, open-GOP detection,+ and the check of the joined file."""++ def test_a_closed_gop_keyframe_is_not_open(self):+ packets = gop_packets()+ self.assertFalse(cut.gop_is_open(packets, 60))+ self.assertFalse(cut.gop_is_open(packets, 0))++ def test_leading_pictures_after_a_keyframe_make_it_open(self):+ packets = gop_packets(leading=3)+ i = next(i for i, p in enumerate(packets) if p[2] and abs(p[0] - 2.0) < 1e-9)+ self.assertTrue(cut.gop_is_open(packets, i))+ self.assertFalse(cut.gop_is_open(packets, 0), "the first keyframe has nothing before it")++ def test_a_keyframe_at_the_end_of_the_file_is_not_open(self):+ packets = gop_packets()[:61]+ self.assertTrue(packets[60][2])+ self.assertFalse(cut.gop_is_open(packets, 60))++ def test_a_missing_timestamp_in_the_gop_counts_as_open(self):+ packets = gop_packets()+ packets[62] = (None, packets[62][1], False)+ self.assertTrue(cut.gop_is_open(packets, 60))+ packets = gop_packets()+ packets[62] = (packets[62][0], None, False)+ self.assertTrue(cut.gop_is_open(packets, 60))++ def test_the_part_ends_at_the_end_keyframes_dts(self):+ packets = gop_packets()+ plan = cut.plan_part(packets, 0.0, 1.8, 0.5, 12.0, 30)+ self.assertIsNone(plan["reason"])+ self.assertEqual((plan["start_pts"], plan["end_pts"]), (0.0, 2.0))+ self.assertAlmostEqual(plan["t"], 2.0 - 2 / 30, delta=0.001)+ self.assertLess(plan["t"], 2.0 - 2 / 30, "the keyframe's own packet stays out of the part")++ def test_an_end_keyframe_decoded_before_the_start_is_not_a_candidate(self):+ """-ss 1.95 lands on the keyframe at 2.0 (dts 1.933): that keyframe would give -t < 0, and+ the next one (4.0) is 1.9 s from the end, past tolerance."""+ packets = gop_packets()+ plan = cut.plan_part(packets, 1.95, 2.1, 0.5, 12.0, 30)+ self.assertEqual(plan["start_pts"], 2.0)+ self.assertEqual(plan["reason"], "tolerance")+ plan = cut.plan_part(packets, 1.95, 3.9, 0.5, 12.0, 30)+ self.assertEqual(plan["end_pts"], 4.0)+ self.assertGreater(plan["t"], 0)+ # 2.0 is nearer 2.3, but the copy starts from it: the end is the keyframe after+ plan = cut.plan_part(packets, 1.95, 2.3, 1.8, 12.0, 30)+ self.assertEqual((plan["reason"], plan["end_pts"]), (None, 4.0))++ def test_a_start_just_before_the_end_keyframes_dts_is_not_cut(self):+ """Keyframes 5 ms apart: a start 0.05 ms before the next keyframe's dts lands on the one+ before, and -t to that dts would round to nothing."""+ packets = [(0.0, 0.0, True), (0.005, 0.005, True), (0.010, 0.010, False)]+ plan = cut.plan_part(packets, 0.00495, 0.005, -1, 1.0, 200)+ self.assertEqual(plan["reason"], "tolerance")++ def test_each_end_is_judged_on_its_own(self):+ """A start 0.4 s early and an end 0.4 s early used to cancel out in the part's length."""+ packets = gop_packets()+ self.assertEqual(cut.plan_part(packets, 2.4, 5.9, 0.3, 12.0, 30)["reason"], "tolerance")+ self.assertEqual(cut.plan_part(packets, 2.0, 5.6, 0.3, 12.0, 30)["reason"], "tolerance")+ self.assertIsNone(cut.plan_part(packets, 2.0, 5.8, 0.3, 12.0, 30)["reason"])++ def test_an_end_snaps_to_the_first_keyframe_at_or_after_it(self):+ """Never to an earlier one, which would drop requested frames: 2.4 is nearer 2.0 than 4.0,+ and the part still runs to 4.0, or re-encodes when 4.0 is past the tolerance."""+ packets = gop_packets()+ plan = cut.plan_part(packets, 0.0, 2.4, 2.0, 12.0, 30)+ self.assertEqual((plan["reason"], plan["end_pts"]), (None, 4.0))+ self.assertEqual(cut.plan_part(packets, 0.0, 2.4, 0.5, 12.0, 30)["reason"], "tolerance")+ self.assertEqual(cut.plan_part(packets, 0.0, 2.0, 0.5, 12.0, 30)["end_pts"], 2.0, "a keyframe at the end is the end")+ plan = cut.plan_part(packets, 0.0, 11.0, 0.5, 12.0, 30)+ self.assertEqual((plan["reason"], plan["end_pts"], plan["t"]), (None, None, 11.0), "no keyframe after it: as asked")++ def test_without_an_end_snap_only_the_start_is_judged(self):+ packets = gop_packets()+ plan = cut.plan_part(packets, 4.3, 5.1, 0.5, 12.0, 30, snap_end=False)+ self.assertEqual((plan["reason"], plan["start_pts"], plan["end_pts"], plan["t"]), (None, 4.0, None, 5.1 - 4.3))+ self.assertEqual(plan["end_bound"], 5.1)+ self.assertEqual(cut.plan_part(packets, 4.6, 5.1, 0.5, 12.0, 30, snap_end=False)["reason"], "tolerance")++ def test_reorders_is_true_only_when_a_frame_is_presented_before_one_decoded_ahead(self):+ self.assertFalse(cut.reorders(gop_packets()), "dts behind pts, but presented in decode order")+ ipbb = [(n / 30, (i - 1) / 30, n == 0) for i, n in enumerate((0, 3, 1, 2, 6, 4, 5))]+ self.assertTrue(cut.reorders(ipbb))+ self.assertFalse(cut.reorders([(None, 0.0, True), (0.1, 0.1, False)]))++ def test_reorders_is_judged_within_each_read_window(self):+ """Two windows of a no-B source: the second starts later, and an overlap a seek re-read is+ not a reorder either -- video_packets drops it -- but the order across a gap is not+ compared at all."""+ packets = cut._Packets([(1.0, 1.0, True), (1.1, 1.1, False), (0.5, 0.5, True), (0.6, 0.6, False)])+ packets.breaks = {1}+ self.assertFalse(cut.reorders(packets))+ self.assertTrue(cut.reorders(list(packets)))++ def test_only_a_later_edit_listed_part_starting_between_keyframes_hides_pre_roll(self):+ packets = gop_packets()+ plans = [cut.plan_part(packets, s, e, 0.5, 12.0, 30) for s, e in ((0.3, 2.0), (4.0, 6.0), (8.2, 10.0))]+ self.assertEqual(cut.hidden_preroll_start(packets, plans, True), 3, "the first part's pre-roll is not at a join")+ self.assertIsNone(cut.hidden_preroll_start(packets, plans, False), "make_zero parts show it")+ plans = [cut.plan_part(packets, s, e, 0.5, 12.0, 30) for s, e in ((0.3, 2.0), (4.0, 6.0))]+ self.assertIsNone(cut.hidden_preroll_start(packets, plans, True))++ def test_a_part_that_ends_with_the_video_is_cut_to_its_length(self):+ packets = gop_packets()+ plan = cut.plan_part(packets, 10.0, 12.0, 0.5, 12.0, 30)+ self.assertIsNone(plan["reason"])+ self.assertIsNone(plan["end_pts"])+ self.assertEqual(plan["t"], 2.0)++ def fake_ffprobe(self, keys, fps=30, length=600.0):+ """A run() that answers video_packets' ffprobe for a closed-GOP source with keyframes at+ `keys` (seconds): a -read_intervals window seeks to the keyframe at or before its start+ and reads up to its end. Returns (run, the intervals asked for)."""+ n_frames = int(length * fps)+ key_frames = {int(round(k * fps)) for k in keys}+ packets = [(n / fps, n / fps, n in key_frames) for n in range(n_frames)]+ asked = []++ def run(cmd, **kw):+ if "-read_intervals" not in cmd:+ asked.append(None)+ sel = packets+ else:+ lo, hi = cmd[cmd.index("-read_intervals") + 1].split("%")+ asked.append((lo, hi))+ first = 0+ if lo:+ first = max(i for i, p in enumerate(packets) if p[2] and p[1] <= float(lo))+ sel = [p for p in packets[first:] if not hi or p[1] <= float(hi)]+ text = "\n".join(f"{p:.6f},{d:.6f},{'K_' if k else '__'}" for p, d, k in sel)+ return subprocess.CompletedProcess(cmd, 0, text, "")+ return run, asked++ def test_packets_are_read_in_windows_widened_until_the_plan_has_its_gops(self):+ """Keyframes every 30 s: around 100-102 the first window (+-10 s) holds the keyframe at+ 90 but not the one after the end (120); x4 still not the GOP after it (150); x16 does.+ Nothing before the first window's start is read, and the result is cached."""+ run, asked = self.fake_ffprobe([k * 30.0 for k in range(20)])+ with mock.patch.object(cut, "run", run), mock.patch.object(cut, "file_origin", lambda src: 0.0), \+ mock.patch.dict(cut._PACKETS, clear=True):+ packets = cut.video_packets("long.mp4", [(100.0, 102.0)], 0.5, 600.0)+ self.assertEqual(asked, [("90.000000", "112.000000"), ("60.000000", "142.000000"),+ ("", "262.000000")])+ plan = cut.plan_part(packets, 100.0, 102.0, -1, 600.0, 30)+ self.assertEqual((plan["start_pts"], plan["end_pts"]), (90.0, 120.0))+ self.assertFalse(cut.gop_is_open(packets, plan["end_index"]))+ cut.video_packets("long.mp4", [(100.0, 102.0)], 0.5, 600.0)+ self.assertEqual(len(asked), 3, "cached on (source, windows)")++ def test_a_gop_longer_than_every_window_reads_the_whole_file(self):+ """Keyframes at 0 and 1000 s only: no widened window holds the GOP after the end keyframe,+ so the fourth widening is followed by one read of the whole file."""+ run, asked = self.fake_ffprobe([0.0, 1000.0], length=1200.0)+ with mock.patch.object(cut, "run", run), mock.patch.object(cut, "file_origin", lambda src: 0.0), \+ mock.patch.dict(cut._PACKETS, clear=True):+ packets = cut.video_packets("long.mp4", [(500.0, 502.0)], 0.5, 1200.0)+ self.assertEqual(len(asked), 5)+ self.assertIsNone(asked[-1], "no -read_intervals: the whole file")+ self.assertEqual(asked[0], ("490.000000", "512.000000"))+ self.assertEqual(len(packets), 1200 * 30)++ def test_the_first_window_never_seeks_and_windows_merge(self):+ self.assertEqual(cut.packet_windows([(3.0, 5.0), (20.0, 22.0), (50.0, 51.0)], 10.0, 120.0),+ ((None, 32.0), (40.0, 61.0)))+ self.assertEqual(cut.packet_windows([(3.0, 5.0)], 10.0, 12.0), ((None, None),), "the whole file")+ self.assertEqual(cut.packet_windows([(100.0, 110.0)], 10.0, 115.0), ((90.0, None),), "to the end")++ def test_a_gop_cut_off_by_a_read_window_is_not_judged_closed(self):+ """A window that ends inside a GOP has not shown whether a leading picture follows: the+ next packet in the list is a later window's keyframe, not the end of this GOP."""+ packets = cut._Packets(gop_packets()[:70] + gop_packets()[180:250])+ packets.breaks = frozenset({69})+ self.assertTrue(cut.gop_is_open(packets, 60))+ self.assertFalse(cut.gop_is_open(packets, 70), "a GOP read whole is still judged")++ def test_the_expected_packets_are_the_sources_in_each_range(self):+ packets = gop_packets()+ self.assertEqual(cut.expected_packets(packets, [(0.0, 2.0), (4.0, 6.0), (10.0, None)]), 60 + 60 + 60)++ def test_an_exact_join_passes_the_check(self):+ pts = [n / 30 for n in range(180)]+ check = cut.check_join(pts, [60, 60, 60], 30, True, [1 / 30, 1 / 30])+ self.assertTrue(check["ok"])+ self.assertAlmostEqual(check["max_step_seconds"], 1 / 30, places=6)++ def test_bframe_packet_order_sorts_to_an_exact_join(self):+ # I P B B, as decoded: every P before the two B-frames it references+ pts = [n / 30 for i in range(0, 180, 3) for n in (i + 2, i, i + 1)]+ self.assertNotEqual(pts, sorted(pts))+ self.assertTrue(cut.check_join(pts, [180], 30, True)["ok"])++ def test_one_extra_packet_fails_the_check(self):+ pts = [n / 30 for n in range(180)] + [2.0]+ check = cut.check_join(pts, [60, 60, 60], 30, True, [1 / 30, 1 / 30])+ self.assertFalse(check["ok"])+ self.assertEqual((check["packets"], check["expected_packets"]), (181, 180))++ def test_one_missing_frame_fails_the_check(self):+ pts = [n / 30 for n in range(180) if n != 90]+ self.assertFalse(cut.check_join(pts, [60, 60, 60], 30, True, [1 / 30, 1 / 30])["ok"])++ def test_each_join_step_is_held_to_the_step_its_parts_predict(self):+ """The step at a join is what the parts predict (their container ends and picture starts),+ within a millisecond: 56.7 ms at 30 fps for an exact no-B-frame join passes, and a hole of+ one audio packet more fails, however long the audio packets are (#306 allowed a frame plus+ one audio frame, so a large PCM packet let a hole through). Steps inside a part are a+ frame."""+ join = 1 / 30 + 0.0133 + 0.0100+ exact = [n / 30 for n in range(54)] + [53 / 30 + join + n / 30 for n in range(60)]+ check = cut.check_join(exact, [54, 60], 30, True, [join])+ self.assertTrue(check["ok"])+ self.assertAlmostEqual(check["max_step_seconds"], join, places=6)+ hole = [n / 30 for n in range(54)] + [53 / 30 + join + 0.0213 + n / 30 for n in range(60)]+ self.assertFalse(cut.check_join(hole, [54, 60], 30, True, [join])["ok"])+ self.assertFalse(cut.check_join(exact, [54, 60], 30, True, [join + 0.0015])["ok"], "1 ms is the slack")+ self.assertTrue(cut.check_join(exact, [54, 60], 30, True, [join + 0.0009])["ok"])+ self.assertFalse(cut.check_join(exact, [54, 60], 30, True)["ok"], "unpredicted, a join step is held to 1.5 frames")+ inside = [n / 30 for n in range(54)] + [53 / 30 + 0.06 + n / 30 for n in range(60)]+ self.assertTrue(cut.check_join(inside, [54, 60], 30, True, [0.06])["ok"], "the premise: predicted at the join")+ self.assertFalse(cut.check_join(inside, [50, 64], 30, True, [1 / 30])["ok"], "a long step inside a part fails")++ def test_a_join_step_is_predicted_from_the_parts_containers_and_pictures(self):+ """(this part's container end - its last picture) + (the next part's first picture - its+ container start), read from each part's format and video packets."""+ docs = {"a": {"streams": [], "format": {"start_time": "0.000000", "duration": "1.813333"}},+ "b": {"streams": [], "format": {"start_time": "0.000000", "duration": "2.000000"}}}+ pts = {"a": [n / 30 for n in range(54)], "b": [0.01 + n / 30 for n in range(60)]}+ with mock.patch.object(cut, "_part_probe", docs.get), \+ mock.patch.object(cut, "stream_packet_times", lambda path, st, entry, limit=None: pts[path]):+ (step,) = cut.predicted_join_steps(["a", "b"])+ self.assertAlmostEqual(step, (1.813333 - 53 / 30) + 0.01, places=6)+ with mock.patch.object(cut, "_part_probe", lambda path: None), \+ mock.patch.object(cut, "stream_packet_times", lambda *a, **k: []):+ self.assertEqual(cut.predicted_join_steps(["a", "b", "c"]), [None, None])++ def test_a_checked_join_is_placed_under_the_outputs_lock(self):+ """The checked join is written beside the parts and placed afterwards; placing it must+ respect another run's lock on the output, as an ffmpeg write does."""+ with tempfile.TemporaryDirectory() as tmp:+ src, dst = os.path.join(tmp, "joined.mp4"), os.path.join(tmp, "out.mp4")+ Path(src).write_bytes(b"new")+ Path(dst).write_bytes(b"theirs")+ Path(tmp, ".out.mp4.ffskill-lock").write_text(str(os.getpid()))+ with mock.patch.object(cut.STATE, "overwrite", True), self.assertRaises(SystemExit):+ cut.place_output(src, dst)+ self.assertEqual(Path(dst).read_bytes(), b"theirs")++ def audio_join(self, drift, silent=False):+ """check_join_audio on a synthetic two-part join: part 1 is source 0-2 s, part 2 source 4-6 s+ placed at 2 s, its sound `drift` seconds late against its picture."""+ src_a = [(i * 0.02, "z" if silent else f"h{i}") for i in range(-50, 600)]+ out_a = ([(p, h) for p, h in src_a if 0 <= p < 2 - 1e-9]+ + [(p - 2.0 + drift, h) for p, h in src_a if 4 - 1e-9 <= p < 6 - 1e-9])+ vpts = [n / 30 for n in range(120)]++ def hashes(path, lo=None, hi=None, **_):+ if path == "out.mp4":+ return out_a+ return [(p, h) for p, h in src_a if (lo is None or p >= lo) and (hi is None or p <= hi)]+ with mock.patch.object(cut, "audio_packet_hashes", hashes), mock.patch.object(cut, "file_origin", lambda src: 0.0), \+ mock.patch.object(cut, "stream_packet_times", lambda *a, **k: vpts):+ return cut.check_join_audio("src.mp4", "out.mp4", [0.0, 4.0], [60, 60])++ def test_the_audio_check_measures_each_parts_sound_against_its_picture(self):+ check = self.audio_join(0.016)+ self.assertEqual(check["audio_offset_ms"], [0.0, 16.0])+ self.assertEqual(check["audio_parts_checked"], 2)+ self.assertFalse(check["audio_ok"])+ self.assertTrue(self.audio_join(0.004)["audio_ok"], "within 5 ms")+ self.assertFalse(self.audio_join(-0.006)["audio_ok"], "early sound fails too")++ def test_a_part_whose_packets_repeat_is_unmeasured_not_failed(self):+ check = self.audio_join(0.05, silent=True)+ self.assertEqual(check["audio_offset_ms"], [None, None])+ self.assertEqual((check["audio_parts_checked"], check["audio_ok"]), (0, True))++ def test_a_checked_join_is_renamed_into_place_under_the_outputs_lock(self):+ """place_output(move=True) renames the hidden sibling the join was written to (no copy of+ the whole file) and still refuses while another run holds the output's lock."""+ with tempfile.TemporaryDirectory() as tmp:+ dst = os.path.join(tmp, "out.mp4")+ src = cut.sibling_temp(dst, "join")+ self.assertEqual(os.path.dirname(src), tmp)+ self.assertTrue(os.path.basename(src).startswith(".out.ffskill-join-") and src.endswith(".mp4"))+ Path(src).write_bytes(b"new")+ Path(dst).write_bytes(b"theirs")+ lock = Path(tmp, ".out.mp4.ffskill-lock")+ lock.write_text(str(os.getpid()))+ with mock.patch.object(cut.STATE, "overwrite", True), self.assertRaises(SystemExit):+ cut.place_output(src, dst, move=True)+ self.assertEqual(Path(dst).read_bytes(), b"theirs")+ lock.unlink()+ with mock.patch.object(cut.STATE, "overwrite", True), \+ mock.patch("shutil.copyfile", side_effect=AssertionError("copied")):+ cut.place_output(src, dst, move=True)+ self.assertEqual(Path(dst).read_bytes(), b"new")+ self.assertFalse(os.path.exists(src))++ def test_without_constant_timing_only_the_count_is_checked(self):+ pts = [n / 30 + (0.5 if n >= 60 else 0) for n in range(120)]+ check = cut.check_join(pts, [60, 60], 30, False, [1 / 30])+ self.assertTrue(check["ok"])+ self.assertIsNone(check["max_step_seconds"])+++class VfrGuardTests(unittest.TestCase):+ """cut.py's VFR guard on real files: the default average check, the measured timing under+ --vfr-guard sampled, the reasons, and --vfr-guard off."""++ @classmethod+ def setUpClass(cls):+ DIR.mkdir(parents=True, exist_ok=True)+ cls.fp = DIR / "vfr_false_positive.mp4"+ if not cls.fp.exists():+ # every frame 1/30 s apart, but the last one held 8x: the average rate drops to 29.3+ # against a nominal 30, the shape that tripped the old whole-file check+ base = DIR / "vfr_fp_base.mp4"+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "testsrc2=s=160x90:r=30:d=10", "-f", "lavfi", "-i", "sine=d=10",+ "-c:v", "libx264", "-bf", "0", "-g", "30", "-video_track_timescale", "600", "-c:a", "aac", base)+ sh("ffmpeg", "-y", "-v", "error", "-i", base, "-c", "copy", "-bsf:v",+ "setts=duration=if(eq(N\\,299)\\,DURATION*8\\,DURATION)", "-video_track_timescale", "600", cls.fp)+ cls.drop = DIR / "vfr_dropped.mp4"+ if not cls.drop.exists():+ # one frame in every ten dropped, the gaps kept: genuinely variable timing+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "testsrc2=s=160x90:r=30:d=10", "-f", "lavfi", "-i", "sine=d=10",+ "-vf", "select='not(eq(mod(n\\,10)\\,5))'", "-fps_mode", "vfr", "-c:v", "libx264", "-bf", "0", "-g", "30",+ "-c:a", "aac", cls.drop)+ cls.short = DIR / "vfr_short.mp4"+ if not cls.short.exists():+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "testsrc2=s=160x90:r=30:d=0.5", "-c:v", "libx264", "-bf", "0", cls.short)+ cls.late_drops = DIR / "vfr_late_drops.mp4"+ if not cls.late_drops.exists():+ # one keyframe for 20 s, frames dropped only after 14 s: every window seeks back to 0+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "testsrc2=s=160x90:r=30:d=20",+ "-vf", "select='not(gt(t\\,14)*eq(mod(n\\,10)\\,5))'", "-fps_mode", "vfr",+ "-c:v", "libx264", "-bf", "0", "-g", "1000", "-x264-params", "scenecut=0", cls.late_drops)+ cls.tone = DIR / "vfr_tone.wav"+ if not cls.tone.exists():+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", "sine=d=4", cls.tone)++ def test_an_average_rate_below_nominal_is_not_vfr(self):+ self.assertTrue(probe(str(self.fp))["video"]["variable_frame_rate_suspected"], "the premise: the old check trips")+ data = cut_json(self.fp, "--start", "0", "--duration", "2", "--vfr-guard", "sampled", "-o", DIR / "vfr_fp_cut.mp4")+ self.assertEqual((data["vfr_check"]["measured"], data["vfr_check"]["guard"]), ("sampled_cfr", "sampled"))+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))++ def test_dropped_frames_force_a_reencode(self):+ data = cut_json(self.drop, "--start", "0", "--duration", "2", "--vfr-guard", "sampled", "-o", DIR / "vfr_drop_cut.mp4")+ self.assertEqual(data["vfr_check"]["measured"], "vfr")+ self.assertEqual(data["reencode_reason"], ["vfr"])+ self.assertTrue(data["reencoded"])+ self.assertEqual(data["precision"], "frame")++ def test_dropped_frames_late_in_a_long_gop_are_seen(self):+ """Each window reads from its own start, not from the keyframe the read seeks back to."""+ data = cut_json(self.late_drops, "--start", "0", "--duration", "2", "--vfr-guard", "sampled", "--dry-run",+ "-o", DIR / "never_late.mp4")+ self.assertEqual(data["vfr_check"]["windows"], 3)+ self.assertEqual(data["vfr_check"]["measured"], "vfr")++ def test_vfr_guard_off_keeps_the_copy_and_says_so(self):+ data = cut_json(self.drop, "--start", "0", "--duration", "2", "--vfr-guard", "off", "--tolerance", "-1",+ "-o", DIR / "vfr_drop_copy.mp4")+ self.assertEqual((data["vfr_check"]["measured"], data["vfr_check"]["guard"]), ("vfr", "off"))+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ self.assertTrue(any("--vfr-guard off" in n for n in data["notes"]), data["notes"])++ def test_a_vfr_guard_off_join_is_checked_by_its_packet_count_only(self):+ """Variable timing has no step to hold a join to, so --vfr-guard off keeps the copy and the+ join check counts packets only."""+ data = cut_json(self.drop, "--segments", "0-2,4-6", "--vfr-guard", "off", "--tolerance", "-1",+ "-o", DIR / "vfr_drop_join.mp4")+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ self.assertIsNone(data["join_check"]["max_step_seconds"])+ self.assertTrue(data["join_check"]["ok"])+ self.assertEqual(data["join_check"]["packets"], data["join_check"]["expected_packets"])++ def test_too_few_frames_to_measure_reencodes(self):+ data = cut_json(self.short, "--start", "0", "--duration", "0.3", "--vfr-guard", "sampled",+ "-o", DIR / "vfr_short_cut.mp4")+ self.assertEqual(data["vfr_check"]["measured"], "inconclusive")+ self.assertEqual(data["reencode_reason"], ["vfr_inconclusive"])+ self.assertEqual(data["precision"], "frame")++ def test_a_dry_run_measures_and_reports(self):+ data = cut_json(self.drop, "--start", "0", "--duration", "2", "--vfr-guard", "sampled", "--dry-run",+ "-o", DIR / "never_vfr.mp4")+ self.assertEqual(data["vfr_check"]["measured"], "vfr")+ self.assertEqual(data["reencode_reason"], ["vfr"])++ def test_nothing_is_measured_when_nothing_would_copy(self):+ audio = cut_json(self.tone, "--start", "1", "--duration", "1", "-o", DIR / "vfr_tone_cut.wav")+ self.assertNotIn("vfr_check", audio)+ audio = cut_json(self.tone, "--start", "1", "--duration", "1", "--vfr-guard", "sampled", "-o", DIR / "vfr_tone_cut2.wav")+ self.assertNotIn("vfr_check", audio)+ accurate = cut_json(self.drop, "--start", "0", "--duration", "1", "--accurate", "--vfr-guard", "sampled",+ "-o", DIR / "vfr_drop_acc.mp4")+ self.assertNotIn("vfr_check", accurate)+ self.assertEqual(accurate["reencode_reason"], ["requested"])+++ # ---- the default, --vfr-guard average: 2.5.1's guard, with the sample reported++ def test_a_short_constant_clip_copies_by_default(self):+ """2.5.1 copied it; the sampled guard re-encodes it (11 intervals, 20 needed to judge)."""+ self.assertFalse(probe(str(self.short))["video"]["variable_frame_rate_suspected"])+ data = cut_json(self.short, "--start", "0", "--duration", "0.3", "-o", DIR / "vfr_short_default.mp4")+ self.assertEqual((data["mode"], data["reencode_reason"], data["precision"]), ("copy", [], "packet"))+ self.assertNotIn("vfr_check", data, "the average check passed it, so nothing is sampled")++ def test_a_suspected_but_constant_source_reencodes_by_default_and_says_sampled_would_copy(self):+ """2.5.1 re-encoded it, and still does; the sample shows the timing is constant, and the+ note names the guard that would have copied it."""+ out = DIR / "vfr_fp_default.mp4"+ proc = script("cut.py", self.fp, "--start", "0", "--duration", "2", "-o", out, "--json")+ self.assertIn("variable-frame-rate", proc.stderr)+ data = json.loads(proc.stdout)+ self.assertEqual((data["mode"], data["reencode_reason"], data["precision"]), ("accurate", ["vfr"], "frame"))+ self.assertEqual((data["vfr_check"]["measured"], data["vfr_check"]["guard"]), ("sampled_cfr", "average"))+ self.assertTrue(any("--vfr-guard sampled" in n for n in data["notes"]), data["notes"])++ def test_a_dropped_frame_source_reencodes_by_default_without_the_note(self):+ data = cut_json(self.drop, "--start", "0", "--duration", "2", "--dry-run", "-o", DIR / "never_vfr_default.mp4")+ self.assertEqual(data["reencode_reason"], ["vfr"])+ self.assertEqual((data["vfr_check"]["measured"], data["vfr_check"]["guard"]), ("vfr", "average"))+ self.assertFalse(any("--vfr-guard" in n for n in data["notes"]), data["notes"])++ def test_the_vfr_copy_flag_is_gone(self):+ """--vfr-copy never shipped: --vfr-guard off replaced it."""+ proc = script("cut.py", self.drop, "--vfr-copy", "--dry-run", "-o", DIR / "never_vfr_copy.mp4", expect_fail=True)+ self.assertNotEqual(proc.returncode, 0)+ self.assertIn("--vfr-copy", proc.stderr)++if __name__ == "__main__":+ unittest.main(verbosity=2)diff --git a/tests/test_editing.py b/tests/test_editing.pyindex ff21592..6a413a2 100644--- a/tests/test_editing.py+++ b/tests/test_editing.py@@ -106,6 +106,109 @@ class EditingTests(MediaFixtures):self.assertGreater(abs(data["duration_delta_seconds"]), 0.05, "this scenario must produce a real, visible divergence, not a rounding artefact")self.assertAlmostEqual(data["duration_delta_seconds"], data["output_duration"] - data["requested_duration"], places=6)+ def test_cut_json_says_why_it_reencoded_and_how_exact_each_segment_is(self):+ """reencode_reason names every cause, and --codec is named even when --accurate already+ forced the re-encode; segment_precision and least_exact_precision describe the segments."""+ # a clean copy: nothing re-encoded, one segment+ out = OUT / "cut_reasons_copy.mkv"+ data = json.loads(script("cut.py", self.src, "--start", "0", "--end", "2", "--tolerance", "-1", "-o", out, "--json").stdout)+ self.assertEqual((data["mode"], data["reencode_reason"]), ("copy", []))+ self.assertIsNone(data["segment_precision"], "a single segment has no per-segment list")+ self.assertEqual(data["least_exact_precision"], "packet")+ out2 = OUT / "cut_reasons_accurate.mp4"+ data2 = json.loads(script("cut.py", self.src, "--start", "2", "--end", "6", "--accurate", "-o", out2, "--json").stdout)+ self.assertEqual(data2["reencode_reason"], ["requested"])+ self.assertFalse(data2["start_snapped"], "a re-encode starts where asked")+ # .mkv: no edit list can hide the pre-roll, so this copy snaps its start to the keyframe at 0+ # and misses the tight tolerance+ out3 = OUT / "cut_honest_hybrid.mkv"+ data3 = json.loads(script("cut.py", self.src, "--start", "1.13", "--end", "5.71", "--tolerance", "0.02", "-o", out3, "--json").stdout)+ self.assertEqual(data3["mode"], "hybrid")+ self.assertEqual(data3["reencode_reason"], ["tolerance"])+ self.assertFalse(data3["keyframe_snapped"])+ self.assertIn(0.0, data3["nearest_keyframes"])+ out4 = OUT / "cut_reasons_segments.mp4"+ data4 = json.loads(script("cut.py", self.src, "--segments", "1-3,6-9", "--accurate", "-o", out4, "--json").stdout)+ self.assertEqual(data4["reencode_reason"], ["requested"])+ self.assertEqual(data4["segment_precision"], ["frame", "frame"])+ self.assertEqual((data4["precision"], data4["least_exact_precision"]), ("frame", "frame"))+ # --codec forces the re-encode, and says so rather than claiming it was asked for+ out5 = OUT / "cut_honest_codec.mp4"+ data5 = json.loads(script("cut.py", self.src, "--start", "2", "--end", "4", "--codec", "hevc", "-o", out5, "--json").stdout)+ self.assertEqual(data5["mode"], "accurate")+ self.assertEqual(data5["reencode_reason"], ["codec"])+ # ...and --codec is still named when --accurate already forced the re-encode+ out6 = OUT / "cut_honest_accurate_codec.mp4"+ data6 = json.loads(script("cut.py", self.src, "--start", "2", "--end", "4", "--accurate", "--codec", "hevc", "-o", out6, "--json").stdout)+ self.assertEqual(data6["reencode_reason"], ["requested", "codec"])++ def test_cut_top_level_precision_is_the_least_exact_segments(self):+ """least_exact_precision is the least exact segment's precision, so a keyframe-snapped copy+ segment is never hidden behind a re-encoded one."""+ sys.path.insert(0, str(SCRIPTS))+ import cut+ self.assertEqual(cut.least_exact(["frame", "packet"]), "packet")+ self.assertEqual(cut.least_exact(["sample", "codec_frame"]), "codec_frame")+ self.assertEqual(cut.least_exact(["sample", "frame"]), "frame")+ self.assertEqual(cut.least_exact(["sample"]), "sample")++ def test_cut_precision_keeps_its_formula_and_least_exact_precision_is_beside_it(self):+ """`precision` and `keyframe_snapped` keep their 2.x formula (precision_of() for the run;+ keyframe_snapped is precision == packet). The one run where the least exact segment differs+ is an audio-only join of a copied and a re-encoded part: precision says the run re-encoded,+ least_exact_precision that one part is only packet-exact. start_snapped is true when any+ copied start moved, null while one is unmeasured (--dry-run), false otherwise."""+ sys.path.insert(0, str(SCRIPTS))+ import cut+ wav = {"audio": {"codec": "pcm_s16le"}}++ def part(precision, reencoded, snapped):+ return {"precision": precision, "reencoded": reencoded, "start_snapped": snapped}+ mixed = cut.report_precision(wav, "out.wav", True, [part("packet", False, False), part("sample", True, False)])+ self.assertEqual((mixed["precision"], mixed["least_exact_precision"]), ("sample", "packet"))+ self.assertEqual(mixed["segment_precision"], ["packet", "sample"])+ self.assertFalse(mixed["keyframe_snapped"])+ copy = cut.report_precision(wav, "out.wav", False, [part("packet", False, False)])+ self.assertEqual((copy["precision"], copy["least_exact_precision"], copy["keyframe_snapped"]), ("packet", "packet", True))+ self.assertIsNone(copy["segment_precision"])+ video = {"video": {"codec": "h264"}}+ self.assertIs(cut.report_precision(video, "o.mp4", False, [part("packet", False, None), part("packet", False, True)])["start_snapped"], True)+ self.assertIsNone(cut.report_precision(video, "o.mp4", False, [part("packet", False, None), part("packet", False, False)])["start_snapped"])+ self.assertIs(cut.report_precision(video, "o.mp4", True, [part("frame", True, False)])["start_snapped"], False)++ def test_cut_start_snapped_is_measured_and_null_under_dry_run(self):+ """keyframe_snapped is true for every stream copy; start_snapped says whether the copied+ picture really starts away from --start. Matroska keeps no edit list, so a copy from 2 s+ starts at the keyframe at 0; a copy from 0 starts where asked; a dry run measures nothing."""+ out = OUT / "cut_start_snapped.mkv"+ data = json.loads(script("cut.py", self.src, "--start", "2", "--end", "6", "--tolerance", "-1", "-o", out, "--json").stdout)+ self.assertEqual(data["mode"], "copy")+ self.assertTrue(data["keyframe_snapped"])+ self.assertTrue(data["start_snapped"])+ self.assertFalse(data["edit_list"])+ out2 = OUT / "cut_start_exact.mkv"+ data2 = json.loads(script("cut.py", self.src, "--start", "0", "--end", "2", "--tolerance", "-1", "-o", out2, "--json").stdout)+ self.assertTrue(data2["keyframe_snapped"])+ self.assertFalse(data2["start_snapped"])+ data3 = json.loads(script("cut.py", self.src, "--start", "2", "--end", "6", "--dry-run", "-o", OUT / "never_snapped.mkv", "--json").stdout)+ self.assertTrue(data3["keyframe_snapped"], "a planned stream copy")+ self.assertIsNone(data3["start_snapped"], "nothing was cut, so nothing was measured")++ def test_cut_matroska_copy_keyframe_snap_reports_a_real_nonzero_delta(self):+ """The same divergence in Matroska, which has no edit lists: the copy really starts at the+ keyframe before 1.13, and start_snapped says so."""+ out = OUT / "cut_copy_keyframe_snap.mkv"+ data = json.loads(script("cut.py", self.src, "--start", "1.13", "--end", "5.71", "--tolerance", "2.0", "-o", out, "--json").stdout)+ self.assertEqual(data["mode"], "copy")+ self.assertTrue(data["keyframe_snapped"])+ self.assertTrue(data["start_snapped"])+ self.assertFalse(data["edit_list"])+ self.assertFalse(data["reencoded"])+ actual = probe(str(out))["duration"]+ self.assertAlmostEqual(data["output_duration"], actual, places=2)+ self.assertGreater(abs(data["duration_delta_seconds"]), 0.05)+ self.assertAlmostEqual(data["duration_delta_seconds"], data["output_duration"] - data["requested_duration"], places=6)+def test_cut_bad_range_fails(self):script("cut.py", self.src, "--start", "5", "--end", "2", expect_fail=True)diff --git a/tests/test_orchestration.py b/tests/test_orchestration.pyindex 3aca927..3503509 100644--- a/tests/test_orchestration.py+++ b/tests/test_orchestration.py@@ -1484,6 +1484,46 @@ class OrchestrationTests(MediaFixtures):self.assertIsNone(data2["cut_stream_copy"])self.assertNotIn("cut_reencoded", data2["results"][0])+ def test_batch_counts_cut_reencode_reasons_beside_the_stream_copy_rate(self):+ """cut.py's `reencode_reason` reaches batch.py's caller without changing cut_stream_copy:+ each results row lists the reasons its cut.py calls named (once per call), and the+ top-level cut_reencode_reasons counts them across the folder (null when no cut.py step+ ran)."""+ folder = OUT / "batch_cut_reasons"+ folder.mkdir(exist_ok=True)+ # this test edits the cache below, so a rerun starts without one+ (folder / "out" / ".ffskill_cache.json").unlink(missing_ok=True)+ (folder / "a.mp4").write_bytes(Path(self.src).read_bytes())+ recipe = folder / "batch.json"+ # the same two steps as the stream-copy rate test: a tolerance re-encode, then a copy+ recipe.write_text(json.dumps({"glob": "*.mp4", "output_dir": "out", "suffix": "_cut",+ "steps": [["cut.py", "{in}", "--start", "1.13", "--end", "5.71",+ "--tolerance", "0.02", "-o", "{out}"],+ ["cut.py", "{in}", "--start", "0", "--end", "2",+ "--tolerance", "-1", "-o", "{out}"]]}))+ data = json.loads(script("batch.py", folder, "--recipe", recipe, "--fast", "--json").stdout)+ self.assertEqual(data["results"][0]["cut_reencoded"], [True, False])+ self.assertEqual(data["results"][0]["cut_reencode_reasons"], ["tolerance"])+ self.assertEqual(data["cut_reencode_reasons"], {"tolerance": 1})+ self.assertNotIn("reencode_reasons", data["cut_stream_copy"], "cut_stream_copy keeps its 2.x shape")+ # a row served from a cache an earlier 2.x batch wrote has cut_reencoded but no reasons:+ # its re-encoded call counts as "unknown", never as {} ("none re-encoded")+ cache_path = folder / "out" / ".ffskill_cache.json"+ cache = json.loads(cache_path.read_text(encoding="utf-8"))+ for row in cache.values():+ row.pop("cut_reencode_reasons", None)+ cache_path.write_text(json.dumps(cache), encoding="utf-8")+ cached = json.loads(script("batch.py", folder, "--recipe", recipe, "--fast", "--json").stdout)+ self.assertTrue(cached["results"][0]["cached"])+ self.assertEqual(cached["cut_stream_copy"]["reencoded"], 1)+ self.assertEqual(cached["cut_reencode_reasons"], {"unknown": 1})+ recipe2 = folder / "batch_no_cut.json"+ recipe2.write_text(json.dumps({"glob": "*.mp4", "output_dir": "out2", "suffix": "_nc",+ "steps": [["fit.py", "{in}", "--duration", "3", "-o", "{out}"]]}))+ data2 = json.loads(script("batch.py", folder, "--recipe", recipe2, "--dry-run", "--json").stdout)+ self.assertIsNone(data2["cut_reencode_reasons"])+ self.assertIsNone(data2["cut_stream_copy"])+def test_batch_project_recipe_cache_invalidates_on_project_json_content_change(self):"""A "project" recipe is just {"project": "<path>", "clip_key": N} -- the real settings(export preset, captions, everything) live in the file at that path. The cache key used