# Script reference Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--json-brief` (since 1.11.0: the same JSON result trimmed to `status`, `output`, `dry_run`, `verified`, a compact `summary` of the output probe -- duration_s, width, height, fps, vcodec, acodec, channels, and lufs when measured -- the tool's own keys, and the count of commands instead of the command lines; it implies `--json`, leaves `--json`'s own output untouched, and failures print the usual full failure document), `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `--plan FILE` (the dry run written as a plan document that `render.py FILE` executes later; see render.py; `render.py` and `verify.py` refuse it), `-o OUT` (except `probe`, `check`, `cropdetect`, `scenes`, `batch` and `verify`, which take none); every re-encoding tool and `export.py` also take `--hw`/`--no-hw` (h264/hevc/prores on Apple VideoToolbox, Apple Silicon only, CRF mapped to `-q:v`; AV1 stays on the CPU; a job VideoToolbox itself refuses -- the encoder cannot open or its compression session fails -- is re-encoded on the CPU and reported in `hw.fallback`/`hw.notes`, any other failure is not retried; a GPU encode adds a `notes` line that its quality is not CRF-equivalent; `FFMPEG_SKILL_HW=1` makes it the default for every tool except `export.py`, whose delivery presets need `--hw` itself; `render.py`/`batch.py --hw`/`--no-hw` apply to every stage, export included; results name the `encoder` that ran); every editing tool that re-encodes (not `export.py`, whose preset decides the codec) also takes `--codec h264|hevc|av1|prores` (the encoder for the re-encode; default x264 for SDR, x265 Main10 for HDR, unchanged) and `--quality N` (CRF scale, default 18 -- 30 for `proxy.py`; up to 63 for av1; ignored by prores). 2.0 removed `--crf` from these tools (it was `--quality`'s alias); `export.py` keeps its own `--crf`, which is not an alias. Every tool refuses (`kind: input`, `error.reason: output_exists`, before anything runs) to replace an existing output unless `--overwrite` is given. Refusals carry `error.reason` and `error.details` (the facts behind the message; `contract --json` → `json_output.error_reasons`), and what a run decided on its own -- a stale output lock taken over, no lock possible, a plan input nobody fingerprinted, an odd-sized frame scaled to even, subtitle streams dropped on a retry (with the first attempt's error), a font substituted, a measurement skipped under `--dry-run`, an encoder list that could not be read, an invalid `FFMPEG_SKILL_TIMEOUT`, and every `warning:` line -- is in `diagnostics: {warnings, fallbacks, skipped}` as well as on stderr (codes: `contract --json` → `json_output.diagnostic_codes`). `--codec av1`/`prores` with no encoder for it refuses `kind: missing_tool`, `error.reason: encoder_missing`; when the encoder list could not be read at all, `kind: ffmpeg`, `encoder_list_unreadable`. Tools that draw text (`overlay.py --text`, `graphics.py`, `caption.py`, `grid.py --label auto`) report `font_used: {asked, file, family, how, substituted}`. `--codec hevc` on SDR writes 8-bit BT.709 HEVC (`hvc1`), `av1` uses SVT-AV1 (libaom fallback), `prores` is 422 HQ and needs an explicit `-o NAME.mov` (or `.mkv`), `h264` refuses an HDR source (`kind: input`, run `color.py --to-sdr` first). `export.py` keeps choosing the codec from its preset and has neither `--codec` nor `--quality`; a `render.py` project cannot choose a codec either -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) still runs ffprobe, and with `--analyze` ffmpeg to sample picture levels, `check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report`/`silence`/`loudness`/`stabilize` still run their ffmpeg/ffprobe measurements (a dry-run plan rests on real numbers; they just don't write the final artifact), `overlay` measures a multi-line `--text`'s lines on FFmpeg 8.0, 8.0.1 and 8.1.0 (one drawtext on a generated frame), `metadata` with `--auto-chapters` and `cut` with `--snap beats` decode the input for their measurement, `render` and `batch` run each stage or step as its own dry run (so a measuring stage measures an input that exists), and `verify` accepts the flag but ignores it entirely (its document says `dry_run: false` and a note says so). Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). ## Time grammar (every time-taking flag, 1.9) One parser, `time_arg()`, behind every `--start`, `--end`, `--at`, `--from`, `--duration`, `--segments`, cue file and project field: seconds (`12.5`), `mm:ss(.fff)` (`1:30`), `hh:mm:ss(.fff)` (`00:01:30.250`; a comma also works, as in SRT). A four-part `hh:mm:ss:ff` is SMPTE non-drop-frame timecode at the source's frame rate; append `@fps` (`00:01:02:15@29.97`) to name the rate yourself, which is the only way for a tool with no input file (`caption.py --text` without a video, and `--fps` there). A four-part value with no fps anywhere is `kind: input` naming the flag. Nothing else about times differs between tools. ## Verdict thresholds (what passes) The numbers behind `verified`, `check.py`'s PASS/WARN/FAIL rows and the cuts the tools make. A result also carries the tolerance it used in each `verification[]` step (`tolerance`, since 2.18). Every row names the constant or flag it comes from, and a test holds the table to it (`test_the_thresholds_table_matches_the_code`). | what | value | source | used by | |---|---|---|---| | true peak may exceed the dBTP ceiling by | 0.1 dB | `_platforms.TP_TOLERANCE_DB` | `loudness.py`, `check.py`, `export.py` | | a normalised file is on its `-I` target within | 1.0 LU | `loudness.LUFS_TOLERANCE` | `loudness.py` | | a levels pass keeps the sound's length to (or one AAC frame, 1024 samples, if longer) | 0.03 s | `loudness.AUDIO_LENGTH_TOLERANCE` | `loudness.py` | | a joined picture is as long as the clips less the transitions, to (frames) | 1.5 | `join.DURATION_TOLERANCE_FRAMES` | `join.py` | | ... and at least | 0.05 s | `join.DURATION_TOLERANCE_MIN` | `join.py` | | the picture and the sound end together, beyond the gap the inputs had, to | 0.25 s | `_common.emit.STREAM_LENGTH_TOLERANCE` | `cut.py`, `join.py`, `export.py` (`stream_lengths`) | | every kept stream decodes at least one frame in its first and its last | 1.0 s | `_common.emit.DECODE_WINDOW_SECONDS` | `cut.py`, `join.py`, `export.py` (`decode`) | | a lossless cut may land this far from the asked time before it re-encodes | 0.5 s | `cut.py --tolerance` | `cut.py` | | silence is sound at or below | -35 dBFS | `silence.py --threshold` | `silence.py` | | ... lasting at least | 0.6 s | `silence.py --min-silence` | `silence.py` | | a removed silence is digital silence when 99% of it sits at or below | -90 dBFS | `silence.DIGITAL_SILENCE_DB` | `silence.py` (`silence_kinds`) | | a cut is flagged when the level around it is within this much of `--threshold` | 10 dB | `silence.CUT_SOUND_MARGIN_DB` | `silence.py` (`cut_warnings`) | | a track is silent when its peak is at or below | -50 dBFS | `_common.probe.SILENT_PEAK_DBFS` | `check.py`; the `--silence-threshold` default of `join.py`, `audio.py`, `waveform.py` | | a filler word longer than this is a held vowel, kept | 1.2 s | `_common.decision.FILLER_MAX_WORD` | `silence.py --filler` | | a pause this long between two tokens of an unspaced script is a word boundary | 0.1 s | `_common.decision.FILLER_BOUNDARY_GAP` | `silence.py --filler` | | `--content` black: WARN above this share of the duration | 0.10 | `check.BLACK_WARN` | `check.py --content` | | `--content` black: FAIL at this share | 0.95 | `check.BLACK_FAIL` | `check.py --content` | | `--content` black: a pixel is black below this share of the luma range | 0.10 | `_common.probe.CONTENT_BLACK_PIX_TH` | `check.py --content` | | `--content` black: a black run shorter than this is not counted | 0.1 s | `_common.probe.CONTENT_MIN_SPAN` | `check.py --content` | | `--content` frozen: WARN when the longest span is above this, or above 30% | 3.0 s | `check.FROZEN_WARN_S` | `check.py --content` | | `--content` frozen: FAIL when one span covers this share | 0.95 | `check.FROZEN_FAIL` | `check.py --content` | | `--content` frozen: a picture unchanged for at least this long is frozen | 0.5 s | `_common.probe.CONTENT_FREEZE_MIN` | `check.py --content` | | `--content` frozen: frames this close count as unchanged (freezedetect noise) | -60 dB | `_common.probe.CONTENT_FREEZE_NOISE` | `check.py --content` | | `--content` silence: WARN above this share below the silent level | 0.50 | `check.SILENCE_WARN` | `check.py --content` | | `--content` silence: FAIL at this share | 0.95 | `check.SILENCE_FAIL` | `check.py --content` | | `--content` silence: a silent run shorter than this is not counted | 0.5 s | `_common.probe.CONTENT_SILENCE_MIN` | `check.py --content` | | `--content` dropout: a gap of sound at or below | -80 dBFS | `_common.probe.CONTENT_DROPOUT_DB` | `check.py --content` | | ... between (s) and 1 s long, with sound on both sides | 0.02 s | `_common.probe.CONTENT_DROPOUT_MIN` | `check.py --content` | | `--levels`: FAIL when one frame has more than this share of its luma (or of its chroma) samples out of the legal range | 1.0 % | `check.py --levels-tolerance` | `check.py --levels` | | `--legalize`: the written file may keep this share of one frame's luma (or chroma) samples out of range (step `legal_levels`) | 1.0 % | `color.LEGALIZE_TOLERANCE_PCT` | `color.py --legalize` | | a beat grid below this confidence is not snapped to | 0.5 | `_common.decision.BEAT_MIN_CONFIDENCE` | `cut.py --snap beats`, `scenes.py --beats` | Delivery targets per platform (`scripts/_platforms.py`). A file passes loudness within the platform's tolerance of its target, and true peak at or below its ceiling plus 0.1 dB. The maximum length (and the file size `check.py` reads from the same table) is an upload limit: the table's as of `_platforms.UPLOAD_LIMITS_AS_OF`, guidance rather than a requirement, because platforms change it and whoever uploads checks the current one. `check.py` WARNs over it; `export.py` trims to it unless `--allow-long` and holds the written length to it with no tolerance. | platform | loudness | tolerance | true peak | max duration | |---|---|---|---|---| | `tiktok` | -14 LUFS | ±2 LU | -1 dBTP | 600 s | | `reels` | -14 LUFS | ±2 LU | -1 dBTP | 90 s | | `shorts` | -14 LUFS | ±2 LU | -1 dBTP | 180 s | | `youtube` | -14 LUFS | ±2 LU | -1 dBTP | 43200 s | | `youtube-hdr` | -14 LUFS | ±2 LU | -1 dBTP | 43200 s | | `youtube-av1` | -14 LUFS | ±2 LU | -1 dBTP | 43200 s | | `x` | -14 LUFS | ±3 LU | -1 dBTP | 140 s | | `linkedin` | -14 LUFS | ±3 LU | -1 dBTP | 600 s | | `facebook` | -14 LUFS | ±3 LU | -1 dBTP | 14400 s | | `podcast` | -16 LUFS | ±1 LU | -1 dBTP | — | | `broadcast` | -23 LUFS | ±1 LU | -1 dBTP | — | | `custom` | — | ±2 LU | -1 dBTP | — | ## Contents - verdict thresholds — what passes, and where each number lives - probe.py — inspect - cut.py — cut / join segments - fit.py — target duration and/or aspect, rotate/flip - crop.py — crop to an exact pixel rectangle - insert.py — still image to a timed silent clip, with Ken Burns zoom/pan - broll.py — cut away to a B-roll clip for a window and come back - metadata.py — chapter markers and title/artist/comment tags, streams copied - background.py — generate a solid-colour or gradient clip - reverse.py — reverse playback - stabilize.py — motion stabilisation (vidstab) - sequence.py — numbered/globbed image sequence to video - silence.py — remove dead air / jump cuts - join.py — concatenate with transitions - render.py — the whole edit in one project.json - delivery templates — one command per destination (`--template`) - scenes.py — scene changes and highlight candidates - check.py — pre-delivery compliance - batch.py — same recipe over a folder, cached - caption.py --transcribe — optional local speech-to-text - MCP server — the toolkit for any MCP client - graphics.py — motion-graphics templates - brand.json — one file for fonts, colours, logo, margins - report.py — HTML delivery report - multicam.py — align several cameras and switch between them - verify.py — real-footage verification kit - look.py — see the result - caption.py — subtitles (static, animated, karaoke) - overlay.py — logo, image, title, video picture-in-picture, chroma key - sync.py — offset detection, alignment, drift correction - color.py — HDR to SDR, LUTs, colour tags, Dolby Vision - audio.py — clean-up, music, ducking, layout - loudness.py — EBU R128 normalisation - export.py — delivery presets - proxy.py — low-bitrate proxy for analysis/preview ## Scripts ### probe.py — inspect ``` probe.py INPUT... [--compact] [--field duration|video.fps|...] [--keyframes-near T[,T...] [--keyframe-window 5]] ``` `--keyframes-near` adds `keyframes`: for each time, the video keyframes within `--keyframe-window` seconds, and the nearest of those at or before it (`before`) and at or after it (`after`; either is `null` when none is within the window), in seconds from the file's start. These are where a stream copy can start, and where `cut.py --smart` stops re-encoding. 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,start_time}` (`start_time`: where the stream starts on the file's own clock, `null` when unknown). `--compact` gives one line per file. `--field` prints one line per file: a string as itself and any other value as JSON (`true`, `{"codec": ...}`), an empty line for a field that is not there; with `--json` every line is JSON (a string quoted, a missing field `null`). ### cut.py — cut / join segments ``` cut.py INPUT [--start T] [--end T | --duration T] [--segments A-B,C-D,... | --remove A-B,C-D,...] [--accurate | --smart] [--declick-ms 20 | --no-declick] [--edit-list | --no-edit-list] [--keep-hevc | --no-keep-hevc] [--vfr-guard sampled|average|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 to keyframes, instant, lossless); if the snapped result deviates more than `--tolerance` (0.5 s) from the request, that segment is re-encoded automatically (CRF 18: x264, or x265 Main10 with the source's own tags for an HDR or BT.2020 source; an SDR HEVC source (not BT.2020: that keeps its Main10 line and colour tags) stays HEVC as x265 8-bit BT.709, on VideoToolbox under `--hw`, by default since 3.0.0 (`--keep-hevc`; `--no-keep-hevc` uses x264 as 2.x did); `--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). A still picture is refused (`kind: input`): it has no length to cut, and `insert.py` makes a clip of it. Multiple segments are concatenated in the order given. `--remove A-B,...` (2.24) is the inverse: the ranges are dropped (overlaps merged, clamped to the file) and what is left is cut as `--segments` would cut it; a leftover shorter than one frame is not kept, nor (to a video output) one that holds less than one frame of picture, such as sound that runs past the last frame (a note names it), and a removal that leaves nothing is refused. It does not combine with `--segments`, `--start` (even `--start 0`), `--end`, `--duration` or `--snap beats` (a snapped edge could move into a dropped range). Since 2.17.2 every join the re-encode makes fades the sound for `--declick-ms` (20 ms) on each side, so butted cuts do not click; `--no-declick` butts them as before, and a stream-copy join (sound copied) is not faded. The result reports `declick_ms` (null when there was no re-encoded join). stderr reports whether the result was "lossless stream copy" or "re-encoded"; when the snap forced a re-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 keeps its MP4 edit list by default since 3.0.0 (`--edit-list`), so the picture starts at `--start`; `--no-edit-list` shifts its timestamps to zero instead (`-avoid_negative_ts make_zero`, 2.x's default), so the picture starts at the keyframe. With the edit list: `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` with an 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. An `--accurate` re-encode of a video does not pass `-avoid_negative_ts make_zero`, which shifted the picture by the AAC priming (about 21 ms, more when a B-frame decode time is negative) while the sound stayed at 0, and `fit.py --fps` then changed the frame count. A start that lands on a frame leaves that frame at time 0. A start between frames begins on the next source frame and may keep up to one frame of timestamp. A `.mp4`/`.mov` edit list hides the priming. A source whose audio starts after its picture keeps that offset. An audio-only `--accurate` cut still uses `make_zero`; that priming is what `precision: codec_frame` counts in the length, and it pads a sound that starts after `--start` with silence. A stream copy to an audio output cannot: it starts at the sound's first packet, and an `audio_lead_dropped` warning (`{seconds, segments}`) says how much silence it left out (from one frame of the picture on). Since 3.0.0 `keyframe_snapped` equals `start_snapped` (2.x: 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`. `--smart` is the keyframe-aware cut for H.264. A cut point between keyframes is re-encoded only from that point to the next keyframe (and, at the end, from the last keyframe to the end point); the whole GOPs between are stream-copied. The re-encoded parts are encoded with libx264 matched to the source stream: profile, level, pixel format, reorder depth (B-frames), frame size, SAR and colour tags. Every part is written as MPEG-TS, so each keyframe carries its own SPS/PPS and the decoder switches parameter sets at every join. The parts are joined with the concat demuxer, each with its exact length stated, and the output keeps the source's time base. The sound is cut from the source on the same frame grid and encoded once (AAC). Before it is moved into place, the result is checked: - the frame count, and one frame per frame duration (no gap, no repeat); - every copied packet against the source's (MD5 with the parameter-set and delimiter NAL units removed); - framemd5 of every re-encoded part against the same frames decoded from the output, and of the first 300 frames of each copied part against the source's; - the output's stream parameters and time base against the source's. These are reported in `smart.checks` and as `smart_*` verification steps, and `mode` is `smart`. When the source cannot be matched, the result is `mode: accurate`, `reencode_reason` holds `smart_fallback` and `smart: {applied: false, reason, reason_code}`. This happens for: - a source that is not H.264 8-bit 4:2:0 in Baseline/Main/High; - an interlaced, variable-rate or HDR source; - an open GOP at a copy boundary; - a picture that starts after its sound at a segment's start, or more than 32 segments with sound; - an ffmpeg write that fails (x264 cannot make the matched High profile at `--quality 0`); - an output other than `.mp4`/`.mov`/`.m4v`/`.mkv`; - any check failing. `--smart` with `--accurate` is refused. `probe.py --keyframes-near T` lists the keyframes around a time. `reencode_reason` lists every cause of a re-encode (`requested`, `codec`, `vfr`, `vfr_inconclusive`, `pcm_container`, `copy_failed`, `stream_lost`, `tolerance`, `concat_fallback`, `smart`, `smart_fallback`); under `--dry-run`, which does not write or measure the output cut (a `--segments` dry run reads the source's packets), `possible_reencode_reason` lists the ones a real run may still add to a plan of `mode: copy` or `smart` (`tolerance`: where a copy lands is measured only from the written file), and a `notes` line says so; `--segments` adds `segment_precision`; `precision` and `least_exact_precision` are the least exact one (since 3.0.0; 2.x's `precision` was the whole run's, `packet` only when nothing re-encoded). 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`).** `sampled` (default since 3.0.0): `cut.py` samples the packet timestamps before every copy (up to five 6 s windows; no decoding) into `vfr_check` (`measured`: `sampled_cfr`, `vfr` or `inconclusive`, plus `guard`) and re-encodes only on `vfr` / `inconclusive` (reasons `vfr` / `vfr_inconclusive`), so a phone clip at 29.98 against a nominal 30 copies. `average` (2.x's default): a source whose nominal and average frame rates differ (`variable_frame_rate_suspected`) re-encodes as `--accurate` (reason `vfr`), and is then sampled into `vfr_check`; a `sampled_cfr` there adds a note naming `--vfr-guard sampled`. `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`. A multi-segment copy also checks the written total in `verification` (`cut_total_duration`). The total's tolerance is the smaller of `--tolerance` and the requested length, with a floor of one source frame for video. With `--tolerance -1`, the requested length still bounds the verification. A miss keeps the written copy with `verified: false` and a note that suggests `--accurate`. 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 at 120 BPM). The grid comes from the input's own audio, or from `--snap-source` — either a `scenes.py --beats --json` document (no second decode) or a separate music file. The snap happens *before* the keyframe/tolerance decision, so lossless-vs-accurate is judged on where the cut actually lands. "Measured" is exact: the only points a cut may move onto are the `supported_beats` — the grid points a measured onset actually marks — never the full regular grid, which by construction runs on through a passage with no music in it. A cut asked for inside that passage stays where it was asked for, and `snap.grid` is `"supported"` with `snap.grid_points` saying how many there were. `--min-confidence` must be greater than 0: at 0 every grid is "reliable", including one measured from noise. The number of in/out points never changes: a point with no beat inside the tolerance is returned unchanged, and no point is ever invented. Three `kind: input` refusals, nothing written: - confidence below `--min-confidence` → *"no reliable beat grid in this audio (confidence 0.21, needs 0.5): cutting to invented beats would move your in/out points to times nothing in the audio supports. Re-run with `--snap none`, or pass `--snap-source` from a music bed."* - no audio stream → names `--snap none`. - no in/out point at all (a whole-file copy) → there is nothing to snap, and this tool never proposes cuts of its own. Result: `snap.mode`, `snap.tolerance`, `snap.confidence`, `snap.tempo_bpm`, `snap.moved` (one row per point, with `from`/`to`/`delta`/`snapped`), `snap.snapped`, `snap.unchanged`, `snap.grid`, `snap.grid_points`, and `snap.source` (`"measured"` or the path). In a `render.py` result, `snap.clips` carries one entry per snapped clip with `clip` naming its index, and the first entry's keys are repeated at the top level for a single-clip project. A clip served from `--cache` was snapped when it was first rendered, and says so (`source: "cache"`) rather than reporting `snap: null`. A `--snap-source` document that does not carry `beat_grid.supported_beats` (one written before 1.17) is refused rather than treated as if every grid point were supported, as is one whose `tempo_bpm` is null while it lists beats. `render.py` forwards a project's `"snap": {"to": "beats", ...}` (project-wide or per clip) to this flag and reports what came back. ### fit.py — target duration and/or aspect, rotate/flip ``` fit.py INPUT [--duration T --method speed|trim [--from-center] [--max-speed 4]] [--aspect 16:9|9:16|1:1|4:5|W:H --fit pad|crop|blur [--width W] [--height H] [--pad-color black] [--pad-fill color|blur [--pad-blur 20]]] [--rotate 90|180|270] [--flip h|v] [--fps N] [-o OUT] ``` `speed` retimes video and audio together (pitch-preserving `atempo`). It reports `large_speed_change` for factors above 1.15 or below 1/1.15, and refuses factors beyond `--max-speed`. For slow motion add `--smooth blend` (frame blending, fast) or `--smooth interpolate` (motion-compensated `minterpolate`, fluid but roughly 10-20x slower than realtime; its frames are made at `--fps` when given, else at the source's rate). `trim` keeps the head (or the middle with `--from-center`). `--width`/`--height` set the output size: give one and the other follows the aspect (source aspect if `--aspect` isn't also given); give both for an exact frame. `--rotate` applies a new clockwise rotation (90/180/270 swap width/height for 90 and 270 — this is separate from the rotation *metadata* fit.py already reads to size a source correctly); `--flip h|v` mirrors the picture; both can combine, rotate first. `--fps` forces a constant frame rate; VFR sources are conformed automatically even without it. `--pad-fill blur` fills the letterbox/pillarbox bars with a blurred, scaled-to-cover copy of the frame (the look every phone editor gives landscape footage posted as a Short/Reel) instead of the solid `--pad-color`; `--pad-blur` is the blur radius. `export.py --fit pad` takes the same two flags. `--fit blur` (1.14) is the same fill named in one word and with the background dimmed (`eq brightness=-0.15`) so the picture in front reads as the subject: the whole frame is kept (nothing cropped), the borders are a blurred copy of it rather than black. A delivery template asks for it as `"frame": {"aspect": "9:16", "fit": "blur"}`, or `render.py --template tiktok clip.mp4 --fit blur`. The dimming is applied to SDR sources only: an `eq` on PQ/HLG code values is not the −15 % perceptual dim it is on SDR, so an HDR source keeps a blurred but undimmed background (and is never silently tone-mapped); `info` says so. After a reframe (`--aspect`, `--width`, `--height`) the result's `picture` says where the picture sits in the frame written: `{x, y, width, height}`, `frame_share` (its share of the frame's area), `scale` (its width over the source's) and, for `--fit crop`, the source pixels `cropped` on each side. It is measured by running the frame's own filters on a uniform frame (no decode of the source), so a 202x360 frame holding a 202x114 picture is told apart from a full-frame crop without a contact sheet; `subject_framing` stays unverified. After a crop with a discarded margin, `crop_check` samples the kept source time range and checks where luma motion falls. It uses edge detail when motion falls below its measurement threshold. A `crop_content_off_centre` warning may suggest `--crop-x` or `--crop-y`. An unavailable measurement reports `unmeasured`. `--duration` on a still picture is refused (it has no length: `insert.py` makes a clip of it). ### crop.py — crop to an exact pixel rectangle ``` crop.py INPUT --x X --y Y --width W --height H [-o OUT] ``` Crops to a literal `{x, y, width, height}` rectangle in source pixels — distinct from `fit.py --fit crop`, which crops to an *aspect ratio* and picks the rectangle for you. Use this when the rectangle is already known (a face-detection box, a saved crop, a hand-picked region). The rectangle must lie entirely inside the source frame (after accounting for display rotation); `--width`/`--height` must be even (4:2:0 chroma) and are refused, never rounded, if they aren't; an odd `--x`/`--y` is taken as given. The source's subtitle track is kept (converted to mov_text in MP4/MOV, SubRip in Matroska); `dropped_non_av_streams: true` says a subtitle or data stream is not in the output: the container refused it. A refused data stream (a timecode track) is retried away alone, so the subtitles beside it stay (`non_av_streams_dropped` fallback, `dropped: ["data"]`). ### cropdetect.py — measure black bars, report the crop rectangle ``` cropdetect.py INPUT [--seconds N] [--samples N] [--limit F] [--round N] [--motion-centre] ``` Measurement only -- writes no file. Samples `--samples` windows spread across the file (default 5, totalling `--seconds` 10s of footage) and reports the crop rectangle FFmpeg's `cropdetect` filter found most often, as `{x, y, width, height}` ready to hand to `crop.py`. `source_width` / `source_height` are that same displayed frame: a 90° or 270° rotation swaps the stored size, because the filter measures the picture after ffmpeg applies the tag. Distinct from `fit.py --fit crop`, which crops to a target aspect ratio it computes itself with no black-bar measurement involved. A rectangle that matches the full source frame means no bars were found: a picture that reaches every edge is reported as the frame itself, and `--round` (default 16) rounds a detected crop only (1080 is not a multiple of 16). Does not decide whether removing detected bars is wanted -- genuine letterboxed content (a scope-ratio film in a 16:9 frame) "detects" the same way as accidental bars; look at the frame before cropping it away. `windows` / `windows_failed` say how many windows were sampled and how many ffmpeg could not decode (those are skipped, with a `cropdetect_windows_failed` warning; all of them failing is a `kind: ffmpeg` failure). `--limit` is a fraction of the top pixel code, 0..1; `--limit 1` is written to FFmpeg as that top code (255 for an 8-bit source), since FFmpeg reads a bare `1` as code 1. `--motion-centre` (1.18) reports the motion centroid once per second, sampled across the same windows: `motion_centre: [{time, x, y, x_frac, y_frac, motion}]`, `x`/`y` in source pixels and `x_frac`/`y_frac` as a 0..1 fraction of `source_width`/`source_height`. A frame with no measured motion in a window reports `x`/`y`/`x_frac`/`y_frac: null` and `motion: 0`. Report only, like the crop rectangle above -- this hands the calling agent numbers to reframe a 9:16 crop with; it never picks the subject or the crop box itself. ### deinterlace.py — deinterlace interlaced footage ``` deinterlace.py INPUT [--mode frame|field] [--parity auto|tff|bff] [--only-interlaced] [-o OUT] ``` Wraps FFmpeg's `yadif` filter. `--mode frame` (default) keeps the source frame rate; `--mode field` emits one frame per field, doubling the output frame rate. `--parity` overrides field order when the container gets it wrong; `--only-interlaced` skips frames the source doesn't itself mark interlaced. Does not detect whether the source needs deinterlacing -- that's a `look.py` judgement call (visible combing on motion). ### denoise.py — reduce video noise/grain ``` denoise.py INPUT [--strength low|medium|high] [--luma-spatial F] [--chroma-spatial F] [--luma-temporal F] [--chroma-temporal F] [-o OUT] ``` Wraps FFmpeg's `hqdn3d` filter. `--strength` picks a tested preset scaling all four of hqdn3d's spatial/temporal luma/chroma parameters together; the four `--luma-*`/`--chroma-*` flags override any of them individually. Heavier denoising trades fine detail for a cleaner but softer image -- for audio noise reduction use `audio.py --denoise` instead, this tool only touches the picture. ### redact.py — blur, pixelate, or interpolate away an exact rectangle ``` redact.py INPUT --x X --y Y --width W --height H [--mode blur|pixelate|delogo] [--blur-strength N] [--block-size N] [-o OUT] ``` Same rectangle convention as `crop.py` -- the rectangle must already be known (a saved detection box, a hand-picked region); this tool does not locate faces, plates, logos or burned-in text itself. `--mode blur` (default) box-blurs the rectangle; `--mode pixelate` mosaics it into `--block-size`-px blocks, the more unmistakably-redacted look often wanted for compliance footage. `--mode delogo` runs ffmpeg's `delogo` filter, which fills the rectangle from the picture around it: a fixed logo or a burned-in line that does not move. That is a border blend, not inpainting, and a logo that travels or subtitles that change position are out of scope. The filter reads a 1 px ring outside the box, so the box cannot touch the frame edge, and it only interpolates 8-bit YUV (an HDR or 10-bit source is refused; `color.py --to-sdr` first). Blur and pixelate cover the rectangle exactly at an odd `--x`/`--y` too (on 4:2:0 the chroma sample on an odd edge is shared with the pixel outside). The rest of the frame, and the whole clip's timeline, are untouched -- to cover only part of the timeline, `cut.py` the clip into segments first. ### sphere.py — flat viewport extraction from 360/spherical video ``` sphere.py INPUT [--input-projection equirect|fisheye|dfisheye|c3x2|c6x1|barrel|cylindrical|hequirect] [--yaw D] [--pitch D] [--roll D] [--h-fov D] [--v-fov D] [--width W] [--height H] [--interp METHOD] [--stereo mono|sbs|tb] [--audio-stream N] [-o OUT] ``` Wraps FFmpeg's `v360` filter to bake out an ordinary flat clip pointed at a fixed direction — the same "look this way" operation a VR headset or a 360 player's viewport does. `--yaw`/`--pitch`/`--roll` aim the camera (each -180..180, default 0); `--h-fov`/`--v-fov` set how wide the view is (each 1..170; `--h-fov` defaults to 90, and without `--v-fov` the vertical view is the one that keeps the output's pixels square, 58.7 at 90 and 1920x1080; a pair that is not square-pixel is drawn as given and said in `notes`). `--input-projection` must match the source's own projection (default `equirect`, the most common capture/export format) — this tool cannot detect it from the pixels, so a wrong value produces a distorted or garbled output, not an error. There is no subject detection or tracking here: only the typed aim you give it. For a shot that follows a moving subject, call this once per keyframe viewpoint from outside this tool. `--width`/`--height` must be even (4:2:0 chroma); default 1920x1080. ### straighten.py — rotate by an arbitrary angle (horizon correction) ``` straighten.py INPUT --degrees D [--fit crop|pad] [--fill-color C] [-o OUT] ``` Distinct from `fit.py --rotate`, which only turns the picture in exact 90-degree steps -- this wraps FFmpeg's `rotate` filter for a small corrective tilt (`--degrees`, -45..45). Rotating by a non-90-degree angle leaves triangular gaps at the corners: `--fit crop` (default) scales up just enough to fill the frame with no visible gap, losing a thin border of the original picture; `--fit pad` keeps the full original picture and fills the gaps with `--fill-color`. Does not measure the tilt itself -- give the degrees once you can see how far off it is (a `look.py` judgement call). ### insert.py — still image to a timed silent clip ``` insert.py IMAGE --duration T [--width W] [--height H] [--fps N] [--zoom in|out [--zoom-amount 1.3]] [--pan left|right|up|down] [-o OUT] ``` Produces a silent, exact-duration clip from one image. `--width`/`--height` resolve like `fit.py`'s (one given -> the other follows the image's aspect; both given -> exact frame, scaled to fill and centre-cropped, never distorted). `--zoom in|out` is a Ken Burns effect: a slow linear zoom across the whole clip, ending (zoom in) or starting (zoom out) at `--zoom-amount` (default 1.3). `--pan` drifts the visible window across the image while zoomed — it needs `--zoom` (panning uses the extra image area a zoom exposes). ### background.py — generate a solid-colour or gradient clip ``` background.py -o OUT --duration T --width W --height H [--color C | --gradient C1:C2 [--angle DEG]] background.py -o OUT.mov --duration T --width W --height H --transparent [--alpha-codec prores4444|qtrle|png|vp9] [--alpha-mode straight|premultiplied] ``` No input file: ffmpeg's own `color`/`gradients` source filters generate the clip directly. For a title-card background, a placeholder layer, or a base for `overlay.py` to composite onto. `--width`/`--height` must be even. `--angle DEG` (any value, 0 = left to right, 90 = top to bottom) runs the gradient from the corner the direction starts from (C1) to the opposite one (C2). `--transparent` writes a canvas with alpha 0 in every pixel in an alpha line: ProRes 4444 with 16-bit alpha (default; `.mov`/`.mkv`), `qtrle` (`.mov`), `png` (`.mov`/`.mkv`) or `vp9` (`.webm`/`.mkv`). It is the base layer `graphics.py --keep-alpha` and `overlay.py --keep-alpha` draw one element on, for a per-element layer with transparency. Every written frame's alpha is read back (`alpha` step, expected 0); `--color`/`--gradient` do not apply. ### reverse.py — reverse playback ``` reverse.py INPUT [--no-audio] [-o OUT] ``` Reverses video (and audio, unless `--no-audio`) with ffmpeg's `reverse`/ `areverse` filters, which buffer the whole clip in memory — keep this to clips it makes sense to reverse (seconds to a couple of minutes), not something this tool limits for you. A `memory_heavy` warning says when the decoded frames come to more than about 2 GiB (size, chroma, depth and frame count, not the length alone). ### stabilize.py — motion stabilisation ``` stabilize.py INPUT [--shakiness 1-10] [--smoothing N] [--zoom 0-100] [-o OUT] ``` Two-pass `vidstabdetect`/`vidstabtransform`: pass 1 analyses camera motion to a temporary transforms file (deleted after the run), pass 2 smooths and re-renders. `--shakiness` (default 5) trades analysis time for how much motion it looks for; `--smoothing` (default 15) is how many neighbouring frames the camera path is averaged over; `--zoom` crops in slightly to hide the black edges stabilizing can introduce, and is the only zoom applied (0, the default, keeps the original framing and lets the edges show: vidstab's own "optimal zoom" is off). Needs an ffmpeg built with `--enable-libvidstab`; `doctor` reports this tool `usable: no` when that's missing (a plain Homebrew ffmpeg build, for example) rather than failing at run time. The frames keep their times, so the source's subtitle track is kept as `crop.py` keeps it (`dropped_non_av_streams` says when it could not be). vid.stab aborts on an RGB picture, so an RGB source (a PNG, a qtrle or PNG-in-MOV clip) is stabilized as a YUV 4:4:4 copy (converted to BT.709 as every SDR RGB re-encode is, or, for an HDR or BT.2020 RGB source, with the matrix its 10-bit line tags; FFmpeg's own conversion for an SDR source on a `--codec prores` line), with a note; the output's pixel format is the encoder line's (`probe.video.pix_fmt`). ### sequence.py — numbered/globbed image sequence to video ``` sequence.py --dir DIR --pattern "frame_%04d.png"|"*.png" --fps N [--start-number N] [--width W] [--height H] [-o OUT] ``` Turns a numbered or glob-matched set of still images into a video. Glob matches are ordered naturally (`img2` before `img10`). The match is checked on disk before ffmpeg runs (an empty match or a missing first frame is refused here, not discovered from an opaque ffmpeg error), and every frame is decoded once (ffprobe) before the encode. When that check completes, a frame that is not an image it can decode (a text file named `.png`, a truncated PNG) is refused, `kind: input`, `reason: still_unreadable`, with the frames named. When ffprobe fails on the frame list or reads back no frame, the frames are not checked: a note says so and the encode runs. ### waveform.py — audio waveform/spectrum visualization video ``` waveform.py INPUT [--style waveform|spectrum] [--width W] [--height H] [--fps N] [--color C] [--background C] [--waveform-mode M] [--split-channels] [--image PATH] [--image-fit cover|contain|blur] [--position bottom|centre|top|strip] [--vis-height FRAC] [--opacity 0..1] [--platform NAME] [--srt FILE | --text FILE] [--title TEXT] [--brand brand.json] [--on-silent warn|fail] [--silence-threshold -50] [-o OUT] ``` Renders the input's audio as a video: `--style waveform` (default, FFmpeg's `showwaves`) draws amplitude over time; `--style spectrum` (`showspectrum`) draws a frequency-over-time heatmap instead, reading more out of dense mixes at the cost of being less immediately readable. The output always carries the audio it visualizes. The default output of an audio input is `_waveform.mp4` (an audio extension cannot hold the picture), and `-o` with an audio extension is refused. For an audio-only input (no video stream needed) or any file with an audio track worth visualizing. **Audiogram (1.16).** `--image PATH` puts a local still behind the visualisation, which is what turns a podcast episode into something postable. `--image-fit cover` (default) scales to cover and centre-crops; `contain` pads with `--background`; `blur` uses fit.py's blurred-pad plate. `--position` places the band (`strip`, the default, is a band of `--vis-height` -- a fraction of the frame, default 0.35 -- along the bottom, the podcast convention); `--opacity` fades the visualisation over the plate. `--platform` takes the frame size and fps from the delivery table and refuses a destination with no frame (`podcast`) -- the still is fed at that rate, so the plate cannot quietly decide the output's frame rate, and the run verifies the rate it announced along with the frame size and the duration. `--image` must be a file ffmpeg can actually decode: one that is not is refused (`kind: input`) before any encode starts. `--title` draws one label through graphics.py's sticker template and `--srt`/`--text` burns captions by running caption.py afterwards -- both as second processes, so neither of those code paths is re-implemented here. `--image` must be a readable local file: a URL is refused (`kind: input`), nothing is fetched, and the skill never invents cover art -- give an image or a colour. The title and caption stages receive `--overwrite`, `--timeout`, `--fast` and `--dry-run`, and a failed stage reports that tool's own error kind; a missing `--srt`/`--text` file is refused (`kind: input`) before anything is encoded. Without any of these flags the command line is byte-identical to 1.15's. Every run's result carries an `audiogram` object (style, background, image, position, vis_height, platform, captions, title, stages, verified). A real run peak-measures the input audio: at or below `--silence-threshold` (default -50 dBFS) the render is a flat line, so `--on-silent warn` (default) renders it with `silent: true` and a note and `fail` refuses (`kind: input`) before encoding; `silent` is `null` under `--dry-run`. An `--image` ffprobe reports as 0x0 is refused as undecodable. `render.py --template audiogram` is the one-call form; it is deliberately not part of `--template all`. ### freeze.py — hold a frame for N seconds ``` freeze.py INPUT --hold T [--at T] [--mode insert|extend] [-o OUT] ``` `--at` (default: the last frame) is the timestamp to freeze; `--hold` is how long the freeze lasts. `--mode insert` (default) inserts the hold at `--at`, pushing everything after it later by `--hold` seconds. `--mode extend` only works with `--at` at (or past) the clip's end and just makes the last frame last `--hold` seconds longer, with nothing pushed; `--mode insert` at the clip's end (no `--at`) does the same. Audio is silent during the held frame in `--mode insert` (there is no source audio for a frozen moment that didn't exist before). A hold inside the clip or at its start drops a subtitle/data track rather than copy it with timestamps that no longer match the pushed picture (`dropped_non_av_streams: true` in the result), as `fit.py --method speed` does; a hold of the last frame (`--mode extend`, or no `--at`) pushes nothing and keeps it. ### pad.py — add black/silent padding at the start/end ``` pad.py INPUT [--start T] [--end T] [--color C] [-o OUT] ``` Distinct from `fit.py --fit pad`, which pads the *frame* (letterbox/ pillarbox bars around each existing frame) -- this pads the *timeline*: extra seconds of solid colour and silence before and/or after the clip's existing content (seconds or `mm:ss`). At least one of `--start`/`--end` must be > 0. ### speedramp.py — step through different speeds across a clip ``` speedramp.py INPUT --segment START-END:FACTOR [--segment ...] [-o OUT] ``` Distinct from `fit.py --duration --method speed`, which applies one constant factor to the whole clip -- this takes a list of `--segment` pieces (repeatable) covering the clip start to end with no gaps or overlaps, each played at its own constant speed (pitch-preserving audio, matching `fit.py`), then concatenates them: "speed up, then slow way down for the punch, then speed back up," built from a few constant segments rather than a continuous curve. `START`/`END` take seconds or `mm:ss`; `FACTOR` is 0.05..20 (2.0 = twice as fast, 0.5 = half speed). Picking exactly where a ramp should ease in or out is a judgement call for the calling agent, made concrete here as the segment boundaries it supplies. A subtitle/data track in the source is not carried into the retimed/concatenated output; the result says so with `dropped_non_av_streams: true`. ### loop.py — repeat a clip ``` loop.py INPUT --times N | --duration T [--crossfade S | --boomerang] [-o OUT] ``` `--times` repeats the whole clip that many times back to back (2 = original + 1 repeat). `--duration` instead loops (and trims the last repeat) to hit an exact target length. For a background loop, an ambient bed, or filling a fixed slot length with a short clip. Without `--crossfade` the loop point is not smoothed: a clip that doesn't already loop cleanly shows a visible cut/pop at each repeat. `--crossfade S` makes the clip loop first: its last S seconds (whole frames) fade into its first S, picture and sound, so each seam continues the motion. One repeat is then the clip minus S (a 4 s clip with `--crossfade 1` repeats every 3 s), S may be at most half the clip, and `--times 1` writes one seamless loop file. The repeat is written losslessly to a temporary file first, so the output still has a single lossy encode. Every run except `--boomerang` measures the first seam of the written file (`seam`: the picture step across it against the typical step between neighbouring frames, and the sound level step in dB) and checks the length against the request (`expected_duration`, within 1.5 frames). `--boomerang` plays the clip forward, then backward (frames 0..N-1, then N-2..1, repeated), so any clip loops without a jump and neither turnaround frame is shown twice. `--times` then counts round trips (1 is allowed), and `--duration` trims the last one. A boomerang is silent (reversed sound plays backwards; a source's audio is dropped with a `notes` line), so add a bed with `audio.py`. It holds the decoded clip in memory like `reverse.py` and warns above ~2 GiB; a clip needs 3 frames at least, and one cycle at most 32767 (ffmpeg's `loop` filter). ### broll.py — cut away to a B-roll clip and come back ``` broll.py A.mp4 --insert B.mp4 --at T [--duration D | --end T2] [--from T3] [--insert ... --at ...] [--audio a|b|mix] [--pad-color black] [-o OUT] ``` A plays as it is; during each window B's picture is shown instead (scaled and padded to A's displayed frame, A's fps; a 90° or 270° rotation swaps the stored size), and A resumes at its own time when the window ends -- a cutaway, not a splice, so the output is exactly as long as A. One `--insert`/`--at` pair per cutaway (`--duration`, `--end`, `--from` are per cutaway too, or given once for all; defaults 4 s and 0); windows may not overlap or run past A's end, and B must have enough material from `--from`. A still picture as B is shown for the whole window. `--audio a` (default) keeps A's audio untouched and stream-copied; `b` replaces it inside each window with B's; `mix` plays both. The output's length is verified against A's. A subtitle/data track in the source is not carried into the retimed/concatenated output; the result says so with `dropped_non_av_streams: true`. ### metadata.py — chapter markers and container tags, streams copied ``` metadata.py INPUT [--chapters chapters.txt | --clear-chapters | --auto-chapters] [--min-chapter S] [--max-chapters N] [--from silence|scenes|both] [--silence-threshold dB] [--silence-min S] [--scene-threshold N] [--chapters-out FILE] [--description-out FILE] [--title T] [--artist A] [--album A] [--comment C] [--date D] [--genre G] [-o OUT] ``` `chapters.txt` holds one chapter per line, `TIME TITLE` (cut.py's time syntax: seconds, mm:ss, hh:mm:ss.ms; a `-`, dash, `|` or `:` between the two, as in `0:00 - Intro`, is not part of the title); each chapter ends where the next starts and the last runs to the end of the file. Starts must ascend and lie inside the file. Every stream is `-c copy` (bit for bit; `probe` reports the result under `chapters` and `tags`), so this is instant and lossless. Chapter markers need a container that can hold them (.mp4/.m4v/.m4a/.mov, .mkv/.mka/.webm); `.wav`, `.gif`, `.mp3` and `.flac` outputs are refused for `--chapters` rather than silently dropping them. Tags alone are written to any container that has them. `--clear-chapters` removes existing markers; an empty tag value (`--comment ""`) clears that tag. Because nothing is converted, an output container that does not take one of the source's streams as it is refuses the run before ffmpeg starts (`kind: input`, a dry run too): a SubRip or ASS track into `.mp4`/`.mov`, a mov_text track into `.mkv`, a data stream (a timecode track) into Matroska or WebM, an attachment outside Matroska. Keep the source's container (the default output does), or change it first with `export.py --preset copy`, which converts a text track. An audio-only extension for a source with a picture is refused too (reason `output_extension_audio_only`). **Proposed chapters (1.16).** `--auto-chapters` measures the file's own structure instead of reading a file: silencedetect for the pauses (`--from silence`), scdet for the scene cuts (`--from scenes`), both by default. A chapter starts where speech resumes; a scene cut within 1 s of one is the same event and merges to `silence+scene` evidence, which `--max-chapters` never drops before a single-evidence marker. `--min-chapter` (default 60, a long-form default) is the shortest chapter, and nothing is proposed within it of the end of the file. **Two detectors mean two full decodes of the input** (`notes` says so); `--from silence` is the cheap path. Every title is `Chapter N` and the result says `"titles": "placeholder"`: the skill proposes where a chapter starts, it cannot know what is in one -- naming them is the caller's job, and asking this skill to do it is a refusal. `--chapters-out FILE` writes the proposal in this tool's own `--chapters` format, so the titles can be edited and fed straight back; `--description-out FILE` writes the YouTube block (`00:00 Chapter 1` per line, rounded down to the second). The output is still `-c copy`. An input with no video degrades to `--from silence` with a note; an explicit `--from scenes` on it is refused, as is `--from silence` on an input with no audio. The result gains `auto_chapters` (source, min_chapter, proposed, kept, titles, chapters with their evidence, description_block, files). ### grid.py — composite clips into a grid ``` grid.py CLIP1 CLIP2 [...] --cols N --rows N [--cell-width W] [--cell-height H] [--label auto|none] [--font NAME] [--audio-from I] [--pad] [-o OUT] ``` Letterboxes every clip into a common `--cell-width`x`--cell-height` cell (no stretching) and tiles them `--cols`x`--rows`, filled left-to-right, top-to-bottom -- the input count must equal cols*rows exactly. `--label auto` (default) burns each clip's filename (extension stripped) into its cell's bottom-right corner; `--label none` skips it. No audio unless `--audio-from` picks one input's track by index -- mixing every clip's audio together is rarely useful for a comparison grid, so this tool never does that silently. Runs only as long as the shortest clip by default; `--pad` instead holds each shorter clip's last frame (with silence) out to the longest. A still picture fills its cell for the grid's length; a grid of stills only is refused. ### silence.py — remove dead air / jump cuts ``` silence.py INPUT [--threshold -35] [--min-silence 0.6] [--margin 0.2] [--margin-lead S] [--margin-tail S] [--min-keep 0.2] [--list] [--sentence-min-silence S] [--sentence-margin-tail S] (with --words FILE or --transcribe) [--edl keep.txt] [--timemap map.json|map.csv] [--speech-aware] [-o OUT] silence.py INPUT --filler --words transcript.json [--filler-lang auto|en|ja|ko|zh|es|de|fr|pt|it|nl|pl|ru|tr] [--filler-words FILE] [--filler-extra W,W] [--filler-keep W,W] [--filler-pad 0.02] [--transcribe] [--engine auto|parakeet-mlx|parakeet.cpp|whisper.cpp|faster-whisper|openai-whisper] [--model MODEL] [--filler-list] [--max-cuts 400] ``` Runs `silencedetect`, keeps `--margin` seconds of air around speech (none at the start or the end of the sound, where there is no speech to keep it for), drops gaps shorter than `--min-silence`, and re-encodes the kept ranges the way `cut.py --segments --accurate` does: both streams cut on the same frame times, so the sound never drifts from the picture at the cuts, and a sound that starts late keeps its offset. `--list` prints silences, kept ranges and seconds removed without rendering; `--edl` saves the kept ranges in `cut.py --segments` format so the user can edit the list by hand (written once the cut is, as `--timemap` is). `--max-cuts N` (400) refuses to render more than N removal ranges; `--list` reports them whatever their number. Quiet rooms need `--threshold -40` to `-45`; noisy ones `-30`. Always tell the user how many seconds were removed. **Breaths and weak word endings.** `--margin` is the padding kept on each side of every cut (default 0.2 s since 2.22, 0.15 s before; 0.3 s for a speaker who trails off). It is kept around silences only: a filler word's cut is the word plus `--filler-pad` (since 3.1.6). `--margin-tail` is what is kept after speech ends and `--margin-lead` what is kept before it starts again; each defaults to `--margin`, and the result's `margins` gives the two values used. A last syllable that is mostly breath wants more tail than the next word wants lead (`--margin-lead 0.1 --margin-tail 0.4`). `--speech-aware` keeps the short breaths inside a sentence and cuts only at sentence-boundary pauses. A `--threshold` set too high (-25, say) counts a weak word ending as silence: the result then warns. **Pauses inside a sentence and after one.** With word timings (`--words FILE` or `--transcribe`), `--sentence-min-silence S` and `--sentence-margin-tail S` give a silence that follows a sentence end its own floor and its own tail; every other silence keeps `--min-silence` and `--margin-tail`. A sentence end is a transcript word whose text ends in `. ! ? 。 ! ? …` (also `।` and `؟`), read from the transcript and never from the sound; the word before a silence is the last one whose own midpoint lies before the silence's midpoint, which holds when the engine stretched a word's timing into the pause. `--words talk.json --min-silence 0.2 --sentence-min-silence 0.3 --margin 0.1 --sentence-margin-tail 0.3` tightens pauses inside a sentence from 0.2 s and after one from 0.3 s, leaving the sentence end more room. The result lists `silence_positions` (`sentence_end` or `inside`, one per entry of `silences`) and `sentence` (`min_silence`, `margin_tail`, `source`, `word_timings`, `sentence_end_words`, `silences`). With no such punctuation in the transcript no silence is a sentence end: every one uses `--min-silence` and `--margin-tail`, and the run warns `sentence_ends_not_found`. Not with `--speech-aware`, which takes a sentence boundary from the pause's length instead; without a transcript the flags are refused. With `--filler` they turn silence removal on as well (`--filler` alone removes only the words), reading the same transcript. **Cut levels (2.22).** Every run measures the RMS level 50 ms either side of each cut on the source (`cut_points`: `source_time`, `output_time`, `edge` out/in, `rms_dbfs` of the loudest channel, `null` for digital silence; the whole key is `null`, with a `cut_levels_unmeasured` warning, when the source could not be decoded for it) and lists in `cut_warnings` the cuts whose level is within 10 dB of `--threshold`, with a `cut_near_sound` warning. Room tone sits well below the threshold; a breath or a word's weak tail sits just under it. This is a pointer for listening, not a verdict: `verified` is unchanged, and filler-word cuts (which sit in sound by design) are measured but not flagged. **`--timemap FILE` (2.22)** writes the source-to-output time map: every kept range with its source and output times, and every removed range with the output time it was cut at. `.csv` gives `type,source_start,source_end,output_start,output_end` rows (a removed row's two output columns are its cut point); any other path must end in `.json`. Use it to re-time subtitles made on the source, or to find a removed sentence again. Its times advance by the exact lengths of the ranges the render cuts on (with a picture, each bound on its nearest frame time; with sound alone, as asked), rounded only when written, so nothing adds up over many cuts; they are computed, not measured on the written file. An existing map is refused without `--overwrite`, and a missing directory or a directory at the path as `kind: input`, before anything runs (a dry run predicts both); the map is written only after the cut is, so a failed or refused encode leaves none. A dry run writes nothing. **`--filler` (1.17)** removes filler words as well, through the same `keep_ranges()` graph with more, shorter ranges. It is **never** applied without measured word timings: pass `--words` (a whisper JSON carrying per-word `start`/`end`, or whisper.cpp's `--output-json-full` document) or `--transcribe` (the same local engine `caption.py` uses, never required). There is no heuristic fallback — finding an "um" by looking for short quiet blips would cut real speech, so the tool refuses instead. `--filler-list` reports what would go and writes nothing. Built-in lists (2.19): en, ja, ko, zh, es, de, fr, pt, it, nl, pl, ru, tr. They hold hesitation sounds only; words that are as often content (`like`, 저, 那个, 啊, ну) are `--filler-extra` material. Chinese and Japanese are cut only where the transcript shows a word boundary on each side (punctuation or a 0.1 s pause), because whisper splits them into tokens rather than words. `filler.matched_untimed` counts listed words the transcript gives no usable timing for (not removed, and a `filler_words_untimed` warning), and `matched_too_long` those longer than a filler (a held vowel, kept). Built-in lists, one per language: | lang | words | |---|---| | en | um, uh, erm, hmm, mm, mhm, er, ah | | ja | えー, えーと, えっと, あの, あのー, その, そのー, まあ, なんか | | ko | 어, 어어, 에, 음, 음음, 으음, 흠 | | zh | 呃, 呃呃, 嗯, 嗯嗯, 唔 | | es | eh, este, esto, mmm | | de | äh, ähm, hm | | fr | euh, hein | | pt | é, hum | | it | ehm | | nl | eh, ehm, uh, uhm, hm | | pl | yy, yyy, ee, eee, em, emm, hmm | | ru | э, ээ, эм, эмм, мм, хм | | tr | ıı, ııı, ee, eee, hmm | **Discourse markers are not disfluencies.** `like`, `tipo` and `cioè` are deliberately *not* in the default lists: they are grammatical words in most sentences, and removing them cuts meaning rather than noise — a judgement about content, which this skill does not make. They are reachable with `--filler-extra like`, which says so in its own `--help`. Japanese `なんか` is in the `ja` list because leaving it out makes the flag useless for Japanese, and it is orthographically identical to the pronoun use — so every run that removes one warns, and `--filler-keep なんか` takes it back out. Matching is case-folded, punctuation-stripped and whole-token only: `umbrella` survives. Three refusals, all `kind: input`, all before any encode: - `--filler` with neither `--words` nor `--transcribe` → names both flags. - `--transcribe` with no engine on PATH → the same message `caption.py` gives, with its install lines (Parakeet and whisper engines). Engines that were found but did not transcribe are named instead, with why (`reason: engine_failed`, or `english_only` for a Parakeet engine auto passed over for `--filler-lang` that is not English; see `caption.py --transcribe` below). - `--transcribe` where the engine runs but its build produces no word-level timings → names that engine, says some builds do not support word timestamps, and points at `--words`. (`--transcribe` drives whichever engine is installed with *its* word-timestamp option — whisper.cpp `--output-json-full`, faster-whisper `word_timestamps=True`, openai-whisper `--word_timestamps True` — because an SRT cannot answer this: a cue has a start and an end, a word does not. `--words` is the tested path and the one to prefer.) - a transcript with segments but no word-level timings → says that cutting on segment boundaries would remove whole sentences, and how to re-run whisper. Results: `filler.removed_count`, `filler.removed_seconds`, `filler.removed` (one entry per span), `filler.lang`, `filler.list`, `filler.word_timings` and `filler.warnings`; `--filler-lang auto` refuses (`kind: input`) a transcript in a language with no built-in list, so pass `--filler-words FILE` for it. With `--transcribe`, `filler.source` is `whisper:ENGINE` or `parakeet:ENGINE` and `filler.transcription` says which engine, model, language and routing made the words; a top-level `notes` line says when `--engine auto` ran the English-only Parakeet model on English assumed (no `--filler-lang`, and no Whisper engine that could take it). The existing `removed_seconds` keeps exactly the meaning it has always had — the seconds of **silence** this run removed, the figure the same run would report without `--filler` — and `removed_seconds_total` is the additive sibling covering everything that went. A filler word quiet enough to sit inside a detected silence is merged into it rather than counted twice, so the two figures can be equal. **`--speech-aware` (1.18)** keeps breaths shorter than `--min-silence` when they sit inside a sentence, and only cuts at sentence-boundary pauses (`--min-silence` or longer). It re-runs silence detection at a much shorter floor to measure the short gaps at all, then classifies each one: shorter than `--min-silence` is an in-sentence breath (kept, listed in `speech_aware.breaths`); `--min-silence` or longer is a sentence boundary (cut, same as the plain flag). It composes with `--filler` through the same `keep_ranges()`/`merge_spans()` pipeline the filler-inside-a-silence fix already uses, so `--speech-aware --filler` produces one removal list. `--edl` writes the resulting cut list exactly as it does today. ### join.py — concatenate with transitions ``` join.py CLIP1 CLIP2 [...] [--transition fade|dissolve|wipeleft|slideleft|fadeblack|fadewhite|circleopen|none] [--duration 0.5] [--width W --height H] [--fps N] [--fit pad|crop] [-o OUT] join.py CLIP1 CLIP2 [...] --copy --transition none [-o OUT] join.py --list parts.txt [--on-missing fail|skip] [--on-silent warn|fail|skip] [--allow-silent N[,N]] [--silence-threshold -50] [...] ``` A still picture among the clips is refused (`kind: input`), with any `--transition` and `--copy`: it has no length to place, and `insert.py` makes a clip of it. `--copy --transition none` (2.24) joins by stream copy (the concat demuxer, `-c copy`), no re-encode, for clips that already match: the first video and first audio stream of every clip must have the same codec, profile, size, pixel format, frame rate, time base, sample aspect, colour tags (matrix, range, transfer, primaries), sample rate and channels (cover art is not the video stream) (and the same codec configuration), no clip may hide frames before its start with an edit list, every clip must lay out its streams as the first one does (count and order, cover art included: the concat demuxer maps by position), and in each clip picture and sound must start, and end (start plus length), within 50 ms of each other (the demuxer starts the next clip where this one's container ends, so the shorter stream would leave that gap). Anything else is refused before ffmpeg runs (`kind: input`, `reason: join_copy_mismatch`, `details.clips: [{index?, path, differs}]` naming what differs). The join is written beside the output and measured before it is renamed into place: its video packet count must equal the clips' total and its video length their summed length. `mode` is `copy`. `--copy` does not take `--width`, `--height`, `--fps`, `--sample-rate`, `--channels` or a transition, and an audio-only join (which resamples every clip to one format) is refused with it. `--list FILE` (2.2) reads the clips from a file, one per line in order, paths relative to the file (blank lines and `#` comments ignored; ffmpeg's `file 'x.wav'` lines and the `ffconcat version` header accepted, any other concat directive -- `inpoint`, `outpoint`, `duration`, the argument-free `stream` -- refused, since join.py applies none, unless the line names a file that is there), for the segments a TTS or render step wrote. Every input -- listed or given as arguments -- is checked before anything runs: missing, empty (0 bytes) or unreadable as media. By default all of them are named in one refusal (`kind: input`, `problems: [{index, path, reason}]`, nothing encoded); `--on-missing skip` joins the usable ones and reports the rest under `skipped` (always present, `[]` when nothing was). A list with no entries is refused as such, and a skip that leaves fewer than two inputs is refused rather than "joining" one file. Under `--dry-run` an input that does not exist yet is an earlier step's output, with either `--on-missing`: it stays in the plan and is named under `pending: [{index, path}]` and in `notes` (never `skipped`). Its extension stands in for its streams (any audio extension the skill reads, `.aiff` and `.caf` included: no picture), so a pending `.mp4` next to measured audio is refused as the mix a real run would refuse; `expected_duration` is null while any input is pending, and `notes` names the planned frame, rate or xfade offsets that rest on a pending input's unmeasured placeholder. Every existing input with an audio stream is also measured (one volumedetect pass, skipped under `--dry-run`): a peak at or below `--silence-threshold` (default -50 dBFS) is silent, the trace of a TTS call that wrote a valid but empty file. `--on-silent warn` (default) joins it and names it under `silent: [{index, path, peak_db, at, end}]` (`at`/`end`: where it sits in the output, seconds) and in `notes`; `fail` refuses it in the same `kind: input` document (`silent (peak -91.0 dBFS)`); `skip` leaves it out under `skipped`. A pause that is meant to be silent: `--allow-silent 3,7` (1-based) joins those inputs whatever `--on-silent` says and lists them with `intended: true`, no warning. A clip without an audio stream is never silent. Two warnings never refuse or change the command: `short_segments: [{index, path, duration}]` names a clip shorter than 2 frames at the join's fps (audio-only: 0.05 s), and `duplicates: [{path, indices}]` a path listed more than once (a repeat can be intended); both are always present (`[]` when none) and noted. Normalises every clip to one frame size, fps, `yuv420p`, 48 kHz and one channel layout (the widest clip's -- a 5.1 clip keeps 5.1 -- or `--channels`; silent track generated for clips without audio), then chains `xfade` + `acrossfade` (or `concat` for `--transition none`). Every clip has one length for picture and sound -- the video stream's, or the audio's when it runs more than a frame longer -- and the shorter stream is padded (silence / last frame held), so every clip's sound stays with its picture and a plain cut leaves no hole in the video. Output length = sum of clip lengths − transition × (n−1); `verified` checks the output's video-stream length against it. Clips must be longer than 2 × the transition. Use `--transition none` for a plain cut. A subtitle/data track in the source is not carried into the retimed/concatenated output; the result says so with `dropped_non_av_streams: true`. ### render.py — the whole edit in one project.json ``` render.py --init project.json # starter file render.py project.json [--fast] [--dry-run] [--stop-after STAGE] [--work DIR --keep] render.py project.json --cache DIR [--from STAGE] # reuse identical stages from a previous run render.py plan.json [--audit-log FILE] # execute a plan written by --plan plan.json render.py project.json --export-timeline edit.fcpxml|edit.edl|edit.otio # the cut for an editor, nothing rendered render.py project.json --intermediate-preset medium # the stages' own encoder preset instead of superfast ``` A real render first runs its own dry run; when that is refused because a stage needs a filter or an encoder this build lacks (`filter_missing`, `encoder_missing`), the real run is refused with the dry run's document before the first stage encodes, not after the stages before it (`waveform.py` with a title or captions does the same). The optional `stage_pictures` object keeps the fit and export stages' frame geometry under their stage names. Each report measures its own stage's frame and counts cropped pixels from that stage's input. `picture` carries the last sizing stage's report when available. Cache hits replay recorded geometry. Dry runs omit both fields. A `captions` block with `text` (a cue file) delivers the SRT the captions stage generates as `.srt` beside the output (`caption_srt`), guarded with the output before the first stage; it is not delivered (a `caption_srt_not_delivered` skip) when the stage came from `--cache` or the export trimmed the delivery. A Ctrl-C while a stage that writes the delivery runs (the export) names a file it had already written there as kept, unverified; a file that was there before and that the stage left alone is not claimed, and the work directory's files are not called kept when the directory goes at exit. A stage's `--cache` key also covers the logo and font file its `--brand` file names. `--intermediate-preset` (2.15; default `superfast` since 2.16, `veryfast` in 2.15): when the project has an export stage that re-encodes (any preset but `copy`) and the run goes that far (no `--stop-after` before it), the stages before it that encode with x264 or x265 (clips, fit, join, silence, captions, graphics, overlays, audiogram; x265 on the HDR path) encode with this preset instead of `medium`. export.py re-encodes their output and its own preset sets the delivered quality, so the earlier `medium` passes cost time the file does not keep: a 30 s 1080p reels render took 41.7 s instead of 51.8 s on FFmpeg 8.0.1 (SSIM 0.997 between the two deliveries); `superfast` (2.16) took it to 30 s from veryfast's 33 s on 8.0.1, the same time on 6.1, at the same quality. `medium` restores the stages' default; `--fast` still overrides everything; a stage given its own `--preset` keeps it. The result names it as `intermediate_preset` (`null` when not applied). `--export-timeline FILE` (2.1) writes the project's cut as an editor timeline instead of rendering it: `.fcpxml` (FCPXML 1.10: Final Cut Pro, DaVinci Resolve), `.edl` (CMX 3600: Premiere, Resolve, Avid) or `.otio` (OpenTimelineIO JSON: Resolve natively, others through OTIO's adapters). Clips keep their in/out and speed (an M2 line, a `timeMap`, a `LinearTimeWarp`); `transition` becomes a cross dissolve centred on each cut, trimmed so the timeline is exactly as long as `join.py`'s crossfade would render it; `audio.music` is its own track; inline `chapters` are markers. Times take the render's own grammar (`"0:05"`, `hh:mm:ss:ff` at the source's fps; an `out` past a source's end ends at it, as the render cuts it, with a note; a chapter metadata.py would refuse is refused). Source positions count from each source's start timecode at its own frame rate (EDL source timecodes, drop-frame where the source's is; the FCPXML asset's `start`; OTIO's `available_range`), so a conform finds the frames (3.1.6). The sequence is the project's `frame` sized by fit.py's rule (`{aspect 16:9, width 1920}` is 1920x1080; an aspect alone takes the export preset's size when the preset has that aspect; an aspect fit.py refuses, such as `16/9`, is refused unless the project's own `fit.aspect` replaces it in the render), with the project's `fit` object's aspect, mode, sides and rate in place of the frame's where it gives them, as the render's fit stage takes them, for one clip or several (#526). A multi-clip project with an effective `fit: crop` crops each source into the delivery canvas at the join, so a clip of another aspect fills the frame without padding (#552). A clip of another aspect gets its spatial conform in FCPXML (`adjust-conform`: `fill` for `frame.fit: crop`, `fit` for pad); EDL and OTIO cannot state one. Everything else in the project -- captions, graphics, overlays, the silence cut, fit, a reframe the format cannot state (and `blur`'s background), audio processing, loudness, export -- is listed in the result's `timeline.not_exported` and on stderr, never dropped silently. Media paths are absolute file URLs to the sources, nothing is copied or encoded, and the existing-output rule applies (`--overwrite` to replace). The timeline follows the project's numbers exactly; a render of the same project can come out a few frames longer, because `join.py` offsets its crossfades by each part's container duration, audio included. A plan is a single tool's dry run as an artifact: `cut.py in.mp4 --start 2 --end 8 --plan cut.json` writes `{plan_version, tool, argv, inputs (path, size, sha256 of head+tail), unbound_inputs, commands, output, verify}` and runs nothing (`unbound_inputs`: inputs that did not exist yet, so carry no fingerprint). `render.py cut.json` re-fingerprints the inputs (refusing, `kind: input`, `error.reason: plan_inputs_changed`, if any changed since the plan: every input's `{path, status, expected, actual}` -- `actual` `"missing"` for a file that is gone -- plus `plan_sha256` and `checked_at` are in `error.details`, and one JSON line goes to `.audit.jsonl`, or to `--audit-log FILE`; a log that cannot be written is a `diagnostics.warnings` entry, never the failure, and a `--dry-run` writes none), runs the tool with the planned argv, then the verify steps (probe; `check` for a `--platform` or a platform export preset; add `"content": true` to a check step for the black/frozen/silence rows), and reports `plan`, `plan_sha256`, `tool`, `tool_result`, `check` and `unbound_inputs` (each also a `diagnostics.warnings` entry: nothing checked those files). Show the plan to the user, get the yes, execute: one round trip instead of re-deriving the command. Render's `verified` is every stage's: each stage's own verification steps (beyond its intermediate's probe) are in the result's `verification`, tagged with `stage`, and each stage's notes are in `notes`, prefixed with its tool -- an export that misses its platform loudness leaves the render `completed` with `verified: false` and the note naming the fix. `"check": {"platform": ...}`, `{"content": true}` or both run `check.py` after the last stage (content alone: the black/frozen/silence rows, youtube's spec assumed, as `check.py --content` without `--platform`); under `--dry-run` the check is a `check_dry_run` entry in `diagnostics.skipped`. `"export": {"preset": "reels", "normalize": true}` forwards `export.py --normalize` so the rendered file meets the platform's loudness without a separate pass. Since 1.9.0 it is on by default when the preset is a platform's (`youtube`, `youtube4k`, `youtube-hdr`, `youtube-av1`, `reels`, `tiktok`, `shorts`, `x`, `linkedin`, `facebook`: `export.PLATFORM_OF`) and the project has no `loudness` stage; `"normalize": false` opts out. `"audio": {"stems": {"dialogue": -2, "music": -18, "effects": -24}}` names one level per element of the mix: `dialogue` is the main track's gain, `music` the bed's level, `effects` the level of the third file `"audio": {"effects": "sfx.wav"}` adds (never ducked). Each maps to the flag of the same meaning (`--gain`, `--music-volume`, `--effects-volume`); an explicit flag next to a stem wins, and a stems level with no file to apply it to (`effects` without `"effects"`, `music` without `"music"`) is refused, `kind: input`. `"audio": {"voice": "light"|"medium"|"strong"}` picks the voice strength (`true` is `medium`). An `overlays[]` entry draws one of `"logo": true`, `"image"`, `"text"` or `"video"` (#326: a picture-in-picture or green-screen layer, `overlay.py --video`), with `position`, `scale`, `opacity`, `start`, `end`, `margin`, `platform` (and `fade`, `box`, `font*` for the still/text kinds) mapping to overlay.py's flags. `scale` is the layer width in px for a logo, image or video (`"scale": 480` is 480 px of the delivered frame, because the stage runs after `fit`). A text entry's size is `font_size`; `scale` on a text-only entry is refused (`kind: input`) rather than drawn at the default font size. `"chromakey": "0x00ff00"`, `"chromakey_similarity"` and `"chromakey_blend"` key a colour out of the video layer. A template's safe margins apply as they do to a logo. Also refused before the first stage: `video` together with `logo`/`image`/`text` in one entry (a logo, image and text together still draw the first of them, as before), a `chromakey*` key without `video`, `chromakey_similarity`/`_blend` without `chromakey`, and a layer file that does not exist (under `--dry-run` too: no earlier stage writes it). The layer's content is in the stage's `--cache` key, so replacing the file re-runs `overlays` and what follows it; paths are relative to the project file; `--export-timeline` lists the layer under `not_exported`. `"chapters"` is a chapters file path, or an inline list of `{"at": TIME, "title": STR}`; it runs `metadata.py` on the delivered file as the last stage before `check`, so the markers are in the file that ships (streams copied). The entries and the file path are validated before the first stage runs, and the stage plans its `metadata.py` command under `--dry-run`/`--plan` like every other stage, so the plan lists `chapters` and the run does the same work. An inline title is one line: a line feed, carriage return or NUL in it is refused (`kind: input`), since the chapters file holds one `TIME TITLE` line per chapter and FFmpeg ends a title at NUL. Under `--dry-run` the list is written to a temporary file, not into the work directory. **`--stop-after export`** stops once the delivery is written: the chapters and check stages do not run (and their sections are not read). **Without an export stage** the delivery is the last stage's file copied as it is (`.mp4`, or the audio container of an audio-only output), so an output named for another container (`.webm`, `.mkv`) is refused, `kind: input`, before the first stage when the copy is certainly an intermediate and at the copy otherwise (a single uncut clip that no stage touches is its source, copied as it is); `.mov`, `.m4v`, `.m4a` and `.3gp` are the MP4 family and are accepted. **The work directory.** Without `--work`, each run makes a new `_work__/` beside the output and removes it at exit (kept with `--keep`, or by a `--stop-after` preview whose output is in it). `--work DIR` is used as given and never emptied; a stage file an earlier render wrote there, still unchanged (size, mtime, inode: `DIR/.ffskill-render-stages.json` records them), is replaced without `--overwrite`, while any other existing file is refused as before. A `--dry-run` writes nothing there and removes a `--work` directory it had to create. **`--cache DIR` (1.17)** reuses the artifact of a stage that already ran with exactly the same arguments and the same inputs. Opt-in only: **there is no default cache directory** — one appearing on someone's disk unasked would contradict this tool's "a plan leaves nothing behind" posture. The key is a sha1 over the stage name, the tool, its arguments (every existing path replaced by its content hash), the input hashes, the **forwarded** flags (`--fast`, `--overwrite`, `--timeout`; render.py has no `--codec`), the GPU setting (`--hw`/`--no-hw`, `FFMPEG_SKILL_HW`), the output's extension, and **the ffmpeg build banner, the skill version and the contract version**. `--fast` matters as much as any of them: it rewrites every child's preset to `veryfast`, so without it in the key a `--cache --fast` draft would be served back to a later run that asked for the delivery. The banner rather than `major.minor` because two 7.1.x builds with different libx264 produce different bytes from the same command. Those last three are in the key deliberately: a different build simply *misses* rather than being asked to trust a file it did not write, and a stage whose implementation changed cannot serve back an artifact the old one produced. Each entry is `DIR/` plus a `DIR/.json` sidecar (stage, versions, creation time, size, seconds). A hit hardlinks the artifact into the work directory, or copies it where the filesystem will not link — never moves it, since the cache has to outlive the run's own cleanup. A miss is work to do, not an error, but never a silent one: `cache.miss_reasons` says why each stage missed (`not_cached`, `sidecar_missing`, `artifact_missing`, `sidecar_corrupt`, `artifact_truncated`, `no_output_path`, and `destination_not_owned` when the file already at a stage's path in `--work` is not one this render wrote: the stage runs and refuses it by its own overwrite rule), and a damaged entry (`sidecar_corrupt`, `artifact_truncated`) is also a `cache_entry_damaged` warning and a line in `DIR/.ffskill-audit.jsonl`. A sidecar keeps the stage's `verified`, `verification`, `notes` and `diagnostics`, and a hit replays them, so a cached stage counts toward the render's `verified` as a live one does. A store that fails is a `cache_store_failed` warning (the run is unaffected). The key is made again when the stage ends: a stage whose inputs (a `--brand` file's logo or font included) changed while it ran stores nothing, a `cache_inputs_changed` skip (#540); a change undone before the stage ends is not seen. A stage whose flags changed misses the cache, so editing the captions block (for example to `"fit_size": "off"`) re-runs captions and everything after it and serves the earlier stages from the cache. A file is keyed by its name, size, modification time (in nanoseconds; in whole seconds up to 3.8.4) and first and last MiB, the batch cache's key (`batch.file_key()`); a file whose mtime was set back to the old value keeps its key. The chapters file an inline `chapters` list is written to is new every run, so it is keyed by its content instead, and the chapters stage hits when the delivery under it is the cached one (an export served from the cache; a delivery copied without an export stage is a new file, and misses). `stages_done` is unchanged: a cached stage is still a stage that happened. Nothing is written under `--dry-run`, which instead reports `cache.would_hit`. Result: `cache.dir`, `cache.ffmpeg`, `cache.hits`, `cache.misses`, `cache.miss_reasons`, `cache.saved_seconds`, `cache.entries`. `--from STAGE` starts at that stage and takes every earlier one from the cache; without `--cache`, or when an earlier stage is not there, it refuses (`kind: input`) rather than quietly re-encoding what it promised to skip. An unwritable cache directory is `kind: output`. `"snap": {"to": "beats", "tolerance": 0.12, "min_confidence": 0.5, "source": "music.mp3"}` at the project root (or inside one clip) forwards `--snap beats` to the clip cut for every clip that has `in`/`out`; the measured grid comes back in the render result's `snap`. A project without `"snap"` builds the command line 1.16 built. Stages: clips (cut, optional speed) → join (transition) → silence → fit → captions → graphics → overlays → audio → loudness → export → chapters → check. Keys mirror the CLI flags of each script (see the docstring); a key `render.py` does not read -- at the top level or in any stage/clip object -- is refused (`kind: input`) naming the key and the nearest valid one, never silently ignored. Use it whenever an edit has more than two steps or the user is likely to ask for changes: edit the JSON, re-render, and the result is reproducible. `--dry-run --json` prints the complete command plan for review. ### Delivery templates — one command per destination (1.14) ``` render.py --template tiktok INPUT [--cues cues.txt | --srt subs.srt] [--logo logo.png] [--title "..."] [--brand brand.json] [--chapters chapters.txt] [--image cover.png] [--fit crop|pad|blur] [-o OUT] render.py --template all INPUT ... # or a comma list: one delivery per destination + _pack.md render.py --list-templates # the table below, from the running install render.py --template tiktok INPUT --write-project project.json # fill it, edit it, render it later ``` A template is a `render.py` project shipped in `templates/.json` with `$INPUT`, `$OUTPUT`, `$CUES`/`$SRT`, `$LOGO`, `$TITLE`, `$BRAND`, `$CHAPTERS` and `$IMAGE` placeholders. Filling it substitutes what the run was given and **drops any block whose placeholder has no value** — no `--logo` means no overlay stage at all, not an overlay of nothing. The filled project then renders through the normal stages, so `--dry-run --json`, `--stop-after` and the work directory behave as always. An unknown name is refused (`kind: input`) with the list. Output defaults to `_