# 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 1. Enable **Queue**. 2. Enable **Anime Providers**. Configure **Anime Search** to use that provider plugin, choose `anikoto` or `pahe`, 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. 3. Configure/enable **Thumbnails** (Queue plus AnimeSchedule, or a provider-supplied image URL with trusted hostnames). Images are cached privately and served through authenticated routes. 4. 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. 5. 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/v1` endpoint. Nothing calls an AI service until a translation job is submitted. 6. 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. 7. 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 `/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`. ```sh 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...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](https://gitea.coreplay.eu/Dymas/web-framework-resources/wiki/media-suite). ## 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](watchlist.md), [Thumbnails](thumbnails.md), [Anime Search](anime-search.md), [Anime Providers](anime-providers.md), [Media Handoff](media-handoff.md), [AI Subtitles](ai-subtitles.md), [Discord Notifications](discord-notifications.md). ## 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.