Stream Troubleshooter: Diagnose Tunarr Playback Issues

When a channel fails to play, stutters, or produces corrupted output, pinpointing the root cause can be difficult because the problem might originate anywhere in the pipeline — from media source connectivity, to stream selection, to FFmpeg codec configuration. Tunarr’s built-in Stream Troubleshooter runs a full end-to-end diagnostic session that exercises the same code path as real streaming, collects the results into a structured report, and gives you a short transcoded preview so you can verify output quality without opening a live channel.

Accessing the Troubleshooter

There are two entry points to the troubleshooter:

System Navigation

Go to System → Troubleshoot in the top-level navigation tabs. You’ll be prompted to select a program and channel.

Program Context Menu

Open the details for any program in your library or channel guide, then choose Troubleshoot from its context menu. The program is pre-filled for you.

Running a Troubleshoot Session

Select a Program

Use the search box to find the program you’re having trouble with. Only playable media items — movies, TV episodes, and tracks — can be troubleshot. Folders and collections cannot.If you opened the troubleshooter from a program’s context menu, this step is already done.

Select a Channel

Choose the channel where you’re experiencing the issue. The channel determines which transcode configuration and stream selection profile are used during the test, so it’s important to select the specific channel that’s misbehaving.

Override Transcode Config (optional)

By default, the troubleshooter uses the transcode configuration assigned to the selected channel. If you want to test with a different configuration — for example, to determine whether a problem is specific to hardware acceleration settings — select an override from the dropdown.

Set Test Duration

Choose how long the test transcode should run, in seconds. The default is 30 seconds. The minimum is 5 seconds and the maximum is 120 seconds. Longer tests are more thorough but take more time to complete.

Run the Troubleshooter

Click Run Troubleshooter. The tool will:

Gather system information (Tunarr version, FFmpeg version, platform, available hardware accelerators).
Fetch media stream details from your media source (Plex, Jellyfin, Emby, or local files).
Evaluate stream selection rules to determine which audio and subtitle streams are chosen.
Build the FFmpeg transcoding pipeline — the exact same pipeline used during real playback.
Execute a short test transcode using a random segment of the media file.
If the transcode succeeds, play back the result in the browser as a preview.

Understanding the Results

After the troubleshooter finishes, results are displayed in expandable sections. Here’s what each section tells you.

Errors

If anything went wrong, errors appear in a red banner at the top of the results. Common errors include:

Error	Meaning
Program not found	The program was deleted or its ID is no longer valid.
Media source not found	The media server associated with this program is no longer configured in Tunarr.
Failed to get stream details	Tunarr couldn’t reach the media server, or the file is missing or inaccessible.
Failed to create FFmpeg stream session	The pipeline couldn’t be built — for example, because of a missing codec or unsupported hardware acceleration mode.

System Info

Shows the versions and capabilities of your environment:

Field	Description
Tunarr	The running Tunarr version
FFmpeg	The detected FFmpeg version string
Node.js	The Node.js runtime version
Platform	Operating system and kernel version
HW Acceleration	Hardware acceleration methods available to FFmpeg (e.g., `cuda`, `vaapi`, `videotoolbox`)

Media Info

Details about the program and its streams as reported by the media source:

Program metadata: title, type, duration, source type (Plex/Jellyfin/Emby/local), and the stream path (with authentication tokens redacted).
Video streams: codec, resolution, frame rate, pixel format, bit depth, and color information.
Audio streams: codec, language, channel count, title, and whether the stream is marked as default.
Subtitle streams: codec, language, type (text/image-based), and default/forced/SDH flags.

Stream Selection

Shows which stream selection profile was applied and the result of evaluating each rule:

Rules that matched are highlighted in green.
The first matched rule determines the selected audio and subtitle streams.
If no rule matched, the first audio stream is selected and subtitles are disabled.
The Selected Audio and Selected Subtitle chips show exactly which streams will be used during transcoding.

Transcode Config

Displays the transcode configuration used for the test, including video format, resolution, audio format, and hardware acceleration mode.

Pipeline

The constructed FFmpeg pipeline for this program, including:

Builder type and hardware acceleration mode.
FFmpeg Command: The full FFmpeg argument string that was (or would be) executed. Authentication tokens in URLs are automatically redacted.

Test Transcode

Shows whether the short test transcode succeeded or failed:

Success: A green chip and a video player showing the transcoded output for visual verification.
Failed: A red chip with the exit code. Check the FFmpeg Log section below it for details on what went wrong.

FFmpeg Log

The full FFmpeg report log from the test transcode. This contains detailed information about codec initialization, filter graph construction, encoding performance, and any warnings or errors FFmpeg encountered. This is the primary place to look when diagnosing a failed transcode.

Producing a Troubleshoot Report for Bug Reports

When reporting a streaming issue to the Tunarr developers, always attach a troubleshooter report. It contains everything needed to reproduce and diagnose the problem — system versions, media stream details, the full FFmpeg command line, stream selection rule traces, and the FFmpeg log.

Open the Troubleshooter

Navigate to System → Troubleshoot.

Select the Exact Program and Channel

Search for and select the exact program that’s causing issues, then choose the exact channel where you observe the problem. This ensures the report reflects the real-world configuration.

Apply Any Relevant Overrides

If you’re using a non-default transcode configuration, select it in the override dropdown.

Run with Default Duration

Leave the test duration at the default 30 seconds — this is sufficient for most bug reports.

Download or Copy the Report

Once results appear, click Download JSON to save the report as a file, or Copy Full Report to copy the JSON to your clipboard.

Attach to Your Bug Report

Attach the .json file to your GitHub issue or Discord message. The file contains everything the developer needs.

The JSON report contains all the information needed for debugging: system versions, media stream details, the full FFmpeg command line, stream selection rule traces, and the FFmpeg log output. Sensitive information (API tokens for Plex, Jellyfin, and Emby) is automatically redacted.

The test transcode output (HLS segments) is only kept for 5 minutes after the troubleshoot session completes. The downloaded JSON report is permanent — the video preview is just for your own verification.

The downloaded JSON file has this structure:

{
  "systemInfo": { "tunarrVersion": "...", "ffmpegVersion": "...", ... },
  "mediaInfo": { "title": "...", "videoStreams": [...], "audioStreams": [...], ... },
  "streamSelection": { "profileName": "...", "rules": [...], ... },
  "transcodeConfig": { "name": "...", "videoFormat": "...", ... },
  "channelConfig": { ... },
  "pipeline": { "ffmpegArgs": [...], "ffmpegArgsString": "...", ... },
  "testTranscode": { "exitCode": 0, "success": true, ... },
  "ffmpegLog": "...",
  "errors": [],
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Privacy: What’s redacted automatically

Plex tokens (X-Plex-Token) are replaced with REDACTED.
Emby/Jellyfin API keys (X-Emby-Token, api_key) are replaced with REDACTED.
No personal account information is included.

File paths on your media server (e.g., /media/movies/...) are visible in the report. Redact these manually before sharing publicly if needed.

Changing the Log Level for Deeper Debugging

When the troubleshooter’s FFmpeg log isn’t enough detail, increasing Tunarr’s log level produces more verbose output that can reveal exactly where in the pipeline a problem occurs. There are three ways to change the log level.

Web UI
Environment Variable
API

Open System Settings

Go to Settings → System.

Change Log Level

Under Logging, change the Log Level dropdown to debug (or trace for maximum detail).

Save

Click Save. The change takes effect immediately — no restart needed.

You can also set per-category log levels to avoid flooding the logs. For streaming issues, set the streaming category to debug while leaving the global level at info. This gives you detailed stream and transcode logs without noise from other subsystems.

Set the LOG_LEVEL environment variable before starting Tunarr:

# Standalone
LOG_LEVEL=debug node server.js

# Docker run
docker run -e LOG_LEVEL=debug ... chrisbenincasa/tunarr

# Docker Compose
environment:
  - LOG_LEVEL=debug

When LOG_LEVEL is set via environment variable, it overrides the UI setting. Remove the variable and restart to go back to using the UI-configured level.

Set the global log level:

curl -X PUT "http://localhost:8000/api/system/settings" \
  -H "Content-Type: application/json" \
  -d '{
    "logging": {
      "logLevel": "debug"
    }
  }'

Or set only the streaming category to debug while keeping everything else at info:

curl -X PUT "http://localhost:8000/api/system/settings" \
  -H "Content-Type: application/json" \
  -d '{
    "logging": {
      "logLevel": "info",
      "categoryLogLevel": {
        "streaming": "debug"
      }
    }
  }'

Collecting logs for a bug report

Enable debug logging

Set the log level to debug using any of the methods above.

Reproduce the issue

Play the channel that’s failing or trigger the problem you’re reporting.

Collect the logs

Web UI: Go to System → Logs and copy the relevant output.
Log file: Find tunarr.log in your data directory’s logs/ folder (see Logging for the path on your platform).
Docker: Run docker logs tunarr 2>&1 | tail -500 > tunarr-debug.log.

Reset the log level

Set the log level back to info when you’re done to avoid unnecessary disk usage.

Attach to your bug report

Include the log output alongside the troubleshooter JSON in your GitHub issue or Discord message.

For full details on log configuration, file locations, and log rolling, see the Logging documentation.

Search Syntax Reference

Tunarr includes a built-in search index powered by Meilisearch. When scanning libraries from your media sources, Tunarr adds program metadata to the search index, which you can query to filter content when building channel schedules or browsing your library. Tunarr’s search supports a structured query language with typed fields, as well as free-text search across all fields.

Only double-quotes are supported for quoted strings in search queries. Single quotes are not recognized.

String fields

Operator	Description	Example
`:` or `=`	Equals	`title:"30 Rock"`
`<` or `<=`	Starts with	`title <= A`
`!=`	Not equals	`title != "Sesame Street"`
`~`	Contains	`title ~ Hours`
`!~`	Not contains	`title !~ "Sesame"`
`in`	Set includes	`title IN ["30 Rock", "Arrested Development"]`
`not in`	Set excludes	`genre NOT IN [comedy, horror]`

Number fields

Operator	Description	Example
`:` or `=`	Equals	`video_width = 1920`
`<`	Less than	`minutes < 30`
`<=`	Less than or equal to	`minutes <= 22`
`>`	Greater than	`minutes > 60`
`>=`	Greater than or equal to	`minutes >= 60`
`!=`	Not equals	`video_height != 2160`
`between`	Range query (`[]` inclusive, `()` exclusive)	`minutes between [10, 30]`

Date fields

Date fields support both absolute and relative date expressions. Accepted formats are YYYY-MM-DD or YYYYMMDD (optionally wrapped in double quotes). Absolute dates:

Operator	Description	Example
`:` or `=`	Equals	`release_date = 1990-12-05`
`<`	Before	`release_date < 2020-01-01`
`<=`	On or before	`release_date <= 2020-01-01`
`>`	After	`release_date > 2000-01-01`
`>=`	On or after	`added_date >= 2024-06-01`
`!=`	Not equals	`release_date != 2000-01-01`
`between`	Date range	`release_date between [2000-01-01, 2010-12-31]`

Relative dates:

Operator	Description	Example
`inthelast`	Within the given time period	`release_date inthelast 2 weeks`
`notinthelast`	Outside the given time period	`added_date notinthelast 1 year`

Relative dates take a number and a time unit: day(s), week(s), month(s), or year(s). These expressions are evaluated at query time, so inthelast 2 weeks always refers to the most recent two weeks from the current date.

release_date inthelast 30 days
added_date inthelast 6 months
release_date notinthelast 1 year

Compound queries

Use AND and OR to combine query clauses. Use parentheses to group clauses in complex queries:

genre IN [Horror, Comedy] AND title <= A

Available search fields

Field	Type	Description
`title`	string	Program title
`type`	string	Program type (`show`, `movie`, `episode`)
`rating`	string	Content rating (e.g., `PG-13`)
`duration`	number	Duration in milliseconds
`minutes`	number	Duration in minutes
`seconds`	number	Duration in seconds
`actor`	string	Actor name
`writer`	string	Writer name
`director`	string	Director name
`genre`	string	Program genre (e.g., `Comedy`)
`tags`	string	Program tags
`video_codec`	string	Video codec (e.g., `hevc`)
`audio_codec`	string	Audio codec (e.g., `ac3`)
`video_height`	number	Video height in pixels (e.g., `1080`)
`video_width`	number	Video width in pixels (e.g., `1920`)
`video_bit_depth`	number	Video pixel bit depth (e.g., `10`)
`audio_channels`	number	Audio channel count (e.g., `2`; 5.1 = `6`)
`audio_language`	string	Audio language — ISO 639-2 codes (e.g., `eng`, `spa`)
`subtitle_language`	string	Subtitle language — ISO 639-2 codes (e.g., `eng`)
`release_year`	number	Release year (e.g., `1990`)
`release_date`	date	Original release date (`YYYY-MM-DD`)
`added_date`	date	Date added to Tunarr
`show_title`	string	Title of the parent show (episodes only)
`show_genre`	string	Genre of the parent show (episodes only)
`show_tags`	string	Tags on the parent show (episodes only)
`show_studio`	string	Studio of the parent show
`media_source_name`	string	Name of the media source (e.g., `My Plex`)
`library_name`	string	Name of the library within the media source

Get Started

Media Sources

Channels

Scheduling

Library & Clients

Configuration

Help

Stream Troubleshooter: Diagnose Tunarr Playback Issues

Accessing the Troubleshooter

System Navigation

Program Context Menu

Running a Troubleshoot Session

Understanding the Results

Producing a Troubleshoot Report for Bug Reports

Privacy: What’s redacted automatically

Changing the Log Level for Deeper Debugging

Collecting logs for a bug report

Search Syntax Reference

String fields

Number fields

Date fields

Compound queries

Available search fields

Build docs developers (and LLMs) love

Get Started

Media Sources

Channels

Scheduling

Library & Clients

Configuration

Help

Documentation Index

​Accessing the Troubleshooter

System Navigation

Program Context Menu

​Running a Troubleshoot Session

​Understanding the Results

​Producing a Troubleshoot Report for Bug Reports

​Privacy: What’s redacted automatically

​Changing the Log Level for Deeper Debugging

​Collecting logs for a bug report

​Search Syntax Reference

​String fields

​Number fields

​Date fields

​Compound queries

​Available search fields

Build docs developers (and LLMs) love

Accessing the Troubleshooter

Running a Troubleshoot Session

Understanding the Results

Producing a Troubleshoot Report for Bug Reports

Privacy: What’s redacted automatically

Changing the Log Level for Deeper Debugging

Collecting logs for a bug report

Search Syntax Reference

String fields

Number fields

Date fields

Compound queries

Available search fields