Files
web-framework-resources/docs/media-handoff.md
T

3.1 KiB

Media Handoff

The media-handoff capability accepts completed Watchlist items and performs verified per-season library transfers. Configure Queue, mounted source root, target library root, mode (copy by default, or move), and optional subtitle/notification implementations. Roots must exist, be separate and not contain each other. For automatic subtitles, configure that provider's root to the same target library folder. See Docker mounts.

Handoff.submit(item) requires category finished, title and relative media_path, validates season and (for TV) a positive expected episode count, snapshots copy/move mode, and returns a queued job ID. Item fields are title, category, media_path, season, expected and media_type (tv/movie/generic). roots() checks configured paths and rejects overlap. process(payload, progress) repeats readiness checks before mutating files.

Transfer algorithm

  1. Resolve the relative source/target paths within operator roots, rejecting traversal and symbolic links.
  2. For TV, require a matching Season NN directory. Collect nonempty video files from that season and any existing target from an earlier partial transfer. Require every episode 1 through expected using matching SxxExx names or numbered stems within the verified season directory. Movies/general media require a nonempty video file.
  3. Preflight every source file and every existing destination. A differing destination fails before any file is copied. Existing identical files are reused.
  4. Copy through a temporary file in the target filesystem, fsync, verify SHA-256 and publish without overwriting a concurrent destination. Transfer all sidecars within that selected season, preserving sibling seasons.
  5. Verify all destinations. Move mode removes a source file only after its source and target hashes match; copy mode retains originals. Empty directories within the selected season can be removed after verified moves. Retries reuse matching files and can complete partially moved seasons using the already transferred target files.
  6. Optionally submit transferred SRT/VTT files to the selected subtitle service, record history, enqueue a media.handoff notification and report completion.

digest(path, heartbeat) streams hashes and renews the queue lease during long operations. Progress points enforce active/cancelled claims before later mutations. Cancellation is cooperative; verified target files can remain after partial work. A failed subtitle/notification integration does not roll media back or overwrite originals. Queue retry is explicit. A source-missing but complete existing target is reported already present.

GET /plugins/media-handoff/ shows manual submission and recent completed transfers. POST / requires content.write and CSRF, submits a declared-finished season/movie and redirects. service(), index() and submit() are route adapters. Successful history stores title, relative path, file count, mode and timestamp in plugin_data. This plugin does not provision a Jellyfin server or trigger a Jellyfin library scan; it hands files to any configured media-library directory.