---
name: pop-subtitle-ops
description: Subtitle selection, pairing, and sync operations for popcorn-cli playback. Use when working on `play`, `cast`, `cast-magnet`, `subsync`, subtitle candidate ranking, `--subtitle-index`, or subtitle mismatch/out-of-sync debugging across VLC and Chromecast flows.
---

# Pop Subtitle Ops

## Quick Use

Run this workflow when subtitle behavior is wrong or needs tuning:

1. Reproduce with CLI JSON output.
2. Inspect chosen stream and subtitle metadata.
3. Apply deterministic fixes (candidate override, next-launch offset, or selection heuristics).
4. Re-run and confirm output fields and command args are correct.
5. Add/adjust tests for the changed behavior.

## Workflow

### 1) Reproduce deterministically

Use `--json` and prefer `--dry-run` first when possible.

Examples:

```bash
./pop --json play "movie title" --lang es --vlc --dry-run
./pop --json play "movie title" --lang es --device "Cuarto de estar" --dry-run
./pop --json cast-magnet "magnet:..." --lang es --imdb tt1234567 --dry-run
```

### 2) Validate subtitle attachment contract

Verify output includes expected fields:

- `selected_subtitle`
- `subtitle_asset`
- `subtitle_attached`
- `subtitle_offset_ms_applied`

For manual candidate control, use:

```bash
./pop --json play "movie title" --lang es --subtitle-index 1 --vlc --dry-run
```

### 3) Fix selection before syncing

Prioritize matching subtitle release to selected stream release.

- Prefer release-aware ranking logic for default autopick.
- Use `--subtitle-index` when the user wants explicit override.
- Reject invalid indices with clear argument errors.

### 4) Use sync as launch-time offset only

Use `subsync` as cached next-launch offset control.

```bash
./pop --json subsync +1.5
./pop --json subsync reset
```

Expect:

- `applied_live: false`
- `applies_on_next_launch: true` on shift commands

Do not reintroduce default live key injection paths.

### 5) Debug health and pairing quality

Use subtitle health tooling when captions are malformed or likely wrong release/framerate:

```bash
./pop --json subtitle-health "<subtitle-path-or-url>" --sample 5
```

Use results to decide whether to:

- choose another subtitle candidate
- apply a measured offset
- improve release-matching heuristics

## Guardrails

- Keep Chromecast and VLC subtitle attachment behavior in parity.
- Treat readiness/recast checks as best-effort unless device discovery explicitly fails.
- Avoid OS keystroke automation in default subtitle flow.
- Add regression tests for every behavior change in runner/provider subtitle paths.