John O'Keefe
e21e1facde
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.
53 lines
1.8 KiB
Markdown
53 lines
1.8 KiB
Markdown
---
|
|
method: GET
|
|
path: /api/media-items/:id/audio/:trackIndex
|
|
auth: jwt
|
|
area: media-items
|
|
---
|
|
<!-- source: internal/handlers/media.go:3088 MediaHandler.GetAudioTrack -->
|
|
|
|
# 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](get_audio_chapters.md).
|
|
|
|
**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
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer $TOKEN" \
|
|
-H "Range: bytes=0-1023" \
|
|
"http://localhost:8765/api/media-items/550e8400-.../audio/{track_index}"
|
|
```
|