add task

backlog/tasks/task-70 - Polish-YouTube-subtitle-generation-pipeline.md

@@ -0,0 +1,43 @@
+---
+id: TASK-70
+title: Polish YouTube subtitle generation pipeline
+status: To Do
+assignee: []
+created_date: '2026-02-26 07:37'
+labels: []
+dependencies: []
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+$Current YouTube subtitle generation in launcher/youtube.ts is functional but has implicit behavior, low observability, and unnecessary full-file work. This task modernizes the existing pipeline without changing core architecture.
+
+Scope:
+- Make track selection explicit (manual > auto > whisper per primary/secondary) with deterministic reasons.
+- Avoid running whisper/audio work when a track is already satisfied.
+- Add bounded execution for yt-dlp and whisper subprocesses.
+- Improve stage-level logging for both automatic and preprocess modes.
+- Make secondary track fallback decisions explicit and not implicit.
+- Preserve existing user behavior except where policy is clarified.
+
+Files expected:
+- launcher/youtube.ts
+- launcher/commands/playback-command.ts (if mode/status behavior requires)
+- launcher/types.ts (if schema updates needed)
+- launcher/config/args-normalizer.ts (if timeout/config options added)
+- launcher/util.ts (if runExternalCommand timeout controls added)
+- Add/update launcher subtitle-generation tests
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [ ] #1 Define deterministic track priority for each track: manual, then auto, then whisper (per track) and record source choice with reason.
+- [ ] #2 If manual or auto satisfies a track, skip whisper for that same track and avoid unrelated full extraction/transcription work.
+- [ ] #3 Introduce timeout or budget caps for yt-dlp and whisper calls; timeout should fail safe and unblock automatic playback.
+- [ ] #4 Emit explicit status logs at each stage: metadata load, manual sub fetch, auto sub fetch, whisper audio extraction, whisper run, publish/load, final success/failure summary.
+- [ ] #5 Make secondary handling explicit: transcribe target and translate target must only run when required by config and not by side-effect of primary logic.
+- [ ] #6 Keep preprocess and automatic modes stable in success paths while making behavior in failure paths explicit and bounded.
+- [ ] #7 Add tests for track-combination cases: primary available, secondary available, both missing, partial fallback, both missing with missing whisper config, timeout/error behavior.
+- [ ] #8 Document any behavior changes if user-visible, especially fallback order, timeout behavior, and fallback disablement.
+<!-- AC:END -->