# Playback reference

Bookclerk can play the audiobooks it keeps. This page describes the
playback core the daemon serves: what it stores, the routes a player
calls and the rules behind them. The decisions are in the
[Playback ADR](/docs/adr/playback/index.md); every route is in the
[Web API](/docs/server/api/index.md) reference with example requests and responses.

> [!NOTE]
> The web app's player and the desktop window's player use this core
> (see [Listen in the web app](/docs/guide/listening/index.md)). Phone and car
> apps reach it through the [player API](/docs/server/player-apps/index.md).

## What is stored

| Table               | One row per          | Holds                                                                                    |
| ------------------- | -------------------- | ---------------------------------------------------------------------------------------- |
| `playback_progress` | Person and edition   | Position, the runtime the player reported, finished flag and times                       |
| `playback_sessions` | Stretch of listening | The edition, the player's kind and name, where it started and stopped, and time listened |
| `bookmarks`         | Marked place         | Position and a note                                                                      |

All three belong to one library user and are removed with the user.
Finishing an edition also marks its work finished for that person.
Progress imported from other servers stays in `listening_progress`.

## Routes

Every route needs a signed-in library user. The operator token has no
user and gets `403`. An edition outside the caller's
[patron scope](/docs/guide/sharing/index.md#limit-what-a-patron-sees) is `404`.
The **Download**
[control](/docs/guide/sharing/index.md#limit-what-a-patron-may-do) does not apply
to playing: it stops taking copies to keep, and a patron who can see a
book may listen to it.

| Route                                               | Purpose                                                                                                      |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `GET /api/library/editions/{id}/playback`           | Whether this server can play the edition for the caller, its tracks and chapters, and the caller's progress and bookmarks |
| `POST /api/playback/sessions`                       | Open a play session: tracks with stream paths, and where to start                                            |
| `POST /api/playback/sessions/{id}/sync`             | Report the position while playing                                                                            |
| `POST /api/playback/sessions/{id}/close`            | Send the last report and end the session                                                                     |
| `GET /api/playback/sessions/{id}/tracks/{index}`    | One track's bytes, whole or by `Range`                                                                       |
| `GET /api/playback/progress`                        | The caller's progress, most recent first                                                                     |
| `PUT`, `DELETE /api/playback/progress/{edition_id}` | Set or forget the caller's progress                                                                          |
| `GET`, `POST /api/library/editions/{id}/bookmarks`  | List or add the caller's bookmarks in an edition                                                             |
| `PUT`, `DELETE /api/playback/bookmarks/{id}`        | Change or remove one                                                                                         |

## How a player uses them

1. Read the manifest. `playable` is true when this server has a
   destination holding the edition's audio and the caller may hear it.
2. Open a session with the edition's id. The answer lists the tracks in
   play order, each with a `path`, and `position_ms`: the caller's saved
   position, or 0 when they have none or had finished the edition.
3. Play each track's `path`. The route answers `Range` requests, so a
   browser's `<audio>` element can seek. The session cookie signs the
   request; no token goes in the URL.
4. Send `sync` every few seconds with `position_ms`, and `listened_ms`
   since the last report.
5. Send `close` when playback stops.

Positions are milliseconds on the edition's whole timeline, across all
of its tracks.

## Rules worth knowing

- **Tracks** are the edition's primary audio file and its parts.
  Per-chapter files, covers and documents are not tracks.
- **Finished** means the position reached the last 1 percent of the
  runtime, or its last 30 seconds for a recording over a minute.
- **A session stops streaming** when it is closed, when it has not
  reported for 24 hours, when the caller may no longer see the edition,
  or when the edition's files change. Stream requests to a session that
  stopped get `409` with `session_ended`, as does a report to a closed
  session; the player opens a new session. Turning a member's Download
  control off does not end a session: it does not cover listening.
- **A session streams from the server that opened it.** Another server
  on the same library answers `421`.
- **Limits:** a position or runtime is at most sixty days, a session
  lists at most 512 tracks, and a person keeps at most 200 bookmarks in
  one edition. A bookmark's note is at most 200 bytes with no control
  characters, and a player's name is kept to 64 bytes.
- **Request bodies** are JSON objects with only the documented fields.
  One out of range gets `400`; one of another shape gets `422`. A
  report (`sync` or `close`) is at most 1024 bytes and every other body
  at most 4096 bytes; a longer one gets `413`.
- **Time listened** in a session is the sum of what its reports carry,
  so reports that overlap all count.
- **Cross-site requests** are refused like every other cookie-signed
  write: `POST`, `PUT` and `DELETE` need the app's own `Origin`.

## The desktop window

The desktop window's custom scheme carries no `Range` requests, so its
page can't stream a track to an `<audio>` element. The window has its own
player instead, and the web app's player drives it in place of an audio
element:

1. The page opens the session and reports progress through the same
   routes as in a browser.
2. To play a track, the page hands its `path` to the window. The host
   reads the track through that same stream route, in process, one
   `Range` request per block, so each block gets the same checks: an
   open session, this server, the patron scope and the files.
3. A confined media worker decodes the blocks (see
   [Audio for the desktop player](/docs/server/media/index.md#audio-for-the-desktop-player)).
   The window changes the speed (0.5× to 3×) without changing the pitch,
   converts the sample rate, and plays through the system's default
   output device.
4. The system's media controls show the book and its position and send
   their buttons back to the page: MPRIS on Linux, the media overlay on
   Windows and Now Playing on macOS.

The window listens as the patron it is signed in as. While that patron
is elevated to the operator, or impersonating someone from the
elevation, the window still keeps their own listening state, because it
is the person at the computer who is listening. Before the library has
an Owner the window is the operator and has nothing to play as.

## Chapters

Chapters belong to the edition and are kept in the database, so every
player and every stored copy shows the same list. Each source that knows
an edition's chapters adds a claim, and the library chooses the list it
plays (decisions in the [Edition chapters ADR](/docs/adr/edition-chapters/index.md)):

1. A claim an Administrator pinned.
2. An Administrator's own edit. An empty edit clears the chapters on
   purpose.
3. Otherwise the best machine source, best first: Bookclerk's chapters
   aligned to the audio during acquire; a metadata provider's chapters
   with exact starts; the store's chapters; a file's chapters; a provider's
   estimated chapters; store markers of unknown kind; store track markers;
   one chapter per delivered part.

A storefront says whether its markers are chapters or tracks
(`chapterKind` in the [Plugin ABI](/docs/plugins/abi/index.md)), so a store's
track list never outranks a book's real chapters.

| Route | Who | Purpose |
| --- | --- | --- |
| `GET /api/library/editions/{id}/chapters` | Anyone who may see the edition | The chapters it plays, in pre-order with depths, and where they came from |
| `GET /api/library/editions/{id}/chapters/claims` | Administrator | Every source's list, and which one plays |
| `PUT /api/library/editions/{id}/chapters` | Administrator | Set the chapters by hand; `{"chapters": []}` clears them |
| `DELETE /api/library/editions/{id}/chapters` | Administrator | Remove the edit, so the best remaining source plays again |
| `PUT`, `DELETE /api/library/editions/{id}/chapters/pin` | Administrator | Pin one source's list, or remove the pin |

"Administrator" here means the operator, an Owner or an Administrator, as
for every other metadata edit; an Owner can stop one Administrator
changing chapters with the **Fix the catalog** switch (see
[Sharing](/docs/guide/sharing/index.md)), which leaves the claims readable. An edit is checked strictly and stored
exactly as sent: at most 2,000 chapters, each title 1 to 512 bytes with no
control character and no leading or trailing space, starts that never go
back and are at most 60 days in, and each depth (0 to 7) at most one
deeper than the chapter above. A body that breaks a rule gets `400`, one
over 2 MiB gets `413`.

When the list an edition plays changes, the host emits `edition_updated`
with `fields: ["chapters"]`. Media files keep the chapters they were
written with.

Players read the list from the database:

- The playback manifest's `chapters` holds it in pre-order, each chapter
  with its depth and an `end_ms` at the next chapter's start (the last
  ends at the runtime). The web player shows the chapter playing, lists
  the chapters and skips to the previous or next one.
- The [player apps](/docs/server/player-apps/index.md) at `/player` get the same list
  flattened, as Audiobookshelf answers: an expanded item's
  `media.chapters` and a play session's `chapters`, in seconds.

## Events and live updates

Plugins can consume three host events (see
[Plugin ABI](/docs/plugins/abi/index.md)): `playback_started`,
`playback_progress` and `playback_finished`. Periodic sync reports
publish nothing.

The web app's live socket has a `playback` topic. It moves when a session
opens or closes, an edition is finished, progress is set outright or a
bookmark changes.
