11 KiB
Modular media plugins
The media suite adapts Kaizoku's watchlist/scheduler workflow, provider bridge, subtitle formatting, and per-season library handoff into independent resource packages. Source reference: Dymas/kaizoku b20ac193431f423036b05fa21e4e1a75a7728b96. Existing Kaizoku data is not modified or implicitly migrated.
Upgrade the framework to 0.9.0 or newer first. Install Queue and the desired media packages through Add resources, then restart once to discover them. All packages remain disabled until enabled. In framework 0.9.2+, newly installed packages appear immediately in Config → Plugins as pending restart; restart to load Settings, then enable providers before consumers. Each card and settings window identify missing or disabled dependencies. Watchlist and AI Subtitles both need Queue installed and enabled. Only enabled plugins with their own page appear in the menu. Newly developed plugin implementations live entirely in the adjacent resource repository.
Setup order
- Enable Queue.
- Enable Anime Providers. Configure Anime Search to use that provider plugin, choose
anikotoorpahe, then enable it. AniNeko is retired and only retained for legacy IDs. The provider bridge includes source and GPL-3.0-or-later attribution. It performs search/metadata requests, not media downloads. - Configure/enable Thumbnails (Queue plus AnimeSchedule, or a provider-supplied image URL with trusted hostnames). Images are cached privately and served through authenticated routes.
- Optionally configure Discord Notifications with Queue, an official webhook URL, and allowed event names. Saved webhooks are encrypted/write-only. Enabling does not send a message; the test button or connected plugin event submits a delivery job.
- Optionally configure AI Subtitles with Queue, a mounted library root, backend URL, model, source/target languages, and language code. Ollama runs separately; its URL must be reachable from the application container. For OpenAI, use the configured model, API key and
https://api.openai.com/v1endpoint. Nothing calls an AI service until a translation job is submitted. - Configure Media Handoff with source and target roots, copy/move mode, and optional subtitle/notification providers. The subtitle root must match the target library root for automatic post-handoff subtitle jobs.
- Configure Watchlist with the desired search, thumbnail, handoff and notification plugin IDs, or leave optional integrations at None. Enable it. Manual entries work without anime metadata integrations. Enable its scheduler when automatic refreshes/handoffs are wanted and choose an interval of 60–604800 seconds.
The settings UI lists installed plugins advertising the required capability. A selected provider must be enabled before enabling its consumer. Active selected providers cannot be disabled until consumers are reconfigured or disabled. Alternative plugins can replace implementations by publishing the same capability contract. Anime Search's Add to watchlist action chooses an active Watchlist provider at submission time, avoiding a circular saved dependency.
Data and workers
Background workers run by default in the workspace process; [runtime].background_workers = false disables them for embedded/manual processing. Plugin workers poll only enabled providers. New packages register one bounded worker iteration at a time; queued work uses FIFO claims and a 30-minute renewable lease. Disabling a plugin prevents later iterations and cooperative progress points. Existing arbitrary Python/network calls finish within their configured timeouts. Queue cancellation is cooperative, not a process kill.
Watchlist entries and scheduler due times persist in control SQLite. The scheduler advances a due time atomically before queuing work, so independent schedulers sharing that store do not queue the same due slot. Refreshes report available episodes, not downloaded completion. Mark media finished and provide a relative media/season folder and expected episode count before handoff. Queue logs/progress cover refreshes, thumbnails, handoffs, subtitles, and notifications.
Media roots and subtitle originals are external files. Thumbnails live in <data_dir>/plugins/thumbnails; jobs, checkpoints, metadata and secrets remain in the persistent control store. Back up control data, the key, resource mounts and media/library folders together. Job delivery is at least once; retries can repeat a network request or notification. Subtitle checkpoints avoid repeating completed batches, and existing matching outputs are reused.
Docker mounts
The image contains Node.js and locked Axios/Cheerio dependencies for the provider bridge. It does not create an Ollama server, a Discord webhook, or media files. For source installs, install Node.js and run npm ci --omit=dev in the installed Anime Providers folder, or set NODE_PATH to the locked dependencies under deploy/node-runtime/node_modules.
export WEB_FRAMEWORK_MEDIA_SOURCE=/absolute/host/downloads
export WEB_FRAMEWORK_MEDIA_LIBRARY=/absolute/host/library
docker compose -f compose.yaml -f deploy/compose.media.yaml up -d
Configure Handoff roots as /media/source and /media/library; configure Subtitles root as /media/library. Host directories must already exist. Allow application UID/GID 10001 the required read/write access. The overlay does not change existing ownership and mounts the source read-only by default. Copy mode retains originals. To intentionally enable move mode, use a writable source mount (WEB_FRAMEWORK_MEDIA_SOURCE_READ_ONLY=false) and choose move in Handoff settings. Copy/move roots must not be nested.
TV handoff operates only on Show/Season NN, verifies the selected season and expected numbered video files, preserves other seasons, preflights all destination conflicts and verifies SHA-256 before removing sources. Originals and conflicting destination files are never overwritten. Subtitle processing creates separately named .ai.<language>.<fingerprint>.srt/vtt files; original timestamps, VTT metadata and formatting are preserved.
Full plugin function/route references and integration tests are maintained in the resource wiki.
Capability interfaces
| Capability | Provider package | Required public methods |
|---|---|---|
queue |
queues | enqueue, claim, progress, complete, fail, jobs, get |
anime-provider |
anime-providers | search(query, provider=..., page=1), info(identifier, provider=...), episodes(identifier, provider=...) |
anime-search |
anime-search | search(query, page=1), info(identifier), episodes(identifier) |
thumbnails |
thumbnails | request(title, image_url=''), get(title) |
watchlist |
watchlist | add(title, external_id=..., category=...), items(), get(id), edit(id, ...), handoff(id) |
media-handoff |
media-handoff | submit(item) |
subtitles |
ai-subtitles | submit(relative_path) |
notify |
discord-notifications | send(event, message) |
Resolve selected settings with get_plugins().resolve(consumer_id, setting_name). These are trusted internal Python contracts; browser endpoints remain authenticated, permission checked, CSRF protected and template escaped. Optional selectors may return None. Service references retained by plugins still check activation at operation boundaries. Selecting another conforming implementation changes integration routing without editing Watchlist source.
Function references: Watchlist, Thumbnails, Anime Search, Anime Providers, Media Handoff, AI Subtitles, Discord Notifications.
Validation
Run PYTHONPATH=../web-framework ../web-framework/.venv/bin/python -m pytest tests plugins/queues/tests -q from this repository. tests/test_media_plugins.py covers provider selection, real persisted queue jobs, scheduler execution without browser traffic, search-to-watchlist routing, thumbnail bytes/authentication, collision/missing-file/symlink/season/path rejection, copy/move/idempotency, original subtitle preservation, cue/format validation, OpenAI Responses request shape, notification filtering, secret storage and mention suppression.
Run tests/browser_media_check.py with the same Python/PYTHONPATH and a Playwright Chromium installation for the complete UI workflow and mobile layout. Those tests mock external providers, AI and Discord; no paid calls or real messages are sent. Public read-only checks on 2026-10-29 verified provider module loading, Anikoto search and AnimeSchedule metadata availability. Provider access remains dependent on external sites.
Availability check on 2026-10-29: Anikoto search returned 26 results for the test query and AnimeSchedule metadata returned HTTP 200. AnimePahe search returned HTTP 403 from the test host. The adapter is included, but that upstream restriction is not bypassed. AniNeko remains retired.
Framework 0.9.1+ opens Settings for in a floating settings window. Integration selectors and Save keep their existing behavior. Long forms scroll internally; Cancel, ×, Escape or the backdrop close the window and discard unsaved edits.
Catalog dependencies (resource release 0.5.0)
Every plugin manifest and generated catalog entry now contains dependencies, an array of default required plugin IDs. Watchlist, Thumbnails, Media Handoff, AI Subtitles and Discord Notifications require queues; Anime Search requires anime-providers. Queue, Anime Providers and the three starter plugins declare []. Optional Watchlist/search/thumbnail/handoff/notification integrations remain selections in settings and are not automatically installed.
Framework 0.10.0+ displays these requirements in a floating window before installation. Install adds all missing direct/transitive packages; Ignore installs just the selected plugin; Cancel installs nothing. Installed packages are retained and any missing dependencies of those packages are included. Restart to load newly installed code, then configure and enable providers before consumers. Earlier frameworks still install the same compatible packages but do not offer dependency groups.
The catalog builder validates unique slug IDs, existing local dependency targets and absence of cycles before writing the catalog. Tests compare metadata dependencies with every plugin's static requirements and mandatory service defaults, and verify runtime/manifest/archive versions match. Package metadata changes ship as new patch versions (0.1.1 for Queue/media providers; 0.2.1 for starters). Existing archives remain unchanged; changed published source must receive a new version.