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. Results already in any watchlist are highlighted green and tagged with their watchlist name. - Filter Search results by Sub, Dub, or Sub + Dub (the default full result set) without changing the selected download mode.
- 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, Jellyfin handoffs and grouped AI subtitle translations 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.
- Backfill missing English subtitle sidecars for existing watchlist videos with Download all → Subtitles only, without downloading the video again.
- 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 TV seasons or movie folders to Jellyfin, then optionally request a scan of only the configured Jellyfin library.
- Catalog Jellyfin SRT/VTT subtitles and existing Czech ASS/SSA/SUB/TTML sidecars, including
cs/czlanguage suffixes. Queue English-to-Czech SRT/VTT translations for individual files, seasons or full series from AI Subtitles; existing Czech sidecars are shown and skipped. - Choose Ollama or the OpenAI API in Config → AI Subtitles, enter a custom endpoint/model, and load available models from the selected service. Ollama defaults to
http://192.168.88.15:11434withtranslategemma:4b; OpenAI defaults tohttps://api.openai.com/v1withgpt-4.1-mini. An OpenAI API key is required for OpenAI translation and is kept out of public config responses. OpenAI API billing is separate from ChatGPT subscriptions. - 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
The Watchlist Auto-download dialog's custom name and season control the final library path: for example, name My Series and season 3 produce tv/My Series/Season 03/My Series - S03E01.mp4. The source title continues identifying the provider anime. Saving these settings also updates unstarted pending downloads linked to that anime; save again after upgrading to apply them to existing pending jobs. Running jobs and retries with completed episodes keep their original layout, and existing files are not moved or renamed automatically. A custom library name entered in Search is retained when adding the result to the watchlist.
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.
For older videos, open the series card in Watchlist and choose Download all → Subtitles only. Kaizoku checks the selected season in its Downloads folder and the configured Jellyfin TV or movie folder (including Season 1 and Season 01 layouts), queues only existing videos without English or untagged subtitle sidecars, and tries available sub and dub provider streams for English external tracks. It saves a sidecar with the exact video basename, such as Old Show - S01E01.eng.srt, without changing the video, existing subtitles, watchlist download state, or sending a video-download notification. TV filenames must identify an episode using S01E01, Episode 1, or - 01 style numbering; movie folders must contain one video. The watchlist library name, season, and episode offset must match where the older files live. A job with no available external English tracks reports a failure in the Queue log; partially available tracks are saved and skipped episodes are listed there. If Refresh after handoff is enabled and a subtitle lands in Jellyfin, Kaizoku requests the same configured library refresh. Subtitles already embedded or burned into a video cannot be extracted by this action.
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. Manual Jellyfin handoff selects only watchlist entries whose expected episode videos are present in Downloads; the same check applies to automatic handoff. Completed TV handoffs move only the configured season, leaving other seasons in Downloads. Movies require a nonempty video file. 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.
AI Subtitles
Open AI Subtitles in the left menu. The catalog scans on application startup; Scan libraries refreshes it after adding or changing subtitles. It uses Config → Jellyfin TV/movie directories, falling back to /jellyfin/tv and /jellyfin/movies (the existing Docker mounts). TV titles are grouped by their top-level folder and season folder or Sxx filename; movies by their top-level folder. External .srt and .vtt files can be translated when they contain UTF-8 dialogue. Existing Czech .ass, .ssa, .sub and .ttml sidecars are catalogued as well, but cannot be translated here. Embedded tracks and other encodings must be extracted/converted first.
Choose Anime TV Shows or Anime Movies. Titles appear in a compact list with search, an All / 0–9 / A–Z filter and pagination. Choose 20, 50, 100, 200, 500 or All entries per page; the default is 50. Alphabet filters use the first character of the title (accented letters match their base letter). Search and alphabet filters work together.
Click a title, then Queue file, Queue season, or Queue full series / Queue movie. English tracks are translated to Czech; Czech tracks (cs, ces, cze, cz, or detected Czech text) remain catalogued and are skipped. Language labels come from filename suffixes or a conservative English/Czech text estimate. Confirm or correct uncertain labels using the language dropdown before queueing. Other languages are catalogued but not translated by this English-to-Czech workflow. Existing Czech sidecars for the same track are also skipped, including across supported catalog formats.
In Config → AI Subtitles, choose Ollama or OpenAI API, then set the endpoint and model. Load available models fetches the current model names; you can also enter a custom name. Ollama defaults to http://192.168.88.15:11434 and translategemma:4b; install that model with ollama pull translategemma:4b if needed. KAIZOKU_OLLAMA_URL and KAIZOKU_SUBTITLE_MODEL supply initial defaults for existing deployments, while saved Config values take precedence. OpenAI defaults to https://api.openai.com/v1 and gpt-4.1-mini and requires an API token. The token is stored in .kaizoku config, omitted from config API responses, and can be replaced or cleared from Config. The OpenAI API uses separate billing from a ChatGPT subscription. New jobs retain their chosen provider, endpoint and model for resuming; OpenAI jobs read the current saved API token when they run.
The Queue → AI Subtitles tab shows one job for each new single-file request or season/full-series request, with per-file status, combined cue progress and persistent logs for batch saves, retries, splits, failures and completion. Pause/resume controls affect the files in that job, and removing a finished/failed queue card only hides it; checkpoints and history remain. Existing jobs from earlier versions are preserved as individual queue entries because their original request grouping was not recorded.
After a rescan marks a subtitle missing, Remove missing hides its stale catalog entry. Pause any queued/running translation first. This action never deletes library files, checkpoints or queue history. A file that reappears is restored to the catalog on the next scan.
Use Review beside a translated file to open the English source and generated Czech cues side by side, with timing and length warnings. Unfinished jobs show their saved translations and blank cells for unfinished cues. The floating review window closes only with Close; outside clicks and Escape leave it open. Review is read-only and rejects a changed English source rather than pairing it with obsolete translations.
Translations run one file at a time in natural episode order, in batches of up to eight cues with preceding bilingual dialogue and recent examples from the same title. Add recurring names, preferred terms, honorifics, character relationships and speech styles under Terminology & character voices before queueing a title. Notes are captured when jobs are created, so a resumed translation uses the same notes. Translation memory, notes, catalog and per-batch checkpoints live in .kaizoku/ai_subtitles.sqlite3; keep this database with the rest of the persistent state.
The model receives dialogue with synthetic markers, never actual cue IDs or timestamps. Python preserves SRT numbering, timing, VTT identifiers/settings, headers, metadata, styling, BOM and newline format. Missing/duplicate/reordered cues, empty text, formatting changes, malformed responses and truncated output trigger up to three attempts per batch. Malformed batches are split into smaller groups, down to individual cues. If a single cue still loses inline formatting markers, Python keeps the original tags and whitespace and translates only the visible text spans, carrying preceding dialogue and already-translated spans as context. Empty or malformed span translations still fail validation; existing checkpoints remain available for retry. Resume / retry reuses saved batches; Pause preserves progress, although an in-flight model request can take up to three minutes to return. Pending/running jobs recover after restart; manually paused and failed jobs wait for you. Changed source files stop safely with their old checkpoints retained; restore the source to resume or use a new filename for a new job.
Cues exceeding two lines or 42 characters per line receive one shortening attempt. Remaining length warnings list cue positions for review. Translation quality and nuanced anime terminology still need human review, especially with a 4B model; structural validation cannot prove semantic accuracy. Completed translations are written alongside the source as Title.cs.srt or Title.cs.vtt (track qualifiers such as forced remain). Output is UTF-8, atomically published only after all cues validate, and never overwrites an existing file. Library mounts must permit creating files and hard links. Source subtitles, videos and existing Kaizoku state remain intact. Jellyfin discovers the new sidecars through its normal library scan; this page does not trigger a Jellyfin API refresh.
Rebuild/restart the Docker service after updating so the new page and worker are included. The existing Jellyfin and .kaizoku volume mappings are reused.