mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-03-26 00:26:05 -07:00
docs: apply M PLUS 1 and Manrope font defaults for docs content
This commit is contained in:
145
docs-site/youtube-integration.md
Normal file
145
docs-site/youtube-integration.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user