From 5ef79860cfdf8fb6fd3705f61d4ba993d920de96 Mon Sep 17 00:00:00 2001 From: Bendix Hemsen Date: Thu, 1 Oct 2026 09:43:22 +0200 Subject: [PATCH 1/6] docs(spec): subtitle sidecars for --to web (roadmap phase 14) A browser does not show in-band mov_text, so --to web drops every subtitle today. The spec writes each text subtitle as a WebVTT sidecar in a separate ffmpeg step after the ladder, guards every sidecar path by the grammar of its name so selection stays probe-free, and authors the vision, architecture and three design carriers for ratification. Co-Authored-By: Claude Opus 5.5 --- docs/architecture.md | 24 ++- docs/design/degradation-ladder.md | 19 +- docs/design/source-selection.md | 16 ++ docs/design/stream-decision.md | 17 +- docs/specs/spec-subtitle-sidecars.md | 291 +++++++++++++++++++++++++++ docs/vision.md | 3 + 6 files changed, 359 insertions(+), 11 deletions(-) create mode 100644 docs/specs/spec-subtitle-sidecars.md diff --git a/docs/architecture.md b/docs/architecture.md index 397cc7e..c845f4d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -11,11 +11,11 @@ Everything else exists today. | Component | Responsibility | | --------- | -------------- | | `converter/cli.py` | Argument parsing, target-format selection, the interactive prompt, usage errors, exit codes | -| `converter/profiles.py` | One declarative profile per target format: the copy mask, the fallback encoder and the drop reason per stream type, the container flags, the ffmpeg muxer that writes it, the cheap and last-resort attempts the format declares as data, and whether that cheap attempt's mapping is partial by construction | -| `converter/jobs.py` | The generic conversion engine: turns a profile plus a probed stream list into an ordered ladder of attempts, and into the notes a *successful* partial cheap attempt owes. It owns the *order* of the rungs and how the selective rung is built; the profiles own what each declared rung contains | +| `converter/profiles.py` | One declarative profile per target format: the copy mask, the fallback encoder and the drop reason per stream type, the container flags, the ffmpeg muxer that writes it, the cheap and last-resort attempts the format declares as data, whether that cheap attempt's mapping is partial by construction, and — for a probe-first profile — which streams it writes as sidecar files instead (codecs, options, muxer, suffix) | +| `converter/jobs.py` | The generic conversion engine: turns a profile plus a probed stream list into an ordered ladder of attempts, and into the notes a *successful* partial cheap attempt owes. It owns the *order* of the rungs, how the selective rung is built and which streams a sidecar step writes; the profiles own what each declared rung contains | | `converter/batch.py` | Bounded parallel execution, the per-file outcome, the progress bar, the aggregate summary and the process exit code; hands each result to a caller-supplied callback | -| `converter/report.py` | Rendering results: the human text lines and the `--json` records (JSON Lines), both over `batch.Result` / `batch.Summary` | -| `converter/paths.py` | Input discovery, output-path construction, tree mirroring, collision detection, Windows path-length diagnosis | +| `converter/report.py` | Rendering results: the human text lines and the `--json` records (JSON Lines, including each converted file's `sidecars`), both over `batch.Result` / `batch.Summary` | +| `converter/paths.py` | Input discovery, output-path construction, sidecar naming (language normalisation, the duplicate rule, the stale-partial sweep), tree mirroring, collision detection, Windows path-length diagnosis | | `converter/ffmpegtool.py` | Locating ffmpeg and ffprobe, building argv, running without a shell, probing streams; keeps every running process in a registry it can terminate, bound to a Job Object on Windows | | `converter/__main__.py` | The `python -m converter` entry point | @@ -95,6 +95,14 @@ only on `cli`. takes. A probe-first profile (`web`) has no cheap attempt at all and succeeds on the selective rung instead; see the 2026-08-26 (issue #41) entries in `docs/specs/archive/spec-profile-registry.md`'s Decision log. + A profile that routes streams to sidecars (`web`'s text subtitles) adds one + step after whichever rung wrote the output: `jobs.plan_sidecars` names the + streams from the stream list already probed, `paths.sidecar_paths` names + their files, and `batch` runs **one** further ffmpeg process with one + `.partial` output per sidecar. A failure there drops the sidecars with a + note each and never the output. Every sidecar is renamed into place + **before** the output, so an output at its final path implies its sidecar + step finished (`docs/specs/spec-subtitle-sidecars.md`). 2. **Degradation.** The attempt exits non-zero, so *now* `ffmpegtool.probe_streams` describes the file. Each stream is first resolved to a rule — by its disposition when it is an attached picture and the profile declares a rule for @@ -121,7 +129,10 @@ only on `cli`. 3. **Idempotent re-run.** An output that already exists and no `--overwrite` makes the file `skipped` without starting a process (a stale `.partial` from a killed run is removed first), so a second run over a finished - tree does no work for the files it already converted. A source whose output + tree does no work for the files it already converted. Sidecars take no part + in that decision: the output's existence alone decides it, and stale sidecar + partials beside it are swept by name grammar (`paths.stale_sidecar_partials`) + whether the file is skipped or not. A source whose output path would be its own input path is `skipped` too — reported rather than passed over in silence, and counted, per `docs/design/source-selection.md`. 4. **Failure.** The `.partial` file is removed — an existing output is left @@ -142,7 +153,8 @@ only on `cli`. thread (`KeyboardInterrupt`, or `ffmpegtool.Terminated` from the SIGTERM handler), which calls `ffmpegtool.terminate_all`: the registry closes to new spawns and every running process is killed and reaped. Each worker sees the - shutdown flag after its `run()` returns, deletes its own `.partial` and stops + shutdown flag after its `run()` returns, deletes its own `.partial` (and its + sidecar partials, when the sidecar step was running) and stops without a result; the main thread waits for them, then removes any partial still in flight. The run exits 130 or 143 without a summary. A Windows `TerminateProcess` cannot be caught: the Job Object kills ffmpeg with the diff --git a/docs/design/degradation-ladder.md b/docs/design/degradation-ladder.md index 8458af4..abdd44b 100644 --- a/docs/design/degradation-ladder.md +++ b/docs/design/degradation-ladder.md @@ -24,7 +24,10 @@ flowchart TD PLAN["build the selective plan
(no subprocess — see stream-decision.md)"] SEL["Attempt 2 — selective
(ffmpeg)"] FIN["Attempt 3 — the profile's last-resort attempt
(ffmpeg; a profile may declare none)"] - OK["converted — the winning attempt's notes are reported"] + OK["the attempt succeeded — its notes are the run's notes"] + SCQ{"did the stream plan route any stream to a sidecar?
(only a probe-first profile can declare one)"} + SCS["sidecar step — one ffmpeg, one output per sidecar
(each to its own .partial; a failure drops the sidecars
with a note each, never the output)"] + DONE["converted — renamed into place, sidecars first,
the output last; the notes are reported"] BAD["failed — partial output removed, ffmpeg's stderr kept per rung"] PF -->|"no"| A @@ -47,10 +50,24 @@ flowchart TD SEL -->|"exit != 0"| FIN FIN -->|"exit 0"| OK FIN -->|"exit != 0, or no last-resort attempt declared"| BAD + OK --> SCQ + SCQ -->|"no"| DONE + SCQ -->|"yes"| SCS + SCS --> DONE ``` ## Rules the diagram encodes +- **The sidecar step runs after the ladder, never inside it.** Whichever rung + wrote the output — the selective rung or the last resort — the streams the + plan routed to a sidecar (`stream-decision.md`'s `SIDECAR`) are written by one + further ffmpeg process with one output per sidecar, built from the stream + list the up-front probe already holds, so it spends no probe. A sidecar that + fails costs its own file and a note, never the output and never a rung: + carrying sidecars as extra outputs on a rung would let a subtitle the WebVTT + encoder rejects push the video down to a re-encode. Every sidecar is renamed + before the output, so an output at its final path implies its sidecar step + finished (`docs/specs/spec-subtitle-sidecars.md`). - **A probe-first profile starts at `P`.** It declares no cheap attempt, because a blind remux is precisely what would carry streams the target accepts but cannot use — `web`'s HEVC or AC-3 in an MP4 a browser cannot play. Its one probe is the diff --git a/docs/design/source-selection.md b/docs/design/source-selection.md index 4e6649d..ea09ec0 100644 --- a/docs/design/source-selection.md +++ b/docs/design/source-selection.md @@ -140,6 +140,22 @@ flowchart TD file is counted, because `0 converted, 12 skipped` is the idempotent-re-run evidence the vision promises. A `.txt`, or a file inside the output tree, is not, because counting everything a directory happens to hold means nothing. +- **Every path a source writes is guarded, but only the output is selected.** + A target that writes sidecars (`--to web`'s WebVTT files) has more than one + path per source, and selection cannot know them: their names follow from the + source's subtitle streams, which only a probe reveals. The guards above still + cover them, by construction of the name — a sidecar is the output's name with + its suffix replaced by `.[.]`, where `` is never + purely numeric, `` always is, and neither holds a dot. Two distinct output + names in one directory therefore never share a sidecar (their components + cannot line up), a sidecar never equals an output (different suffix), and it + never equals a selected source's input path (the sidecar suffix is in no + source-suffix set, and a named file's own sidecars carry one component more + than its stem). So `COLL`, `SELF` and `HAZ` hold for sidecars without a node of + their own, and `cli.py` is unchanged. `EXISTS` is the one guard that is asked + **per sidecar, after the ladder**, not here: an existing sidecar path is left + alone without `--overwrite` and named in a note, and the output's own + existence alone decides the skip (`docs/specs/spec-subtitle-sidecars.md`). - **Selection cannot tell whether a source can *produce* the target.** Whether a video-only file has audio to put in a WAV is only knowable from a probe, and selection has no probe to spend: the one the ladder may now spend on a diff --git a/docs/design/stream-decision.md b/docs/design/stream-decision.md index dba9c87..6368512 100644 --- a/docs/design/stream-decision.md +++ b/docs/design/stream-decision.md @@ -35,6 +35,8 @@ flowchart TD D1["drop — note: t stream i (c) dropped: not supported by TARGET"] D2["drop — note: t stream i (c) dropped: TARGET holds LIMIT t stream
(the noun agrees in number with LIMIT)"] D3["drop — note: t stream i (c) dropped: DROP_REASON"] + SIDE{"does the rule declare a sidecar
that accepts c?"} + SIDECAR["sidecar — not mapped into the output; written to a file
of its own after the ladder (degradation-ladder.md's sidecar step)
note only when the sidecar format gives up styling"] S --> PIC PIC -->|"yes — use that rule"| ROOM @@ -46,7 +48,9 @@ flowchart TD MASK -->|"yes"| COPY MASK -->|"no"| ENC ENC -->|"yes"| REENC - ENC -->|"no"| D3 + ENC -->|"no"| SIDE + SIDE -->|"yes"| SIDECAR + SIDE -->|"no"| D3 REENC --> OPT OPT -->|"yes"| OVERRIDE OPT -->|"no"| STAND @@ -61,9 +65,14 @@ flowchart TD declares no `attached_pic` rule is unaffected, since the fallback is what it already did. The engine still counts a carried picture under `video`, because ffmpeg numbers it as a video output stream. -- **Three outcomes, never a fourth.** A stream is accepted, re-encoded, or - dropped. Every drop edge names the reason, because a silent drop is exactly - what the vision forbids. +- **Four outcomes, never a fifth.** A stream is accepted, re-encoded, dropped, + or — only where the rule declares a sidecar (`web`'s text subtitles) — moved + into a sidecar file of its own. `SIDE` sits on `ENC`'s `no` edge, so a stream + the output itself can carry is never diverted: the sidecar is the alternative + to a drop, not to a copy (`docs/specs/spec-subtitle-sidecars.md`). A sidecar + is not a drop and earns no drop note; a sidecar format that cannot hold the + stream's styling earns a styling note instead. Every drop edge names the + reason, because a silent drop is exactly what the vision forbids. - **A re-encoded stream may also need a source-dependent option.** `OPT` sits after `REENC`: a rule may declare a value its fallback needs only when a second, independent probed property — not the one `MASK` already used to diff --git a/docs/specs/spec-subtitle-sidecars.md b/docs/specs/spec-subtitle-sidecars.md new file mode 100644 index 0000000..1a352bb --- /dev/null +++ b/docs/specs/spec-subtitle-sidecars.md @@ -0,0 +1,291 @@ +# Spec: subtitle-sidecars (roadmap phase 14) + +> Created: 2026-10-01 + +`converter --to web` writes every text subtitle stream of a source as a WebVTT +file beside the MP4, so a browser can load it through ``; image +subtitles stay dropped with a note. It is the first phase where one source +writes more than one path, so the guards, the `.partial` handling and the JSON +record are widened to cover every path a source writes. This spec carries no +lifecycle state — acceptance is the spec merged on the default branch with a +milestone and issues, and all progress lives in the GitHub issues and +milestone. A completed spec is moved to `docs/specs/archive/`. + +## The gap + +`--to web` (phase 13) drops every subtitle stream with the note "subtitles are +not shown by a browser from inside an MP4" (`profiles.WEB`'s `subtitle` rule). +That is honest, but for *videothek* it means a film with English and German +subtitles plays with none. No browser exposes an in-band `mov_text` track as a +`TextTrack` in a plain progressive `