John O'Keefe
50282895f5
Fix all wrong-path artifacts identified by the audit: - Kobo sync endpoints (init/bookmark/markup/sync-from-server/analytics): add missing :token device segment (6 doc files incl. kobo-protocol.md) - Highlights/notes update+delete: add missing /:id media-item prefix - media-items/download_media_item.md: removed (static /uploads route, not an API endpoint; info about the file route is recoverable from OPDS docs) - Bruno: /libraries/visible -> /visibility, /collections/books missing id, /audio/0 -> track_index - operations/troubleshooting.md: same /libraries/visible -> /visibility fix - media-items/get_audio_track.md + get_audio_chapters.md: /audio/0 examples fixed - Deleted monolithic docs/developer/api-reference.md (duplicate of split docs) - Fixed 4 stale entries in docs/developer/api/api-reference.md (split index) Audit re-run: orphan docs 0, orphan Bruno 6 (all scenario files with literal IDs).
45 lines
1.6 KiB
Markdown
45 lines
1.6 KiB
Markdown
# 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}"
|
|
```
|