0 Fork 0

Files

T

John O'Keefe e21e1facde docs(media-items,collections,koreader,admin): Beam batch 11 — final backfill

All remaining endpoint docs frontmatter'd: media-item bulk ops + audio
surface, collections book-listing/preview, koreader rating/review/stats
plugin protocol, hash-conflicts JSON list.

Scope call (Claude): resolve_hash_conflict.md DELETED — the resolve POST
renders an htmx fragment (renderResolved), a web-admin flow under rule 3;
only the GET list is a JSON API. update_media_review skipped by Beam
(correct): ratings/upsert_media_review.md already covers the PUT.

Registry: 16 entries. koreader rating/review/stats all bind
koreaderBookRef (query or body) — odd=half-star rating scale; audio track
endpoint serves raw bytes (ServeContent, Range) — response nil. Fixed
drift: deleted_annotations doc's secondary restore/purge fences
unlabeled (gate validates labeled blocks against the ONE frontmatter
route); chapters example labeled. UNVERIFIED: 1 (koreader book-ref
fields, push_stats). make test 9/9.

2026-10-24 18:21:17 -04:00

1.8 KiB

Raw Blame History

method, path, auth, area

method	path	auth	area
GET	/api/media-items/:id/audio/:trackIndex	jwt	media-items

Get Audio Track

Streams one playable track of a multi-file audiobook (folder-of-tracks or zip-of-audio book). Track indexes and bounds come from the track manifest on Get Audio Chapters.

Endpoint: GET /api/media-items/{id}/audio/{trackIndex} Auth: Required (JWT — Bearer header or session cookie; the web player's <audio> element authenticates by cookie)

Serving

Folder books: the track is served straight from its real file (http.ServeContent) — full Range support.
Zip books: the entry is extracted in place. Forward seeks discard bytes in the open stream; backward seeks re-open the entry and skip (deflate has no random access — cheap at audio bitrates). Range requests are honored.

Single-file books have no track manifest — they stream through the /uploads path exactly as before and this endpoint answers 404.

Library visibility

The item's library must be visible to the requester; a hidden library answers 403 on every track (same gate as the download endpoint).

Error Responses

Code	Description
400	Invalid media item id or track index
401	Missing/invalid token
403	Library not visible to the requester
404	Book/track not found, or single-file book
500	audio_metadata failed to parse

Example

curl -H "Authorization: Bearer $TOKEN" \
  -H "Range: bytes=0-1023" \
  "http://localhost:8765/api/media-items/550e8400-.../audio/{track_index}"

1.8 KiB Raw Blame History