get-subtitles

# Get Subtitles Use this skill to ensure a movie has a verified subtitle artifact before Watch, Orpheus, or ingest workflows trust it. Bazarr language metadata is not enough: the skill must return a real local subtitle file path or a fail-closed receipt. ## Contract - Use Bazarr first for local movie metadata and subtitle recovery. - Use `X-API-KEY: $BAZARR_API_KEY`; never print the key. - Verify an actual local subtitle file after every search/download attempt. - Return JSON receipts by default for automation. - Compose `brave-search` for external movie discovery and subtitle/transcript URL discovery. Brave snippets are candidate seeds only; a non-local movie is not recommendable until this skill fetches a subtitle/transcript artifact, stores it locally, scans it, and finds timecoded Orpheus cue markers. - Do not access ArangoDB directly. Use `memory` when durable state is needed. ## Commands ```bash ./run.sh doctor --json ./run.sh movies --query "Bad Santa" --json ./run.sh verify-file --media-path /path/movie.mkv --language en --json ./run.sh ensure-radarr --radarr-id 149 --language en --json ./run.sh providers --radarr-id 149 --json ./run.sh download-provider --radarr-id 149 --provider OpenSubtitles --subtitle '<provider payload>' --original-format --json ./run.sh api-search-download --series-id 123 --episode-id 456 --language en --preferred-formats vtt,ass,srt --json ./run.sh discover --actor "Kristen Stewart" --genre comedy --emotion laugh --json ./run.sh orpheus-sanity --actor "Kristen Stewart" --genre comedy --all-orpheus-emotions --output out/kristen-stewart-orpheus-sanity.json --json ./run.sh scan-srt --subtitle /path/movie.en.srt --all-orpheus-emotions --json ./run.sh batch-ensure-radarr --radarr-ids 149,150 --all-orpheus-emotions --json ``` ## Receipt Shape Verified: ```json { "status": "verified", "language": "en", "subtitle_path": "/path/movie.en.srt", "primary_subtitle_format": "srt", "subtitle_files": [ { "path": "/path/movie.en.srt", "format": "srt", "verified": true, "speaker_metadata_status": "not_present" } ], "media_path": "/path/movie.mkv", "radarr_id": 149, "source": "filesystem", "safe_default": "allow_watch_processing" } ``` Not verified: ```json { "status": "not_verified", "reason": "english_srt_missing", "safe_default": "do_not_process_for_watch_or_orpheus" } ``` ## Bazarr Endpoints Used The local Bazarr Swagger currently exposes: - `GET /api/movies` - `GET /api/system/searches?query=...` - `GET /api/providers/movies?radarrid=...` - `PATCH /api/movies/subtitles?radarrid=...&language=en&forced=False&hi=False` - `POST /api/providers/movies?...provider=...&subtitle=...&original_format=True` - `GET /api/subtitles?subtitlesPath=...&radarrMovieId=...` The local Swagger does not expose a generic `GET /api/subtitles/search` plus `POST /api/subtitles/download` workflow. The skill still exposes `api-search-download` as a compatibility command for Bazarr versions that do support the API shape: ```bash ./run.sh api-search-download \ --series-id 123 \ --episode-id 456 \ --language en \ --preferred-formats vtt,ass,srt \ --json ``` When those generic endpoints are absent, the command fails closed with `status: not_available` and points to the provider workflow. For this Bazarr install, manual format-preserving selection is: 1. `GET /api/providers/movies?radarrid=...` 2. Filter the returned provider payload by available extension/format when the provider includes that field. 3. `POST /api/providers/movies` with `original_format=True`, `provider`, and the exact returned `subtitle` payload. 4. Verify the resulting local file on disk. The provider response alone is not sufficient evidence. If a provider only offers `.srt`, do not invent `.vtt` or `.ass`. Preserve `.vtt`, `.ass`, or `.ssa` only when Bazarr/provider actually supplies it. ## Orpheus Subtitle Coverage `scan-srt` accepts `.srt`, `.vtt`, `.ass`, and `.ssa` files. It reads only explicit bracketed or parenthetical cue markers and returns exact cue locations: ```json { "emotion": "laugh", "marker": "(LAUGHS)", "timecode": "00:02:24,000 --> 00:02:26,200", "start_seconds": 144.0, "end_seconds": 146.2, "line": "(LAUGHS)" } ``` The scan output also includes `metadata` with path/filename-derived title/year and any obvious inline SRT metadata fields such as `Title:`, `Year:`, `Actors:`, `IMDB:`, or `Source:`. These fields are extracted only when present or path-derived; the skill must not infer actors from dialogue or hallucinate cast. Speaker metadata is reported only when present in the subtitle artifact: - `.ass/.ssa`: structured `Dialogue` `Name` field. - `.vtt`: structured `<v Speaker Name>` cue tags. - `.srt`: inline text labels like `Willie: ...` only. Plain `.srt` subtitles generally do not carry reliable speaker identity. If speaker identity is absent, report `speaker_metadata_status: not_present` and let Watch/Memory/Brave verification handle speaker attribution as a separate evidence step. Ambient markers such as `[PEOPLE CHATTERING]`, `[MUSIC]`, and `[BACKGROUND NOISE]` are rejected as Orpheus emotion evidence. `batch-ensure-radarr` runs concurrent Bazarr ensure tasks and scans each SRT as soon as it verifies, using `asyncio.as_completed`. Its output includes coverage counts and `missing_emotions` so the project agent can decide which movies still need acquisition through `ingest-movie`. `orpheus-sanity` is the end-to-end subtitle/discovery-only sanity check. It: 1. Runs concurrent `brave-search` batch queries for each requested Orpheus emotion. 2. Deduplicates title/year candidate movies from Brave snippets. 3. Checks local Bazarr/Radarr inventory for those candidates. 4. For every local Bazarr/Radarr match, asks Bazarr to download missing English subtitles by default (`--download`; use `--no-download` only for a passive audit). 5. Verifies the resulting local subtitle file on disk. 6. Scans verified subtitle files for Orpheus cue markers. 7. Optionally runs external subtitle/tag probes for non-local candidates. These are leads only; they are not trusted until a subtitle file is downloaded and scanned. 8. Optionally fetches external subtitle/transcript URLs discovered through Brave. Supported direct fetches are stored under `out/external-subtitles/`; SubtitleCat HTML pages are followed to their English `*-en.srt` download when present. Fetched HTML transcript pages are stored as text but only timecoded subtitle artifacts are eligible for acquisition recommendations. 9. Optionally probes non-local candidates through Radarr/Bazarr metadata: `--probe-nonlocal-bazarr --create-radarr-stubs` adds an unmonitored Radarr metadata record with `searchForMovie=false`, triggers Bazarr `update_movies`, and then attempts Bazarr provider search only if Bazarr indexes the record. This does not download the movie. 10. Writes a final JSON artifact with separate fields for: - `local_verified_hits` - `local_bazarr_recovery` - `external_subtitle_candidates` - `external_fetched_subtitle_scans` - `external_verified_hits` - `movie_recommendations` (unified local + non-local recommendation list) - `ingest_movie_handoff` (normalized acquisition/extraction contract for `ingest-movie`) - `local_movie_recommendations` - `movie_download_recommendations` - `nonlocal_bazarr_subtitle_vetting` - `nonlocal_movie_download_recommendations` - `combined_emotion_coverage` - `unfound_emotion_tags` It must not download movies. Acquisition remains a separate `ingest-movie` step after subtitle coverage gaps are known. Bazarr subtitle recovery is part of this sanity check for movies already present in local Radarr/Bazarr. `movie_download_recommendations` must be fail-closed: a movie can appear there only when a subtitle file has been verified and scanned and the requested Orpheus tag exists in the subtitle text. External Brave/Bazarr/provider search results can populate `external_subtitle_candidates`, but those entries remain unvetted leads until the subtitle artifact is downloaded and scanned. `movie_recommendations` is the unified consumer-facing list. It includes local verified recommendations with `scope: local` and non-local acquisition candidates with `scope: nonlocal`. Keep the older split fields for scripts that need to distinguish local usable movies from acquisition candidates. `ingest_movie_handoff` is the next-stage contract for `ingest-movie`. Each entry must include normalized `title`, `year`, Orpheus-TTS acquisition profile, subtitle-rich NZBGeek search commands, exact cue windows grouped under `subtitle_evidence`, and post-import verification gates. The handoff is not a training-ready claim; it remains blocked until local movie audio and local English `.srt` are verified after import. Provider-only recommendations without a concrete fetched or local subtitle path must not enter this handoff. `nonlocal_movie_download_recommendations` is weaker and must be labeled as an acquisition queue only. It may include movies when a fetched external subtitle artifact contains timecoded Orpheus cue markers, or when Bazarr provider search can see subtitle candidates for a Radarr metadata stub. Bazarr-provider-only entries are still not Orpheus evidence until the movie is acquired, an actual subtitle file is downloaded, and `scan-srt` verifies Orpheus cue markers with timecodes. On the current local Bazarr install, Bazarr does not index Radarr metadata-only movie stubs that have no movie file. In that case `nonlocal_bazarr_subtitle_vetting` must report `bazarr_did_not_index_radarr_metadata_stub_without_movie_file`, and the safe default is no non-local movie recommendation from Bazarr. ## Failure Policy Fail closed if: - `BAZARR_API_KEY` is missing. - Bazarr is unreachable. - The movie cannot be identified. - Bazarr reports subtitles but no real local subtitle file can be verified. - Download returns success but no subtitle file appears on disk. For Watch and Orpheus, Whisper-only transcripts or future subtitle availability must not satisfy this skill's verification contract.