Skip to content

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.

Add ffmpeg-skill: local FFmpeg video-editing Agent Skill (#1)

kajisho5ea9adb32df4b
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..56956fb
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,17 @@
+# demo / test output
+examples/out/
+tests/out/
+*.log
+
+# python
+__pycache__/
+*.pyc
+
+# node
+node_modules/
+package-lock.json
+
+# editors / OS
+.DS_Store
+.vscode/
+.idea/
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..6d76d5f
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kajisho5
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
index 185f3ed..21fa783 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,111 @@
-# ffmpeg-skill
\ No newline at end of file
+# ffmpeg-skill
+
+**Give your coding agent a video editor.** Local FFmpeg, Python standard library, nothing else.
+
+![before / after demo](assets/demo.gif)
+
+```bash
+npx ffmpeg-skill
+```
+
+`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any other agent that reads `SKILL.md`. It teaches the agent a fixed editing workflow (probe → edit losslessly where possible → verify) and ships eight small CLI scripts that do the actual work with `ffmpeg`/`ffprobe`. Think of it as the fully local FFmpeg counterpart to cloud video-agent tools such as browser-use/video-use.
+
+**No API keys. No cloud. No dependencies.** If `ffmpeg` and `python3` are on your PATH, it works — offline, on any footage you'd rather not upload.
+
+## Features
+
+- **Probe first, verify last** — the skill forces the agent to read real duration/fps/resolution before editing and to check the result after, so you get "final.mp4: 59.98 s, 1080×1920, 30 fps" instead of guesses.
+- **Lossless when possible** — cuts and joins use stream copy by default; re-encoding only happens when it must (frame-accurate cuts, filters, format changes).
+- **Cut & join** segments with `mm:ss` / `hh:mm:ss.ms` times.
+- **Captions** — burn SRT/ASS with font, size, colour, outline and position control; generate SRT from a plain timed-text file.
+- **Fit** to an exact duration (pitch-preserving speed change or trim) and to 16:9 / 9:16 / 1:1 / 4:5 by padding or cropping.
+- **Multicam / external-audio sync** — offset detection by cross-correlation implemented in pure Python (no numpy).
+- **Loudness** — two-pass EBU R128 normalisation to −14 LUFS (or any target) with true-peak ceiling.
+- **Overlays** — logos, watermarks and titles with position, time range, opacity and fades.
+- **Export presets** — YouTube, Instagram Reels/Shorts/TikTok, X, ProRes 422 HQ master, H.265, GIF — all tagged BT.709.
+- **Agent-friendly CLI** — every script has `--help`, prints the output path on stdout, exits non-zero with a reason on stderr, and names outputs `<input>_<operation>.<ext>` by default.
+
+## Install
+
+```bash
+# Claude Code (default) → ~/.claude/skills/ffmpeg-skill
+npx ffmpeg-skill
+
+# Cursor → ~/.cursor/skills/ffmpeg-skill
+npx ffmpeg-skill --cursor
+
+# Codex → ~/.codex/skills/ffmpeg-skill
+npx ffmpeg-skill --codex
+
+# everything, or a project-local copy, or a custom directory
+npx ffmpeg-skill --all
+npx ffmpeg-skill --project
+npx ffmpeg-skill --dir ./my-skills
+```
+
+Or without Node: clone this repo and copy `SKILL.md` and `scripts/` into your agent's skills directory.
+
+You also need FFmpeg:
+
+| OS | Command |
+|----|---------|
+| macOS | `brew install ffmpeg` |
+| Ubuntu / Debian | `sudo apt install ffmpeg` |
+| Windows | `winget install Gyan.FFmpeg` |
+
+## Usage
+
+Once installed, just talk to your agent. Five things you can say to Claude Code:
+
+1. **"Take `interview.mp4`, keep 0:45–3:10 and 5:00–6:30, and make it exactly 60 seconds for Reels."**
+ → `probe.py` → `cut.py --segments 0:45-3:10,5:00-6:30` → `fit.py --duration 60 --aspect 9:16 --fit crop` → `export.py --preset reels` → `probe.py` to confirm 60.0 s at 1080×1920.
+2. **"Burn these captions in, white text with a black outline at the top, in Japanese."**
+ → `caption.py --text cues.txt --font "Noto Sans CJK JP" --position top --outline 3`.
+3. **"The lav mic recording is out of sync with the camera — fix it and normalise to −14 LUFS."**
+ → `sync.py camera.mp4 lav.wav --replace-audio` → `loudness.py` → report the detected offset and final LUFS.
+4. **"Put our logo in the top-right corner for the whole video at 80% opacity, and a title card for the first 4 seconds."**
+ → `overlay.py --image logo.png --position top-right --scale 220 --opacity 0.8` → `overlay.py --text "…" --start 0 --end 4 --fade 0.4`.
+5. **"Give me a ProRes master and an H.265 copy of the final cut."**
+ → `export.py --preset prores` and `export.py --preset h265`.
+
+The scripts also work on their own:
+
+```bash
+python3 ~/.claude/skills/ffmpeg-skill/scripts/probe.py input.mp4 --compact
+python3 ~/.claude/skills/ffmpeg-skill/scripts/fit.py input.mp4 --duration 60 --aspect 9:16
+```
+
+More examples: [examples/README.md](examples/README.md). To see everything run end-to-end on generated footage: `bash examples/make_demo.sh`.
+
+## Scripts
+
+| Script | What it does |
+|--------|--------------|
+| `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, colour space, audio channels as JSON |
+| `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact |
+| `caption.py` | Burn SRT/ASS (font, size, colour, outline, position); build SRT from timed plain text |
+| `fit.py` | Fit to a duration (speed or trim) and/or aspect ratio (pad or crop), force constant fps |
+| `sync.py` | Detect offset between two recordings by audio cross-correlation; output aligned video/audio |
+| `loudness.py` | Two-pass EBU R128 `loudnorm` to −14 LUFS / −1 dBTP (or custom), video stream-copied |
+| `overlay.py` | Composite image/logo or drawtext title with position, time range, opacity, fade |
+| `export.py` | Presets: `youtube`, `youtube4k`, `reels`, `x`, `prores`, `h265`, `gif` |
+
+All scripts: Python 3.9+, standard library only, `--help`, non-zero exit + stderr message on failure.
+
+## Requirements
+
+- FFmpeg 5.0+ with `libx264`, `libx265`, `libass` and `prores_ks` (the default builds from Homebrew, apt and gyan.dev include all of them)
+- Python 3.9+
+- Node 16+ only for the `npx` installer
+
+## Development
+
+```bash
+bash examples/make_demo.sh # generates footage, runs every script, rebuilds assets/demo.gif
+python3 tests/test_all.py # end-to-end tests (needs ffmpeg)
+node bin/install.js --dir /tmp/skills # try the installer without touching ~/.claude
+```
+
+## License
+
+[MIT](LICENSE)
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..ea10807
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,165 @@
+---
+name: ffmpeg-skill
+description: Professional video editing with local FFmpeg — cut, caption, fit to duration/aspect, sync multicam audio, normalise loudness, overlay logos and export platform presets, all from Python stdlib scripts with no cloud or API keys.
+---
+
+# ffmpeg-skill
+
+You are editing video for the user with FFmpeg through the scripts in `scripts/`.
+Everything runs locally. Nothing is uploaded, no keys are needed, and the only
+requirements are `ffmpeg`/`ffprobe` on PATH and Python 3.9+.
+
+Run scripts with `python3 <skill-dir>/scripts/<name>.py ...`. Every script has
+`--help`, exits non-zero on failure with the reason on stderr, prints the output
+path on stdout, and defaults the output name to `<input>_<operation>.<ext>`.
+
+## Workflow (always follow this order)
+
+1. **Probe first.** Run `probe.py` on every input before touching it. Read the
+ duration, fps, resolution, codecs, audio channels and the
+ `variable_frame_rate_suspected` flag. Plan the edit from real numbers, never
+ from assumptions about the file.
+2. **Prefer lossless.** If the request can be satisfied without re-encoding
+ (plain cuts on keyframes, remuxing, audio-only changes), do not re-encode.
+ `cut.py` and `loudness.py` stream-copy video by default; only pass
+ `--accurate` to `cut.py` when the user needs frame-exact cuts.
+3. **Chain operations in a sensible order.** Cut → fit → caption/overlay →
+ sync/loudness → export. Do the destructive/aspect changes before burning
+ text so captions are sized for the final frame. Re-encode as few times as
+ possible: if several re-encoding steps are needed, keep intermediates at
+ CRF 18 (the default) and only use `export.py` for the last step.
+4. **Verify the output.** Run `probe.py` on each result and confirm duration,
+ resolution, fps and audio match what was requested. Report those numbers to
+ the user (e.g. "final.mp4: 59.98 s, 1080x1920, 30 fps, AAC stereo").
+5. **Keep the user's originals.** Never overwrite the source file. Write new
+ files next to the input or where the user asked.
+
+## Request → script
+
+| User says | Do |
+|-----------|----|
+| "what's in this file", "how long is it", "is it 4K" | `probe.py input.mp4` |
+| "cut from 1:20 to 2:05", "trim the first 10 seconds" | `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 it in 30s" | `fit.py input.mp4 --duration 60` (speed) or `--method trim` |
+| "make it vertical / for TikTok / 9:16", "square for Instagram" | `fit.py input.mp4 --aspect 9:16 --fit pad` (or `--fit crop`) |
+| "add subtitles from this SRT", "burn in captions" | `caption.py input.mp4 --srt subs.srt` |
+| "caption it with these lines" (plain text with times) | `caption.py input.mp4 --text cues.txt` |
+| "put our logo top-right", "add a watermark" | `overlay.py input.mp4 --image logo.png --position top-right --scale 200` |
+| "add a title for the first 4 seconds" | `overlay.py input.mp4 --text "Title" --position top --start 0 --end 4 --fade 0.4` |
+| "sync the lav mic to the camera", "line up the two cameras" | `sync.py camera.mp4 mic.wav --replace-audio` / `sync.py camA.mp4 camB.mp4 --trim-second` |
+| "fix the audio levels", "normalise to -14 LUFS" | `loudness.py input.mp4` (`-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast) |
+| "export for YouTube / Reels / X", "give me a ProRes master", "make it HEVC" | `export.py input.mp4 --preset youtube|reels|x|prores|h265` |
+| "make a GIF preview" | `export.py input.mp4 --preset gif` |
+
+## Scripts
+
+### probe.py — inspect
+```
+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}`,
+`audio{codec,channels,sample_rate}`. `--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]
+```
+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
+(x264 CRF 18). `--accurate` always re-encodes; `--tolerance -1` never does.
+Multiple segments are concatenated in the order given. stderr reports whether
+the result was "lossless stream copy" or "re-encoded".
+
+### fit.py — target duration and/or aspect
+```
+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 [--width W] [--pad-color black]]
+ [--fps N] [-o OUT]
+```
+`speed` retimes video and audio together (pitch-preserving `atempo`); it
+refuses factors beyond `--max-speed`. `trim` keeps the head (or the middle with
+`--from-center`). `--fps` forces constant frame rate — use it on VFR sources.
+
+### caption.py — subtitles
+```
+caption.py INPUT --srt FILE | --ass FILE | --text CUES.txt [--write-srt OUT.srt]
+ [--font NAME] [--fonts-dir DIR] [--size N] [--color RRGGBB] [--outline N] [--outline-color RRGGBB]
+ [--bold] [--box] [--position bottom|top|center|top-left|...] [--margin N] [-o OUT]
+caption.py --text CUES.txt --write-srt OUT.srt # generate the SRT only
+```
+Text cue format, one per line: `0:00-0:03 Hello`, `00:00:03.500 --> 00:00:06 Two | lines`.
+Lines without a time run for `--auto-seconds` (3 s) after the previous cue. `|` is a line break.
+
+### overlay.py — logo, image, title
+```
+overlay.py INPUT --image PNG [--scale W | --scale-percent P] | --text "..." [--font-file F.ttf] [--font-size N] [--box]
+ [--position top-right|bottom-left|center|X,Y] [--margin N] [--start T] [--end T] [--fade S] [--opacity 0-1] [-o OUT]
+```
+Alpha in PNGs is respected. Fades apply to the overlay only; the video keeps playing.
+
+### sync.py — offset detection and alignment
+```
+sync.py REFERENCE SECOND [--json] [--max-offset 30] [--analyze-seconds 120]
+ [--replace-audio | --trim-second] [-o OUT]
+```
+Cross-correlates loudness envelopes (pure Python FFT, ~5 ms resolution).
+Positive offset = the second recording started later. `--replace-audio` writes
+the reference video with the second file's audio aligned (video stream copied).
+`--trim-second` writes the second file shifted to the reference timeline.
+Check `confidence` (0–1); below ~0.3 the match is doubtful — try a longer
+`--analyze-seconds` or a window that contains a clear event (clap).
+
+### loudness.py — EBU R128 normalisation
+```
+loudness.py INPUT [-I -14] [--tp -1] [--lra 11] [--measure-only] [-o OUT]
+```
+Two-pass `loudnorm`: measure, then apply with measured values (linear mode when
+the true-peak ceiling allows). Video is stream-copied; audio becomes AAC in
+video containers or the codec matching the extension (.wav → PCM, .flac, .mp3).
+
+### export.py — delivery presets
+```
+export.py INPUT --preset youtube|youtube4k|reels|x|prores|h265|gif [--fit pad|crop] [--no-scale] [--allow-long] [--crf N] [-o OUT]
+export.py --list
+```
+Scales into the preset frame (pad by default), tags BT.709, sets `+faststart`,
+trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`.
+
+## Gotchas
+
+- **Variable frame rate (phone/screen recordings).** `probe.py` sets
+ `variable_frame_rate_suspected` when `r_frame_rate` and `avg_frame_rate`
+ disagree. VFR causes audio drift and bad concat joins. Fix it early with
+ `fit.py --fps 30` (or 60) before cutting with `--accurate`, captioning or
+ syncing; add `--accurate` to `cut.py` because copy-cuts on VFR are unreliable.
+- **Audio drift / sync.** Don't mix files with different frame rates or sample
+ rates in one `cut.py --segments` join without re-encoding (`--accurate`).
+ After `sync.py`, verify by running it again on the output: the offset should
+ be ~0. If dialogue drifts over a long recording, the clocks differ; align the
+ start with `sync.py`, then fix drift with `fit.py --duration` on the audio-only
+ track to match the reference length.
+- **Colour.** All H.264/H.265 outputs are tagged BT.709 (`-colorspace`,
+ `-color_primaries`, `-color_trc`) and `yuv420p`. If `probe.py` shows a
+ BT.2020/HDR source (`color_transfer` smpte2084 or arib-std-b67), tell the
+ user the output will be tagged as SDR BT.709 without tone mapping, and add
+ `-vf zscale=t=linear:npl=100,tonemap=hable,zscale=p=bt709:t=bt709:m=bt709`
+ manually with ffmpeg if they need a proper SDR conversion.
+- **CJK and other non-Latin text.** libass and drawtext need a font that has
+ the glyphs. Check with `fc-list | grep -i cjk`. Then either name it
+ (`caption.py --font "Noto Sans CJK JP"`) or point at the file
+ (`overlay.py --font-file /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc`,
+ `caption.py --fonts-dir ./fonts --font "Noto Sans CJK JP"`). Without a
+ matching font you get boxes, not an error. Install: `apt install fonts-noto-cjk`,
+ `brew install --cask font-noto-sans-cjk`.
+- **Keyframe cuts.** A 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.
+- **Rotation metadata.** Phone footage often has a `rotation` tag; `probe.py`
+ reports it and `fit.py` accounts for it when computing the output frame.
+- **Odd dimensions.** `yuv420p` needs even width/height; `fit.py` and
+ `export.py` round to even values automatically.
+- **Speed.** Re-encodes use x264 `medium`. For long files add `--preset veryfast`
+ to intermediates and keep the default for the final export.
diff --git a/assets/demo.gif b/assets/demo.gif
new file mode 100644
index 0000000..d0b6de3
Binary files /dev/null and b/assets/demo.gif differ
diff --git a/bin/install.js b/bin/install.js
new file mode 100755
index 0000000..f3b3e01
--- /dev/null
+++ b/bin/install.js
@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * ffmpeg-skill installer.
+ *
+ * Copies SKILL.md and scripts/ into the skills directory of one or more
+ * coding agents. Default target is Claude Code (~/.claude/skills/ffmpeg-skill).
+ *
+ * npx ffmpeg-skill # Claude Code
+ * npx ffmpeg-skill --cursor # Cursor (~/.cursor/skills/ffmpeg-skill)
+ * npx ffmpeg-skill --codex # Codex (~/.codex/skills/ffmpeg-skill)
+ * npx ffmpeg-skill --all # all of the above
+ * npx ffmpeg-skill --dir ./skills # custom parent directory
+ * npx ffmpeg-skill --project # ./.claude/skills/ffmpeg-skill in the current project
+ * npx ffmpeg-skill --uninstall # remove from the selected targets
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const SKILL_NAME = 'ffmpeg-skill';
+const ROOT = path.resolve(__dirname, '..');
+const PAYLOAD = ['SKILL.md', 'scripts'];
+
+const args = process.argv.slice(2);
+const has = (flag) => args.includes(flag);
+const optValue = (flag) => {
+ const i = args.indexOf(flag);
+ return i !== -1 && args[i + 1] ? args[i + 1] : null;
+};
+
+if (has('--help') || has('-h')) {
+ console.log(fs.readFileSync(__filename, 'utf8').split('*/')[0].replace(/^\/\*\*?\s?|^\s\*\s?/gm, ''));
+ process.exit(0);
+}
+
+const home = os.homedir();
+const targets = [];
+const want = { claude: has('--claude'), cursor: has('--cursor'), codex: has('--codex') };
+if (has('--all')) want.claude = want.cursor = want.codex = true;
+const customDir = optValue('--dir');
+const project = has('--project');
+
+if (!want.claude && !want.cursor && !want.codex && !customDir && !project) want.claude = true;
+
+if (want.claude) targets.push({ label: 'Claude Code', dir: path.join(home, '.claude', 'skills', SKILL_NAME) });
+if (want.cursor) targets.push({ label: 'Cursor', dir: path.join(home, '.cursor', 'skills', SKILL_NAME) });
+if (want.codex) targets.push({ label: 'Codex', dir: path.join(home, '.codex', 'skills', SKILL_NAME) });
+if (project) targets.push({ label: 'project (.claude/skills)', dir: path.join(process.cwd(), '.claude', 'skills', SKILL_NAME) });
+if (customDir) targets.push({ label: 'custom', dir: path.join(path.resolve(customDir), SKILL_NAME) });
+
+function copyRecursive(src, dst) {
+ const stat = fs.statSync(src);
+ if (stat.isDirectory()) {
+ fs.mkdirSync(dst, { recursive: true });
+ for (const entry of fs.readdirSync(src)) {
+ if (entry === '__pycache__') continue;
+ copyRecursive(path.join(src, entry), path.join(dst, entry));
+ }
+ } else {
+ fs.copyFileSync(src, dst);
+ if (src.endsWith('.py')) fs.chmodSync(dst, 0o755);
+ }
+}
+
+function checkFfmpeg() {
+ const r = spawnSync('ffmpeg', ['-version'], { encoding: 'utf8' });
+ if (r.error || r.status !== 0) {
+ console.warn('\n warning: ffmpeg was not found on PATH. The skill needs FFmpeg to run:');
+ console.warn(' macOS: brew install ffmpeg');
+ console.warn(' Ubuntu: sudo apt install ffmpeg');
+ console.warn(' Windows: winget install Gyan.FFmpeg\n');
+ return false;
+ }
+ console.log(` found ${r.stdout.split('\n')[0]}`);
+ return true;
+}
+
+let failed = false;
+for (const t of targets) {
+ try {
+ if (has('--uninstall')) {
+ fs.rmSync(t.dir, { recursive: true, force: true });
+ console.log(`removed ${t.label}: ${t.dir}`);
+ continue;
+ }
+ fs.rmSync(t.dir, { recursive: true, force: true });
+ fs.mkdirSync(t.dir, { recursive: true });
+ for (const item of PAYLOAD) copyRecursive(path.join(ROOT, item), path.join(t.dir, item));
+ console.log(`installed ${t.label}: ${t.dir}`);
+ } catch (err) {
+ failed = true;
+ console.error(`failed for ${t.label} (${t.dir}): ${err.message}`);
+ }
+}
+
+if (!has('--uninstall')) {
+ checkFfmpeg();
+ console.log('\nDone. Ask your agent things like "make this video 60 seconds and add captions".');
+}
+process.exit(failed ? 1 : 0);
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..b835488
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,115 @@
+# Examples
+
+Natural-language requests and the commands the agent runs for them. Paths
+assume the skill is installed at `~/.claude/skills/ffmpeg-skill`; shorten with
+`S=~/.claude/skills/ffmpeg-skill/scripts`.
+
+Run `bash examples/make_demo.sh` to generate sample footage from nothing and
+push it through every script (outputs land in `examples/out/`).
+
+---
+
+### "What am I working with?"
+```bash
+python3 $S/probe.py footage.mov --compact
+python3 $S/probe.py footage.mov # full JSON, check variable_frame_rate_suspected
+```
+
+### "Cut from 1:20 to 2:05"
+```bash
+python3 $S/cut.py footage.mov --start 1:20 --end 2:05 # lossless, keyframe-snapped
+python3 $S/cut.py footage.mov --start 1:20 --end 2:05 --accurate # frame-exact
+```
+
+### "Keep the intro and the ending, drop the middle"
+```bash
+python3 $S/cut.py talk.mp4 --segments 0-1:30,18:40-20:00 -o talk_short.mp4
+```
+
+### "Make it exactly 60 seconds"
+```bash
+python3 $S/fit.py talk_short.mp4 --duration 60 # speed up/down (pitch preserved)
+python3 $S/fit.py talk_short.mp4 --duration 60 --method trim # keep the first 60 s
+```
+
+### "Make a vertical version for TikTok / Reels"
+```bash
+python3 $S/fit.py final.mp4 --aspect 9:16 --fit pad --width 1080 --pad-color black
+python3 $S/fit.py final.mp4 --aspect 9:16 --fit crop --width 1080 # centre-crop instead
+```
+
+### "Square for Instagram feed, 15 seconds"
+```bash
+python3 $S/fit.py final.mp4 --aspect 1:1 --fit crop --duration 15 --method trim --from-center
+```
+
+### "Add these captions"
+`cues.txt`:
+```
+0:00-0:02.5 Welcome back
+0:02.5-0:06 Today: three tips | for cleaner audio
+Tip one: get the mic close
+```
+```bash
+python3 $S/caption.py final.mp4 --text cues.txt --size 26 --bold --position bottom
+python3 $S/caption.py final.mp4 --srt subtitles.srt --font "Inter" --color FFFFFF --outline 3
+python3 $S/caption.py final.mp4 --ass styled.ass
+python3 $S/caption.py --text cues.txt --write-srt cues.srt # SRT only, no video
+```
+
+### "Japanese subtitles"
+```bash
+fc-list | grep -i "cjk" # find an installed CJK font
+python3 $S/caption.py final.mp4 --srt jp.srt --font "Noto Sans CJK JP" --size 28
+python3 $S/overlay.py final.mp4 --text "第1話" --font-file /usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc --position top --box
+```
+
+### "Logo top-right, 80% opacity, fade in and out"
+```bash
+python3 $S/overlay.py final.mp4 --image logo.png --position top-right --scale 220 --opacity 0.8 --start 0.5 --end 58 --fade 0.5
+```
+
+### "Title card for the first 4 seconds"
+```bash
+python3 $S/overlay.py final.mp4 --text "Episode 12 — Clean Audio" --position top-left --font-size 48 --box --start 0 --end 4 --fade 0.4
+```
+
+### "Sync the lav mic to the camera"
+```bash
+python3 $S/sync.py camera.mp4 lav.wav --json # just tell me the offset
+python3 $S/sync.py camera.mp4 lav.wav --replace-audio -o camera_synced.mp4
+python3 $S/sync.py camera_synced.mp4 lav.wav --json # verify: offset should be ~0 (on the new file's audio)
+```
+
+### "Line up camera B with camera A"
+```bash
+python3 $S/sync.py camA.mp4 camB.mp4 --trim-second -o camB_aligned.mp4
+```
+
+### "Fix the levels"
+```bash
+python3 $S/loudness.py final.mp4 # -14 LUFS / -1 dBTP (YouTube, Spotify)
+python3 $S/loudness.py podcast.wav -I -16 --tp -1.5 # Apple Podcasts
+python3 $S/loudness.py final.mp4 --measure-only # report only
+```
+
+### "Export for YouTube and Reels, plus a ProRes master"
+```bash
+python3 $S/export.py final.mp4 --preset youtube
+python3 $S/export.py final.mp4 --preset reels --fit crop
+python3 $S/export.py final.mp4 --preset prores -o final_master.mov
+python3 $S/export.py final.mp4 --preset h265
+python3 $S/export.py final.mp4 --preset gif -o preview.gif
+```
+
+### Full pipeline in one go
+```bash
+python3 $S/probe.py raw.mp4 --compact
+python3 $S/cut.py raw.mp4 --segments 0:45-3:10,5:00-6:30 -o step1.mp4
+python3 $S/fit.py step1.mp4 --duration 60 --aspect 9:16 --fit crop --width 1080 -o step2.mp4
+python3 $S/caption.py step2.mp4 --text cues.txt -o step3.mp4
+python3 $S/overlay.py step3.mp4 --image logo.png --position top-right --scale 180 -o step4.mp4
+python3 $S/loudness.py step4.mp4 -o step5.mp4
+python3 $S/export.py step5.mp4 --preset reels -o final_reels.mp4
+python3 $S/probe.py final_reels.mp4 --compact # confirm 60 s, 1080x1920, 30 fps
+```
diff --git a/examples/make_demo.sh b/examples/make_demo.sh
new file mode 100755
index 0000000..76d96b7
--- /dev/null
+++ b/examples/make_demo.sh
@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# Generate demo footage from nothing (ffmpeg testsrc2 + synthesized audio),
+# run every script in scripts/ on it, and build assets/demo.gif (before/after).
+#
+# bash examples/make_demo.sh # writes examples/out/
+# OUT=/tmp/demo bash examples/make_demo.sh
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPTS="$ROOT/scripts"
+OUT="${OUT:-$ROOT/examples/out}"
+PY="${PYTHON:-python3}"
+mkdir -p "$OUT" "$ROOT/assets"
+
+command -v ffmpeg >/dev/null || { echo "ffmpeg not found on PATH" >&2; exit 127; }
+
+step() { printf '\n\033[1;34m==> %s\033[0m\n' "$*"; }
+
+# ------------------------------------------------------------------ material
+step "1/10 generate source footage (12 s, 1280x720, 30 fps, non-periodic tones)"
+TONES="0.6*sin(2*PI*440*t)*gt(sin(2*PI*0.37*t)\,0.3)+0.4*sin(2*PI*880*t)*gt(sin(2*PI*0.53*t+1)\,0.6)+0.3*sin(2*PI*220*t)*gt(sin(2*PI*0.21*t+2)\,0.7)"
+ffmpeg -y -hide_banner -loglevel error \
+ -f lavfi -i "testsrc2=size=1280x720:rate=30" \
+ -f lavfi -i "aevalsrc='$TONES':s=48000" \
+ -t 12 -c:v libx264 -preset veryfast -crf 20 -pix_fmt yuv420p -c:a aac -b:a 128k \
+ "$OUT/source.mp4"
+
+# external "lav mic" recording that started 2.5 s later than the camera
+ffmpeg -y -hide_banner -loglevel error -ss 2.5 -i "$OUT/source.mp4" -vn -c:a pcm_s16le "$OUT/lavmic.wav"
+
+# a logo with transparency
+ffmpeg -y -hide_banner -loglevel error -f lavfi -i "[email protected]:s=240x90,format=rgba" -frames:v 1 "$OUT/logo.png"
+
+# caption cues in the plain-text format caption.py understands
+cat > "$OUT/cues.txt" <<'CUES'
+0:00-0:02.5 Shot on nothing but FFmpeg
+0:02.5-0:05 Captions | burned in with libass
+0:05-0:08 Cut, fit, sync, normalise, export
+0:08-0:12 No API keys. No cloud. No dependencies.
+CUES
+
+# ------------------------------------------------------------------ pipeline
+step "2/10 probe.py"
+"$PY" "$SCRIPTS/probe.py" "$OUT/source.mp4" --compact
+
+step "3/10 cut.py (two segments, lossless copy + concat)"
+"$PY" "$SCRIPTS/cut.py" "$OUT/source.mp4" --segments 1-4,7-10 -o "$OUT/01_cut.mp4"
+
+step "4/10 fit.py (retime to 8 s, pad to 9:16 at 720 px wide)"
+"$PY" "$SCRIPTS/fit.py" "$OUT/source.mp4" --duration 8 --aspect 9:16 --fit pad --width 720 -o "$OUT/02_fit.mp4"
+
+step "5/10 caption.py (text cues -> SRT -> burn in)"
+"$PY" "$SCRIPTS/caption.py" "$OUT/source.mp4" --text "$OUT/cues.txt" --write-srt "$OUT/cues.srt" \
+ --size 26 --bold --position bottom --margin 40 -o "$OUT/03_captioned.mp4"
+
+step "6/10 overlay.py (logo top-right with fade, plus a title)"
+"$PY" "$SCRIPTS/overlay.py" "$OUT/03_captioned.mp4" --image "$OUT/logo.png" --position top-right \
+ --scale 200 --opacity 0.9 --start 0.5 --end 11.5 --fade 0.5 -o "$OUT/04_logo.mp4"
+"$PY" "$SCRIPTS/overlay.py" "$OUT/04_logo.mp4" --text "ffmpeg-skill demo" --position top-left \
+ --font-size 40 --box --start 0.5 --end 4 --fade 0.4 -o "$OUT/05_titled.mp4"
+
+step "7/10 sync.py (detect the 2.5 s lav-mic offset, replace camera audio)"
+"$PY" "$SCRIPTS/sync.py" "$OUT/source.mp4" "$OUT/lavmic.wav" --json | tee "$OUT/sync.json"
+"$PY" "$SCRIPTS/sync.py" "$OUT/05_titled.mp4" "$OUT/lavmic.wav" --replace-audio -o "$OUT/06_synced.mp4"
+
+step "8/10 loudness.py (-14 LUFS, -1 dBTP, two-pass)"
+"$PY" "$SCRIPTS/loudness.py" "$OUT/06_synced.mp4" -o "$OUT/07_loudnorm.mp4"
+
+step "9/10 export.py (YouTube, Reels, X, ProRes, H.265)"
+"$PY" "$SCRIPTS/export.py" "$OUT/07_loudnorm.mp4" --preset youtube -o "$OUT/08_youtube.mp4"
+"$PY" "$SCRIPTS/export.py" "$OUT/07_loudnorm.mp4" --preset reels --fit crop -o "$OUT/08_reels.mp4"
+"$PY" "$SCRIPTS/export.py" "$OUT/07_loudnorm.mp4" --preset x -o "$OUT/08_x.mp4"
+"$PY" "$SCRIPTS/export.py" "$OUT/07_loudnorm.mp4" --preset prores -o "$OUT/08_prores.mov"
+"$PY" "$SCRIPTS/export.py" "$OUT/07_loudnorm.mp4" --preset h265 -o "$OUT/08_h265.mp4"
+
+step "10/10 before/after GIF -> assets/demo.gif"
+ffmpeg -y -hide_banner -loglevel error -i "$OUT/source.mp4" -i "$OUT/07_loudnorm.mp4" -filter_complex \
+ "[0:v]scale=400:-2,drawtext=text='BEFORE':fontsize=22:fontcolor=white:borderw=2:x=(w-text_w)/2:y=h-34[a];\
+ [1:v]scale=400:-2,drawtext=text='AFTER':fontsize=22:fontcolor=white:borderw=2:x=(w-text_w)/2:y=h-34[b];\
+ [a][b]hstack=inputs=2,fps=10,split[s0][s1];[s0]palettegen=max_colors=128:stats_mode=diff[p];[s1][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle" \
+ -t 12 -loop 0 "$ROOT/assets/demo.gif"
+
+step "summary"
+"$PY" "$SCRIPTS/probe.py" "$OUT"/0*.mp4 "$OUT"/0*.mov --compact
+ls -la "$ROOT/assets/demo.gif"
+echo
+echo "all scripts ran successfully. outputs in $OUT"
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..2a71413
--- /dev/null
+++ b/package.json
@@ -0,0 +1,31 @@
+{
+ "name": "ffmpeg-skill",
+ "version": "0.1.0",
+ "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg. No API keys, no cloud, no dependencies.",
+ "keywords": ["ffmpeg", "video", "agent-skill", "claude-code", "cursor", "codex", "skill", "video-editing"],
+ "license": "MIT",
+ "author": "kajisho5",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/kajisho5/ffmpeg-skill.git"
+ },
+ "homepage": "https://github.com/kajisho5/ffmpeg-skill#readme",
+ "bugs": "https://github.com/kajisho5/ffmpeg-skill/issues",
+ "bin": {
+ "ffmpeg-skill": "bin/install.js"
+ },
+ "files": [
+ "bin/",
+ "scripts/",
+ "SKILL.md",
+ "README.md",
+ "LICENSE"
+ ],
+ "scripts": {
+ "test": "python3 tests/test_all.py",
+ "demo": "bash examples/make_demo.sh"
+ },
+ "engines": {
+ "node": ">=16"
+ }
+}
diff --git a/scripts/_common.py b/scripts/_common.py
new file mode 100755
index 0000000..d3b37f1
--- /dev/null
+++ b/scripts/_common.py
@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""Shared helpers for ffmpeg-skill scripts.
+
+Standard library only. Locates ffmpeg/ffprobe on PATH, runs them with clear
+error reporting, and provides a compact media probe used by every script.
+"""
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from fractions import Fraction
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+INSTALL_HINTS = {
+ "Darwin": " brew install ffmpeg",
+ "Linux": (
+ " Debian/Ubuntu: sudo apt install ffmpeg\n"
+ " Fedora: sudo dnf install ffmpeg\n"
+ " Arch: sudo pacman -S ffmpeg"
+ ),
+ "Windows": (
+ " winget install Gyan.FFmpeg\n"
+ " or: choco install ffmpeg\n"
+ " or download a build from https://ffmpeg.org/download.html and add it to PATH"
+ ),
+}
+
+
+def die(msg: str, code: int = 1) -> "None":
+ sys.stderr.write(f"error: {msg}\n")
+ sys.exit(code)
+
+
+def info(msg: str) -> None:
+ sys.stderr.write(f"{msg}\n")
+
+
+def require_tool(name: str) -> str:
+ """Return the absolute path of ffmpeg/ffprobe or exit with install steps."""
+ path = shutil.which(name)
+ if path:
+ return path
+ system = platform.system()
+ hint = INSTALL_HINTS.get(system, " See https://ffmpeg.org/download.html")
+ die(
+ f"'{name}' was not found on PATH.\n"
+ f"Install FFmpeg (which includes ffprobe) for {system}:\n{hint}",
+ code=127,
+ )
+ return "" # unreachable
+
+
+def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprocess.CompletedProcess:
+ """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True."""
+ if not quiet:
+ info("$ " + " ".join(shell_quote(c) for c in cmd))
+ proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ if check and proc.returncode != 0:
+ tail = "\n".join(proc.stderr.strip().splitlines()[-15:])
+ die(f"command failed ({proc.returncode}): {cmd[0]}\n{tail}", code=proc.returncode or 1)
+ return proc
+
+
+def shell_quote(s: str) -> str:
+ if not s or any(ch in s for ch in " \t\"'\;|&<>()[]{}$*?"):
+ return "'" + s.replace("'", "'\\''") + "'"
+ return s
+
+
+def ffmpeg_base(overwrite: bool = True) -> List[str]:
+ cmd = [require_tool("ffmpeg"), "-hide_banner", "-loglevel", "error", "-nostdin"]
+ cmd.append("-y" if overwrite else "-n")
+ return cmd
+
+
+def probe(path: str) -> Dict[str, Any]:
+ """Return a compact, script-friendly description of a media file."""
+ if not os.path.exists(path):
+ die(f"input not found: {path}")
+ ffprobe = require_tool("ffprobe")
+ proc = run(
+ [ffprobe, "-v", "error", "-print_format", "json", "-show_format", "-show_streams", path],
+ quiet=True,
+ check=False,
+ )
+ if proc.returncode != 0:
+ die(f"ffprobe failed on {path}:\n{proc.stderr.strip()}")
+ raw = json.loads(proc.stdout or "{}")
+ fmt = raw.get("format", {})
+ streams = raw.get("streams", [])
+ video = next((s for s in streams if s.get("codec_type") == "video" and s.get("disposition", {}).get("attached_pic", 0) == 0), None)
+ audio = next((s for s in streams if s.get("codec_type") == "audio"), None)
+ subs = [s for s in streams if s.get("codec_type") == "subtitle"]
+
+ duration = _to_float(fmt.get("duration"))
+ if duration is None and video:
+ duration = _to_float(video.get("duration"))
+ if duration is None and audio:
+ duration = _to_float(audio.get("duration"))
+
+ out: Dict[str, Any] = {
+ "file": path,
+ "format": fmt.get("format_name"),
+ "duration": duration,
+ "size_bytes": _to_int(fmt.get("size")),
+ "bitrate": _to_int(fmt.get("bit_rate")),
+ "video": None,
+ "audio": None,
+ "subtitle_streams": len(subs),
+ }
+ if video:
+ r_rate = _fraction(video.get("r_frame_rate"))
+ avg_rate = _fraction(video.get("avg_frame_rate"))
+ fps = float(avg_rate) if avg_rate else (float(r_rate) if r_rate else None)
+ vfr = bool(r_rate and avg_rate and abs(float(r_rate) - float(avg_rate)) > 0.01)
+ w, h = _to_int(video.get("width")), _to_int(video.get("height"))
+ rotation = 0
+ for sd in video.get("side_data_list", []) or []:
+ if "rotation" in sd:
+ rotation = int(round(float(sd["rotation"])))
+ if "rotate" in (video.get("tags") or {}):
+ try:
+ rotation = int(video["tags"]["rotate"])
+ except ValueError:
+ pass
+ out["video"] = {
+ "codec": video.get("codec_name"),
+ "profile": video.get("profile"),
+ "width": w,
+ "height": h,
+ "display_aspect": video.get("display_aspect_ratio") or _aspect_string(w, h),
+ "fps": round(fps, 3) if fps else None,
+ "r_frame_rate": video.get("r_frame_rate"),
+ "avg_frame_rate": video.get("avg_frame_rate"),
+ "variable_frame_rate_suspected": vfr,
+ "pix_fmt": video.get("pix_fmt"),
+ "color_space": video.get("color_space"),
+ "color_primaries": video.get("color_primaries"),
+ "color_transfer": video.get("color_transfer"),
+ "color_range": video.get("color_range"),
+ "rotation": rotation,
+ "nb_frames": _to_int(video.get("nb_frames")),
+ "bitrate": _to_int(video.get("bit_rate")),
+ }
+ if audio:
+ out["audio"] = {
+ "codec": audio.get("codec_name"),
+ "channels": _to_int(audio.get("channels")),
+ "channel_layout": audio.get("channel_layout"),
+ "sample_rate": _to_int(audio.get("sample_rate")),
+ "bitrate": _to_int(audio.get("bit_rate")),
+ }
+ return out
+
+
+def default_output(input_path: str, suffix: str, ext: Optional[str] = None) -> str:
+ p = Path(input_path)
+ new_ext = ext if ext else p.suffix.lstrip(".") or "mp4"
+ return str(p.with_name(f"{p.stem}_{suffix}.{new_ext}"))
+
+
+def parse_time(value: str) -> float:
+ """Accept seconds ('12.5'), mm:ss ('1:30'), hh:mm:ss(.ms) ('00:01:30.250') or SRT '00:01:30,250'."""
+ v = value.strip().replace(",", ".")
+ if not v:
+ raise ValueError("empty time")
+ parts = v.split(":")
+ if len(parts) > 3:
+ raise ValueError(f"bad time: {value}")
+ total = 0.0
+ for part in parts:
+ total = total * 60 + float(part)
+ return total
+
+
+def fmt_srt_time(seconds: float) -> str:
+ if seconds < 0:
+ seconds = 0.0
+ ms = int(round(seconds * 1000))
+ h, rem = divmod(ms, 3_600_000)
+ m, rem = divmod(rem, 60_000)
+ s, ms = divmod(rem, 1000)
+ return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
+
+
+def escape_filter_path(path: str) -> str:
+ """Escape a path for use inside an ffmpeg filter graph option value."""
+ p = str(Path(path))
+ p = p.replace("\\", "/")
+ p = p.replace(":", "\\:").replace("'", "\\'").replace(",", "\\,").replace("[", "\\[").replace("]", "\\]")
+ return p
+
+
+def escape_drawtext(text: str) -> str:
+ return (
+ text.replace("\\", "\\\\")
+ .replace(":", "\\:")
+ .replace("'", "\\\\\\'")
+ .replace("%", "\\%")
+ .replace(",", "\\,")
+ .replace("[", "\\[")
+ .replace("]", "\\]")
+ )
+
+
+def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) -> List[str]:
+ args = ["-c:v", "libx264", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
+ if keep_bt709:
+ args += ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
+ return args
+
+
+def aac_args(bitrate: str = "192k") -> List[str]:
+ return ["-c:a", "aac", "-b:a", bitrate]
+
+
+AUDIO_CODECS = {
+ ".wav": ["-c:a", "pcm_s16le"],
+ ".flac": ["-c:a", "flac"],
+ ".mp3": ["-c:a", "libmp3lame", "-q:a", "0"],
+ ".m4a": ["-c:a", "aac", "-b:a", "256k"],
+ ".aac": ["-c:a", "aac", "-b:a", "256k"],
+ ".ogg": ["-c:a", "libvorbis", "-q:a", "6"],
+ ".opus": ["-c:a", "libopus", "-b:a", "128k"],
+}
+
+
+def audio_codec_for(output_path: str, default_bitrate: str = "192k") -> List[str]:
+ """Pick an audio codec that the output container can actually hold."""
+ ext = os.path.splitext(output_path)[1].lower()
+ return list(AUDIO_CODECS.get(ext, ["-c:a", "aac", "-b:a", default_bitrate]))
+
+
+def print_json(obj: Any) -> None:
+ sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
+
+
+def _to_float(v: Any) -> Optional[float]:
+ try:
+ return float(v) if v is not None else None
+ except (TypeError, ValueError):
+ return None
+
+
+def _to_int(v: Any) -> Optional[int]:
+ try:
+ return int(v) if v is not None else None
+ except (TypeError, ValueError):
+ return None
+
+
+def _fraction(v: Optional[str]) -> Optional[Fraction]:
+ if not v or v in ("0/0", "0"):
+ return None
+ try:
+ f = Fraction(v)
+ return f if f > 0 else None
+ except (ValueError, ZeroDivisionError):
+ return None
+
+
+def _aspect_string(w: Optional[int], h: Optional[int]) -> Optional[str]:
+ if not w or not h:
+ return None
+ f = Fraction(w, h)
+ return f"{f.numerator}:{f.denominator}"
diff --git a/scripts/caption.py b/scripts/caption.py
new file mode 100755
index 0000000..4dd8ca9
--- /dev/null
+++ b/scripts/caption.py
@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Burn SRT/ASS subtitles into a video, or generate an SRT from plain text.
+
+Styling (font, size, colour, outline, position) applies to SRT input via
+libass force_style. ASS files carry their own styles and are rendered as-is.
+
+Text-to-SRT input format (one cue per line, blank lines ignored):
+ 0:00-0:03 Hello and welcome
+ 00:00:03.500 --> 00:00:06 Second line | with a manual line break
+ Text without a time is auto-timed after the previous cue (--auto-seconds)
+
+Examples:
+ python3 caption.py input.mp4 --srt subs.srt
+ python3 caption.py input.mp4 --srt subs.srt --font "Noto Sans CJK JP" --size 28 --position top
+ python3 caption.py --text cues.txt --write-srt cues.srt # only produce the SRT
+ python3 caption.py input.mp4 --text cues.txt # generate + burn in one go
+"""
+import argparse
+import os
+import re
+import sys
+from typing import List, Tuple
+
+from _common import aac_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
+
+ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
+
+TIME_RE = re.compile(
+ r"^\s*(?P<a>[\d:.,]+)\s*(?:-->|-|–|to)\s*(?P<b>[\d:.,]+)\s+(?P<text>.+)$"
+)
+
+
+def parse_text_cues(path: str, auto_seconds: float, gap: float) -> List[Tuple[float, float, str]]:
+ cues: List[Tuple[float, float, str]] = []
+ cursor = 0.0
+ with open(path, encoding="utf-8") as fh:
+ for raw in fh:
+ line = raw.rstrip("\n")
+ if not line.strip():
+ continue
+ m = TIME_RE.match(line)
+ if m:
+ try:
+ start, end = parse_time(m.group("a")), parse_time(m.group("b"))
+ except ValueError:
+ start, end, text = cursor, cursor + auto_seconds, line.strip()
+ else:
+ text = m.group("text").strip()
+ else:
+ start, end, text = cursor, cursor + auto_seconds, line.strip()
+ if end <= start:
+ die(f"cue '{line}': end must be after start")
+ text = text.replace(" | ", "\n").replace("|", "\n")
+ cues.append((start, end, text))
+ cursor = end + gap
+ if not cues:
+ die(f"no cues found in {path}")
+ return cues
+
+
+def write_srt(cues: List[Tuple[float, float, str]], path: str) -> None:
+ with open(path, "w", encoding="utf-8") as fh:
+ for i, (s, e, t) in enumerate(cues, 1):
+ fh.write(f"{i}\n{fmt_srt_time(s)} --> {fmt_srt_time(e)}\n{t}\n\n")
+
+
+def ass_color(hex_rgb: str, alpha: int = 0) -> str:
+ h = hex_rgb.lstrip("#")
+ if len(h) != 6:
+ die(f"colour must be RRGGBB hex, got '{hex_rgb}'")
+ r, g, b = h[0:2], h[2:4], h[4:6]
+ return f"&H{alpha:02X}{b}{g}{r}".upper()
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input", nargs="?", help="video to burn captions into (omit with --write-srt to only generate)")
+ ap.add_argument("-o", "--output", help="output video (default: <name>_captioned.<ext>)")
+ src = ap.add_argument_group("subtitle source")
+ src.add_argument("--srt", help="SRT file to burn")
+ src.add_argument("--ass", help="ASS file to burn (styles inside the file are used)")
+ src.add_argument("--text", help="plain text cue file to convert into SRT (see format above)")
+ src.add_argument("--write-srt", help="where to save the generated SRT (default: <text>.srt)")
+ src.add_argument("--auto-seconds", type=float, default=3.0, help="duration for cues without timing (default 3)")
+ src.add_argument("--gap", type=float, default=0.0, help="gap after auto-timed cues in seconds")
+ sty = ap.add_argument_group("style (SRT only)")
+ sty.add_argument("--font", default="DejaVu Sans", help="font family, e.g. 'Noto Sans CJK JP' for Japanese")
+ sty.add_argument("--fonts-dir", help="directory with extra .ttf/.otf files")
+ sty.add_argument("--size", type=int, default=24, help="font size in ASS points (relative to a 288p script height, scales automatically)")
+ sty.add_argument("--color", default="FFFFFF", help="text colour RRGGBB (default FFFFFF)")
+ sty.add_argument("--outline-color", default="000000", help="outline colour RRGGBB")
+ sty.add_argument("--outline", type=float, default=2.0, help="outline width (default 2)")
+ sty.add_argument("--shadow", type=float, default=0.0, help="shadow depth (default 0)")
+ sty.add_argument("--bold", action="store_true")
+ sty.add_argument("--position", choices=sorted(ALIGN), default="bottom", help="on-screen placement (default bottom)")
+ sty.add_argument("--margin", type=int, default=30, help="vertical margin from the edge (default 30)")
+ sty.add_argument("--box", action="store_true", help="draw an opaque box behind text instead of an outline")
+ enc = ap.add_argument_group("encoding")
+ enc.add_argument("--crf", type=int, default=18)
+ enc.add_argument("--preset", default="medium")
+ args = ap.parse_args()
+
+ if not (args.srt or args.ass or args.text):
+ die("give one of --srt, --ass or --text")
+
+ srt_path = args.srt
+ if args.text:
+ cues = parse_text_cues(args.text, args.auto_seconds, args.gap)
+ srt_path = args.write_srt or os.path.splitext(args.text)[0] + ".srt"
+ write_srt(cues, srt_path)
+ info(f"wrote {srt_path} ({len(cues)} cues)")
+ if not args.input:
+ print(srt_path)
+ return 0
+
+ if not args.input:
+ die("input video is required unless you only use --text/--write-srt")
+ probe(args.input)
+
+ if args.ass:
+ if not os.path.exists(args.ass):
+ die(f"ASS file not found: {args.ass}")
+ vf = f"ass={escape_filter_path(args.ass)}"
+ if args.fonts_dir:
+ vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
+ else:
+ if not srt_path or not os.path.exists(srt_path):
+ die(f"SRT file not found: {srt_path}")
+ style = [
+ f"FontName={args.font}",
+ f"FontSize={args.size}",
+ f"PrimaryColour={ass_color(args.color)}",
+ f"OutlineColour={ass_color(args.outline_color)}",
+ f"BackColour={ass_color(args.outline_color, 0x80)}",
+ f"BorderStyle={3 if args.box else 1}",
+ f"Outline={args.outline:g}",
+ f"Shadow={args.shadow:g}",
+ f"Bold={-1 if args.bold else 0}",
+ f"Alignment={ALIGN[args.position]}",
+ f"MarginV={args.margin}",
+ ]
+ force = ",".join(style).replace("\\", "\\\\").replace("'", "\\'")
+ vf = f"subtitles={escape_filter_path(srt_path)}:force_style='{force}'"
+ if args.fonts_dir:
+ vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
+
+ output = args.output or default_output(args.input, "captioned")
+ cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf] + x264_args(args.crf, args.preset) + aac_args() + [output]
+ run(cmd)
+ result = probe(output)
+ info(f"wrote {output} ({result.get('duration'):.3f}s)")
+ print(output)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/cut.py b/scripts/cut.py
new file mode 100755
index 0000000..cd3f03e
--- /dev/null
+++ b/scripts/cut.py
@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Cut a clip or several segments out of a video and (optionally) join them.
+
+Lossless stream copy (-c copy) is preferred. Cuts snap to keyframes in that
+mode, so if frame accuracy matters pass --accurate to re-encode. Multiple
+segments are cut individually and concatenated with the concat demuxer.
+
+Examples:
+ python3 cut.py input.mp4 --start 00:00:10 --end 00:00:25
+ python3 cut.py input.mp4 --segments 0:05-0:12,1:00-1:20 -o highlights.mp4
+ python3 cut.py input.mp4 --start 3.5 --duration 10 --accurate
+"""
+import argparse
+import os
+import sys
+import tempfile
+from typing import List, Tuple
+
+from _common import aac_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+
+
+def parse_segments(spec: str) -> List[Tuple[float, float]]:
+ segs = []
+ for raw in spec.split(","):
+ raw = raw.strip()
+ if not raw:
+ continue
+ if "-" not in raw:
+ die(f"segment '{raw}' must look like START-END (e.g. 0:05-0:12)")
+ a, b = raw.rsplit("-", 1)
+ start, end = parse_time(a), parse_time(b)
+ if end <= start:
+ die(f"segment '{raw}': end must be after start")
+ segs.append((start, end))
+ if not segs:
+ die("no segments given")
+ return segs
+
+
+def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: int, preset: str, tolerance: float = 0.5) -> bool:
+ """Cut one segment. Returns True if the result was re-encoded."""
+ dur = end - start
+ if reencode:
+ cmd = ffmpeg_base() + ["-ss", f"{start:.3f}", "-i", src, "-t", f"{dur:.3f}"]
+ cmd += x264_args(crf, preset) + aac_args() + ["-avoid_negative_ts", "make_zero", dst]
+ else:
+ cmd = ffmpeg_base() + ["-ss", f"{start:.3f}", "-i", src, "-t", f"{dur:.3f}", "-c", "copy", "-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)
+ die(f"ffmpeg failed:\n{proc.stderr.strip()}")
+ if not reencode and tolerance >= 0:
+ got = probe(dst).get("duration") or 0.0
+ if abs(got - dur) > tolerance:
+ 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")
+ return cut_one(src, start, end, dst, True, crf, preset, tolerance)
+ return reencode
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_cut.<ext>)")
+ g = ap.add_argument_group("range (single segment)")
+ g.add_argument("--start", default="0", help="start time (seconds, mm:ss or hh:mm:ss.ms). default 0")
+ g.add_argument("--end", help="end time")
+ 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 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("--crf", type=int, default=18, help="x264 CRF when re-encoding (default 18)")
+ ap.add_argument("--preset", default="medium", help="x264 preset when re-encoding")
+ args = ap.parse_args()
+
+ meta = probe(args.input)
+ total = meta.get("duration") or 0.0
+
+ if args.segments:
+ segments = parse_segments(args.segments)
+ else:
+ start = parse_time(args.start)
+ if args.end and args.duration:
+ die("use --end or --duration, not both")
+ if args.end:
+ end = parse_time(args.end)
+ elif args.duration:
+ end = start + parse_time(args.duration)
+ else:
+ end = total
+ if end <= start:
+ die("end must be after start")
+ segments = [(start, end)]
+
+ for s, e in segments:
+ 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]
+
+ output = args.output or default_output(args.input, "cut")
+ ext = os.path.splitext(output)[1] or ".mp4"
+
+ reencoded = False
+ if len(segments) == 1:
+ reencoded = cut_one(args.input, segments[0][0], segments[0][1], output, args.accurate, args.crf, args.preset, args.tolerance)
+ else:
+ 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)
+ 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("file '" + p.replace("'", "'\\''") + "'\n")
+ cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile, "-c", "copy", 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] + x264_args(args.crf, args.preset) + aac_args() + [output]
+ run(cmd)
+
+ result = probe(output)
+ expected = sum(e - s for s, e in segments)
+ info(f"wrote {output} ({result.get('duration'):.3f}s, expected ~{expected:.3f}s, "
+ + ("re-encoded" if reencoded else "lossless stream copy") + ")")
+ print(output)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/export.py b/scripts/export.py
new file mode 100755
index 0000000..902bd7e
--- /dev/null
+++ b/scripts/export.py
@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Export with delivery presets. Scales/pads to the preset's frame (keeping
+the source aspect inside it), constrains duration where the platform does,
+sets BT.709 tags, and picks sensible codecs/bitrates.
+
+Presets:
+ youtube 1920x1080 H.264 CRF 18 high profile, AAC 192k, 48 kHz, faststart
+ youtube4k 3840x2160 H.264 CRF 18, AAC 192k
+ reels 1080x1920 9:16 H.264 CRF 20, AAC 128k, max 90 s (also Shorts/TikTok)
+ x 1280x720 H.264 CRF 22, AAC 128k, max 140 s (Twitter/X)
+ prores ProRes 422 HQ .mov, PCM 16-bit audio (editing master)
+ h265 HEVC CRF 24 (libx265) with hvc1 tag for Apple compatibility
+ gif 480px wide palette-optimised GIF at 12 fps (short previews)
+
+Examples:
+ python3 export.py final.mp4 --preset youtube
+ python3 export.py final.mp4 --preset reels --fit crop
+ python3 export.py final.mp4 --preset prores -o master.mov
+ python3 export.py --list
+"""
+import argparse
+import sys
+from typing import Dict, List
+
+from _common import default_output, die, ffmpeg_base, info, probe, run
+
+PRESETS: Dict[str, Dict] = {
+ "youtube": {"w": 1920, "h": 1080, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "1080p H.264, AAC 192k"},
+ "youtube4k": {"w": 3840, "h": 2160, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "2160p H.264, AAC 192k"},
+ "reels": {"w": 1080, "h": 1920, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "medium", "-crf", "20", "-profile:v", "high", "-pix_fmt", "yuv420p", "-r", "30"], "audio": ["-c:a", "aac", "-b:a", "128k", "-ar", "48000"], "max": 90.0, "desc": "9:16 1080x1920, 30fps, max 90s (Reels/Shorts/TikTok)"},
+ "x": {"w": 1280, "h": 720, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "medium", "-crf", "22", "-profile:v", "high", "-pix_fmt", "yuv420p", "-r", "30"], "audio": ["-c:a", "aac", "-b:a", "128k", "-ar", "44100"], "max": 140.0, "desc": "720p H.264, max 140s (Twitter/X)"},
+ "prores": {"w": None, "h": None, "ext": "mov", "video": ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"], "audio": ["-c:a", "pcm_s16le"], "max": None, "desc": "ProRes 422 HQ master, PCM audio, source resolution"},
+ "h265": {"w": None, "h": None, "ext": "mp4", "video": ["-c:v", "libx265", "-preset", "medium", "-crf", "24", "-pix_fmt", "yuv420p", "-tag:v", "hvc1"], "audio": ["-c:a", "aac", "-b:a", "160k"], "max": None, "desc": "HEVC CRF 24, hvc1 tag, source resolution"},
+ "gif": {"w": 480, "h": None, "ext": "gif", "video": [], "audio": [], "max": None, "desc": "480px palette GIF, 12fps"},
+}
+
+BT709 = ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input", nargs="?")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_<preset>.<ext>)")
+ ap.add_argument("--preset", choices=sorted(PRESETS), help="delivery preset")
+ ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how to reach the preset frame when aspect differs (default pad)")
+ ap.add_argument("--pad-color", default="black")
+ ap.add_argument("--no-scale", action="store_true", help="keep source resolution even for platform presets")
+ ap.add_argument("--allow-long", action="store_true", help="do not trim to the platform's max duration")
+ ap.add_argument("--crf", type=int, help="override CRF")
+ ap.add_argument("--list", action="store_true", help="list presets and exit")
+ args = ap.parse_args()
+
+ if args.list:
+ for name, p in PRESETS.items():
+ print(f"{name:10s} {p['desc']}")
+ return 0
+ if not args.input or not args.preset:
+ die("input and --preset are required (or use --list)")
+
+ p = PRESETS[args.preset]
+ meta = probe(args.input)
+ if not meta.get("video"):
+ die("input has no video stream")
+ has_audio = bool(meta.get("audio"))
+ output = args.output or default_output(args.input, args.preset, p["ext"])
+
+ vf: List[str] = []
+ if p["w"] and not args.no_scale:
+ if p["h"]:
+ if args.fit == "crop":
+ vf += [f"scale={p['w']}:{p['h']}:force_original_aspect_ratio=increase", f"crop={p['w']}:{p['h']}"]
+ else:
+ vf += [f"scale={p['w']}:{p['h']}:force_original_aspect_ratio=decrease", f"pad={p['w']}:{p['h']}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"]
+ vf.append("setsar=1")
+ else:
+ vf.append(f"scale={p['w']}:-2")
+ cmd = ffmpeg_base() + ["-i", args.input]
+
+ if args.preset == "gif":
+ chain = ",".join(["fps=12"] + vf) if vf else "fps=12"
+ fc = f"[0:v]{chain},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle"
+ cmd += ["-filter_complex", fc, "-loop", "0", output]
+ run(cmd)
+ info(f"wrote {output}")
+ print(output)
+ return 0
+
+ if vf:
+ cmd += ["-vf", ",".join(vf)]
+ video = list(p["video"])
+ if args.crf is not None and "-crf" in video:
+ video[video.index("-crf") + 1] = str(args.crf)
+ cmd += video
+ if args.preset not in ("prores",):
+ cmd += BT709
+ if p["ext"] == "mp4":
+ cmd += ["-movflags", "+faststart"]
+ cmd += (p["audio"] if has_audio else ["-an"])
+ if p["max"] and not args.allow_long and (meta.get("duration") or 0) > p["max"]:
+ info(f"trimming to the platform maximum of {p['max']:.0f}s (use --allow-long to keep full length)")
+ cmd += ["-t", f"{p['max']:.3f}"]
+ cmd.append(output)
+ run(cmd)
+ result = probe(output)
+ v = result["video"]
+ info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['codec']})")
+ print(output)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/fit.py b/scripts/fit.py
new file mode 100755
index 0000000..d67f199
--- /dev/null
+++ b/scripts/fit.py
@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+"""Fit a video to a target duration and/or aspect ratio.
+
+Duration: --duration N with --method speed (retime video+audio, pitch-preserving
+via atempo chaining) or --method trim (keep the first N seconds, or a centred
+window with --from-center). Aspect: --aspect 16:9|9:16|1:1|4:5|W:H with
+--fit pad (letterbox/pillarbox with --pad-color, default black) or --fit crop
+(centre crop). --width sets the output width; height follows the aspect.
+
+Examples:
+ python3 fit.py input.mp4 --duration 60 # speed up/down to exactly 60s
+ python3 fit.py input.mp4 --duration 30 --method trim
+ python3 fit.py input.mp4 --aspect 9:16 --fit pad --width 1080
+ python3 fit.py input.mp4 --aspect 1:1 --fit crop --duration 15
+"""
+import argparse
+import math
+import sys
+from fractions import Fraction
+from typing import List
+
+from _common import aac_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+
+ASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}
+
+
+def parse_aspect(value: str) -> Fraction:
+ if value in ASPECT_PRESETS:
+ return ASPECT_PRESETS[value]
+ try:
+ w, h = value.split(":")
+ return Fraction(int(w), int(h))
+ except (ValueError, ZeroDivisionError):
+ die(f"bad aspect '{value}', use W:H like 16:9")
+ return Fraction(1) # unreachable
+
+
+def atempo_chain(factor: float) -> str:
+ """atempo accepts 0.5..100 per instance; chain for extreme factors."""
+ parts: List[str] = []
+ remaining = factor
+ while remaining < 0.5:
+ parts.append("atempo=0.5")
+ remaining /= 0.5
+ while remaining > 100.0:
+ parts.append("atempo=100.0")
+ remaining /= 100.0
+ parts.append(f"atempo={remaining:.6f}")
+ return ",".join(parts)
+
+
+def even(n: float) -> int:
+ v = int(round(n))
+ return v if v % 2 == 0 else v + 1
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_fit.<ext>)")
+ d = ap.add_argument_group("duration")
+ d.add_argument("--duration", help="target duration (seconds or mm:ss)")
+ d.add_argument("--method", choices=["speed", "trim"], default="speed", help="how to reach the duration (default speed)")
+ d.add_argument("--from-center", action="store_true", help="with --method trim, keep the middle instead of the start")
+ d.add_argument("--max-speed", type=float, default=4.0, help="refuse speed factors above this (default 4x)")
+ a = ap.add_argument_group("aspect")
+ a.add_argument("--aspect", help="target aspect ratio, e.g. 16:9, 9:16, 1:1, 4:5")
+ a.add_argument("--fit", choices=["pad", "crop"], default="pad", help="pad (letterbox) or crop to reach the aspect (default pad)")
+ a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect)")
+ a.add_argument("--pad-color", default="black", help="pad colour, e.g. black, white, 0x101010 (default black)")
+ e = ap.add_argument_group("encoding")
+ e.add_argument("--crf", type=int, default=18)
+ e.add_argument("--preset", default="medium")
+ e.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
+ args = ap.parse_args()
+
+ if not args.duration and not args.aspect and not args.width and not args.fps:
+ die("nothing to do: give --duration, --aspect, --width and/or --fps")
+
+ meta = probe(args.input)
+ if not meta.get("video"):
+ die("input has no video stream")
+ src_dur = meta["duration"] or 0.0
+ sw, sh = meta["video"]["width"], meta["video"]["height"]
+ if meta["video"].get("rotation") in (90, -90, 270, -270):
+ sw, sh = sh, sw
+ has_audio = bool(meta.get("audio"))
+
+ vf: List[str] = []
+ af: List[str] = []
+ pre_input: List[str] = []
+ post: List[str] = []
+ factor = 1.0
+
+ # ---- duration
+ if args.duration:
+ target = parse_time(args.duration)
+ if target <= 0:
+ die("target duration must be > 0")
+ if args.method == "speed":
+ factor = src_dur / target # >1 = speed up
+ if factor > args.max_speed or factor < 1 / args.max_speed:
+ die(f"required speed factor {factor:.2f}x exceeds --max-speed {args.max_speed}x; use --method trim or raise the limit")
+ if abs(factor - 1.0) > 1e-4:
+ vf.append(f"setpts={1/factor:.8f}*PTS")
+ if has_audio:
+ af.append(atempo_chain(factor))
+ post += ["-t", f"{target:.3f}"]
+ else:
+ if target < src_dur:
+ start = (src_dur - target) / 2 if args.from_center else 0.0
+ pre_input += ["-ss", f"{start:.3f}"]
+ post += ["-t", f"{target:.3f}"]
+ else:
+ info(f"source ({src_dur:.2f}s) is already shorter than {target:.2f}s; trim does nothing")
+
+ # ---- aspect / size
+ if args.aspect or args.width:
+ src_ratio = Fraction(sw, sh)
+ ratio = parse_aspect(args.aspect) if args.aspect else src_ratio
+ if args.width:
+ out_w = even(args.width)
+ else:
+ out_w = even(sw if ratio <= src_ratio else sh * ratio)
+ out_h = even(out_w / ratio)
+ if args.fit == "crop":
+ vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase")
+ vf.append(f"crop={out_w}:{out_h}")
+ else:
+ vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease")
+ vf.append(f"pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}")
+ vf.append("setsar=1")
+
+ if args.fps:
+ vf.append(f"fps={args.fps:g}")
+
+ output = args.output or default_output(args.input, "fit")
+ cmd = ffmpeg_base() + pre_input + ["-i", args.input]
+ if vf:
+ cmd += ["-vf", ",".join(vf)]
+ if af:
+ cmd += ["-af", ",".join(af)]
+ cmd += x264_args(args.crf, args.preset)
+ if has_audio:
+ cmd += aac_args()
+ else:
+ cmd += ["-an"]
+ cmd += post + [output]
+ run(cmd)
+
+ result = probe(output)
+ msg = f"wrote {output} ({result['duration']:.3f}s, {result['video']['width']}x{result['video']['height']})"
+ if abs(factor - 1.0) > 1e-4:
+ msg += f", speed {factor:.3f}x"
+ info(msg)
+ print(output)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/loudness.py b/scripts/loudness.py
new file mode 100755
index 0000000..c33bd49
--- /dev/null
+++ b/scripts/loudness.py
@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Two-pass EBU R128 loudness normalisation (ffmpeg loudnorm).
+
+Pass 1 measures integrated loudness, true peak, LRA and threshold; pass 2
+applies loudnorm in linear mode with those measurements so the result hits
+the target without the pumping of single-pass mode. Video is stream-copied.
+
+Common targets: -14 LUFS (YouTube/Spotify), -16 (Apple Podcasts), -23 (EBU broadcast).
+
+Examples:
+ python3 loudness.py input.mp4 # -14 LUFS, -1 dBTP
+ python3 loudness.py podcast.wav -I -16 --tp -1.5 -o podcast_norm.wav
+ python3 loudness.py input.mp4 --measure-only
+"""
+import argparse
+import json
+import os
+import re
+import sys
+
+from _common import AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run
+
+
+
+def measure(path: str, I: float, tp: float, lra: float) -> dict:
+ ffmpeg = require_tool("ffmpeg")
+ cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]
+ proc = run(cmd, check=False)
+ m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr, re.S)
+ if proc.returncode != 0 or not m:
+ die(f"loudness measurement failed:\n{proc.stderr.strip()[-1500:]}")
+ data = json.loads(m.group(0))
+ for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset"):
+ if data.get(k) in (None, "-inf", "inf", "nan"):
+ die(f"loudnorm returned unusable value for {k}: {data.get(k)} (silent input?)")
+ return data
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_loudnorm.<ext>)")
+ ap.add_argument("-I", "--lufs", type=float, default=-14.0, help="integrated loudness target in LUFS (default -14)")
+ ap.add_argument("--tp", type=float, default=-1.0, help="true peak ceiling in dBTP (default -1)")
+ ap.add_argument("--lra", type=float, default=11.0, help="loudness range target in LU (default 11)")
+ ap.add_argument("--measure-only", action="store_true", help="print the measured stats as JSON and exit")
+ ap.add_argument("--audio-bitrate", default="192k", help="AAC bitrate when the container is video (default 192k)")
+ ap.add_argument("--sample-rate", type=int, help="output sample rate (default: 48000; loudnorm upsamples internally to 192k)")
+ args = ap.parse_args()
+
+ meta = probe(args.input)
+ if not meta.get("audio"):
+ die("input has no audio stream")
+
+ stats = measure(args.input, args.lufs, args.tp, args.lra)
+ info(f"measured: {float(stats['input_i']):.1f} LUFS, TP {float(stats['input_tp']):.1f} dBTP, LRA {float(stats['input_lra']):.1f} LU")
+ if args.measure_only:
+ print(json.dumps({k: stats[k] for k in ("input_i", "input_tp", "input_lra", "input_thresh", "target_offset")}, indent=2))
+ return 0
+
+ output = args.output or default_output(args.input, "loudnorm")
+ af = (
+ f"loudnorm=I={args.lufs}:TP={args.tp}:LRA={args.lra}"
+ f":measured_I={stats['input_i']}:measured_TP={stats['input_tp']}:measured_LRA={stats['input_lra']}"
+ f":measured_thresh={stats['input_thresh']}:offset={stats['target_offset']}:linear=true:print_format=summary"
+ )
+ sr = args.sample_rate or meta["audio"].get("sample_rate") or 48000
+ ext = os.path.splitext(output)[1].lower()
+ cmd = ffmpeg_base() + ["-i", args.input, "-af", af, "-ar", str(sr)]
+ if ext in AUDIO_CODECS or not meta.get("video"):
+ cmd += ["-vn"] + audio_codec_for(output, args.audio_bitrate)
+ else:
+ cmd += ["-map", "0:v:0", "-map", "0:a:0", "-c:v", "copy", "-c:a", "aac", "-b:a", args.audio_bitrate]
+ cmd.append(output)
+ run(cmd)
+
+ after = measure(output, args.lufs, args.tp, args.lra)
+ info(f"result: {float(after['input_i']):.1f} LUFS, TP {float(after['input_tp']):.1f} dBTP (target {args.lufs} LUFS)")
+ print(output)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/overlay.py b/scripts/overlay.py
new file mode 100755
index 0000000..3b846ab
--- /dev/null
+++ b/scripts/overlay.py
@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Composite a logo/image or a text title onto a video with position, timing,
+opacity and fade in/out.
+
+Positions: top-left, top, top-right, left, center, right, bottom-left, bottom,
+bottom-right, or explicit "X,Y" pixels (negative counts from the far edge).
+
+Examples:
+ python3 overlay.py input.mp4 --image logo.png --position top-right --scale 200 --opacity 0.8
+ python3 overlay.py input.mp4 --image lower_third.png --position bottom-left --start 2 --end 8 --fade 0.5
+ python3 overlay.py input.mp4 --text "Episode 12" --position bottom --font-size 48 --start 1 --end 5 --fade 0.3
+ python3 overlay.py input.mp4 --text "こんにちは" --font-file /path/NotoSansCJK-Bold.ttc --box
+"""
+import argparse
+import sys
+from typing import List, Optional
+
+from _common import aac_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
+
+POS = {
+ "top-left": ("{m}", "{m}"),
+ "top": ("(W-w)/2", "{m}"),
+ "top-right": ("W-w-{m}", "{m}"),
+ "left": ("{m}", "(H-h)/2"),
+ "center": ("(W-w)/2", "(H-h)/2"),
+ "right": ("W-w-{m}", "(H-h)/2"),
+ "bottom-left": ("{m}", "H-h-{m}"),
+ "bottom": ("(W-w)/2", "H-h-{m}"),
+ "bottom-right": ("W-w-{m}", "H-h-{m}"),
+}
+
+
+def position_exprs(pos: str, margin: int, text_mode: bool):
+ if pos in POS:
+ x, y = (e.format(m=margin) for e in POS[pos])
+ else:
+ try:
+ xs, ys = pos.split(",")
+ xv, yv = int(xs), int(ys)
+ except ValueError:
+ die(f"bad --position '{pos}'")
+ x = f"W-w{xv}" if xv < 0 else str(xv)
+ y = f"H-h{yv}" if yv < 0 else str(yv)
+ if text_mode:
+ # drawtext uses w/h for the text box but lower-case main dims differ: W/H -> w/h, w/h -> text_w/text_h
+ x = x.replace("W", "main_w").replace("w", "text_w").replace("H", "main_h").replace("h", "text_h")
+ y = y.replace("W", "main_w").replace("w", "text_w").replace("H", "main_h").replace("h", "text_h")
+ x = x.replace("main_text_w", "main_w").replace("main_text_h", "main_h")
+ y = y.replace("main_text_w", "main_w").replace("main_text_h", "main_h")
+ return x, y
+
+
+def enable_expr(start: Optional[float], end: Optional[float]) -> str:
+ if start is None and end is None:
+ return ""
+ s = f"{start:.3f}" if start is not None else "0"
+ if end is None:
+ return f"gte(t,{s})"
+ return f"between(t,{s},{end:.3f})"
+
+
+def alpha_expr(opacity: float, start: Optional[float], end: Optional[float], fade: float) -> str:
+ """Time-varying alpha with linear fade in/out inside [start, end]."""
+ if fade <= 0 or (start is None and end is None):
+ return f"{opacity:g}"
+ s = start if start is not None else 0.0
+ parts = [f"{opacity:g}"]
+ fin = f"min(1,(t-{s:.3f})/{fade:g})"
+ parts.append(fin)
+ if end is not None:
+ parts.append(f"min(1,({end:.3f}-t)/{fade:g})")
+ return "max(0," + "*".join(parts) + ")"
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_overlay.<ext>)")
+ src = ap.add_mutually_exclusive_group(required=True)
+ src.add_argument("--image", help="PNG/JPG (alpha respected) to composite")
+ src.add_argument("--text", help="text to draw (drawtext)")
+ ap.add_argument("--position", default="top-right", help="named position or X,Y (default top-right)")
+ ap.add_argument("--margin", type=int, default=24, help="margin from the edges in px (default 24)")
+ ap.add_argument("--start", help="show from this time (default: whole video)")
+ ap.add_argument("--end", help="hide after this time")
+ ap.add_argument("--fade", type=float, default=0.0, help="fade in/out duration in seconds")
+ ap.add_argument("--opacity", type=float, default=1.0, help="0..1 (default 1)")
+ img = ap.add_argument_group("image options")
+ img.add_argument("--scale", type=int, help="scale the image to this width in px (keeps aspect)")
+ img.add_argument("--scale-percent", type=float, help="scale the image to this %% of the video width")
+ txt = ap.add_argument_group("text options")
+ txt.add_argument("--font", default="DejaVu Sans", help="fontconfig font name")
+ txt.add_argument("--font-file", help="explicit .ttf/.otf/.ttc path (use this for CJK fonts)")
+ txt.add_argument("--font-size", type=int, default=42)
+ txt.add_argument("--font-color", default="white")
+ txt.add_argument("--border", type=int, default=2, help="text outline width (default 2)")
+ txt.add_argument("--border-color", default="black")
+ txt.add_argument("--box", action="store_true", help="draw a translucent box behind the text")
+ txt.add_argument("--box-color", default="[email protected]")
+ enc = ap.add_argument_group("encoding")
+ enc.add_argument("--crf", type=int, default=18)
+ enc.add_argument("--preset", default="medium")
+ args = ap.parse_args()
+
+ meta = probe(args.input)
+ if not meta.get("video"):
+ die("input has no video stream")
+ vw = meta["video"]["width"]
+ start = parse_time(args.start) if args.start else None
+ end = parse_time(args.end) if args.end else None
+ if start is not None and end is not None and end <= start:
+ die("--end must be after --start")
+ if not 0 <= args.opacity <= 1:
+ die("--opacity must be within 0..1")
+
+ output = args.output or default_output(args.input, "overlay")
+ enable = enable_expr(start, end)
+ cmd = ffmpeg_base() + ["-i", args.input]
+
+ if args.image:
+ probe(args.image)
+ chain: List[str] = ["format=rgba"]
+ if args.scale_percent:
+ chain.append(f"scale={int(vw * args.scale_percent / 100)}:-1")
+ elif args.scale:
+ chain.append(f"scale={args.scale}:-1")
+ if args.opacity < 1:
+ chain.append(f"colorchannelmixer=aa={args.opacity:g}")
+ if args.fade > 0 and (start is not None or end is not None):
+ s = start if start is not None else 0.0
+ chain.append(f"fade=t=in:st={s:.3f}:d={args.fade:g}:alpha=1")
+ if end is not None:
+ chain.append(f"fade=t=out:st={end - args.fade:.3f}:d={args.fade:g}:alpha=1")
+ x, y = position_exprs(args.position, args.margin, text_mode=False)
+ ov = f"overlay={x}:{y}:format=auto"
+ if enable:
+ ov += f":enable='{enable}'"
+ # -loop 1 turns the still into a timed stream so fade/enable expressions see real timestamps
+ cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", "-i", args.image]
+ fc = f"[1:v]{','.join(chain)},setpts=PTS-STARTPTS[ov];[0:v][ov]{ov}[out]"
+ cmd += ["-filter_complex", fc, "-map", "[out]", "-map", "0:a?", "-shortest"]
+ else:
+ x, y = position_exprs(args.position, args.margin, text_mode=True)
+ opts = [f"text='{escape_drawtext(args.text)}'", f"fontsize={args.font_size}", f"x={x}", f"y={y}",
+ f"borderw={args.border}", f"bordercolor={args.border_color}"]
+ if args.font_file:
+ opts.append(f"fontfile={escape_filter_path(args.font_file)}")
+ else:
+ opts.append(f"font='{args.font}'")
+ alpha = alpha_expr(args.opacity, start, end, args.fade)
+ opts.append(f"fontcolor={args.font_color}")
+ if alpha != "1":
+ opts.append(f"alpha='{alpha}'")
+ if args.box:
+ opts += ["box=1", f"boxcolor={args.box_color}", "boxborderw=12"]
+ if enable:
+ opts.append(f"enable='{enable}'")
+ cmd += ["-vf", "drawtext=" + ":".join(opts)]
+
+ cmd += x264_args(args.crf, args.preset)
+ cmd += aac_args() if meta.get("audio") else ["-an"]
+ cmd.append(output)
+ run(cmd)
+ result = probe(output)
+ info(f"wrote {output} ({result['duration']:.3f}s)")
+ print(output)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/probe.py b/scripts/probe.py
new file mode 100755
index 0000000..d6713e9
--- /dev/null
+++ b/scripts/probe.py
@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""Inspect a media file and print a compact JSON summary.
+
+Reports duration, fps (and whether variable frame rate is suspected), resolution,
+codecs, pixel format / color space, audio channels and sample rate.
+
+Examples:
+ python3 probe.py input.mp4
+ python3 probe.py a.mp4 b.mov --compact
+ python3 probe.py input.mp4 --field duration
+"""
+import argparse
+import sys
+
+from _common import print_json, probe
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("inputs", nargs="+", help="media file(s) to inspect")
+ ap.add_argument("--compact", action="store_true", help="one human-readable line per file instead of JSON")
+ ap.add_argument("--field", help="print only this top-level field (e.g. duration) or dotted path (video.fps)")
+ args = ap.parse_args()
+
+ results = [probe(p) for p in args.inputs]
+
+ if args.field:
+ for r in results:
+ cur = r
+ for key in args.field.split("."):
+ cur = cur.get(key) if isinstance(cur, dict) else None
+ print(cur if cur is not None else "")
+ return 0
+
+ if args.compact:
+ for r in results:
+ v, a = r.get("video") or {}, r.get("audio") or {}
+ dur = r.get("duration")
+ line = f"{r['file']}: {dur:.3f}s" if dur is not None else f"{r['file']}: ?s"
+ if v:
+ line += f" | {v.get('width')}x{v.get('height')} @ {v.get('fps')}fps {v.get('codec')} {v.get('pix_fmt')}"
+ if v.get("variable_frame_rate_suspected"):
+ line += " (VFR?)"
+ else:
+ line += " | no video"
+ if a:
+ line += f" | audio {a.get('codec')} {a.get('channels')}ch {a.get('sample_rate')}Hz"
+ else:
+ line += " | no audio"
+ print(line)
+ return 0
+
+ print_json(results[0] if len(results) == 1 else results)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/sync.py b/scripts/sync.py
new file mode 100755
index 0000000..fb002b6
--- /dev/null
+++ b/scripts/sync.py
@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""Detect the time offset between two recordings by audio cross-correlation
+and (optionally) write a synced output.
+
+Pure standard library: both tracks are decoded by ffmpeg to mono 8 kHz PCM,
+reduced to a coarse loudness envelope, and cross-correlated with an FFT
+implemented in Python. Precision is roughly +/- one envelope step (default
+5 ms), which is plenty for lining up a lav mic or a second camera.
+
+Offset semantics: a positive offset means the SECOND input starts LATER
+than the reference, i.e. `second` must be shifted earlier by that amount.
+
+Examples:
+ python3 sync.py camera.mp4 lavmic.wav # print offset only
+ python3 sync.py camera.mp4 lavmic.wav --replace-audio -o synced.mp4
+ python3 sync.py camA.mp4 camB.mp4 --trim-second -o camB_synced.mp4
+ python3 sync.py cam.mp4 mic.wav --max-offset 60 --json
+"""
+import argparse
+import cmath
+import json
+import math
+import os
+import struct
+import subprocess
+import sys
+from typing import List
+
+from _common import aac_args, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, x264_args
+
+SR = 8000 # decode sample rate
+
+
+def decode_mono(path: str, seconds: float) -> List[float]:
+ ffmpeg = require_tool("ffmpeg")
+ cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-i", path, "-t", f"{seconds:.3f}",
+ "-vn", "-ac", "1", "-ar", str(SR), "-f", "s16le", "-"]
+ proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+ if proc.returncode != 0 or not proc.stdout:
+ die(f"could not decode audio from {path}:\n{proc.stderr.decode(errors='replace').strip()}")
+ n = len(proc.stdout) // 2
+ return [v / 32768.0 for v in struct.unpack(f"<{n}h", proc.stdout[: n * 2])]
+
+
+def envelope(samples: List[float], step: int) -> List[float]:
+ """RMS energy per block, mean-removed so silence does not correlate."""
+ env = []
+ for i in range(0, len(samples) - step + 1, step):
+ block = samples[i : i + step]
+ env.append(math.sqrt(sum(x * x for x in block) / step))
+ if not env:
+ return env
+ mean = sum(env) / len(env)
+ return [e - mean for e in env]
+
+
+def fft(a: List[complex]) -> List[complex]:
+ """Iterative radix-2 Cooley-Tukey FFT. len(a) must be a power of two."""
+ n = len(a)
+ a = list(a)
+ j = 0
+ for i in range(1, n):
+ bit = n >> 1
+ while j & bit:
+ j ^= bit
+ bit >>= 1
+ j ^= bit
+ if i < j:
+ a[i], a[j] = a[j], a[i]
+ length = 2
+ while length <= n:
+ ang = -2 * math.pi / length
+ wlen = complex(math.cos(ang), math.sin(ang))
+ half = length // 2
+ for i in range(0, n, length):
+ w = 1 + 0j
+ for k in range(half):
+ u = a[i + k]
+ v = a[i + k + half] * w
+ a[i + k] = u + v
+ a[i + k + half] = u - v
+ w *= wlen
+ length <<= 1
+ return a
+
+
+def ifft(a: List[complex]) -> List[complex]:
+ n = len(a)
+ conj = [x.conjugate() for x in a]
+ out = fft(conj)
+ return [x.conjugate() / n for x in out]
+
+
+def cross_correlate(ref: List[float], other: List[float], max_lag: int):
+ n = 1
+ while n < len(ref) + len(other):
+ n <<= 1
+ fa = fft([complex(x) for x in ref] + [0j] * (n - len(ref)))
+ fb = fft([complex(x) for x in other] + [0j] * (n - len(other)))
+ prod = [x * y.conjugate() for x, y in zip(fa, fb)]
+ corr = ifft(prod)
+ # corr[k] = sum ref[i+k]*other[i] -> lag k means 'other' is delayed by k relative to ref? see below
+ best_lag, best_val = 0, -float("inf")
+ max_lag = min(max_lag, n // 2 - 1)
+ for lag in range(-max_lag, max_lag + 1):
+ val = corr[lag % n].real
+ if val > best_val:
+ best_val, best_lag = val, lag
+ energy = math.sqrt(sum(x * x for x in ref) * sum(x * x for x in other)) or 1.0
+ return best_lag, best_val / energy
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("reference", help="reference recording (usually the camera video)")
+ ap.add_argument("second", help="recording to align (external audio or second camera)")
+ ap.add_argument("-o", "--output", help="output file when writing a synced result")
+ ap.add_argument("--max-offset", type=float, default=30.0, help="largest offset to search in seconds (default 30)")
+ ap.add_argument("--analyze-seconds", type=float, default=120.0, help="how much audio to analyse from each file (default 120)")
+ ap.add_argument("--step-ms", type=float, default=5.0, help="envelope resolution in ms (default 5)")
+ ap.add_argument("--json", action="store_true", help="print the result as JSON")
+ mode = ap.add_mutually_exclusive_group()
+ mode.add_argument("--replace-audio", action="store_true", help="write reference video with the second file's audio, aligned")
+ mode.add_argument("--trim-second", action="store_true", help="write the second file shifted so it lines up with the reference")
+ ap.add_argument("--crf", type=int, default=18)
+ args = ap.parse_args()
+
+ for p in (args.reference, args.second):
+ if not probe(p).get("audio"):
+ die(f"{p} has no audio stream to correlate")
+
+ step = max(1, int(SR * args.step_ms / 1000))
+ ref = envelope(decode_mono(args.reference, args.analyze_seconds), step)
+ oth = envelope(decode_mono(args.second, args.analyze_seconds), step)
+ if len(ref) < 10 or len(oth) < 10:
+ die("not enough audio to analyse")
+
+ max_lag = int(args.max_offset * SR / step)
+ lag, score = cross_correlate(ref, oth, max_lag)
+ # With prod = FFT(ref) * conj(FFT(other)), the peak sits at lag k where ref[i] ~ other[i - k]:
+ # the same event happens k steps later in the reference than in the second file, which
+ # means the second recording STARTED k steps later. Positive offset = second starts later.
+ offset = lag * step / SR
+
+ result = {
+ "reference": args.reference,
+ "second": args.second,
+ "offset_seconds": round(offset, 4),
+ "confidence": round(max(0.0, min(1.0, score)), 3),
+ "meaning": ("second starts %.3fs %s than reference" % (abs(offset), "later" if offset > 0 else "earlier")),
+ }
+ if result["confidence"] < 0.1:
+ info("warning: low correlation confidence; check that both files contain the same audio event")
+
+ if args.replace_audio or args.trim_second:
+ output = args.output or default_output(args.reference if args.replace_audio else args.second, "synced", "mp4")
+ # second started later (offset > 0) -> delay it by `offset` (pad the head)
+ # second started earlier (offset < 0) -> drop its first `-offset` seconds
+ delay_ms = int(round(offset * 1000))
+ head_trim = -offset if offset < 0 else 0.0
+ second_meta = probe(args.second)
+ has_video = bool(second_meta.get("video"))
+
+ if args.replace_audio:
+ cmd = ffmpeg_base() + ["-i", args.reference]
+ if head_trim > 0:
+ cmd += ["-ss", f"{head_trim:.4f}"]
+ cmd += ["-i", args.second, "-map", "0:v:0", "-map", "1:a:0", "-c:v", "copy"]
+ if delay_ms > 0:
+ cmd += ["-af", f"adelay={delay_ms}:all=1"]
+ cmd += aac_args() + ["-shortest", output]
+ proc = run(cmd, check=False)
+ if proc.returncode != 0:
+ cmd = [c for c in cmd if c != "copy"]
+ idx = cmd.index("-c:v"); del cmd[idx]
+ cmd = cmd[:-1] + x264_args(args.crf) + [output]
+ run(cmd)
+ else:
+ if head_trim > 0:
+ cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second, "-c", "copy", "-avoid_negative_ts", "make_zero", output]
+ proc = run(cmd, check=False)
+ if proc.returncode != 0:
+ cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second] + (x264_args(args.crf) if has_video else []) + audio_codec_for(output) + [output]
+ run(cmd)
+ else:
+ af = f"adelay={delay_ms}:all=1"
+ cmd = ffmpeg_base() + ["-i", args.second]
+ if has_video:
+ cmd += ["-vf", f"tpad=start_duration={offset:.4f}"] + x264_args(args.crf)
+ cmd += ["-af", af] + audio_codec_for(output) + [output]
+ run(cmd)
+ result["output"] = output
+ info(f"wrote {output}")
+
+ if args.json:
+ print(json.dumps(result, indent=2))
+ else:
+ print(f"offset: {result['offset_seconds']:+.3f}s ({result['meaning']}), confidence {result['confidence']:.2f}")
+ if "output" in result:
+ print(result["output"])
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tests/test_all.py b/tests/test_all.py
new file mode 100644
index 0000000..d57dd09
--- /dev/null
+++ b/tests/test_all.py
@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""End-to-end tests: build synthetic footage, run every script, verify with probe.
+
+ python3 tests/test_all.py # or: python3 -m unittest tests/test_all.py
+"""
+import json
+import os
+import shutil
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPTS = ROOT / "scripts"
+OUT = Path(os.environ.get("OUT", ROOT / "tests" / "out"))
+sys.path.insert(0, str(SCRIPTS))
+from _common import probe # noqa: E402
+
+TONES = ("0.6*sin(2*PI*440*t)*gt(sin(2*PI*0.37*t)\\,0.3)+0.4*sin(2*PI*880*t)*gt(sin(2*PI*0.53*t+1)\\,0.6)"
+ "+0.3*sin(2*PI*220*t)*gt(sin(2*PI*0.21*t+2)\\,0.7)")
+
+
+def sh(*cmd, expect_fail=False):
+ proc = subprocess.run([str(c) for c in cmd], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ if expect_fail:
+ assert proc.returncode != 0, f"expected failure but succeeded: {cmd}"
+ return proc
+ assert proc.returncode == 0, f"{cmd}\nSTDOUT:\n{proc.stdout}\nSTDERR:\n{proc.stderr}"
+ return proc
+
+
+def script(name, *args, **kw):
+ return sh(sys.executable, SCRIPTS / name, *args, **kw)
+
+
+class FFmpegSkillTests(unittest.TestCase):
+ @classmethod
+ def setUpClass(cls):
+ if not shutil.which("ffmpeg"):
+ raise unittest.SkipTest("ffmpeg not on PATH")
+ OUT.mkdir(parents=True, exist_ok=True)
+ cls.src = OUT / "source.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+ "-f", "lavfi", "-i", "testsrc2=size=1280x720:rate=30",
+ "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000",
+ "-t", "12", "-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p",
+ "-c:a", "aac", "-b:a", "128k", cls.src)
+ cls.mic = OUT / "lavmic.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "2.5", "-i", cls.src, "-vn", "-c:a", "pcm_s16le", cls.mic)
+ cls.logo = OUT / "logo.png"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "[email protected]:s=240x90,format=rgba", "-frames:v", "1", cls.logo)
+ cls.cues = OUT / "cues.txt"
+ cls.cues.write_text("0:00-0:03 Hello world\n0:03-0:06 Second | line\nAuto timed cue\n", encoding="utf-8")
+
+ def assertClose(self, a, b, tol, msg=""):
+ self.assertIsNotNone(a, msg)
+ self.assertLessEqual(abs(a - b), tol, f"{msg}: {a} vs {b} (tol {tol})")
+
+ # ---------------------------------------------------------------- probe
+ def test_probe_json_and_fields(self):
+ out = script("probe.py", self.src).stdout
+ data = json.loads(out)
+ self.assertClose(data["duration"], 12.0, 0.1)
+ self.assertEqual((data["video"]["width"], data["video"]["height"]), (1280, 720))
+ self.assertClose(data["video"]["fps"], 30.0, 0.01)
+ self.assertEqual(data["video"]["codec"], "h264")
+ self.assertEqual(data["audio"]["channels"], 1)
+ self.assertEqual(data["audio"]["sample_rate"], 48000)
+ field = script("probe.py", self.src, "--field", "video.width").stdout.strip()
+ self.assertEqual(field, "1280")
+ compact = script("probe.py", self.src, "--compact").stdout
+ self.assertIn("1280x720", compact)
+
+ def test_probe_missing_file_fails(self):
+ proc = script("probe.py", OUT / "nope.mp4", expect_fail=True)
+ self.assertIn("not found", proc.stderr)
+
+ # ---------------------------------------------------------------- cut
+ def test_cut_single_copy(self):
+ out = OUT / "cut1.mp4"
+ script("cut.py", self.src, "--start", "2", "--end", "6", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 4.0, 0.5, "lossless cut falls back to re-encode when the keyframe snap is too far")
+ self.assertEqual(m["video"]["codec"], "h264")
+
+ def test_cut_copy_never_reencodes_when_tolerance_disabled(self):
+ out = OUT / "cut3.mp4"
+ proc = script("cut.py", self.src, "--start", "2", "--end", "6", "--tolerance", "-1", "-o", out)
+ self.assertIn("lossless stream copy", proc.stderr)
+
+ def test_cut_segments_accurate(self):
+ out = OUT / "cut2.mp4"
+ script("cut.py", self.src, "--segments", "1-3,6-9", "--accurate", "-o", out)
+ self.assertClose(probe(str(out))["duration"], 5.0, 0.15)
+
+ def test_cut_bad_range_fails(self):
+ script("cut.py", self.src, "--start", "5", "--end", "2", expect_fail=True)
+
+ # ---------------------------------------------------------------- fit
+ def test_fit_duration_speed_and_aspect_pad(self):
+ out = OUT / "fit1.mp4"
+ script("fit.py", self.src, "--duration", "6", "--aspect", "9:16", "--fit", "pad", "--width", "540", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 6.0, 0.15)
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (540, 960))
+
+ def test_fit_trim_and_crop_square(self):
+ out = OUT / "fit2.mp4"
+ script("fit.py", self.src, "--duration", "4", "--method", "trim", "--from-center", "--aspect", "1:1", "--fit", "crop", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 4.0, 0.15)
+ self.assertEqual(m["video"]["width"], m["video"]["height"])
+
+ def test_fit_refuses_extreme_speed(self):
+ script("fit.py", self.src, "--duration", "1", expect_fail=True)
+
+ # ---------------------------------------------------------------- caption
+ def test_caption_text_to_srt_and_burn(self):
+ srt = OUT / "cues.srt"
+ out = OUT / "cap.mp4"
+ script("caption.py", self.src, "--text", self.cues, "--write-srt", srt, "--position", "top", "--bold", "-o", out)
+ text = srt.read_text(encoding="utf-8")
+ self.assertIn("00:00:03,000 --> 00:00:06,000", text)
+ self.assertIn("Second\nline", text)
+ self.assertIn("00:00:06,000 --> 00:00:09,000", text, "auto-timed cue follows previous")
+ m = probe(str(out))
+ self.assertClose(m["duration"], 12.0, 0.15)
+ self.assertEqual(m["video"]["width"], 1280)
+
+ def test_caption_srt_only(self):
+ srt = OUT / "only.srt"
+ proc = script("caption.py", "--text", self.cues, "--write-srt", srt)
+ self.assertTrue(srt.exists())
+ self.assertEqual(proc.stdout.strip(), str(srt))
+
+ # ---------------------------------------------------------------- overlay
+ def test_overlay_image_and_text(self):
+ out1 = OUT / "ov_img.mp4"
+ script("overlay.py", self.src, "--image", self.logo, "--position", "top-right", "--scale", "200",
+ "--opacity", "0.8", "--start", "1", "--end", "5", "--fade", "0.5", "-o", out1)
+ m = probe(str(out1))
+ self.assertClose(m["duration"], 12.0, 0.2)
+ self.assertIsNotNone(m["audio"], "audio must be kept")
+ out2 = OUT / "ov_txt.mp4"
+ script("overlay.py", self.src, "--text", "Episode 12", "--position", "bottom", "--box", "--start", "1", "--end", "5", "--fade", "0.3", "-o", out2)
+ self.assertClose(probe(str(out2))["duration"], 12.0, 0.15)
+
+ # ---------------------------------------------------------------- sync
+ def test_sync_detects_offset_and_replaces_audio(self):
+ proc = script("sync.py", self.src, self.mic, "--json")
+ data = json.loads(proc.stdout)
+ self.assertClose(data["offset_seconds"], 2.5, 0.05, "lav mic started 2.5 s later")
+ self.assertGreater(data["confidence"], 0.5)
+ out = OUT / "synced.mp4"
+ script("sync.py", self.src, self.mic, "--replace-audio", "-o", out)
+ again = json.loads(script("sync.py", self.src, out, "--json").stdout)
+ self.assertClose(again["offset_seconds"], 0.0, 0.05, "aligned output has no residual offset")
+
+ def test_sync_negative_offset_trim_second(self):
+ early = OUT / "early.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "aevalsrc=0:s=48000:d=1.5",
+ "-i", self.src, "-filter_complex", "[0:a][1:a]concat=n=2:v=0:a=1", early)
+ data = json.loads(script("sync.py", self.src, early, "--json").stdout)
+ self.assertClose(data["offset_seconds"], -1.5, 0.05)
+ out = OUT / "early_synced.wav"
+ script("sync.py", self.src, early, "--trim-second", "-o", out)
+ self.assertEqual(probe(str(out))["audio"]["codec"], "pcm_s16le")
+ again = json.loads(script("sync.py", self.src, out, "--json").stdout)
+ self.assertClose(again["offset_seconds"], 0.0, 0.05)
+
+ # ---------------------------------------------------------------- loudness
+ def test_loudness_two_pass(self):
+ out = OUT / "loud.mp4"
+ script("loudness.py", self.src, "-I", "-16", "--tp", "-1.5", "-o", out)
+ stats = json.loads(script("loudness.py", out, "--measure-only", "-I", "-16", "--tp", "-1.5").stdout)
+ self.assertClose(float(stats["input_i"]), -16.0, 1.0, "integrated loudness")
+ self.assertLessEqual(float(stats["input_tp"]), -1.0, "true peak ceiling")
+ self.assertEqual(probe(str(out))["video"]["codec"], "h264", "video stream copied")
+
+ # ---------------------------------------------------------------- export
+ def test_export_presets(self):
+ cases = {
+ "youtube": ("mp4", "h264", (1920, 1080)),
+ "reels": ("mp4", "h264", (1080, 1920)),
+ "x": ("mp4", "h264", (1280, 720)),
+ "prores": ("mov", "prores", (1280, 720)),
+ "h265": ("mp4", "hevc", (1280, 720)),
+ }
+ for preset, (ext, codec, size) in cases.items():
+ with self.subTest(preset=preset):
+ out = OUT / f"export_{preset}.{ext}"
+ script("export.py", self.src, "--preset", preset, "-o", out)
+ m = probe(str(out))
+ self.assertEqual(m["video"]["codec"], codec)
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), size)
+ self.assertClose(m["duration"], 12.0, 0.2)
+ if preset in ("youtube", "reels", "x", "h265"):
+ self.assertEqual(m["video"]["color_space"], "bt709")
+
+ def test_export_list(self):
+ self.assertIn("youtube", script("export.py", "--list").stdout)
+
+ # ---------------------------------------------------------------- help
+ def test_every_script_has_help(self):
+ for name in sorted(p.name for p in SCRIPTS.glob("*.py") if not p.name.startswith("_")):
+ with self.subTest(script=name):
+ out = script(name, "--help").stdout
+ self.assertIn("usage:", out)
+
+
+if __name__ == "__main__":
+ unittest.main(verbosity=2)