Kaizoku
Kaizoku is a local web app for searching, tracking, and downloading anime from Anikoto, AniNeko, and AnimePahe. It keeps its own SQLite state under .kaizoku/, resolves streams through bundled JavaScript provider modules, and finalizes downloads into Jellyfin-friendly TV or movie folders.
Features
- Search anime through the configured provider and tag results with available
SUBandDUBepisode languages, ignoring empty provider language groups that do not expose playable servers. - Choose the active provider from Config defaults or directly from the Search page.
- Prefer provider-supplied search artwork, with a local title-based thumbnail fallback when provider artwork is missing or broken.
- Fill Watchlist thumbnails from AnimeSchedule or AniDB title metadata when provider artwork is missing.
- Queue single episodes or batches in subbed or dubbed mode.
- Monitor downloads and Jellyfin handoffs in separate Queue tabs, with compact collapsible jobs, per-episode download progress, segment counts, live downloader output, and episode-by-episode copy status.
- Open result actions in a floating window for watchlist, media type, subbed/dubbed mode, library name, season, episode range, and download folder choices.
- Fall back across the other configured providers when an episode or stream cannot be resolved on the primary provider.
- Save files with Jellyfin-friendly layout:
TV/Series Name/Season 01/Series Name - S01E01.mp4, including Season 00 for specials. - Save English external subtitles when the provider exposes usable subtitle tracks.
- Manage focused watchlists for
Watching,Planned,Finished, andDropped, with provider source tags and title links back to the original provider page. - Periodically refresh selected watchlists with a single visible advancing progress bar and auto-download newly available episodes.
- Sync watchlist download flags from completed video files on the filesystem; subtitles, metadata, and partial downloads do not count as downloaded episodes or movies.
- Hand completed libraries to Jellyfin TV or movie folders, then optionally request a scan of only the configured Jellyfin library.
- Export/import watchlist backups.
- Send unified Discord notifications for downloads, refreshes, Jellyfin handoff, and runtime errors.
- Check bundled provider JavaScript against upstream
TheYogMehta/extensionsfrom the Config page. - Store configuration, queue state, and watchlist data in SQLite under
.kaizoku/.
Requirements
- Python 3.12 or newer.
- Node.js and npm for the provider bridge.
ffmpegavailable inPATH.opensslavailable inPATHfor AES-128 encrypted HLS segments.pytestis optional; the current regression tests areunittest-compatible and can run with the Python standard library.- Docker builds install the locked Node dependencies with
npm ci; rebuild the image after dependency updates.
Install Node dependencies once:
npm install
Run locally:
./kaizoku
Then open:
http://127.0.0.1:8421/
For Uptime Kuma or another HTTP availability monitor, use http://IP:PORT/status. GET returns HTTP 200 with OK; HEAD also returns HTTP 200. The endpoint needs no authentication and reports whether Kaizoku's HTTP server is responding. It does not check provider or download health. For a monitor on another machine, bind Kaizoku to a reachable address and set KAIZOKU_ALLOW_REMOTE=1; the normal app and API routes still require configured credentials for remote clients.
For a dashboard, request GET /api/watchlist/homepage?include_downloads=1. The usual watchlist, planned, finished, dropped, and total counts remain, and downloads adds total, running, pending, failed, and a jobs array. downloads.total counts the jobs in these three states. Each job includes id, name, title, status, episodes, mode, provider, and available progress fields such as percent, episode, and message. name is the task name, with title retained for existing dashboard clients. The array lists running, pending, and failed downloads in that order, including live progress for the current job; completed and canceled jobs and Jellyfin handoffs are excluded. Without the query option, the response has the original counts only. This route always requires HTTP Basic auth, even for local requests. It uses the KAIZOKU_AUTH_USERNAME and KAIZOKU_AUTH_PASSWORD supplied to Docker Compose; set both before starting the container. A missing or invalid Basic header receives HTTP 401 with a WWW-Authenticate challenge.
curl -u 'admin:your-password' 'http://IP:PORT/api/watchlist/homepage?include_downloads=1'
Run the local regression tests:
python3 -m unittest -q
Useful environment variables:
KAIZOKU_HOST=0.0.0.0KAIZOKU_PORT=8421KAIZOKU_ALLOW_REMOTE=1to allow non-loopback clients.KAIZOKU_AUTH_USERNAME=adminandKAIZOKU_AUTH_PASSWORD=choose-a-long-random-passwordfor remote access.KAIZOKU_JOB_STDOUT=trueto mirror job logs to container or terminal output.KAIZOKU_STATE_ROOT=/path/to/stateto move SQLite state, config, thumbnails, sessions, and staging.KAIZOKU_DOWNLOAD_DIR=/downloadsfor the default library output path.KAIZOKU_REMOTE_PATH_ROOTS=/downloads,/jellyfin/tv,/jellyfin/moviesto limit remote filesystem browsing; comma-separated and platform path separators are accepted.KAIZOKU_MODE=sub,KAIZOKU_QUALITY=best, andKAIZOKU_DEBUG=1for runtime defaults and diagnostics.KAIZOKU_SEGMENT_RETRIES=8,KAIZOKU_SEGMENT_RETRY_DELAY=1.25,KAIZOKU_SEGMENT_RETRY_MAX_DELAY=15, andKAIZOKU_SEGMENT_DOWNLOAD_DELAY=0to tune retry/backoff and optional pacing behavior for native HLS segment downloads. Retries cover temporary HTTP responses, DNS failures, connection errors, and socket timeouts.KAIZOKU_MEDIA_HTTP_CLIENT=autoto let protected HLS segment fetches fall back from Python HTTP tocurlor curl-impersonate afterHTTP 403; usecurlorurllibto force one client, andKAIZOKU_CURL_BIN=/path/to/curl_chrome142to prefer a specific curl-compatible binary. Playlist, segment, and encryption-key requests preserve provider CDN session cookies for the duration of the download process.
Docker
docker compose up -d --build
The compose file builds the local checkout and runs Kaizoku on port 8421 by default. KAIZOKU_PORT changes the published host port; the app continues listening on port 8421 inside the container. It mounts:
./downloadsto/downloads${JELLYFIN_TV_DIR:-./jellyfin/tv}to/jellyfin/tv${JELLYFIN_MOVIE_DIR:-./jellyfin/movies}to/jellyfin/movies./.kaizokuto/app/.kaizoku
Use /jellyfin/tv for the Jellyfin TV directory and /jellyfin/movies for the Jellyfin movie directory inside the Config page. Override JELLYFIN_TV_DIR and JELLYFIN_MOVIE_DIR to point those container paths at your real host Jellyfin library folders.
If filesystem monitoring is unavailable (for example with some Samba mounts), enable Refresh after handoff and enter the Jellyfin server URL, an API key created in Jellyfin's API Keys dashboard, and the exact library name or item ID. After a successful handoff batch copies all queued files, Kaizoku resolves that virtual library and calls Jellyfin's item-refresh API once. It does not start the server-wide /Library/Refresh scan.
Kaizoku sends the API key with Jellyfin's current Authorization: MediaBrowser scheme, which is required by Jellyfin 12 and remains compatible with earlier supported servers.
The Docker image installs Python, Node.js, npm, curl, curl-impersonate browser wrappers, ffmpeg, openssl, and util-linux for optional UID/GID switching, then runs npm ci --omit=dev for the provider bridge. Downloads go through Kaizoku's provider bridge and provider_downloader.py.
Useful Compose overrides:
KAIZOKU_PORT=8080 docker compose up -d --build
KAIZOKU_ALLOW_REMOTE=1 KAIZOKU_AUTH_USERNAME=admin KAIZOKU_AUTH_PASSWORD='change-me' docker compose up -d
USER_UID=$(id -u) USER_GID=$(id -g) docker compose up -d
When USER_UID and USER_GID are set, the entrypoint attempts to adjust ownership for /downloads, /jellyfin/tv, /jellyfin/movies, and Kaizoku state paths. Ownership changes are best-effort so policy-managed or read-only Jellyfin mounts can still be browsed and used when their existing permissions allow it.
Keep ./.kaizoku mounted for production instances. That directory contains the SQLite database, configuration, queue history, watchlist data, thumbnail cache, remote sessions, and temporary staging files. Removing the mount starts Kaizoku with a fresh empty state.
Download Flow
Anikoto searches use the site's filter endpoint, which supports paginated queries. When Anikoto returns HTTP 500 for a query, Kaizoku retries with the lowercase phrase and then its first meaningful word. The fallback results may be broader than the original phrase. If a provider remains unavailable, Search shows a temporary-unavailability message instead of an unexpected application error. AnimePahe checks each of its configured mirrors once per search, so a blocked API does not cause repeated wait cycles.
Kaizoku stores provider-backed show IDs as provider:id, for example anikoto:some-show-slug. Queue jobs resolve the episode source through providers/bridge.js, then provider_downloader.py downloads the media with ffmpeg into a staging directory. If a provider returns multiple servers for the requested sub or dub mode, Kaizoku tries every same-mode server source in quality order before falling back to another provider, including when resolving one server's playlist raises an HTTP error. It does not use sub sources for dub downloads, or dub sources for sub downloads. If a provider returns a master HLS playlist, Kaizoku selects the highest-bandwidth variant before starting ffmpeg. When a media playlist uses extensionless, SnapCDN, or disguised CDN segments, Kaizoku skips direct ffmpeg and uses a StrawVerse-style segment downloader; if HLS preflight fails, it stays on that native path instead of falling through to ffmpeg. The native downloader fetches the media playlist, preserves provider CDN session cookies across playlist, segment, and encryption-key requests, downloads and concatenates segments itself with browser-like media headers and the provider referer, can fall back to curl-impersonate browser wrappers after protected CDN HTTP 403 responses, strips short PNG wrappers when present, retries temporary HTTP failures such as 429 Too Many Requests, optionally paces requests with KAIZOKU_SEGMENT_DOWNLOAD_DELAY, then remuxes the local transport stream to MP4. Direct ffmpeg attempts also have a timeout guard so stalled HLS inputs can fall back cleanly. Each episode is written as a temporary .mp4.part file and moved into the downloads library after that episode succeeds, so already-finished episodes from a larger batch survive if a later episode fails. Retrying that failed queue job requests only the remaining episodes while keeping the original episode range for display and watchlist sync. Finalization preserves episode numbers from staged SxxEyy or Episode yy filenames before applying configured season/episode offsets.
Provider bridge subprocesses time out after 120 seconds by default. Watchlist refreshes apply their shorter request timeout to each metadata and episode-list call, so an unresponsive bridge can fail and allow subsequent work to continue. Fractional episode numbers such as 12.5 keep distinct filenames instead of colliding with episode 12.
Provider server aliases that resolve to the same URL and request headers are downloaded only once, avoiding duplicate CDN requests and unnecessary rate limiting.
When the selected source exposes English external subtitle tracks, Kaizoku saves the first successfully fetched track alongside the video as .eng.vtt, .eng.srt, .eng.ass, or .eng.ssa. Subtitle requests use provider/track headers, session cookies, retries, and the media HTTP fallback. Subtitles move into the library with each completed video and keep matching filenames after custom naming, season/episode offsets, or filename collisions. Subtitle failures do not fail an otherwise completed video; the queue log reports failed tracks or that no English external track was exposed. Burned-in subtitles cannot be saved as a separate file, and Kaizoku does not extract embedded or HLS-playlist-only subtitle tracks. The bundled AnimePahe adapter currently exposes no external subtitle tracks. These changes apply to new downloads and do not backfill subtitles for existing videos.
If the primary provider cannot list, resolve, or download a requested episode, Kaizoku searches the selected provider's title on the remaining providers and tries the matching episode there. A custom library name is used only for output naming. Fallback requires a unique normalized title match, retaining season, part, and cour labels; equivalent notation such as Season 2 and 2nd Season is accepted. Shared words or a matching title prefix are insufficient. Ambiguous results, different seasons, and titles that cannot be verified (including alternate translations) are skipped. If no matching source succeeds, the job fails while preserving completed episodes. This prevents unavailable later-season episodes from being silently replaced with season 1 episodes; it does not identify or repair previously downloaded incorrect files. Existing finalization code moves staged files into the configured library layout, preserving data already present in production download folders. If a library move fails, the queue reports failure and leaves remaining completed files in the staging folder shown in the job log for manual recovery. Resolve the storage/permission problem and recover those files before retrying the download.
Data Safety
Kaizoku uses additive SQLite migrations for queue and watchlist schema changes. Upgrades do not delete configuration, watchlists, queue history, or downloaded files. Jellyfin handoff moves only completed library folders that pass the existing readiness checks, and both manual and automatic handoffs are persisted with per-episode progress in the Jellyfin Queue tab. Handoffs keep videos and subtitle sidecars paired when destination names collide, preserving existing files with numbered names for the incoming pair. Source and target folders must not contain each other; overlapping folders are rejected before moving files.
Provider Source
The Anikoto, AniNeko, and AnimePahe parser modules in providers/extensions/Anime/ are adapted from TheYogMehta/extensions and retain their GPL/license headers. The bundled anime provider versions are currently:
- Anikoto
5.0.4with Kaizoku patches - AniNeko
3.0.4 - AnimePahe
5.0.6with Kaizoku bridge patches
All three modules were checked against upstream tree ae21244a5f3cabc58bd281fff0b3560cbfb7a0f8 on 2026-10-12. AnimePahe includes the upstream same-version UUID recovery update.
The Config page checks the bundled JavaScript against the upstream main branch and reports whether upstream updates are available. The patched Anikoto and AnimePahe modules keep their official version numbers and are reported separately as local changes while their upstream bases are current. Kaizoku acts as a local client-side parser/downloader wrapper and does not host media.