SubMiner/docs-site/youtube-integration.md

# YouTube Integration

SubMiner auto-loads Japanese subtitles when you play a YouTube URL, giving you the same sentence-mining overlay experience as local video files. It probes available subtitle tracks via `yt-dlp`, selects the best primary and secondary tracks, downloads them, and loads them into mpv before playback resumes.

## Requirements

- **yt-dlp** must be installed and on `PATH` (or set `SUBMINER_YTDLP_BIN` to its path)
- mpv with `--input-ipc-server` configured (handled automatically by the `subminer` launcher)

## How It Works

When SubMiner detects a YouTube URL (or `ytsearch:` target), it pauses mpv at startup and runs a subtitle pipeline before resuming playback:

1. **Probe** --- `yt-dlp --dump-single-json` extracts all available subtitle tracks (manual uploads and auto-generated captions) along with video metadata.
2. **Discover** --- Each track is normalized into a `YoutubeTrackOption` with language code, kind (`manual` or `auto`), display label, and direct download URL.
3. **Select** --- SubMiner picks the best primary track (Japanese, preferring manual over auto) and secondary track (English, preferring manual over auto).
4. **Download** --- Selected tracks are fetched via direct URL when available, falling back to `yt-dlp --write-subs` / `--write-auto-subs`. YouTube TimedText XML formats (`srv1`/`srv2`/`srv3`) are converted to VTT on the fly. Auto-generated VTT captions are normalized to remove rolling-caption duplication.
5. **Load** --- Subtitle files are injected into mpv via `sub-add`. Playback resumes once the primary track is ready; secondary failures do not block.

## Pipeline Diagram

```mermaid
flowchart TD
    classDef step fill:#c6a0f6,stroke:#494d64,color:#24273a
    classDef action fill:#8aadf4,stroke:#494d64,color:#24273a
    classDef result fill:#a6da95,stroke:#494d64,color:#24273a
    classDef enrich fill:#8bd5ca,stroke:#494d64,color:#24273a
    classDef ext fill:#eed49f,stroke:#494d64,color:#24273a

    A[YouTube URL detected]:::step
    B[yt-dlp probe]:::ext
    C[Track discovery]:::action
    D{Auto or manual selection?}:::step
    E[Auto-select best tracks]:::action
    F[Manual picker — Ctrl+Alt+C]:::action
    G[Download subtitle files]:::action
    H[Convert TimedText to VTT]:::enrich
    I[Normalize auto-caption duplicates]:::enrich
    K[sub-add into mpv]:::action
    L[Overlay renders subtitles]:::result

    A --> B
    B --> C
    C --> D
    D -- startup --> E
    D -- user request --> F
    E --> G
    F --> G
    G --> H
    H --> I
    I --> K
    K --> L
```

## Auto-Load Flow

On startup with a YouTube URL:

1. mpv launches paused.
2. SubMiner calls `yt-dlp --dump-single-json` to probe all subtitle tracks.
3. Tracks are split into **manual** (human-uploaded) and **auto** (machine-generated) categories.
4. The selection algorithm picks:
   - **Primary**: first Japanese manual track, then Japanese auto track, then any manual track, then first available track.
   - **Secondary**: first English manual track, then English auto track (excluding the primary).
5. If mpv already exposes an authoritative matching track, SubMiner reuses it instead of downloading again.
6. Missing tracks are downloaded to a temp directory and loaded via `sub-add`.
7. Playback unpauses once the primary subtitle is ready.

## Manual Subtitle Picker

Press **Ctrl+Alt+C** during YouTube playback to open the subtitle picker overlay. This lets you:

- Browse all discovered tracks (manual and auto-generated)
- Select different primary and secondary tracks
- Retry track loading if the auto-load failed or picked the wrong track

The picker displays each track with its language, kind (manual/auto), and title when available.

## Subtitle Format Handling

SubMiner handles several YouTube subtitle formats transparently:

| Format | Handling |
| ------ | -------- |
| `srt`, `vtt` | Used directly (preferred for manual tracks) |
| `srv1`, `srv2`, `srv3` | YouTube TimedText XML --- converted to VTT automatically |
| Auto-generated VTT | Normalized to remove rolling-caption text duplication |

For auto-generated tracks, SubMiner prefers `srv3` > `srv2` > `srv1` > `vtt` (TimedText XML produces cleaner output). For manual tracks, `srt` > `vtt` is preferred.

## Configuration Reference

### Primary Subtitle Languages

```jsonc
{
  "youtube": {
    "primarySubLanguages": ["ja", "jpn"]
  }
}
```

| Option | Type | Description |
| ------ | ---- | ----------- |
| `primarySubLanguages` | `string[]` | Language priority for YouTube primary subtitle auto-loading (default `["ja", "jpn"]`) |

### Secondary Subtitle Languages

Secondary track selection uses the shared `secondarySub` config:

```jsonc
{
  "secondarySub": {
    "secondarySubLanguages": ["eng", "en"],
    "autoLoadSecondarySub": true,
    "defaultMode": "hover"
  }
}
```

| Option | Type | Description |
| ------ | ---- | ----------- |
| `secondarySubLanguages` | `string[]` | Language codes for secondary subtitle auto-loading (default: English) |
| `autoLoadSecondarySub` | `boolean` | Auto-detect and load matching secondary track |
| `defaultMode` | `"hidden"` / `"visible"` / `"hover"` | Initial display mode for secondary subtitles (default: `"hover"`) |

Precedence: CLI flag > environment variable > `config.jsonc` > built-in default.

## Limitations and Troubleshooting

- **No subtitles found**: The video may not have Japanese subtitles. Open the picker with `Ctrl+Alt+C` to see all available tracks.
- **yt-dlp not found**: Install `yt-dlp` and ensure it is on `PATH`, or set `SUBMINER_YTDLP_BIN` to the binary path.
- **Probe timeout**: `yt-dlp` has a 15-second timeout per operation. Slow connections or rate-limited IPs may hit this. Retry or update `yt-dlp`.
- **Auto-caption quality**: YouTube auto-generated captions vary in quality. Manual subtitles (when available) are always preferred.
- **`ytsearch:` targets**: `subminer ytsearch:"keyword"` plays the first search result. Subtitle availability depends on the matched video.
- **Secondary subtitle fails**: Secondary track failures never block playback. The primary subtitle loads independently.
- **Native mpv secondary rendering**: Stays hidden during YouTube flows so the SubMiner overlay remains the visible secondary subtitle surface.

## Related Pages

- [Usage --- YouTube Playback](/usage#youtube-playback)
- [Configuration --- YouTube Playback Settings](/configuration#youtube-playback-settings)
- [Configuration --- Secondary Subtitle](/configuration#secondary-subtitle)
- [Keyboard Shortcuts](/shortcuts)
- [Jellyfin Integration](/jellyfin-integration)