yolo/arr
3
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects Releases Wiki Activity

Extract text subtitle streams to sidecar SRT #189

New Issue
Closed
opened 2026-08-24 21:28:32 +01:00 by naps62-yolo · 2 comments
naps62-yolo commented 2026-08-24 21:28:32 +01:00
Owner
Copy Link
Copy Source

Extract text-format embedded subtitle tracks to sidecar SRT files, so an
embedded English track can serve as a translation source. Bazarr cannot do
this, and it is the single reason the operator asked for embedded handling at
all (DESIGN.md §15, added by #183).

  • arr-probe already reports subtitle tracks with resolved languages. It must
    additionally report the codec, because the split that matters is text versus
    bitmap.
  • Text formats — subrip, ass, mov_text — extract with ffmpeg, mapping
    the single stream and converting to SRT. Spawn-and-die, like ffprobe.
  • Image formats — PGS, VobSub — carry bitmaps. They satisfy their language for
    viewing and are recorded as satisfying, but they are never extracted and
    never become a translation source. No OCR (that is deliberately deferred; see
    the separate backlog issue).
  • Every embedded track, extracted or not, gets a subtitle row from #186 so the
    reconcile loop can tell a satisfied language from a gap without re-probing.

An extracted track is written as a sidecar under the naming rule in §15, with
no .mt segment — it is a real subtitle, not a machine translation.

Depends on: #184, #186

Extract text-format embedded subtitle tracks to sidecar SRT files, so an embedded English track can serve as a translation source. Bazarr cannot do this, and it is the single reason the operator asked for embedded handling at all (DESIGN.md §15, added by #183). - `arr-probe` already reports subtitle tracks with resolved languages. It must additionally report the codec, because the split that matters is text versus bitmap. - Text formats — `subrip`, `ass`, `mov_text` — extract with `ffmpeg`, mapping the single stream and converting to SRT. Spawn-and-die, like `ffprobe`. - Image formats — PGS, VobSub — carry bitmaps. They satisfy their language for viewing and are recorded as satisfying, but they are never extracted and never become a translation source. No OCR (that is deliberately deferred; see the separate backlog issue). - Every embedded track, extracted or not, gets a subtitle row from #186 so the reconcile loop can tell a satisfied language from a gap without re-probing. An extracted track is written as a sidecar under the naming rule in §15, with no `.mt` segment — it is a real subtitle, not a machine translation. Depends on: #184, #186
naps62-yolo added this to the Subtitles milestone 2026-08-24 21:28:32 +01:00
naps62-yolo added the area/subsphase/9-subtitlestype/featuredifficulty/moderate labels 2026-08-24 21:28:32 +01:00
naps62-yolo added a new dependency 2026-08-24 21:29:27 +01:00
#184 Add the arr-subs crate with the provider trait
naps62-yolo added a new dependency 2026-08-24 21:29:27 +01:00
#186 Persist subtitle files and per-language attempts
naps62-yolo added a new dependency 2026-08-24 21:29:27 +01:00
#196 Close the subtitle gap in the reconcile loop
naps62-yolo commented 2026-08-24 22:14:16 +01:00
Author
Owner
Copy Link
Copy Source

Scope addition from the milestone driver — please fold this in.

Two separate reports (#184 and #186) landed on the same gap: arr_core::SubtitleTrack carries only language. It needs two more facts, and both belong to the probe change this issue already owns:

  1. The codec — already in this issue's scope, splitting text formats (subrip, ass, mov_text) from image formats (PGS, VobSub) per §15.
  2. The forced disposition — not currently in any issue. §15 says a forced track never satisfies a want. #186's schema keys embedded rows on (media_file_id, language, forced, sdh), but with nothing supplying forced every embedded track records as forced = false, so a file carrying only a forced English track reads as satisfied for English and the reconcile loop stops looking. ffprobe reports it as disposition.forced (and disposition.hearing_impaired for SDH, worth carrying at the same time).

Add both to SubtitleTrack and to whatever arr-probe fills it from. This does not widen the issue much — it is the same struct and the same ffprobe read.

Scope addition from the milestone driver — please fold this in. Two separate reports (#184 and #186) landed on the same gap: `arr_core::SubtitleTrack` carries only `language`. It needs two more facts, and both belong to the probe change this issue already owns: 1. **The codec** — already in this issue's scope, splitting text formats (`subrip`, `ass`, `mov_text`) from image formats (PGS, VobSub) per §15. 2. **The `forced` disposition** — *not* currently in any issue. §15 says a forced track never satisfies a want. #186's schema keys embedded rows on `(media_file_id, language, forced, sdh)`, but with nothing supplying `forced` every embedded track records as `forced = false`, so a file carrying only a forced English track reads as satisfied for English and the reconcile loop stops looking. ffprobe reports it as `disposition.forced` (and `disposition.hearing_impaired` for SDH, worth carrying at the same time). Add both to `SubtitleTrack` and to whatever `arr-probe` fills it from. This does not widen the issue much — it is the same struct and the same ffprobe read.
naps62-yolo commented 2026-08-24 22:35:32 +01:00
Author
Owner
Copy Link
Copy Source

Implemented #189 on branch subtitles/189-extract-subs (two commits, based off blitz/subtitles). arr_core::SubtitleTrack now carries the codec — a new SubtitleCodec enum (SubRip, Ass, MovText, Pgs, VobSub, Other) with an is_text() split per §15 — plus the forced and sdh dispositions from the milestone-driver comment; arr-probe fills all three from ffprobe's codec_name and disposition. Extraction lives in a new arr_probe::Extractor: one spawn-and-die ffmpeg call maps a single subtitle stream and converts it to SRT, writing beside the target under a dot-name and renaming so no half-written sidecar is ever visible. A pure layout::subtitle_name helper builds §15's <video>.<lang>.srt / .mt.srt names. The committed fixture clip gained a forced track and was regenerated via make-probe-fixtures.sh; tests cover codec mapping (including PGS/VobSub names), live extraction of text tracks, stream indexing by subtitle position, and out-of-range-stream failure.

just ci: passed (gate exit 0; 499 tests green). Not merged, no PR opened.

Findings

  • ffmpeg has no PGS encoder (and refuses text→bitmap subtitle conversion generally), so the fixture uses a forced SRT track instead of a bitmap one; the PGS/VobSub codec-name mapping is covered by a unit test on ffprobe's documented names rather than a real clip.
  • The daemon's probed_json (crates/arr-daemon/src/import.rs) now serialises codec/forced/sdh into the media_files.probed column, but nothing yet writes embedded tracks to subtitle_files at import time — I read that wiring as #196's step 1 and left it there.
  • NewSubtitleFile::extracted in arr-db takes the path but ignores its own builder pattern (..Self::new) inconsistently with the other constructors — cosmetic only, works fine.
Implemented #189 on branch `subtitles/189-extract-subs` (two commits, based off `blitz/subtitles`). `arr_core::SubtitleTrack` now carries the codec — a new `SubtitleCodec` enum (`SubRip`, `Ass`, `MovText`, `Pgs`, `VobSub`, `Other`) with an `is_text()` split per §15 — plus the `forced` and `sdh` dispositions from the milestone-driver comment; `arr-probe` fills all three from ffprobe's `codec_name` and `disposition`. Extraction lives in a new `arr_probe::Extractor`: one spawn-and-die ffmpeg call maps a single subtitle stream and converts it to SRT, writing beside the target under a dot-name and renaming so no half-written sidecar is ever visible. A pure `layout::subtitle_name` helper builds §15's `<video>.<lang>.srt` / `.mt.srt` names. The committed fixture clip gained a forced track and was regenerated via `make-probe-fixtures.sh`; tests cover codec mapping (including PGS/VobSub names), live extraction of text tracks, stream indexing by subtitle position, and out-of-range-stream failure. `just ci`: **passed** (gate exit 0; 499 tests green). Not merged, no PR opened. ## Findings - ffmpeg has no PGS encoder (and refuses text→bitmap subtitle conversion generally), so the fixture uses a forced SRT track instead of a bitmap one; the PGS/VobSub codec-name mapping is covered by a unit test on ffprobe's documented names rather than a real clip. - The daemon's `probed_json` (`crates/arr-daemon/src/import.rs`) now serialises codec/forced/sdh into the `media_files.probed` column, but nothing yet writes embedded tracks to `subtitle_files` at import time — I read that wiring as #196's step 1 and left it there. - `NewSubtitleFile::extracted` in arr-db takes the path but ignores its own builder pattern (`..Self::new`) inconsistently with the other constructors — cosmetic only, works fine.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/api
arr-api
 area/ci
CI and test harness
 area/compat
arr-compat
 area/core
arr-core
 area/daemon
arr-daemon
 area/db
arr-db
 area/dl
arr-dl
 area/indexer
arr-indexer
 area/infra
workspace and tooling
 area/meta
arr-meta
 area/parse
arr-parse
 area/probe
arr-probe
 area/subs
arr-subs crate: providers, extraction, translation, sync
 area/web
web/
 difficulty/easy
bounded, obvious approach, few files
 difficulty/hard
subtle correctness or cross-cutting
 difficulty/moderate
multiple files, judgement, an interface to design
 difficulty/trivial
one file, mechanical, no design decisions
 phase/1-skeleton
workspace, CI, config, database, empty API and SPA
 phase/2-logic
parsing and policy engine, pure, no network
 phase/3-sourcing
TMDB and Prowlarr, read-only
 phase/4-movies
movies end to end
 phase/5-ui
search, buckets, library views, queues
 phase/6-tv
seasons, episodes, tracking, derived status
 phase/7-people
owner tags and notifications
 phase/8-compat
Jellyseerr shim
 phase/9-subtitles
build order: subtitles, DESIGN.md §15
 type/bug
type/chore
type/feature
type/test
No labels area/subs difficulty/moderate phase/9-subtitles type/feature
Milestone
No items
No Milestone Subtitles
Projects
Clear projects
No projects
Assignees
Clear assignees
hermes (Hermes (agent)) naps62 (Miguel Palhas) naps62-yolo (naps62-yolo (agent))
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Blocks
#196 Close the subtitle gap in the reconcile loop
yolo/arr
Depends on
#184 Add the arr-subs crate with the provider trait
yolo/arr
#186 Persist subtitle files and per-language attempts
yolo/arr
Reference: yolo/arr#189