Skip to content

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.

caption.py --mode mux: keep the input's existing subtitle track(s) (#93) (#94)

Shogo Kajiyama336e0c4d6311
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 edits
Prompted by an external review pushing back that "feature-complete" for this project now means
diff --git a/docs/contract.md b/docs/contract.md
index 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 the
ToolSpec 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.json
index 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.py
index 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 0
maps = ["-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.py
index 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)