Transcoding
Transcoding converts video, audio, HDR, or subtitles into a form your playback device can use. Norri avoids transcoding whenever possible. When the file is already compatible, it streams the original media directly.
Playback Methods
Norri chooses a playback method for every session based on the file, the selected tracks, and the device playing it.
| Method | When Norri uses it | What to expect |
|---|---|---|
| Direct play | The container, video codec, audio codec, subtitles, and HDR format are supported by the client. | Fastest startup and smoothest seeking. The original file is streamed without conversion. |
| HLS remux | The video and audio codecs are supported, but the container is not. Common example: MKV with H.264 video and AAC audio in a browser. | Copies compatible streams without re-encoding. Startup and seeking can pause while the server reads the source and prepares segments. |
| Transcode | The video, audio, HDR format, or selected subtitle track needs conversion. | Uses CPU or GPU resources. Hardware acceleration is recommended for 4K, HDR tone mapping, and multiple simultaneous streams. |
When Transcoding Happens
Transcoding may be needed when:
- The device cannot play the source video codec.
- The device cannot play the selected audio codec or channel layout.
- HDR content is played on a device that does not support the source HDR format.
- Image-based subtitles need to be rendered into the video.
- Styled ASS or SSA subtitles need burn-in because the client cannot render their styling directly.
- The connection quality setting is lower than the source bitrate.
Container-only incompatibility does not require full transcoding. For example, a browser that cannot play an MKV container but can play the H.264 video and AAC audio inside it gets an HLS remux instead.
Transcoded Video Quality
Choose how the web app handles connection speed when a movie or TV episode needs video transcoding:
- Go to Settings → Web Client → Playback.
- Under Transcoded video, choose a Connection handling option.
- Click Save video setting.
| Option | What it does |
|---|---|
| No connection test | Uses the highest compatible quality available for the source, player, and server, without measuring the connection. Keeps that quality during playback. |
| Test when playback starts | The default. Measures the connection when needed, selects a suitable quality, and keeps it during playback. |
| Test and adjust during playback | Measures the connection when needed, then lets the player change transcoded video quality based on actual media delivery. Available on supported desktop Chrome and Firefox players. |
All choices respect the player’s capabilities and server limits. Safari keeps its native player and offers the first two choices only. Norri provides it with a single selected quality.
The setting is saved for your account in this browser only and applies the next time you play a movie or episode. Other browsers, devices, and accounts have their own choice. Clearing this site’s browser data resets the choice to the default.
The connection test briefly downloads a sample from your server. Direct play skips it. For HLS playback, Norri may measure the connection to decide whether it can deliver the original video or needs a lower bitrate. The test can also run when a later subtitle change first requires video conversion. It adds a short wait when needed and does not run at login. If the test fails, Norri uses its fallback quality selection instead of an old connection estimate. No connection test skips this wait.
With Test and adjust during playback, the player prepares its starting video buffer before playback begins. You may see Preparing playback… while this happens.
Fixed quality does not compensate if the connection later slows down, so playback can buffer. With automatic adjustment enabled, a quality change can also cause a pause while the server starts the replacement transcode. The interruption depends on the connection and server performance.
These choices control video transcoding, including H.264 output. They do not add automatic video quality changes to direct play or remuxing, or change music playback.
Transcoding Settings
Admins can change transcoding behavior in Settings → Transcoding.
| Setting | Default | What it does |
|---|---|---|
| Hardware Acceleration | Auto-detect | Uses a supported GPU encoder when available. Choose a detected GPU or CPU (software transcoding) to select a specific device. |
| Max Sessions Per User | 5 | Limits the number of active playback sessions one user can start. |
| Max Global Sessions | 10 | Limits total active playback sessions across the server. |
| Buffer Ahead | 60 seconds | Controls how far ahead Norri prepares a transcoded stream. Higher values can help unstable networks but use more temporary storage. |
| Subtitle Burn Mode | Auto | Controls when subtitles are rendered into the video. Auto burns image-based subtitles when required. |
| Burn In Styled Subtitles | On | Preserves ASS and SSA styling by rendering it into the video when the client needs this fallback. Compatible clients can render styled subtitles directly. Turning burn-in off can lose styling on other clients. |
| Prefer External Subtitles | Off | Chooses matching sidecar subtitle files before embedded subtitle tracks during automatic selection. |
| Enable HDR Tone Mapping | On | Converts HDR to SDR when the playback device does not support the source HDR format. |
Tip
Leave Hardware Acceleration on Auto-detect unless you need to select a particular device. When more than one GPU is detected, the list names each available card. A changed selection applies after the server restarts; streams already playing are not interrupted by saving it.
Monitor Active Playback
Admins can open Settings → Active Sessions to see who is currently streaming, what they are playing, their playback method, and whether a transcode is using hardware. The hardware summary shows the detected transcoding hardware as ready or in use. This page shows active playback, not a list of everyone who is signed in or a GPU utilization percentage. An admin can stop a session from its card.
HDR Playback
Norri detects HDR10, HLG, and Dolby Vision during file analysis. When a client reports support for the source HDR format, Norri keeps the HDR stream intact. When the client does not support it, Enable HDR Tone Mapping converts the video to SDR so colors look correct on standard displays.
Codec support and display support are separate. For example, Safari on an SDR screen may decode HEVC Main 10 but still need HDR converted to SDR. Ten-bit files without HDR signaling are treated as SDR after successful file analysis.
Leave Enable HDR Tone Mapping enabled if you use devices that cannot display your HDR files correctly.
Starting a transcode or seeking to an unprepared part of a movie can take several seconds, especially with HDR conversion. Playback should continue from the requested position. See Common Issues if it remains stuck or resumes at the wrong point.
Session Timing
The session timing settings control how long Norri keeps playback and transcoding work alive when activity stops.
| Setting | Default | What it does |
|---|---|---|
| Transcode Idle Timeout | 300 seconds | Keeps a paused transcode available for 5 minutes without activity before tearing it down. |
| Active Playback Idle Timeout | 300 seconds | Ends a playing session if the client stops checking in. This usually means the app was closed, the tab was killed, or the network dropped. |
| Paused Playback Idle Timeout | 86,400 seconds | Keeps a paused session alive for 24 hours so you can resume later without immediately rebuilding the stream. |
Lower these values on small servers with limited CPU, GPU, memory, or cache space. Raise them if clients on your network pause frequently and you want fewer stream restarts.
Track Changes
Changing audio or subtitle tracks can briefly reload the stream. Norri resumes at the current position and keeps other devices playing the same item independent from your session.
A short spinner during a track change is normal. If playback remains stuck, see Common Issues.
Hardware Transcoding
For best performance, use hardware transcoding with a supported GPU:
- Intel Quick Sync, for supported Intel integrated GPUs and Intel Arc graphics
- NVIDIA NVENC, for NVIDIA GeForce or Quadro GPUs
- AMD VCE/VCN, for supported AMD GPUs
GPU access requires the matching host drivers and Docker configuration. Docker Desktop on macOS cannot pass the Mac GPU into this Linux container. See Hardware Transcoding for setup instructions.