ffmpeg-skill 1.1.1 → 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
 
@@ -128,7 +128,7 @@ If a request needs an FFmpeg feature none of the 40 scripts expose, say so and n
 | "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`) |
+| "make it vertical / for TikTok / 9:16", "square for Instagram" | `fit.py input.mp4 --aspect 9:16 --fit pad` (or `--fit crop`); add `--pad-fill blur` for the blurred-background bars phone editors produce |
 | "resize to a specific height, width follows" | `fit.py input.mp4 --height 1080` (or `--width`, or both for an exact frame) |
 | "crop to this exact box/rectangle" (known x/y/width/height, not an aspect ratio) | `crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920` |
 | "are there black bars on this?", "what's the crop rectangle to remove the letterboxing" | `cropdetect.py input.mp4` |
@@ -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.1.1",
-  "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

@@ -58,7 +58,7 @@ the result was "lossless stream copy" or "re-encoded".
 ### fit.py — target duration and/or aspect, rotate/flip
 ```
 fit.py INPUT [--duration T --method speed|trim [--from-center] [--max-speed 4]]
-             [--aspect 16:9|9:16|1:1|4:5|W:H --fit pad|crop [--width W] [--height H] [--pad-color black]]
+             [--aspect 16:9|9:16|1:1|4:5|W:H --fit pad|crop [--width W] [--height H] [--pad-color black] [--pad-fill color|blur [--pad-blur 20]]]
              [--rotate 90|180|270] [--flip h|v] [--fps N] [-o OUT]
 ```
 `speed` retimes video and audio together (pitch-preserving `atempo`); it
@@ -73,6 +73,10 @@ is separate from the rotation *metadata* fit.py already reads to size a
 source correctly); `--flip h|v` mirrors the picture; both can combine, rotate
 first. `--fps` forces a constant frame rate; VFR sources are conformed
 automatically even without it.
+`--pad-fill blur` fills the letterbox/pillarbox bars with a blurred, scaled-to-cover copy
+of the frame (the look every phone editor gives landscape footage posted as a Short/Reel)
+instead of the solid `--pad-color`; `--pad-blur` is the blur radius. `export.py --fit pad`
+takes the same two flags.
 
 ### crop.py — crop to an exact pixel rectangle
 ```
@@ -283,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

@@ -9,6 +9,7 @@ from __future__ import annotations
 import json
 import os
 import platform
+import argparse
 import re
 import shutil
 import subprocess
@@ -106,6 +107,31 @@ def drawtext_boxborderw(vertical: int, horizontal: int) -> str:
     return str(max(vertical, horizontal))
 
 
+def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int) -> str:
+    """The letterbox/pillarbox step shared by fit.py and export.py, as one -vf segment.
+
+    fill="color": scale to fit, then pad with a solid colour (the historical behaviour).
+    fill="blur": the bars are a blurred, scaled-to-cover copy of the same frame -- what every
+    phone editor's "make it vertical" does with landscape footage (#139). Built as a small
+    graph inside the -vf chain: split, one branch scaled to cover and cropped to the frame
+    then boxblur'ed, the other scaled to fit, overlaid centred. Only `filter:boxblur` is
+    needed beyond the usual scale/pad set, and that is already required by redact.py."""
+    if fill == "blur":
+        radius = max(1, int(blur))
+        return (f"split[__fitfg][__fitbg];"
+                f"[__fitbg]scale={out_w}:{out_h}:force_original_aspect_ratio=increase,crop={out_w}:{out_h},"
+                f"boxblur={radius}:2[__fitbgb];"
+                f"[__fitfg]scale={out_w}:{out_h}:force_original_aspect_ratio=decrease[__fitfgs];"
+                f"[__fitbgb][__fitfgs]overlay=(W-w)/2:(H-h)/2:format=auto")
+    return f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease,pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={color}"
+
+
+def add_pad_fill_args(parser: "argparse.ArgumentParser") -> None:
+    parser.add_argument("--pad-fill", choices=["color", "blur"], default="color",
+                        help="what fills the letterbox/pillarbox bars under --fit pad: a solid --pad-color (default) or a blurred, scaled-up copy of the frame")
+    parser.add_argument("--pad-blur", type=int, default=20, help="blur radius in pixels for --pad-fill blur (default 20)")
+
+
 def die(msg: str, code: int = 1, kind: str = "input") -> "None":
     """Exit with a message. Under --json also print a machine-readable failure document
     (status: failed) on stdout so callers get the same shape as a success; exit codes are unchanged."""
@@ -442,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,
     )
@@ -476,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

@@ -74,7 +74,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                 required=FF, optional=[{"capability": X264, "when": "re-encode: --accurate, VFR source, or a keyframe farther than --tolerance"}, HDR_X265, {"capability": AAC, "when": "re-encode of a video container"}] + AUDIO_OUT,
                 video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "fit": dict(role="execution", inputs=["video asset"], outputs=["video artifact at the requested duration / aspect / fps"],
-                required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:minterpolate", "when": "--smooth interpolate"}],
+                required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:minterpolate", "when": "--smooth interpolate"},
+                                                     {"capability": "filter:boxblur", "when": "--pad-fill blur"}],
                 video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "crop": dict(role="execution", inputs=["video asset"], outputs=["video artifact cropped to the given pixel rectangle"],
                  required=FF + [X264, AAC], optional=[HDR_X265],
@@ -112,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),
@@ -174,7 +178,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "export": dict(role="execution", inputs=["video asset"], outputs=["delivery artifact in the preset's format"],
                    required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "preset youtube / youtube4k / reels / x / h265 (prores uses pcm_s16le, copy stream-copies, gif has no audio)"},
                                           {"capability": X265, "when": "preset h265"}, {"capability": "encoder:prores_ks", "when": "preset prores"},
-                                          {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}],
+                                          {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}, {"capability": "filter:boxblur", "when": "--pad-fill blur"}],
                    video_required=True, audio_only=False, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "check": dict(role="verification", inputs=["media artifact"], outputs=["compliance rows JSON on stdout (no file)"],
                   required=["ffprobe"], optional=[{"capability": "ffmpeg", "when": "loudness rows (default)"}, {"capability": "filter:loudnorm", "when": "loudness rows (default)"}],
@@ -239,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/export.py

@@ -26,8 +26,7 @@ import sys
 from pathlib import Path
 from typing import Dict, List
 
-from _common import STATE, add_common, apply_common, bt709_tag_args, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_color
-
+from _common import STATE, add_common, apply_common, bt709_tag_args, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_color, pad_filters, add_pad_fill_args
 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"},
@@ -48,6 +47,7 @@ def main() -> int:
     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")
+    add_pad_fill_args(ap)
     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")
@@ -80,7 +80,7 @@ def main() -> int:
             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(pad_filters(p["w"], p["h"], args.pad_fill, args.pad_color, args.pad_blur))
             vf.append("setsar=1")
         else:
             vf.append(f"scale={p['w']}:-2")

package/scripts/fit.py

@@ -4,7 +4,7 @@
 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.
+--fit pad (letterbox/pillarbox with --pad-color, default black, or --pad-fill blur\nfor a blurred copy of the frame behind the picture) or --fit crop.
 --width and/or --height set the output size: give one and the other follows
 the aspect (source aspect if --aspect is not also given); give both for an
 exact frame. --rotate 90|180|270 (clockwise) and --flip h|v apply a new
@@ -24,6 +24,7 @@ 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 9:16 --fit pad --pad-fill blur   # the phone-editor look: blurred frame behind the bars
   python3 fit.py input.mp4 --aspect 1:1 --fit crop --duration 15
   python3 fit.py input.mp4 --aspect 9:16 --fit crop --crop-x 1   # keep the right edge (e.g. product held stage-right)
   python3 fit.py input.mp4 --height 1080                         # width follows the source aspect
@@ -37,8 +38,7 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args
-
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_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)}
 
 
@@ -93,6 +93,7 @@ def main() -> int:
     a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect); with --height also given, both are used directly")
     a.add_argument("--height", type=int, help="output height in px (default: keep source height or the height implied by the aspect); with --width also given, both are used directly")
     a.add_argument("--pad-color", default="black", help="pad colour, e.g. black, white, 0x101010 (default black)")
+    add_pad_fill_args(a)
     a.add_argument("--crop-x", type=float, default=0.5, help="with --fit crop, horizontal anchor 0=left, 0.5=centre (default), 1=right")
     a.add_argument("--crop-y", type=float, default=0.5, help="with --fit crop, vertical anchor 0=top, 0.5=centre (default), 1=bottom")
     r = ap.add_argument_group("rotate / flip")
@@ -115,6 +116,8 @@ def main() -> int:
     if not 0.0 <= args.crop_y <= 1.0:
         die(f"--crop-y must be 0..1, got {args.crop_y}")
     validate_color(args.pad_color, "--pad-color")
+    if args.pad_blur <= 0:
+        die(f"--pad-blur must be > 0, got {args.pad_blur}")
 
     meta = probe(args.input)
     if not meta.get("video"):
@@ -212,8 +215,7 @@ def main() -> int:
             vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase")
             vf.append(f"crop={out_w}:{out_h}:(in_w-out_w)*{args.crop_x:g}:(in_h-out_h)*{args.crop_y:g}")
         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(pad_filters(out_w, out_h, args.pad_fill, args.pad_color, args.pad_blur))
         vf.append("setsar=1")
 
     if args.fps:

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())