synctv/docs/playback-background-workers.md

# Playback Background Workers

Playback background workers use the current process's active room set as their scheduling boundary.

An active room for these workers means a room with at least one realtime connection registered in the local `ConnectionRuntime`. It is intentionally local-node state. In cluster deployments, the same room may be active on more than one node, and each node may attempt the same background work for that room.

This is a deliberate ownership boundary:

- a room with local realtime connections already has lifecycle state on the current node;
- background playback work only needs rooms this node can observe locally;
- global hot-room stats are presence/analytics data for lists, admin views, and metrics.

These workers run on every node so rooms connected to any replica receive duration probing, auto-advance, and playback resource lifecycle work.

Correctness for duplicate attempts belongs at the storage and state-transition layer:

- duration probing claims rows with database locks and `SKIP LOCKED`, so one worker owns a probe attempt;
- playback auto-advance uses the playback state transaction and optimistic version checks, so concurrent attempts converge to one committed state transition;
- workers use local realtime ownership, which keeps lifecycle work tied to rooms the node can observe.

Use shared presence or global hot-room queries for user-facing room lists and cross-node statistics. Use `ConnectionRuntime::active_room_ids()` for per-node playback lifecycle work. Use leader election for true singleton tasks such as partition management and cleanup.

This rule also applies when optimizing for fewer background scans. An active room already exists on one or more processes because clients are connected there. Each process scans its own active rooms, and the write paths provide the lock or version guard. Keeping analytics data out of lifecycle scheduling keeps live resource ownership easy to reason about.

## SQLx Query Cache

Repository queries for playback background work use SQLx checked macros. When any of these queries change, update `.sqlx` with `cargo sqlx prepare --workspace -- --all-targets`, then verify with `SQLX_OFFLINE=true cargo check --workspace --all-targets`.

Keep checked SQLx macros in repository code and treat `.sqlx` updates as part of the SQL change.

The room-scoped queries must keep the `room_id = ANY(...)` filter and the join to the current `room_playback_progress.target_hash`. The room filter preserves the local active-room scheduler boundary. The target hash binds media and dynamic playlist playback to the currently selected item.

Auto-advance must move state through the playback-state transaction and version write path. When several nodes scan the same active room, exactly one state transition should commit.

Finite sequential playlists persist a stable ended or paused state when there is no next item. The persisted end state lets later scan intervals skip the already-finished source.

## End-to-End Coverage

Playback background changes require manual end-to-end checks in addition to unit tests:

- start a built `synctv` binary so startup, config, migrations, and routes are covered;
- keep a room active through a real WebSocket connection;
- use `synctv` CLI for setup/control and `curl` for HTTP/media assertions;
- verify duration probing initializes metadata only for local active rooms;
- verify auto-advance advances once when multiple workers can see the same room;
- verify provider playback URLs by actually requesting direct/proxy/manifest/segment URLs;
- cover dynamic playlist media resolution, path return, switching, cover/thumbnail paths, and auto-advance target changes.

Provider E2E coverage should include Direct URL, Alist, Emby, Jellyfin, Bilibili anonymous playback, RTMP, live proxy, HLS, FLV, cache hit/miss, URL expiry, and cleanup behavior.

The scheduling source for these checks is `ConnectionRuntime::active_room_ids()`.
Presence hot-room queries are analytics inputs for lists and metrics. Playback
workers use local realtime ownership, and storage/state transitions provide
cross-node convergence.

Provider checks must request every mode and auxiliary URL returned in
`PlaybackResult`: upstream URLs, `proxy_*` URLs, manifests, indexed segments,
subtitles, danmaku, thumbnails, Range responses, cache hit/miss paths, expiry
handling, and live resource cleanup. Add `synctv` CLI coverage for workflows
that require manual verification, then exercise them through CLI plus `curl`.

Use cached playback results as part of the provider checklist. Cache hits and
fresh provider responses must expose the same usable mode names and resolver
actions, including MPD/HLS manifests and indexed segment routes.

RTMP and live proxy checks should prove the full lifecycle: create the publish
key or live proxy media through CLI, publish with a real upstream such as
`ffmpeg`, request stream info, fetch HLS playlists and segments, fetch FLV, stop
the viewer or publisher, and observe idle cleanup releasing the stream.

## Provider Playback Contract

Every Provider signs and finalizes playback inside `generate_playback`, then
serves every generated proxy action through its resolver.

`VersionedPlayback` is the cache payload plus proxy lookup index. The `version`
maps every generated `/stream`, `/m3u8`, `/mpd`, subtitle, danmaku, thumbnail,
FLV, and HLS segment URL back to the provider-owned playback result. Response
finalization applies the provider's signer/rewrite callback for the current
request. Policy still lives in that provider: mode names, default mode, header
exposure, direct/proxy shape, manifest metadata, and live lifecycle data.

| Provider | Coverage |
| --- | --- |
| Direct URL | upstream mode, `proxy_*` sibling, proxy default for header-bound sources, HLS segment rewriting, Range |
| Alist | direct/transcode modes, proxy siblings, thumbnail, subtitle, HLS segment, stream resolver |
| Emby/Jellyfin | upstream/transcode modes, proxy siblings, allowed token headers, stream/HLS/subtitle proxy |
| Bilibili | anonymous playback, DASH/MPD proxy default, proxied manifest segments, subtitle, danmaku, thumbnail, cache metadata |
| RTMP | publish key, stream info, HLS playlist/segment, FLV, provider-proxy URL, idle cleanup |
| live proxy | external RTMP/HTTP-FLV pull, HLS/FLV provider-proxy URL, publisher registration and unregister cleanup |