Playback And Recovery
Recover, replay, resume, fallback, and keep playback state predictable.
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, /recover | Refresh current provider intent |
| Fallback provider | f, /fallback | Next compatible provider |
| Recompute | /recompute | Bypass stale cache for current episode |
| Replay | /replay | Start current episode from beginning |
| Source / quality | k, /source, /quality | Switch within resolved inventory |
| 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, skipRecap, skipPreview, skipCredits | Auto-skip when IntroDB/AniSkip timing exists |
/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 requires timing metadata — not every title has it.
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.
- 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.
Related
- Providers — fallback chains and retry semantics
- Media selection — pickers and inventory model
- Diagnostics and reporting — evidence collection
- Commands and shortcuts — full command list
Last updated on