ffmpeg-skill 0.8.3 → 0.8.5

package/README.md

@@ -163,6 +163,10 @@ python3 evals/run.py --list     # routing eval prompts (see evals/)
 node bin/install.js --dir /tmp/skills   # try the installer without touching ~/.claude
 ```
 
+## Support
+
+If this skill saves you time, you can help keep it maintained through [GitHub Sponsors](https://github.com/sponsors/kajisho5). Issues and pull requests are just as welcome.
+
 ## License
 
 [MIT](LICENSE)

package/SKILL.md

@@ -49,7 +49,8 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
    crops keeping the subject, colours not washed out, transitions landing
    where intended. The job is not finished until the report's `Look:` line
    names that PNG; a probe alone cannot see a caption sitting on someone's
-   face. Audio-only jobs (sync, loudness, silence) write `Look: not needed`.
+   face. Audio-only jobs (sync, loudness, silence, or any job whose input is
+   an audio file) write `Look: not needed`; there is no picture to inspect.
 
 
 ## Before you run anything: what to ask, what to assume
@@ -112,6 +113,34 @@ Do not ask for things `probe.py` can tell you.
 | "it's a phone video with variable frame rate" | nothing extra: every re-encoding script conforms VFR to constant fps automatically; `fit.py --fps 30` to pick the rate |
 
 
+## Audio-only files
+
+Audio files are a first-class input, not a special case. `probe.py`, `cut.py`,
+`silence.py`, `loudness.py`, `audio.py`, `sync.py` and `check.py --platform
+podcast` all accept WAV, FLAC, MP3, M4A/AAC, OGG and Opus (any container ffmpeg
+can read) and write the codec that fits the output extension, so the same
+commands work with `talk.wav` in place of `talk.mp4`. What changes:
+
+- The output extension picks the format: `-o out.mp3` converts, `-o out.wav`
+  keeps PCM, `-o out.m4a` writes AAC. `audio.py in.wav -o out.mp3` with no
+  other flag is a plain conversion.
+- `cut.py` stream-copies audio too, so trims are lossless unless the format
+  cannot be cut on a packet boundary.
+- `Look: not needed` in the report; `Check:` still applies for loudness
+  (`check.py file.wav --platform podcast` measures LUFS and true peak).
+- Scripts that need a picture (`fit`, `caption`, `overlay`, `graphics`,
+  `color`, `export`, `join`, `scenes`, `look`) refuse an audio file with
+  "input has no video stream". Say so instead of forcing a video wrapper.
+
+| User says (audio file) | Do |
+|-----------|----|
+| "normalise this WAV to -14 LUFS", "podcast levels" | `loudness.py talk.wav -I -14 --tp -1 -o talk_norm.wav` (`-I -16 --tp -1.5` for podcasts) |
+| "remove the silence from this recording" | `silence.py talk.wav -o talk_tight.wav` |
+| "clean up the noise in this M4A" | `audio.py talk.m4a --voice -o talk_clean.m4a` (speech) or `--denoise` |
+| "convert this WAV to MP3" | `audio.py talk.wav -o talk.mp3` |
+| "trim this audio from 00:30 to 02:00" | `cut.py talk.wav --start 0:30 --end 2:00 -o talk_cut.wav` |
+| "is this loud enough for Apple Podcasts?" | `check.py talk.m4a --platform podcast` |
+
 ## Report format
 
 Finish every job with this shape (numbers from `probe.py`/`check.py`, not memory):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Agent Skill that lets coding agents (Claude Code, Cursor, Codex) do professional video editing with local FFmpeg: MCP server, batch processing, declarative project rendering, brand kits, motion-graphics templates, HTML delivery reports, scene detection, delivery checks, cut, silence removal, transitions, multicam, captions, sync with drift correction, HDR to SDR, LUTs, audio clean-up and ducking, loudness, platform exports. No API keys, no cloud, no dependencies.",
   "keywords": ["ffmpeg", "video", "agent-skill", "claude-code", "cursor", "codex", "skill", "video-editing"],
   "license": "MIT",

package/scripts/_common.py

@@ -37,6 +37,9 @@ def die(msg: str, code: int = 1) -> "None":
 
 
 def info(msg: str) -> None:
+    # under --dry-run nothing is written; do not let scripts claim otherwise
+    if msg.startswith("wrote ") and STATE.dry_run:
+        msg = "[dry-run] would write " + msg[len("wrote "):]
     sys.stderr.write(f"{msg}\n")
 
 

package/scripts/overlay.py

@@ -15,7 +15,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import STATE, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -150,11 +150,13 @@ def main() -> int:
             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):
+        if args.fade > 0:
+            # no --start/--end: fade in at 0 and out at the end of the video
             s = start if start is not None else 0.0
+            e = end if end is not None else (meta.get("duration") or 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")
+            if e > args.fade:
+                chain.append(f"fade=t=out:st={e - 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:
@@ -171,7 +173,8 @@ def main() -> int:
             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)
+        alpha = alpha_expr(args.opacity, start if start is not None else (0.0 if args.fade > 0 else None),
+                           end if end is not None else ((meta.get("duration") or None) if args.fade > 0 else None), args.fade)
         opts.append(f"fontcolor={args.font_color}")
         if alpha != "1":
             opts.append(f"alpha='{alpha}'")
@@ -185,8 +188,9 @@ def main() -> int:
     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)")
+    if not STATE.dry_run:
+        result = probe(output)
+        info(f"wrote {output} ({result['duration']:.3f}s)")
     emit(output)
     return 0