Playback and Recovery
Recover, recompute, replay, resume, and fall back: the five ways Kunai handles a stalled stream, and which one to reach for when playback stops behaving.
Kunai keeps playback centered on one shell session. After mpv exits, you return to Kunai with browse context, history, and recovery tools intact.
This guide covers the full playback lifecycle, from first resolve through recovery when providers or networks misbehave.
Playback flow
Search or continue
kunai -S "Title"
kunai --continue
kunai -i 438631 -t movieSearch lands on results unless you add --jump 1 or -q for auto-select.
Pick season, episode, and media options
When inventory has choices, Kunai shows source, quality, audio, and subtitle pickers. See Media selection.
Watch in mpv
Kunai launches mpv with required headers and subtitle attachments, then supervises through IPC.
Return to the shell
When mpv closes, Kunai shows post-play options: next episode, replay, fallback, diagnostics, or new search.
Resume and continue
Local watch history drives resume. Nothing leaves your machine unless you opt into sync.
| Entry | Behavior |
|---|---|
--continue / --resume | Newest unfinished history entry |
--history | Manual pick from watch history |
/history | Same from inside the shell |
| Resume overlay | When resumeStartChoicePrompt is on, choose resume vs start over before seek |
| Shared link timestamp | kunai:// t= applies once on first mpv launch, then per-episode history resume |
Episode numbers in the UI are 1-based. Providers adapt internally.
More: Continue watching and new episodes, Share links.
Recovery commands
Provider catalogs drift. Recovery is normal usage.
| Action | Keys / command | Effect |
|---|---|---|
| Recover stream | r in the recovery prompt or during playback, /recover | Refresh current provider intent |
| Refresh stream (in mpv) | Ctrl+R | Re-resolve the same episode without leaving playback |
| Resume saved position | Alt+R | Jump back to your last position after refresh |
| Fallback provider | ⇧F, /fallback | Next compatible provider |
| Recompute | /recompute | Bypass stale cache for current episode |
| Replay | /replay | Start current episode from beginning |
| Source | o, /source | Switch source / mirror |
| Quality | k, /quality | Switch quality |
| Reset provider health | /reset-provider-health | Forget down-provider memory so auto-fallback can retry |
| Clear cache | /clear-cache | Drop cached stream URLs |
| Diagnostics | /diagnostics | Runtime panel with attempt timeline |
| Export | /export-diagnostics | Redacted support bundle |
Try recover before fallback
Recover keeps the same provider and may reload mpv or re-resolve. Fallback switches providers and may change quality or subtitles.
Recovery mode
Configure in /settings or config.json:
- guided (default): explain failures; suggest recover then fallback
- fallback-first: move to next provider sooner after classified failures
- manual: you drive
/recoverand/fallback
See Customization and Providers.
Autoplay and auto-skip
| Setting | Effect |
|---|---|
autoNext | Advance to next released episode when current ends |
autoplayRecommendations | When caught up, countdown into top recommendation |
skipIntro | Auto-skip intros when timing exists (default on) |
skipCredits | Auto-skip credits when timing exists (default on) |
skipRecap | Auto-skip recaps (default off) |
skipPreview | Auto-skip previews (default off) |
/toggle-autoplay | Toggle autoplay for current session |
/toggle-autoskip | Toggle auto-skip for current session |
/stop-after-current | Finish current episode then stop chain |
Autoskip needs IntroDB (TMDB-keyed) and/or AniSkip (MAL-keyed, anime mode). Not every title has timing. Episode numbers in the UI are 1-based; providers adapt internally.
AniSkip for split-cour anime: when the only MAL mapping is TMDB season-1, Kunai skips AniSkip for season 2+ rather than applying the wrong show's windows. Miruro is keyed on AniList, where each cour is its own entry with its own MAL id, so that gap does not arise there; AniDB stamps MAL at resolve when it can.
Audio and subtitles
- Language profiles differ for anime, series, and movies (
animeLanguageProfile, etc.). - Kunai passes preferred subtitle first when launching mpv.
- Additional subtitle tracks attach when available; switch inside mpv without another lookup.
- Press
sduring playback to reload subtitles. - Late subtitle search uses Wyzie only when you set
wyzieApiKeyin Settings › Language. Kunai ships no key. - Source/quality/language variants prefer cached stream inventory to avoid extra network calls.
Use /source or /tracks during playback for the grouped media panel.
mpv supervision
Kunai monitors mpv through IPC and the Kunai bridge Lua script:
- Progress reporting for history and Discord presence
- In-process stream reconnect after network-read-dead stalls (configurable)
- Auto-skip overlay when timing metadata and autoskip are enabled
When playback recovers on its own (buffering clears, a stall resolves, or a
seek completes), the shell returns to playing as soon as fresh progress arrives,
so a transient hiccup no longer leaves the header stuck on "buffering" for the
rest of the episode. Recovery never overrides a deliberate state: pausing,
stopping, or finishing stays exactly as you left it, and only resuming restarts
playback. Diagnostics keep the record of the stall or the source switch even
after playback looks healthy again, so /diagnostics can still explain what
happened mid-episode.
Starting a new episode or stopping playback retires the old mpv session immediately. Late events from that retired session are discarded rather than applied, so a replaced episode cannot be revived by the previous one's activity.
Debug mpv for one run:
kunai --mpv-debug --mpv-log-file /tmp/kunai-mpv.log -S "Title"See CLI Reference.
Post-playback behavior
When mpv exits:
- Near end:
quitNearEndBehaviorcontrols whether autoplay may still advance - Autoplay chain: next episode resolves automatically when enabled
- Recommendation rail: optional compact suggestions after series completion
- History write: position and watched state persist locally
Queue recovery: if a previous session crashed with pending queue items, Kunai may show a recoverable queue notice. Restoring moves items into the current session without autoplaying them.
When playback fails
- Open
/diagnostics: read provider timeline and mpv/player section. - Press
rto recover. - Press
⇧Fif recover loops or failure class suggests provider exhaustion. - Export evidence:
/export-diagnostics.
Symptom-specific steps: Troubleshooting.
Offline playback
Completed downloads play through the same mpv path with local file URLs:
kunai --offline
/libraryOffline playback writes history with the same shape as online. Opening the offline library never calls providers.
More: Downloads and offline.
Last updated on
Media Selection
How Kunai picks a provider, source, and stream, then chooses quality, audio track, and subtitles, plus how to override each decision from the shell.
Continue Watching and New Episodes
How Kunai reconciles watch history, decides what counts as a new episode, raises notifications, and keeps your continue-watching list accurate over time.