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.

probe.py: add subtitle_stream_details, mirroring audio_streams (#68)

Shogo Kajiyama0beb73a4fb94
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a9726de..9fca96c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
## Unreleased
+- **`probe.py`: `subtitle_stream_details`.** `subtitle_streams` was a plain integer count while `audio_streams` was already a detailed array, so nothing could tell which subtitle index was which language on a multi-track input (e.g. an MKV with Japanese and English subs already muxed in). `subtitle_stream_details` adds that detail as a new, purely additive array — `[{"index", "codec", "language", "title"}, ...]`, one entry per embedded subtitle stream in file order (index n is `-map 0:s:n`), mirroring `audio_streams`' shape minus the audio-only fields (channels, layout, sample rate) ffprobe doesn't expose for subtitle streams. `subtitle_streams`' existing type and meaning (the int count) are unchanged. No writing tool selects among existing embedded subtitle streams yet; this is a `probe.py`-only enrichment. Closes [#63](https://github.com/kajisho5/ffmpeg-skill/issues/63).
- **`caption.py --audio-stream N`: explicit multi-audio-track selection.** Confirmed `caption.py` did silently pick a track on a multi-audio-track input (dubbed languages, M&E stems): burn mode had no `-map` at all (ffmpeg's own automatic stream-selection heuristic, not necessarily index 0, decided), mux mode and the karaoke energy-timing/`--transcribe` audio extraction both hardcoded `0:a:0`. `--audio-stream N` (default 0, matching `audio.py`'s existing flag and unchanged prior behaviour) now threads the same explicit track index through all four: burn's re-encoded audio, mux's stream-copied audio, `--transcribe`'s speech-to-text source, and karaoke's energy-timing analysis, refusing an out-of-range index the same way `audio.py --audio-stream` already does. Closes [#55](https://github.com/kajisho5/ffmpeg-skill/issues/55).
- **`caption.py --text`: SMPTE non-drop-frame timecode cues.** Cues were positioned by decimal seconds only; broadcast-style deliverables often supply cue timing as `hh:mm:ss:ff` frame timecode instead. `--text` cue lines now also accept that format (e.g. `00:00:03:15 --> 00:00:06:00 ...`) — the frame count is converted to seconds with `--fps`, or the input video's own probed fps when `--input` is given and `--fps` is not. A cue that is shaped like a timecode but has no fps available (no `--fps`, no `--input`) is refused with a clear error naming the missing `--fps`, rather than silently misread as a plain text line the way an ordinary unparseable cue line already is. `_common.py` gains the reusable pieces other tools can build on later: `parse_time()` takes an optional `fps` argument for the `hh:mm:ss:ff` case (raising the new `MissingFpsError`, a `ValueError` subclass, when fps is needed but absent), and `fmt_smpte_time()` formats seconds back to `hh:mm:ss:ff` — used here to echo the interpreted cue range in the `wrote ... .srt` report line so a caller can confirm the timecode was read correctly. The written `.srt` itself stays decimal-millisecond SRT timing, since that is the only timing SRT/mux subtitle codecs actually carry; nothing claims frame-exact precision it can't hold. Drop-frame (29.97/59.94 fps) counting is out of scope. Closes [#54](https://github.com/kajisho5/ffmpeg-skill/issues/54).
- **`references/process-pitfalls.md`: development-process mistakes already made once.** Distinct from `references/ci-platform-pitfalls.md` (ffmpeg/CI behaviour differences): this is about the process of making a change safely, not FFmpeg itself. Three entries to start: narrowing a `TOOL_META[...]["required"]` capability list without first grepping `tests/test_contract.py`'s `DoctorDetectionTests` for the fixture-pinned `usable` outcome it protects (nearly broken twice, in #51 and #52, caught before landing both times); retrying a git tag push or GitHub Release creation in this environment, where both are scoped out (branch pushes work, tag pushes 403 at the git-receive-pack level; no `create_release`/`create_tag` MCP tool exists; the outbound proxy itself blocks a raw REST API call to the releases endpoint) rather than accepting it after one confirmation; and redesigning a test fixture a third time instead of recognising, after two independently-redesigned fixtures failed differently on the same platform, that the platform's real behaviour (not the fixture) is the actual cause (`stabilize.py`'s macOS libvidstab test). A living document — add to it whenever one of these recurs. Docs-only; no behaviour changed.
diff --git a/scripts/_common.py b/scripts/_common.py
index e50d482..454f178 100755
--- a/scripts/_common.py
+++ b/scripts/_common.py
@@ -315,6 +315,13 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
"video": None,
"audio": None,
"subtitle_streams": len(subs),
+ # every subtitle stream in file order: index n here is `-map 0:s:n`
+ "subtitle_stream_details": [{
+ "index": n,
+ "codec": s.get("codec_name"),
+ "language": (s.get("tags") or {}).get("language"),
+ "title": (s.get("tags") or {}).get("title"),
+ } for n, s in enumerate(subs)],
}
if video:
r_rate = _fraction(video.get("r_frame_rate"))
diff --git a/tests/test_contract.py b/tests/test_contract.py
index d09f7ef..700960a 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -76,6 +76,15 @@ class ContractTests(unittest.TestCase):
ffmpeg("-f", "lavfi", "-i", "[email protected]:s=120x40,format=rgba", "-frames:v", "1", cls.logo)
cls.cues = OUT / "c_cues.txt"
cls.cues.write_text("0:00-0:02 Hello\n0:02-0:04 World\n", encoding="utf-8")
+ cls.srt_en = OUT / "c_en.srt"
+ cls.srt_en.write_text("1\n00:00:00,000 --> 00:00:02,000\nHello\n", encoding="utf-8")
+ cls.srt_ja = OUT / "c_ja.srt"
+ cls.srt_ja.write_text("1\n00:00:00,000 --> 00:00:02,000\nこんにちは\n", encoding="utf-8")
+ cls.subbed = OUT / "c_subbed.mkv"
+ ffmpeg("-i", cls.src, "-i", cls.srt_en, "-i", cls.srt_ja, "-map", "0", "-map", "1", "-map", "2",
+ "-c:v", "copy", "-c:a", "copy", "-c:s", "srt",
+ "-metadata:s:s:0", "language=eng", "-metadata:s:s:0", "title=English",
+ "-metadata:s:s:1", "language=jpn", "-metadata:s:s:1", "title=Japanese", cls.subbed)
cls.garbage = OUT / "c_garbage.mp4"
cls.garbage.write_bytes(bytes((i * 7919) % 256 for i in range(200_000)))
cls.empty = OUT / "c_empty.mp4"
@@ -775,6 +784,26 @@ class ContractTests(unittest.TestCase):
self.assertEqual(doc["probe"]["audio"]["channels"], 2)
self._verify("audio", doc["output"])
+ def test_probe_subtitle_stream_details(self):
+ """subtitle_streams stays the existing int count; subtitle_stream_details is the new,
+ additive, audio_streams-shaped array (index/codec/language/title per embedded track)."""
+ doc = self._run_structured("probe", {"inputs": [str(self.subbed)]})
+ self.assertEqual(doc["subtitle_streams"], 2)
+ details = doc["subtitle_stream_details"]
+ self.assertEqual(len(details), 2)
+ self.assertEqual(details[0]["index"], 0)
+ self.assertEqual(details[0]["codec"], "subrip")
+ self.assertEqual(details[0]["language"], "eng")
+ self.assertEqual(details[0]["title"], "English")
+ self.assertEqual(details[1]["index"], 1)
+ self.assertEqual(details[1]["codec"], "subrip")
+ self.assertEqual(details[1]["language"], "jpn")
+ self.assertEqual(details[1]["title"], "Japanese")
+ # no subtitle tracks at all: still present, just an empty list; subtitle_streams stays 0
+ doc2 = self._run_structured("probe", {"inputs": [str(self.src)]})
+ self.assertEqual(doc2["subtitle_streams"], 0)
+ self.assertEqual(doc2["subtitle_stream_details"], [])
+
def test_color_overlay_caption_export_check_look_render_via_contract(self):
doc = self._run_structured("color", {"input": str(self.hdr), "to_sdr": True, "fast": True, "output": str(self.out("sdr.mp4"))})
self.assertFalse(doc["probe"]["video"]["hdr"])