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
caption.py --mode mux: keep the input's existing subtitle track(s) (#93) (#94)
Shogo Kajiyama336e0c4d6311
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 84f61f1..c926ba5 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,21 @@(nothing yet)+## 0.12.2 — `caption.py --mode mux` no longer drops the input's existing subtitle track(s)++Found while discussing a real use case (adding both an English and a Japanese soft subtitle+track to a foreign video) and reproduced directly: chaining `--mode mux` once per language —+the natural way to build a multi-language subtitle set — silently dropped every earlier+language but the last, because the mode's `-map` list never included the main input's own+existing subtitle stream(s), only the freshly-added one. Same class of bug fixed across+`fit.py`/`color.py`/`graphics.py`/`overlay.py` in 0.12.1/#91 (deliberately scoped out of that+pass since burn mode raises a real design question mux mode doesn't have: mux mode explicitly+promises "copies video/audio untouched, adds the SRT as a soft, toggleable subtitle stream", so+keeping what was already there has one obvious answer). Existing tracks are now mapped and+stream-copied (`-c:s:i copy` per existing index) ahead of the new one, whose own `-c:s`/+`-metadata:s:s:N` now target its real index instead of always `0`. Closes+[#93](https://github.com/kajisho5/ffmpeg-skill/issues/93).+## 0.12.1 — Stream-preservation audit: subtitle/data streams no longer silently dropped by picture-only editsPrompted by an external review pushing back that "feature-complete" for this project now meansdiff --git a/docs/contract.md b/docs/contract.mdindex ac74026..815f408 100644--- a/docs/contract.md+++ b/docs/contract.md@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:| Field | Meaning | Changes when ||---|---|---|| `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |-| `skill.version` | the npm / package.json version (`0.12.1`) | any release |+| `skill.version` | the npm / package.json version (`0.12.2`) | any release |A release that adds a tool or a flag keeps `contract_version`; a breaking change to theToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`@@ -39,7 +39,7 @@ drifting silently.```json{"contract_version": "1.0",- "skill": {"id": "ffmpeg-skill", "version": "0.12.1", "execution_mode": "local", "kind": "execution",+ "skill": {"id": "ffmpeg-skill", "version": "0.12.2", "execution_mode": "local", "kind": "execution","entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},"not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},"requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},diff --git a/package.json b/package.jsonindex 9c118ff..6848c8c 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "ffmpeg-skill",- "version": "0.12.1",+ "version": "0.12.2","description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 28 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",diff --git a/scripts/caption.py b/scripts/caption.pyindex e3883d5..b0583e1 100755--- a/scripts/caption.py+++ b/scripts/caption.py@@ -427,14 +427,23 @@ def main() -> int:if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and args.text)):die(f"SRT file not found: {srt_path}")codec = mux_subtitle_codec(output)+ # Keep any subtitle track(s) the input already has (e.g. chaining --mode mux once per+ # language to build a multi-language set) -- copied byte-identical, distinct from the+ # newly-added SRT's own codec below.+ existing_subs = meta.get("subtitle_streams") or 0maps = ["-map", "0:v:0"]cmd = ffmpeg_base() + ["-i", args.input, "-i", srt_path]if meta.get("audio"):maps += ["-map", f"0:a:{args.audio_stream}"]+ if existing_subs:+ maps += ["-map", "0:s?"]maps += ["-map", "1:0"]- cmd += maps + ["-c:v", "copy"] + (["-c:a", "copy"] if meta.get("audio") else []) + ["-c:s", codec]+ cmd += maps + ["-c:v", "copy"] + (["-c:a", "copy"] if meta.get("audio") else [])+ for i in range(existing_subs):+ cmd += [f"-c:s:{i}", "copy"]+ cmd += [f"-c:s:{existing_subs}", codec]if args.language:- cmd += ["-metadata:s:s:0", f"language={args.language}"]+ cmd += [f"-metadata:s:s:{existing_subs}", f"language={args.language}"]cmd += [output]run(cmd)result = probe(output, role="output")diff --git a/tests/test_all.py b/tests/test_all.pyindex 502e3bf..ec1d323 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -560,6 +560,28 @@ class FFmpegSkillTests(unittest.TestCase):self.assertEqual(m["audio"]["codec"], "aac", "audio must be copied untouched")self.assertClose(m["duration"], 12.0, 0.15)+ def test_caption_mux_chained_keeps_every_language_track(self):+ """--mode mux used to drop any subtitle track the input already had when adding a new+ one (its map list never included 0:s?), so chaining it once per language -- the natural+ way to build a multi-language subtitle set (e.g. an English track, then a Japanese one)+ -- silently lost every earlier language but the last (#93). Each call must now keep what+ was already there."""+ srt_en = OUT / "mux_chain_en.srt"+ srt_en.write_text("1\n00:00:00,000 --> 00:00:02,000\nHello\n", encoding="utf-8")+ srt_ja = OUT / "mux_chain_ja.srt"+ srt_ja.write_text("1\n00:00:00,000 --> 00:00:02,000\nこんにちは\n", encoding="utf-8")+ step1 = OUT / "cap_mux_chain1.mkv"+ script("caption.py", self.src, "--srt", srt_en, "--mode", "mux", "--language", "en", "-o", step1)+ step2 = OUT / "cap_mux_chain2.mkv"+ script("caption.py", step1, "--srt", srt_ja, "--mode", "mux", "--language", "ja", "-o", step2)+ m = probe(str(step2))+ self.assertEqual(m["subtitle_streams"], 2)+ langs = sh("ffprobe", "-v", "error", "-select_streams", "s", "-show_entries", "stream_tags=language",+ "-of", "csv=p=0", step2).stdout.split()+ self.assertEqual(langs, ["en", "ja"])+ self.assertEqual(m["video"]["codec"], "h264", "video must stay copied through both chained calls")+ self.assertEqual(m["audio"]["codec"], "aac", "audio must stay copied through both chained calls")+def test_caption_mux_picks_the_subtitle_codec_from_the_container(self):srt = OUT / "mux_container_cues.srt"script("caption.py", "--text", self.cues, "--write-srt", srt)