ADR: Playback is a host feature with one core
- Status: Accepted (decisions made with the maintainer on 2026-11-19). Decisions 1 to 8 are built (8 in the player API ADR); 9 is planned
- Date: 2026-11-19
- Related: Library data model, Patron scopes and linked sign-in, Event delivery model, Untrusted-input fuzzing
Bookclerk acquires audiobooks and files them on storage destinations, but
until now nothing in it played one. People listened in another server's
app and Bookclerk imported their progress from there
(listening_progress, one row per provider and work).
Three players are wanted: the web app, the desktop window, and the phone
and car apps people already use with an Audiobookshelf server. Each needs
the same things from the library: which files an edition is, whether this
person may hear them, the bytes by Range, and somewhere to keep the
position. Building those three times would give three answers to "may this
person play this".
Two shapes were considered and rejected:
- Serve app compatibility from the
audiobookshelfplugin. That plugin links Bookclerk to someone's Audiobookshelf server. Serving a player API from it would mean plugins handling arbitrary inbound HTTP routes, which the plugin ABI does not do and should not grow to do. - A "streaming copy" setting per destination. Players read the copy the library already keeps. A second, stream-shaped copy adds storage and a setting for no gain while transcoding is not built.
The player is a native feature. Its tables, routes and rules live in the
host (bookclerk-library and bookclerkd), and no plugin entrypoint is
added or changed for it. The plugin ABI is not widened to carry general
HTTP handling or routes a plugin was not designed around.
Everything a player needs comes from one core:
- the tables
playback_progress,playback_sessionsandbookmarks; - the routes under
/api/playbackand/api/library/editions/{id}; - one stream route that serves an edition file by
Range; - three host events and one live topic.
The web player, the desktop window's native engine and the app-compatible API (decision 8) are faces over that core. A face adds its own wire shape and nothing else: it keeps no progress, checks no rights and reads no files of its own.
playback_progress is keyed (user_id, edition_id). An abridged and an
unabridged recording, or two narrators, are different editions with
different timelines, so a position in one means nothing in the other.
Finishing is a fact about the work: when a listener reaches the end of an
edition (the last 1 percent, or the last 30 seconds of a recording longer
than a minute), the same batch sets user_title_state.is_finished for the
edition's work. Opening a finished edition again starts it over and clears
the edition's flag; the work stays finished.
listening_progress is unchanged. It holds what other servers report,
per provider; playback_progress holds what Bookclerk's own players
report.
control_plane::plan_playback answers whether a person may play an
edition and which files that means. It is the rule a copy grant uses (the
titles of the edition the person may see, and the edition's files on each
destination), narrowed to audio: the primary file and its parts, not
per-chapter files, covers or documents. The manifest, a new session and
every stream request call it.
A patron scope is applied before it, as on every library page: an edition
outside the caller's scope is 404, the same answer as an unknown id.
The Download member control
(patron scopes ADR) does not cover
streaming. It stops taking copies to keep: downloads to a branch or a
clerk, and an app's offline downloads. A patron who can see a book may
listen to it, which is what the apps the /player API serves expect.
POST /api/playback/sessions records the person, the edition, this node,
the destination and a digest of the edition's files there. A stream
request is served only when:
- its caller is the session's person, signed in now;
- the session is open and was reported on within 24 hours;
- this node opened it;
- the edition is still in the person's scope and
plan_playbackstill gives the same files (same digest) on the same destination.
So a right that ends, a scope that narrows or a file that is replaced
stops the next request. The player is told 409 session_ended and opens
a new session, which gives the real answer.
The session cookie is the credential on the stream route too. An <audio>
element on the app's own origin plays with no token in a URL, so nothing
secret reaches logs, history or a Referer. The stream route streams
from the destination with the code a copy download uses; nothing is
staged or decoded in the host.
Closed sessions are kept as listening history (what was played, on which kind of player, for how long). They hold no file keys.
A player reports its position every few seconds. A report updates the session and the progress row in one batch and publishes nothing.
The host publishes, best effort after the write:
| Event | When |
|---|---|
playback_started |
A session opens |
playback_progress |
A session closes, or progress is set outright |
playback_finished |
A listener reaches the end of an edition |
They are host event types: a plugin can consume them and cannot produce
them. The playback live topic moves on a session opening or closing, a
finish, an outright progress write and a bookmark change, so another open
tab re-reads Continue listening without hearing every report.
A sync body and a stream path are parsed sans IO in bookclerk-library
(parse_playback_sync_request, parse_track_path) and fuzzed as
playback_request against an independent oracle. Positions and runtimes
are a bounded type (at most sixty days of milliseconds), a session lists
at most 512 tracks, and an edition takes at most 200 bookmarks per person.
Apps written for an Audiobookshelf server connect to Bookclerk at
/player, served by the host from a first-party crate over the core
above. The path names Bookclerk's own implementation; it is not /abs.
Sign-in there mints library cards (a short access token and a rotating
refresh token), and every item, progress and stream call lands on the
same tables and the same check as the web player. The
player API ADR records how.
The desktop window's custom scheme delivers no request headers on Linux,
so it cannot serve Range to a web view. The window decodes in the
confined media worker and plays through the operating system's audio and
media controls, reading files and writing progress through the same
core.
The host reads each block of the track through the session's own stream
route in process, so the window gets no second path to the files. A
pcm worker per track decodes them under the same rules as the tag
worker: no path, no network, ranges only inside the file. Speed changes
use WSOLA time-stretching and the rate conversion uses a windowed-sinc
resampler, both in a small engine crate (bookclerk-player-engine) with
no I/O. The page's stage B player drives that engine as if it were an
audio element, so the timeline, sync and bookmark logic exist once. The
system's media controls come from souvlaki. The window listens as the
patron it is signed in as, and keeps doing so while that patron is
elevated or impersonating someone from the elevation.
- The core itself has no user interface. The routes are in the Web API reference and are exercised by tests; the web app's player is their first caller.
- An edition is playable only on a node that has one of its destinations
deployed. A session is tied to the node that opened it; behind a load
balancer without session affinity a stream request can reach another
node and be answered
421. - Runtime is what a player reports, or the catalog's length to the minute before one has. Exact per-file lengths for editions in several files arrive with the stored media probe.
- Playback events carry a user id, an edition and a position. A plugin that consumes them learns what a person listens to, which an operator accepts when granting that plugin the event.
playback_sessionsgrows by one row per stretch of listening and is not pruned yet.- No transcoding: a file the browser cannot decode does not play in the web player until transcoding is built.
Source: docs/adr/playback.md at main · View as Markdown