Documentation Index
Fetch the complete documentation index at: https://mintlify.com/chrisbenincasa/tunarr/llms.txt
Use this file to discover all available pages before exploring further.
Each Tunarr channel has two layers of transcoding configuration: the stream mode, which determines the overall pipeline architecture used to produce the channel’s output, and the transcode configuration profile, which controls the specific encoding parameters (codec, resolution, bitrate, hardware acceleration, and more). Both are set on the channel’s Transcoding tab and can be changed independently without affecting your programming lineup.
Regardless of which stream mode you choose, clients that require an MPEG-TS stream will still work correctly. Tunarr handles the container conversion internally.
Stream Modes
HLS (recommended)
HLS alt
HLS Direct
HLS Direct v2
MPEG-TS
HLS
HLS is the default and recommended streaming mode. In Tunarr’s testing it offers the best combination of reliability, efficiency, and client compatibility. It is analogous to ErsatzTV’s “HLS Segmenter” mode.How it works:
Tunarr creates a single FFmpeg process per program in the lineup. That process applies all transcoding configuration — scaling, watermarks, codec conversion, frame rate normalization, and so on — and outputs an HLS segment stream. Tunarr then manages interleaving these per-program processes to produce a seamless, continuously updating .m3u8 playlist for the client to consume.When to use it:
Use HLS for virtually all new channel setups. It is the newest and most actively developed mode in Tunarr and is the best default choice unless you have a specific reason to use another mode.Because HLS is the newest mode, there may occasionally be edge cases. If you encounter stream issues, check the Tunarr logs and consider trying HLS alt as a more robust fallback before switching to legacy modes.
HLS alt
HLS alt is a second HLS streaming mode that trades CPU efficiency for stream robustness. It is analogous to ErsatzTV’s “HLS Segmenter V2” mode.How it works:
This mode runs two FFmpeg processes instead of one. The first process is per-program and handles video manipulation: scaling, cropping, watermark overlays, and frame rate changes. It outputs a raw video stream (not a finished encoded file). The second process receives the raw output from all per-program processes and concatenates them while applying bitrate limits and codec conversion to produce the final stream.When to use it:
Consider HLS alt if you experience reliability issues with standard HLS mode — for example, artifacts at program transitions or stuttering under load. The two-process architecture can produce a more stable concatenated stream in some scenarios.The per-program process in HLS alt mode requires software encoding, which is significantly more CPU-intensive than hardware-accelerated encoding. On modest or low-power hardware this can cause dropped frames or the inability to keep up with real-time playback. Additionally, the two-stage pipeline introduces generation loss (re-encoding the video twice), which can reduce output quality compared to HLS mode.
HLS Direct
HLS Direct is a no-normalization mode for clients that can handle the source stream format directly.How it works:
When a client requests the channel’s .m3u8 playlist, Tunarr returns a playlist containing a single item URL set to the duration of the current program. That URL streams the program content directly, remuxed into the container format configured in FFmpeg settings (MPEG-TS, MKV, or MP4). No codec conversion, scaling, or normalization is applied.When to use it:
Use HLS Direct when you want to pass through source streams without any transcoding overhead and your client supports the source format. Clients confirmed to work in this mode include Jellyfin and MPV, though many others likely work as well.Because HLS Direct skips stream normalization, program transitions require the client to essentially reset itself between each program. Not all clients handle this gracefully. If you see the stream freeze or stall at the boundary between two programs, the client may not be compatible with this mode.
HLS Direct v2
HLS Direct v2 combines the direct-stream approach of HLS Direct with the proper segmented HLS playlist structure of standard HLS mode — no transcoding, but full HLS compatibility.How it works:
Instead of returning a single-item .m3u8 pointing directly to the program stream (as HLS Direct does), HLS Direct v2 produces a proper continuous HLS playlist of segmented chunks — the same structure clients receive in standard HLS mode. The source content is remuxed directly into segments without any codec conversion or normalization.When to use it:
HLS Direct v2 is the preferred no-transcoding option for clients that do not rely on FFmpeg’s HLS demuxer implementation, or that expect a standard segmented HLS playlist structure. Program transitions are handled more gracefully than with HLS Direct because the playlist structure is continuous and well-formed.As with HLS Direct, no stream normalization is applied. If your lineup mixes source files with different codecs, resolutions, or frame rates, playback behavior at transition points will depend on the client’s tolerance for format changes.
MPEG-TS
MPEG-TS is a legacy mode included primarily for compatibility with setups migrated from DizqueTV. It most closely replicates the DizqueTV streaming experience.How it works:
Like HLS alt, this mode uses two FFmpeg processes. The first performs a per-program transcode and outputs a raw MPEG-TS stream. The second process concatenates these raw streams and outputs the final MPEG-TS to the client.When to use it:
Only use MPEG-TS if you have a specific client or workflow that requires it and none of the HLS modes work for your situation. This mode has the most known issues of any stream mode in Tunarr.MPEG-TS mode has numerous known issues that were the primary motivation for developing the HLS-based modes. It is not recommended for new setups.
Stream Mode Comparison
| Mode | FFmpeg Processes | Normalization | Client Reset Needed | Best For |
|---|
| HLS | 1 per program | ✅ Full | No | Most setups — start here |
| HLS alt | 2 | ✅ Full | No | Maximum reliability at cost of CPU |
| HLS Direct | 1 | ❌ None | Yes | Pass-through with compatible clients |
| HLS Direct v2 | 1 | ❌ None | No | Pass-through with standard HLS clients |
| MPEG-TS | 2 | ✅ Full | No | Legacy / DizqueTV migration |
Transcode Configuration Profiles
A transcode configuration is a reusable named set of encoding parameters that you assign to a channel. It controls the detailed output characteristics of the stream: video codec, output resolution, bitrate, hardware acceleration (NVIDIA CUDA, Intel VAAPI/QSV, AMD VAAPI, Apple VideoToolbox), audio codec, loudness normalization, and error handling behavior.
Transcode configurations are created and managed globally and can be shared across multiple channels. To create or edit a profile, navigate to Settings → Transcode Configs.
For a full breakdown of every available setting — including hardware acceleration options, HDR tonemapping, audio settings, and error modes — see the Transcode Configs reference page.