How Norri Works
Components
Norri consists of several components working together:
Server
The core application that handles:
- Media scanning and metadata
- User authentication
- Streaming and transcoding
- API for client apps
Database
Norri uses PostgreSQL to store:
- Media metadata
- User accounts and preferences
- Watch history and playback positions
Client Apps
Native applications for each platform that communicate with the server via API.
Playback Pipeline
Norri analyzes media files during library scans. This records the container, video codec, audio tracks, subtitle tracks, chapters, keyframe data, and HDR format. The result is used later when you press play.
When playback starts, the client tells Norri what it can play. Norri then chooses one of three paths:
| Path | What happens |
|---|---|
| Direct play | The original file is streamed without conversion. |
| HLS remux | The original video and audio are copied into an HLS stream when only the container is incompatible. |
| Transcode | Video, audio, HDR, or subtitles are converted for the playback device. |
This decision is made per session. The same movie can direct play on one device and transcode on another if their capabilities differ.
HDR Routing
Norri detects HDR10, HLG, and Dolby Vision during file analysis. Clients report whether they support those HDR formats when playback starts.
If the client supports the source HDR format, Norri keeps HDR intact. If the client does not support it, Norri tone-maps HDR to SDR when Enable HDR Tone Mapping is enabled in Settings → Transcoding.
Session Tracking
Playback runs through a session. Sessions track the selected audio and subtitle tracks, the stream URL, the playback method, and liveness.
Clients use heartbeats during normal playback so Norri can keep the session alive and save resume progress. Clients can also send a liveness-only ping when they need to keep a session alive without moving the saved position.
Admins control idle behavior in Settings → Transcoding:
- Active Playback Idle Timeout, for playing sessions that stop checking in
- Paused Playback Idle Timeout, for paused sessions that stop checking in
- Transcode Idle Timeout, for inactive transcode workers
Track Changes
Audio and subtitle track changes are scoped to the current playback session. If another device is playing the same item, its stream is kept separate.
When a track change requires a new stream, the client reloads at the current position. Cached requests from the old stream are rejected so the player does not mix old and current segments.