API Reference
Norri exposes a REST API for the web app, client apps, and local integrations. This page covers the playback routes most likely to be useful to client authors.
Authentication
Most API requests require a bearer token.
curl -H "Authorization: Bearer YOUR_TOKEN" \
http://localhost:8096/api/playback/sessions/activeStreaming URLs may use a stream token in the URL because browser video and audio elements cannot attach authorization headers.
Base Path
API routes use the /api prefix.
Playback Sessions
| Method | Endpoint | Description |
|---|---|---|
POST | /api/playback/sessions | Create a playback session for a movie or episode. |
GET | /api/playback/sessions/active | List the current user’s active sessions. |
GET | /api/playback/sessions/:sessionId | Get session state, selected tracks, and stream metadata. |
POST | /api/playback/sessions/:sessionId/heartbeat | Keep the session alive and update playback position. |
POST | /api/playback/sessions/:sessionId/ping | Keep the session alive without updating resume position or progress history. |
PATCH | /api/playback/sessions/:sessionId/tracks | Change the selected audio or subtitle track. |
POST | /api/playback/sessions/:sessionId/stop | Stop playback with a final position. |
DELETE | /api/playback/sessions/:sessionId | End playback and fall back to the last heartbeat position. |
Use heartbeat while normal playback is progressing. Use ping for liveness-only situations where the session should stay alive but the saved position should not move.
Client Capabilities
When creating a playback session, clients send a client_profile object describing what they can play. Accurate capabilities let Norri choose direct play, HLS remux, or transcoding correctly.
HDR-aware clients should report support for:
| Capability | Meaning |
|---|---|
supportsHDR10 | Client can play HDR10 correctly. |
supportsHLG | Client can play HLG correctly. |
supportsDoVi | Client can play Dolby Vision correctly. |
If a client does not report support for the source HDR format, Norri tone-maps HDR to SDR when Enable HDR Tone Mapping is on.
Subtitle Delivery
Session responses include delivery_method on each subtitle track so clients know how the track will be delivered if selected.
| Value | Meaning |
|---|---|
external | Sent as an external text subtitle file. |
hls | Sent through the HLS stream. |
embed | Already embedded in a directly playable file. |
burnin | Rendered into the video during transcoding. |
drop | Not delivered for this session. |
This field is informational for clients. Users choose subtitles by track name, language, and type, not by delivery method.
Transcoding Settings
Admins can read or update transcoding settings through:
| Method | Endpoint | Description |
|---|---|---|
GET | /api/playback/settings | Read transcoding settings. |
PATCH | /api/playback/settings | Update transcoding settings. |
See Configuration Options for setting names, defaults, and valid values.