Media Selection
How Kunai picks providers, sources, streams, audio, subtitles, and quality.
Kunai separates provider inventory (what the provider reported) from mpv state (what is actually playing). That split lets you switch streams quickly when inventory is cached, while still supporting fresh lookup when needed.
This guide explains what each picker means and when Kunai shows it.
Profiles by mode
Anime, series, and movie playback each has its own media profile in config.json:
| Mode | Config key | Typical fields |
|---|---|---|
| Anime | animeLanguageProfile | audio, subtitle, quality |
| Series | seriesLanguageProfile | audio, subtitle, quality |
| Movies | movieLanguageProfile | audio, subtitle, quality |
Example:
{
"animeLanguageProfile": { "audio": "ja", "subtitle": "en", "quality": "1080" },
"seriesLanguageProfile": { "audio": "en", "subtitle": "en" },
"movieLanguageProfile": { "audio": "en", "subtitle": "en" }
}These preferences flow into provider resolution first, then into mpv as player hints. Episode numbers remain 1-based in the UI.
Additional anime display preference:
animeTitlePreference— English, romaji, native, or provider-native title labelsfavoriteSources— pin preferred source/server names to the top of pickers
Configure in /settings. See Customization.
What the pickers mean
Kunai only shows controls when inventory has more than one useful choice. A title with one stream and one subtitle should not grow a noisy menu.
| Picker | What it chooses |
|---|---|
| Provider | Which registered provider resolves the title (before or during playback) |
| Source | Provider source or mirror family when multiple exist |
| Stream | Full playable stream inventory for the current episode |
| Quality | Narrow streams by quality label or rank |
| Subtitle | Soft subtitle track when already known; may trigger lookup if not |
| Audio / hardsub | Language or hardsub variant within cached inventory |
Open the grouped panel during playback:
/source
/tracks
/kJump directly when a section has alternatives:
/qualityResolution vs playback state
Provider resolve
→ source inventory (sources, streams, subtitles, trace)
→ selected stream candidate
→ mpv launch (active track, position, headers)
→ mpv state (what player reports back)Diagnostics shows both layers without exposing signed URLs:
- Inventory — what Kunai knows from the last resolve
- mpv state — what is actively playing or stalled
When you switch a known stream, Kunai prefers cached inventory. When you ask for a language or quality not yet discovered, Kunai may run provider lookup again.
Anime vs series/movie behavior
Anime providers often expose:
- Sub vs dub as separate streams
- Hardsub variants
- Multiple source families (fansub groups, official mirrors)
Kunai treats each as stream candidates in the same inventory model. The anime language profile selects defaults; pickers let you override per session.
Default provider and fallback: animeProvider, animeProviderPriority — see Providers.
Series and movie providers more often expose:
- Quality tiers (720p, 1080p, etc.)
- Subtitle language differences
- Fewer distinct source families
The same picker model applies — Kunai does not force a different UI per provider type.
Default provider and fallback: provider, providerPriority.
Auto-selection rules
When multiple streams match your profile, Kunai ranks by:
- User favorites (
favoriteSources) - Profile language and quality match
- Provider default ranking and health signals
- Cached selection from previous watch on same title
You can always override before or during playback.
Switching during playback
| Situation | Best action |
|---|---|
| Wrong subtitle language | /source → subtitle section |
| Want higher quality | /quality if alternatives exist in inventory |
| Stream stalled | r recover first; then /source if inventory has alternates |
| Provider exhausted | f fallback — see Providers |
| Inventory looks stale | /recompute bypasses cache for current episode |
Inventory-bound switching
Switching source/quality/subtitle from pickers avoids full re-resolve when the provider already reported those candidates. If nothing matches, Kunai fetches fresh inventory.
Provider priority and per-title overrides
Session default provider comes from config. Per-title overrides (titleProviderPreferences) win on resume when you explicitly picked a provider earlier.
Example flow:
- Start "Show X" with Videasy.
- Playback fails; you fallback to VidLink and continue.
- Kunai may store VidLink preference for "Show X" on explicit pick.
See Customization.
Diagnostics for selection issues
When pickers look empty or wrong:
/diagnostics→ provider timeline (did resolve return inventory?)- Check failure class — empty inventory vs filtered-out streams
/recomputeif cache may be stale/export-diagnosticsif reporting upstream
More: Diagnostics and reporting, Troubleshooting.
Related
- Providers — fallback and resolve behavior
- Playback and recovery — hotkeys and recover flow
- Customization — language profiles and favorites
Last updated on