Skip to main content

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.

Tunarr uses FFmpeg to transcode and remux content when generating channel streams. All FFmpeg-related settings — from executable paths to subtitle handling — are managed from Settings > FFmpeg in the Tunarr web UI.

​
Executable Paths

Tunarr requires both ffmpeg and ffprobe executables to function. Both binaries typically reside in the same directory, so configuring the parent path is usually sufficient for both.
Docker installations come with a bundled version of FFmpeg. If you are running Tunarr via Docker, you do not need to configure executable paths — they are handled automatically.
For non-Docker installations, we recommend using the FFmpeg 7.1.1 build specially compiled by the ErsatzTV project, available on their GitHub releases page. This build includes patches and filters that Tunarr takes advantage of for hardware acceleration, tonemapping, and subtitle handling.

​
Global FFmpeg Options

​
Logging

FFmpeg log output can be directed to Tunarr’s stdout stream or written to a separate log file, both with a configurable log level. This is useful for diagnosing streaming issues, identifying codec errors, or understanding why a particular channel is producing unexpected output.
It is strongly recommended to only enable FFmpeg logging while actively debugging. Even when this setting is disabled, Tunarr will still generate an error log file if FFmpeg encounters a fatal error — so you will not miss critical failure information. Leaving FFmpeg logging always on can produce a significant volume of output and impact disk usage over time.

​
HLS Direct Output Format

When a channel is configured to use the HLS Direct stream mode, this setting controls the container format used for the output stream. Different players and network devices have varying levels of support for HLS container formats, so this option lets you match the output to what your clients expect. See channel stream modes for more detail on when HLS Direct is used.

​
FFmpeg Transcode Path

This setting controls where FFmpeg writes HLS segments while a channel stream is active. By default, segments are written to disk, but pointing this path to a RAM-backed location can significantly reduce disk I/O and improve segment write latency — particularly useful on systems with slower storage. On a standalone Linux binary installation, you can write segments to RAM by setting the transcode path to /dev/shm.

​
RAM Transcoding in Docker

Transcoding to RAM in a Docker environment requires configuring a tmpfs mount inside the container at startup. Add the following to your docker-compose.yml service definition: 
# ... rest of your docker compose
services:
    tunarr:
    # ... rest of your Tunarr service
    tmpfs:
        - /transcode:size=10G
Once the container is running with the tmpfs mount, set the FFmpeg Transcode Path in Tunarr to /transcode. Adjust the size value to match the amount of RAM you want to allocate — 10 GB is a conservative ceiling for most setups with a few concurrent streams.

​
Audio & Subtitles

​
Subtitle Extraction

If your media files contain embedded, text-based subtitle streams (such as SRT or ASS tracks stored inside an MKV container), this option enables Tunarr to extract them so they can be burned into the output video. Extraction of embedded text-based subtitles is currently a prerequisite for using those subtitle streams during playback. Each hour, Tunarr scans the program guide for upcoming content, identifies items with embedded text-based subtitles, and queues extraction jobs. This process can be CPU- and I/O-intensive depending on your library size. If possible, using sidecar subtitle files (see below) is preferable as they require no extraction step.

​
Sidecar Subtitles

Tunarr supports external subtitle files — .srt, .vtt, and similar formats — placed alongside your media files. When scanning local libraries, Tunarr automatically discovers these sidecar files and associates them with the corresponding media items. For Plex, Jellyfin, and Emby sources, external subtitles reported by the media server are downloaded during the library scan. When using HLS Direct stream mode, sidecar text-based subtitles are served as WebVTT tracks included in the HLS master playlist. Clients that support HLS subtitle renditions — most modern media players — will present them as selectable subtitle options during playback.
Sidecar subtitle support is currently experimental. To enable it, navigate to Settings > Features and turn on the sidecar subtitles feature flag.

​
Language Preference

Language preferences for audio streams are currently configured at the global level only. Use this setting to define an ordered list of preferred audio languages. When Tunarr selects an audio stream for a piece of content, it picks the first stream whose language matches an entry in your preference list. If no match is found, Tunarr falls back to the default audio stream for that item.

Build docs developers (and LLMs) love

Get started for freeTalk to us