ErsatzTV next backend¶
Tunarr can hand a channel to ersatztv-channel, a standalone worker from the ErsatzTV next project that transcodes and segments the channel itself instead of Tunarr running its own FFmpeg pipeline.
Experimental
Tunarr pins ErsatzTV next release v0.2.3 and refuses a bundled worker from any other release. A worker you point at with TUNARR_ERSATZTV_NEXT_PATH still runs, but Tunarr logs a warning and streams may fail in ways its schema checks cannot catch.
This page covers how your FFmpeg and transcode settings reach the worker. For what the backend is and how it plays a channel, see Channel Transcoding Settings.
Turning it on¶
There are two ways in, meant to be used in that order.
One channel at a time. Open a channel, go to the Streaming tab, and tick Use ErsatzTV next Backend. Only that channel moves to the worker; everything else keeps using Tunarr's pipeline. Use this to try the backend on a channel you do not mind breaking before you commit the rest.
All channels at once. Set TUNARR_ERSATZTV_NEXT_ENABLED=true (see Environment Variables), or turn on ErsatzTV next Streaming Backend under Settings → Features. Every eligible channel is then served by the worker whether or not it was ticked individually, so the per-channel box disappears from the editor while this is on. Switching it back off returns each channel to whatever its own box says.
Either way, only channels set to HLS, HLS Direct v2 or MPEG-TS are eligible. The worker only writes HLS, and HLS Direct remuxes without transcoding, which it cannot do, so HLS alt and HLS Direct always stay on Tunarr's pipeline. The per-channel box is disabled on those two modes.
Nothing else about a channel changes. The stream mode you picked still means what it did.
How settings are translated¶
When a channel starts, Tunarr writes a channel.json for the worker, built from the channel's transcode config and the global FFmpeg settings on this page. The worker's configuration does not cover everything a transcode config can express, so a setting either translates, is refused, or is dropped.
Refused settings¶
A transcode config with any of these cannot back a channel on this backend. The channel fails to start rather than streaming with a substitution you did not ask for.
| Setting | Accepted values |
|---|---|
| Audio format | aac, ac3 |
| Hardware acceleration | none, cuda, qsv, vaapi, videotoolbox |
The transcode config editor warns about these while the backend is on globally or for any channel that uses the config. The channel editor shows the same warning under Use ErsatzTV next Backend once the box is ticked. Either way you can find an offending config before a viewer does.
Dropped settings¶
These translate to nothing on the worker. The channel streams; it streams without them.
| Setting | What happens |
|---|---|
| Thread count | The worker chooses its own. |
| Video preset and profile | The worker exposes neither yet. |
| Audio volume | The worker has no volume filter. |
| Normalize frame rate | The worker does not normalize frame rate. |
VAAPI driver nouveau |
It has no counterpart. i965, ihd and radeonsi translate. |
Tunarr logs the dropped settings once when a channel starts, and the transcode config editor lists them.
VAAPI defaults¶
An unset VAAPI device and a driver of system are left for the worker to fill
in. It uses /dev/dri/renderD128, the same default the built-in pipeline uses,
and lets libva choose the driver. An explicit device or driver is passed
through untouched.
Audio and subtitles¶
The channel's stream selection profile picks the audio and subtitle tracks, the same way it does on Tunarr's own pipeline. Tunarr tells the worker which tracks to play for each program.
- Subtitles play only when the channel has subtitles turned on.
- Image subtitles (PGS, DVD) are always burned into the picture.
- Text subtitles depend on the sidecar subtitles feature in Settings > Features. With it on, they become a WebVTT track that players can toggle. With it off, they are burned in, but only when they come from a separate file. Text subtitles embedded in the media file are skipped.
- A file with no audio plays with silence, so the channel keeps its audio track.
Watermarks¶
The channel watermark is drawn by the worker, with the same image, position, size, margins and opacity as on Tunarr's own pipeline. The Disable Watermarks transcode setting and the channel's Hide watermark during filler switch work the same way, and a channel without a watermark URL falls back to its icon. Flex and error screens carry no watermark.
Two timing settings behave a little differently:
- Fade cycles follow the clock, not the start of each program. Every viewer sees the watermark fade in and out at the same moment, and the cycle does not restart when a new program begins. Leading edge decides whether the visible half of each cycle comes first.
- Duration still shows the watermark for that many seconds from the start of each program. With a fade cycle also set, a fade already in progress when the duration runs out finishes before the watermark hides.
Known gaps¶
- Programming edits land at the next item, not immediately. The worker asks Tunarr what to play one item at a time, and it transcodes up to 44 seconds ahead of what viewers see. An edit takes effect the next time the worker asks. Anything already transcoded plays as it was.
Troubleshooting a channel¶
The Stream Troubleshooter runs the same diagnostic transcode it always has, but for a channel on this backend it runs through the worker rather than through Tunarr's pipeline, so the report describes what actually plays.
Two things read differently than they do for a Tunarr-pipeline channel:
- The FFmpeg command is the one the worker resolved, not one Tunarr built.
- The FFmpeg log comes from the dossier the worker leaves behind, which also holds the pipeline, media info and playout item it resolved.
Any refused or dropped setting is listed with the errors, so a report from a channel that streams differently than its config reads says why.
Media server tokens are stripped from the command, the log and the report, so a troubleshoot report is safe to attach to a bug report.
Diagnostic bundles¶
Every time the worker cannot play an item it writes a bundle to etv-diagnostics/<channel id>/ under Tunarr's data directory. Each one holds the FFmpeg report or its stderr tail, the resolved pipeline and hardware acceleration, the playout item, the probe output, the merged channel config the worker actually ran with, and the outcome.
This is on and needs no setting. A channel keeps its five most recent bundles; older ones are removed when the channel next starts. Turning off file logging does not turn it off, because the bundle is what a bug report needs and asking for it after the fact means asking someone to reproduce a failure they have already had.
The Stream Troubleshooter offers Download Backend Diagnostics for a channel that has any, which hands back all five as one zip. Plex, Jellyfin and Emby tokens are removed from the files before they are zipped.