Configuration Options
Norri stores most server preferences in the database and exposes them through the admin UI. Use Settings in the web app for normal configuration. Use environment variables for deployment-level settings such as ports, data paths, and credentials.
See Environment Variables for deployment settings.
Transcoding Settings
Go to Settings → Transcoding as an admin to change these values.
| UI setting | API field | Default | Description |
|---|---|---|---|
| Maximum Streams Per User | max_per_user | 5 | Maximum active playback sessions one user can start. |
| Maximum Streams Server-Wide | max_global | 10 | Maximum active playback sessions across the server. |
| Transcode Idle Timeout (seconds) | idle_timeout_seconds | 300 | How long a transcode survives without activity before Norri tears it down. |
| Active Playback Idle Timeout (seconds) | playback_active_idle_timeout_seconds | 120 | How long a playing session survives without a client heartbeat. |
| Paused Playback Idle Timeout (seconds) | playback_paused_idle_timeout_seconds | 21600 | How long a paused session survives without a client heartbeat. The default is 6 hours. |
| Buffer Ahead (seconds) | throttle_buffer_seconds | 60 | How far ahead Norri prepares a transcoded stream. |
| Hardware Acceleration | hardware_acceleration | auto | GPU acceleration mode. Valid values are auto, videotoolbox, nvidia, vaapi, qsv, and software. |
| Subtitle Burn Mode | subtitle_burn_mode | auto | Subtitle burn-in policy. Valid values are auto, always, and never. |
| Burn In Styled Subtitles | burn_in_styled_subtitles | true | When true, ASS and SSA subtitles are burned into the video to preserve styling. When false, they are side-loaded as plain WebVTT where possible. |
| Prefer External Subtitles | prefer_external_subtitles | false | When true, matching sidecar subtitle files win over embedded subtitle tracks during automatic selection. |
| Enable HDR Tone Mapping | hdr_tone_mapping | true | When true, HDR sources are tone-mapped to SDR for clients that do not support the source HDR format. |
Timeout values are in seconds.
Playback Preferences
Go to Settings → Playback to change user-level playback preferences. Admins can also set server defaults for users who have not customized their own preferences.
| Setting | Description |
|---|---|
| Preferred Audio Language | Selects matching audio automatically when available. |
| Preferred Subtitle Language | Selects matching subtitles when subtitle mode enables them. |
| Subtitle Mode | Controls when subtitles are selected automatically. |
| Prefer SDH | Prefers SDH or CC subtitle tracks over standard subtitles in the same language. |
| Audio Output | Prefers audio tracks that match the selected speaker layout. |
API Access
Integrations can read or update transcoding settings through:
| Method | Endpoint | Purpose |
|---|---|---|
GET | /api/playback/settings | Read current transcoding settings. |
PATCH | /api/playback/settings | Update transcoding settings. Admin only. |