ffmpeg-skill 1.2.0 → 1.3.0

package/README.md

@@ -26,7 +26,7 @@ npx ffmpeg-skill
 
 ![before / after demo](assets/demo.gif)
 
-`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships **40 tools** that do the actual work with `ffmpeg` / `ffprobe`: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also an MCP tool, and the whole set is described by a machine-readable contract.
+`ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships **41 tools** that do the actual work with `ffmpeg` / `ffprobe`: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also an MCP tool, and the whole set is described by a machine-readable contract.
 
 If `ffmpeg` and `python3` are on your PATH, it works: offline, on footage you would rather not upload.
 
@@ -140,7 +140,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 1. **Probe first.** No tool decides from the file name. `probe.py` measures duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth, HDR format including Dolby Vision, colour tags and every audio stream before anything is cut.
 2. **Lossless when possible.** `cut.py`, `join.py` and `loudness.py` stream-copy what they do not need to touch. Re-encoding happens only when it must: frame-accurate cuts, filters, format changes, or a keyframe farther than the tolerance.
 3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress` (percent and ETA). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
-4. **Machine-readable contract.** `contract --json` describes all 40 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 40 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
+4. **Machine-readable contract.** `contract --json` describes all 41 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 40 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
 5. **Contract-derived MCP.** `mcp/server.py` builds its `tools/list` from the contract. Tool names, order and `inputSchema` cannot drift from the scripts; a test keeps the two byte-identical.
 6. **Capability detection.** `doctor` reads `ffmpeg -encoders / -filters / -bsfs` and reports which of the components the tools need are present on this build (libx264, libass, zscale, loudnorm, xfade, …), before a job fails inside ffmpeg.
 7. **Unknown is not missing.** When a listing cannot be read (a layout the parser does not know, ffmpeg exiting non-zero) the affected capabilities are `unknown`: never `missing`, never silently `available`. An installed filter is not reported absent; a failed detection is not a pass.
@@ -149,7 +149,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 
 ## Tools
 
-40 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.
+41 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.
 
 **Analysis and inspection**
 
@@ -184,6 +184,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 | `pad.py` | Add black/silent padding at the start and/or end of the timeline (`--start`, `--end`) — distinct from `fit.py --fit pad`'s per-frame letterbox bars |
 | `speedramp.py` | Step through different constant speeds across a clip via `--segment START-END:FACTOR` (repeatable) — distinct from `fit.py`'s single whole-clip speed factor |
 | `loop.py` | Repeat a clip `--times` N or to a target `--duration` — for background loops and filling a fixed slot length |
+| `metadata.py` | Write container chapter markers from a `TIME TITLE` text file and title/artist/comment tags, every stream copied bit for bit |
 | `grid.py` | Composite `--cols`x`--rows` clips into one grid, each cell letterboxed and labelled with its filename by default (`--label none` to skip) |
 
 **Audio**
@@ -272,7 +273,7 @@ npx ffmpeg-skill contract --json            # or: python3 scripts/_contract.py -
 npx ffmpeg-skill contract --json --static   # without environment detection
 ```
 
-The contract is generated from the code that runs, not maintained beside it. For each of the 40 tools (`ffmpeg-skill/<name>`) it states:
+The contract is generated from the code that runs, not maintained beside it. For each of the 41 tools (`ffmpeg-skill/<name>`) it states:
 
 | Field | Meaning |
 |---|---|

package/SKILL.md

@@ -118,7 +118,7 @@ This skill cuts, joins, measures, syncs, exports and checks files — it execute
 
 The line in general: if the same input and the same explicit parameters always produce the same, verifiable output, it belongs here. If the "right" answer depends on taste, content understanding, or what looks or sounds good, it belongs to whichever skill or agent makes that judgement — this skill only ever executes parameters it's given, never infers them from what something looks or sounds like.
 
-If a request needs an FFmpeg feature none of the 40 scripts expose, say so and name the closest built-in option (`--dry-run` to show what would run, or a documented limitation) — never fall back to guessing a raw `ffmpeg`/`ffprobe` invocation or a hand-built filter graph outside `scripts/*.py`. A raw command bypasses every guarantee this skill makes (no shell, typed arguments, verification afterwards); it is exactly the failure mode this skill exists to prevent, so it is never the fallback when a script's flag doesn't cover something.
+If a request needs an FFmpeg feature none of the 41 scripts expose, say so and name the closest built-in option (`--dry-run` to show what would run, or a documented limitation) — never fall back to guessing a raw `ffmpeg`/`ffprobe` invocation or a hand-built filter graph outside `scripts/*.py`. A raw command bypasses every guarantee this skill makes (no shell, typed arguments, verification afterwards); it is exactly the failure mode this skill exists to prevent, so it is never the fallback when a script's flag doesn't cover something.
 
 ## Request → script
 
@@ -149,6 +149,8 @@ If a request needs an FFmpeg feature none of the 40 scripts expose, say so and n
 | "add some black at the start before the title card" | `pad.py clip.mp4 --start 1.5` |
 | "speed up here, slam into slow-mo there, then speed back up" (known segments) | `speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0` |
 | "loop this background clip to fill 30 seconds" | `loop.py bg_loop.mp4 --duration 30` |
+| "add chapters at 0:00 Intro, 2:15 Setup, …", "chapter markers for YouTube" | `metadata.py episode.mp4 --chapters chapters.txt` (one `TIME TITLE` per line; streams are copied, nothing re-encodes) |
+| "set the title / artist / comment on the file" | `metadata.py episode.mp4 --title "Episode 12" --artist "Studio"` |
 | "put these videos in a 4x2 grid with the filename on each" | `grid.py t1.mp4 t2.mp4 t3.mp4 t4.mp4 t5.mp4 t6.mp4 t7.mp4 t8.mp4 --cols 4 --rows 2` |
 | "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` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.2.0",
-  "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 40 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
+  "version": "1.3.0",
+  "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 41 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",
     "video",

package/references/scripts.md

@@ -287,6 +287,22 @@ loop point (no crossfade at the seam) -- a clip that doesn't already loop
 cleanly will show a visible cut/pop at each repeat, which is a property of
 the source material this tool cannot fix.
 
+### metadata.py — chapter markers and container tags, streams copied
+```
+metadata.py INPUT [--chapters chapters.txt | --clear-chapters]
+                  [--title T] [--artist A] [--album A] [--comment C] [--date D] [--genre G] [-o OUT]
+```
+`chapters.txt` holds one chapter per line, `TIME TITLE` (cut.py's time syntax:
+seconds, mm:ss, hh:mm:ss.ms); each chapter ends where the next starts and the
+last runs to the end of the file. Starts must ascend and lie inside the file.
+Every stream is `-c copy` (bit for bit; `probe` reports the result under
+`chapters` and `tags`), so this is instant and lossless. Chapter markers need a
+container that can hold them (.mp4/.m4v/.m4a/.mov, .mkv/.mka/.webm); `.wav`,
+`.gif`, `.mp3` and `.flac` outputs are refused for `--chapters` rather than
+silently dropping them. Tags alone are written to any container that has them.
+`--clear-chapters` removes existing markers; an empty tag value (`--comment ""`)
+clears that tag.
+
 ### grid.py — composite clips into a grid
 ```
 grid.py CLIP1 CLIP2 [...] --cols N --rows N [--cell-width W] [--cell-height H]

package/scripts/_common.py

@@ -468,7 +468,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         die(f"input not found: {path}")
     ffprobe = require_tool("ffprobe")
     proc = run(
-        [ffprobe, "-v", "error", "-print_format", "json", "-show_format", "-show_streams", path],
+        [ffprobe, "-v", "error", "-print_format", "json", "-show_format", "-show_streams", "-show_chapters", path],
         quiet=True,
         check=False,
     )
@@ -502,6 +502,15 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         "audio": None,
         "subtitle_streams": len(subs),
         "data_streams": data_stream_count,
+        # container-level chapter markers and the common tags, so metadata.py's result is
+        # verifiable the same way every other tool's is (additive keys, 1.x-safe)
+        "chapters": [{
+            "index": n,
+            "start": _to_float(ch.get("start_time")),
+            "end": _to_float(ch.get("end_time")),
+            "title": (ch.get("tags") or {}).get("title"),
+        } for n, ch in enumerate(raw.get("chapters") or [])],
+        "tags": {k.lower(): v for k, v in (fmt.get("tags") or {}).items() if k.lower() in ("title", "artist", "album", "comment", "date", "genre")},
         # every subtitle stream in file order: index n here is `-map 0:s:n`
         "subtitle_stream_details": [{
             "index": n,

package/scripts/_contract.py

@@ -113,6 +113,9 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "speedramp": dict(role="execution", inputs=["video asset"], outputs=["video artifact with a stepped speed ramp applied across segments"],
                       required=FF + [X264, AAC], optional=[HDR_X265],
                       video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+    "metadata": dict(role="execution", inputs=["video or audio asset", "chapters text file (--chapters)"], outputs=["the same streams, stream-copied, with chapter markers and/or title/artist/comment tags written"],
+                     required=FF, optional=[],
+                     video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="bit_exact", deterministic=True),
     "loop": dict(role="execution", inputs=["video asset"], outputs=["video artifact repeated to the requested count or duration"],
                  required=FF + [X264, AAC], optional=[],
                  video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
@@ -240,6 +243,7 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
     "freeze":   dict(video="always", audio="always", note="the tpad/concat filter graph always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
     "pad":      dict(video="always", audio="always", note="the tpad filter always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
     "speedramp": dict(video="always", audio="always", note="setpts/atempo per segment always forces a re-encode of both streams"),
+    "metadata": dict(video="never", audio="never", note="-c copy on every stream; only the container's chapters and tags change"),
     "loop":     dict(video="always", audio="always", note="-stream_loop always re-encodes both streams; the audio codec is always AAC when present"),
     "insert":    dict(video="always", audio="never", note="always encodes a fresh silent clip from the still image; there is no audio stream to touch"),
     "background": dict(video="always", audio="never", note="always encodes a fresh generated clip; there is no input to copy from"),

package/scripts/metadata.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Write container chapters and title/artist/comment tags without touching the streams.
+
+Chapter markers are what YouTube, VLC, Apple Podcasts and MKV players show as a
+seekable list; graphics.py --template chapter burns a *card* into the picture, this
+writes the *metadata*. Every stream is copied bit for bit (-c copy): the only thing
+that changes is the container's metadata, so this is instant and lossless.
+
+Chapters come from a text file, one per line, `TIME TITLE` with the same time syntax
+as cut.py (seconds, mm:ss, hh:mm:ss.ms). Each chapter ends where the next starts; the
+last one ends at the file's duration. Containers with no chapter support (.wav, .gif,
+.mp3, .flac) are refused for --chapters rather than silently dropping them; tags alone
+are written wherever the container can hold them.
+
+Examples:
+  python3 metadata.py episode.mp4 --chapters chapters.txt
+  python3 metadata.py episode.mp4 --title "Episode 12" --artist "Studio" --comment "final cut"
+  python3 metadata.py master.mkv --chapters chapters.txt --title "Master" -o master_tagged.mkv
+  python3 metadata.py episode.mp4 --clear-chapters
+
+chapters.txt:
+  0:00 Intro
+  2:15 Setup
+  1:03:00 Outro
+"""
+import argparse
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run, STATE
+
+CHAPTER_CONTAINERS = {".mp4", ".m4v", ".m4a", ".mov", ".mkv", ".mka", ".webm"}
+TAG_KEYS = ("title", "artist", "album", "comment", "date", "genre")
+
+
+def parse_chapters(path: str, duration: float) -> List[Dict[str, Any]]:
+    """`TIME TITLE` per line -> [{"start", "end", "title"}], validated: ascending starts, every
+    start inside the file, the last chapter running to the file's end."""
+    text = Path(path).read_text(encoding="utf-8")
+    entries: List[Dict[str, Any]] = []
+    for n, raw in enumerate(text.splitlines(), start=1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split(None, 1)
+        try:
+            start = parse_time(parts[0])
+        except ValueError:
+            die(f"{path}:{n}: cannot read the time in {line!r} (use seconds, mm:ss or hh:mm:ss.ms)")
+        title = parts[1].strip() if len(parts) > 1 else f"Chapter {len(entries) + 1}"
+        if entries and start <= entries[-1]["start"]:
+            die(f"{path}:{n}: chapter at {start:g}s does not come after the previous one at {entries[-1]['start']:g}s")
+        if duration and start >= duration:
+            die(f"{path}:{n}: chapter at {start:g}s starts at or after the end of the file ({duration:.3f}s)")
+        entries.append({"start": start, "title": title})
+    if not entries:
+        die(f"{path}: no chapters found (one per line: `0:00 Intro`)")
+    for i, e in enumerate(entries):
+        e["end"] = entries[i + 1]["start"] if i + 1 < len(entries) else duration
+    return entries
+
+
+def _ffmeta_escape(value: str) -> str:
+    # ffmetadata: backslash escapes =, ;, #, \ and newline
+    out = []
+    for ch in value:
+        if ch in "=;#\\":
+            out.append("\\" + ch)
+        elif ch == "\n":
+            out.append("\\\n")
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
+def write_ffmetadata(chapters: List[Dict[str, Any]], path: str) -> None:
+    lines = [";FFMETADATA1"]
+    for c in chapters:
+        lines += ["[CHAPTER]", "TIMEBASE=1/1000", f"START={int(round(c['start'] * 1000))}",
+                  f"END={int(round(c['end'] * 1000))}", f"title={_ffmeta_escape(c['title'])}"]
+    Path(path).write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+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>_meta.<ext>)")
+    ap.add_argument("--chapters", help="text file, one chapter per line: `TIME TITLE` (cut.py time syntax)")
+    ap.add_argument("--clear-chapters", action="store_true", help="remove every chapter marker the input carries")
+    for key in TAG_KEYS:
+        ap.add_argument(f"--{key}", help=f"set the container's {key} tag (empty string clears it)")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if args.chapters and args.clear_chapters:
+        die("--chapters and --clear-chapters exclude each other")
+    tags = {k: getattr(args, k) for k in TAG_KEYS if getattr(args, k) is not None}
+    if not args.chapters and not args.clear_chapters and not tags:
+        die("nothing to write: give --chapters FILE, --clear-chapters and/or --title/--artist/...")
+    if args.chapters and not os.path.exists(args.chapters):
+        die(f"chapters file not found: {args.chapters}")
+
+    meta = probe(args.input)
+    output = args.output or default_output(args.input, "meta")
+    if os.path.abspath(output) == os.path.abspath(args.input):
+        die("output must differ from the input (metadata.py never rewrites a file in place)")
+    out_ext = Path(output).suffix.lower()
+    if (args.chapters or args.clear_chapters) and out_ext not in CHAPTER_CONTAINERS:
+        die(f"{out_ext or 'this'} container cannot hold chapter markers; write to one of "
+            f"{', '.join(sorted(CHAPTER_CONTAINERS))} (the streams are copied, so choose the matching family: .mp4/.mov/.m4a for MPEG-4, .mkv/.mka/.webm for Matroska)")
+
+    duration = meta.get("duration") or 0.0
+    chapters: Optional[List[Dict[str, Any]]] = parse_chapters(args.chapters, duration) if args.chapters else None
+
+    cmd = ffmpeg_base() + ["-i", args.input]
+    tmpdir = None
+    if chapters:
+        tmpdir = tempfile.TemporaryDirectory(prefix="ffskill_meta_")
+        ffmeta = os.path.join(tmpdir.name, "chapters.ffmeta")
+        write_ffmetadata(chapters, ffmeta)
+        cmd += ["-i", ffmeta, "-map", "0", "-map_metadata", "0", "-map_chapters", "1"]
+    elif args.clear_chapters:
+        cmd += ["-map", "0", "-map_metadata", "0", "-map_chapters", "-1"]
+    else:
+        cmd += ["-map", "0", "-map_metadata", "0", "-map_chapters", "0"]
+    for key, value in tags.items():
+        cmd += ["-metadata", f"{key}={value}"]
+    cmd += ["-c", "copy", output]
+    run(cmd)
+    if tmpdir:
+        tmpdir.cleanup()
+
+    result = probe(output, role="output")
+    written = result.get("chapters") or []
+    if chapters is not None and not STATE["dry_run"] and len(written) != len(chapters):
+        die(f"wrote {len(written)} chapters but {len(chapters)} were asked for", kind="output")
+    if args.clear_chapters and not STATE["dry_run"] and written:
+        die(f"{len(written)} chapters survived --clear-chapters", kind="output")
+    info(f"wrote {output} ({len(written)} chapters, tags: {', '.join(sorted(tags)) or 'unchanged'}, streams copied)")
+    emit(output, chapters=written, tags=result.get("tags") or {}, streams_copied=True)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())