feat(run_episodes): batch runner for episode directories (depends on #41)

[xiaogang-sudo]

Summary

Adds a convention-driven episode-batch runner that complements the existing jobs.json / jobs.csv manifest path in srt_driven_edit. Given a root directory whose immediate subdirectories are episodes, it discovers eps that have the required file set and runs the edit pipeline on each.

batch/
├─ ep01/
│   ├─ source.mp4
│   ├─ script.srt
│   ├─ edit_plan.json
│   └─ voice.wav        # optional — becomes ep's global voice
├─ ep02/
│   └─ ...
└─ ep03/
    └─ ...

One command:

python helpers/run_episodes.py batch/
python helpers/run_episodes.py batch/ --bg-volume 0.1 --style cjk-natural --continue-on-error

Each ep gets its own final.mp4 + edit/ artifacts; an aggregate run_episodes_summary.json lands at the root.

Behavior

• Discovery is forgiving. Subdirs missing a required file are skipped with a printed reason instead of aborting the batch. Hard-fails only when no usable ep is found.
• Failure mode mirrors batch-manifest semantics. Without --continue-on-error, the first failing ep aborts the run. With it, the run completes and individual failures appear in the summary. Process exits non-zero whenever any ep failed.
• No new edit primitives — _make_job(...) just composes a Job dataclass and hands it to srt_driven_edit.run_job. So global voice mixing, sync tails, cache invalidation, etc. all behave identically to single-job runs.

Reviewer notes

⚠ Depends on PR #41 (feat: SRT-driven edit pipeline + edit-plan recommender). run_episodes.py imports Job, run_job, preflight, and safe_ascii_name from srt_driven_edit.py, which only exists on that branch. The diff in this PR shows 4 commits because feat/srt-driven-edit has not yet merged to main — only the last commit (b7dbd6e) is new in this PR; the other three are exactly PR #41. Once #41 merges, I'll rebase this branch onto main.

• Tests need ffmpeg + ffprobe on PATH; conftest.py skips otherwise.

Test plan

• pip install -e ".[dev]"
• python -m pytest tests/test_run_episodes.py -v (7 tests, ~12s)
• python -m pytest tests/ -v (35 tests including the full suite, ~55s)

7 pytest cases included:

• discover skips incomplete dirs without erroring
• discover picks up voice.wav when present
• empty root raises
• full e2e with 3 synthetic eps each producing final.mp4
• --continue-on-error skips ep with out-of-bounds range, finishes others
• hard abort without --continue-on-error
• per-ep voice.wav reflected in QC audio.mode

🤖 Generated with Claude Code

---

Summary by cubic

Adds a convention-based batch runner that discovers episode folders and runs the SRT-driven edit pipeline for each, plus a project-root main.py wrapper for single runs. Updates srt_video_editor.py to cut per-cue clips with ffmpeg instead of only validating.

• New Features

  • Discovers episodes at //; requires source.mp4, script.srt, edit_plan.json; picks up optional voice.wav. Skips incomplete dirs; errors only if none are valid.
  • Failure control: aborts on first error by default; --continue-on-error finishes all and exits non-zero if any episode failed.
  • Outputs <ep>/final.mp4 and per-episode edit/ artifacts; writes <root>/run_episodes_summary.json with structured failure records (index, paths, stderr tail).
  • Reuses srt_driven_edit.Job and run_job for parity with manifest mode.
  • Adds main.py wrapper: auto-fills --srt input/script.srt, --plan input/edit_plan.json, and -o output/final.mp4; injects --source input/source.mp4 and --voice input/voice.wav only if files exist; --batch skips these defaults.
  • Updates srt_video_editor.py: Form A only; validates ids, prints SRT-to-source mapping, and now extracts per-cue clips to temp/clip_<id:03d>.mp4 via ffmpeg (-ss before -i, H.264 video, AAC audio). Defaults --srt input/script.srt, --plan input/edit_plan.json, --source input/source.mp4, --temp-dir temp/; clear errors on bad ranges or missing ffmpeg.

• Dependencies

  • Added dev extra with pytest>=7.

^{Written for commit 09783f5. Summary will update on new commits. Review in cubic}