Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
Add ffmpeg-skill: local FFmpeg video-editing Agent Skill (#1)
kajisho5ea9adb32df4b
diff --git a/.gitignore b/.gitignorenew file mode 100644index 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/LICENSEnew file mode 100644index 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.mdindex 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.++++```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.mdnew file mode 100644index 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.gifnew file mode 100644index 0000000..d0b6de3Binary files /dev/null and b/assets/demo.gif differdiff --git a/bin/install.js b/bin/install.jsnew file mode 100755index 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.mdnew file mode 100644index 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.shnew file mode 100755index 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.jsonnew file mode 100644index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100755index 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.pynew file mode 100644index 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)