Skip to content

docs(spec): subtitle sidecars for --to web (roadmap phase 14) - #175

Merged
bhemsen merged 6 commits into
mainfrom
docs/subtitle-sidecars
Oct 1, 2026
Merged

bhemsen merged 6 commits into
mainfrom
docs/subtitle-sidecars

Conversation

@bhemsen

@bhemsen bhemsen commented Oct 1, 2026

Copy link
Copy Markdown
Owner

Spec for roadmap phase 14: --to web writes every text subtitle stream as a WebVTT sidecar beside the MP4, because no browser shows an in-band mov_text track in a plain <video>.

  • A separate sidecar step after the ladder (one ffmpeg, one .partial output per sidecar) — a broken subtitle never costs the video a re-encode.
  • Every sidecar path is guarded by the grammar of its name, so selection stays probe-free and cli.py needs no diff.
  • Sidecars renamed before the MP4; the JSON file record gains sidecars (schema stays 1).
  • Authors the vision, architecture, source-selection, degradation-ladder and stream-decision carriers for ratification.

Three decisions are open for the acceptance gate (duplicate-language naming, whether an MP4 with a missing sidecar counts as done, which codecs earn a styling note).

Docs-only; closes no issue.

🤖 Generated with Claude Code

bhemsen and others added 6 commits October 1, 2026 09:43
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 <noreply@anthropic.com>
An MP4 at its final path counts as done (constraint-determined), sidecars
are never rolled back, the stale sweep compares through normcase rather
than casefold, ASS/SSA are always noted, and placement, note order and
the plan type are fixed so the implementer meets no fork.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
First same-language stream bare, further ones numbered from 2 per
language; no styling note for SubRip or mov_text; an MP4 at its final
path is done, confirmed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bhemsen
bhemsen merged commit 9fce6a5 into main Oct 1, 2026
7 checks passed
@bhemsen
bhemsen deleted the docs/subtitle-sidecars branch October 1, 2026 17:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant