ffmpeg-skill 0.1.0

package/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.

package/README.md

@@ -0,0 +1,111 @@
+# ffmpeg-skill
+
+**Give your coding agent a video editor.** Local FFmpeg, Python standard library, nothing else.
+
+![before / after demo](assets/demo.gif)
+
+```bash
+npx ffmpeg-skill
+```
+
+`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any other agent that reads `SKILL.md`. It teaches the agent a fixed editing workflow (probe → edit losslessly where possible → verify) and ships eight small CLI scripts that do the actual work with `ffmpeg`/`ffprobe`. Think of it as the fully local FFmpeg counterpart to cloud video-agent tools such as browser-use/video-use.
+
+**No API keys. No cloud. No dependencies.** If `ffmpeg` and `python3` are on your PATH, it works — offline, on any footage you'd rather not upload.
+
+## Features
+
+- **Probe first, verify last** — the skill forces the agent to read real duration/fps/resolution before editing and to check the result after, so you get "final.mp4: 59.98 s, 1080×1920, 30 fps" instead of guesses.
+- **Lossless when possible** — cuts and joins use stream copy by default; re-encoding only happens when it must (frame-accurate cuts, filters, format changes).
+- **Cut & join** segments with `mm:ss` / `hh:mm:ss.ms` times.
+- **Captions** — burn SRT/ASS with font, size, colour, outline and position control; generate SRT from a plain timed-text file.
+- **Fit** to an exact duration (pitch-preserving speed change or trim) and to 16:9 / 9:16 / 1:1 / 4:5 by padding or cropping.
+- **Multicam / external-audio sync** — offset detection by cross-correlation implemented in pure Python (no numpy).
+- **Loudness** — two-pass EBU R128 normalisation to −14 LUFS (or any target) with true-peak ceiling.
+- **Overlays** — logos, watermarks and titles with position, time range, opacity and fades.
+- **Export presets** — YouTube, Instagram Reels/Shorts/TikTok, X, ProRes 422 HQ master, H.265, GIF — all tagged BT.709.
+- **Agent-friendly CLI** — every script has `--help`, prints the output path on stdout, exits non-zero with a reason on stderr, and names outputs `<input>_<operation>.<ext>` by default.
+
+## Install
+
+```bash
+# Claude Code (default) → ~/.claude/skills/ffmpeg-skill
+npx ffmpeg-skill
+
+# Cursor → ~/.cursor/skills/ffmpeg-skill
+npx ffmpeg-skill --cursor
+
+# Codex → ~/.codex/skills/ffmpeg-skill
+npx ffmpeg-skill --codex
+
+# everything, or a project-local copy, or a custom directory
+npx ffmpeg-skill --all
+npx ffmpeg-skill --project
+npx ffmpeg-skill --dir ./my-skills
+```
+
+Or without Node: clone this repo and copy `SKILL.md` and `scripts/` into your agent's skills directory.
+
+You also need FFmpeg:
+
+| OS | Command |
+|----|---------|
+| macOS | `brew install ffmpeg` |
+| Ubuntu / Debian | `sudo apt install ffmpeg` |
+| Windows | `winget install Gyan.FFmpeg` |
+
+## Usage
+
+Once installed, just talk to your agent. Five things you can say to Claude Code:
+
+1. **"Take `interview.mp4`, keep 0:45–3:10 and 5:00–6:30, and make it exactly 60 seconds for Reels."**
+   → `probe.py` → `cut.py --segments 0:45-3:10,5:00-6:30` → `fit.py --duration 60 --aspect 9:16 --fit crop` → `export.py --preset reels` → `probe.py` to confirm 60.0 s at 1080×1920.
+2. **"Burn these captions in, white text with a black outline at the top, in Japanese."**
+   → `caption.py --text cues.txt --font "Noto Sans CJK JP" --position top --outline 3`.
+3. **"The lav mic recording is out of sync with the camera — fix it and normalise to −14 LUFS."**
+   → `sync.py camera.mp4 lav.wav --replace-audio` → `loudness.py` → report the detected offset and final LUFS.
+4. **"Put our logo in the top-right corner for the whole video at 80% opacity, and a title card for the first 4 seconds."**
+   → `overlay.py --image logo.png --position top-right --scale 220 --opacity 0.8` → `overlay.py --text "…" --start 0 --end 4 --fade 0.4`.
+5. **"Give me a ProRes master and an H.265 copy of the final cut."**
+   → `export.py --preset prores` and `export.py --preset h265`.
+
+The scripts also work on their own:
+
+```bash
+python3 ~/.claude/skills/ffmpeg-skill/scripts/probe.py input.mp4 --compact
+python3 ~/.claude/skills/ffmpeg-skill/scripts/fit.py input.mp4 --duration 60 --aspect 9:16
+```
+
+More examples: [examples/README.md](examples/README.md). To see everything run end-to-end on generated footage: `bash examples/make_demo.sh`.
+
+## Scripts
+
+| Script | What it does |
+|--------|--------------|
+| `probe.py` | Duration, fps (+ VFR detection), resolution, codecs, colour space, audio channels as JSON |
+| `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact |
+| `caption.py` | Burn SRT/ASS (font, size, colour, outline, position); build SRT from timed plain text |
+| `fit.py` | Fit to a duration (speed or trim) and/or aspect ratio (pad or crop), force constant fps |
+| `sync.py` | Detect offset between two recordings by audio cross-correlation; output aligned video/audio |
+| `loudness.py` | Two-pass EBU R128 `loudnorm` to −14 LUFS / −1 dBTP (or custom), video stream-copied |
+| `overlay.py` | Composite image/logo or drawtext title with position, time range, opacity, fade |
+| `export.py` | Presets: `youtube`, `youtube4k`, `reels`, `x`, `prores`, `h265`, `gif` |
+
+All scripts: Python 3.9+, standard library only, `--help`, non-zero exit + stderr message on failure.
+
+## Requirements
+
+- FFmpeg 5.0+ with `libx264`, `libx265`, `libass` and `prores_ks` (the default builds from Homebrew, apt and gyan.dev include all of them)
+- Python 3.9+
+- Node 16+ only for the `npx` installer
+
+## Development
+
+```bash
+bash examples/make_demo.sh      # generates footage, runs every script, rebuilds assets/demo.gif
+python3 tests/test_all.py       # end-to-end tests (needs ffmpeg)
+node bin/install.js --dir /tmp/skills   # try the installer without touching ~/.claude
+```
+
+## License
+
+[MIT](LICENSE)

package/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.

package/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);

package/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"
+  }
+}