Tunarr: a spoofed HDHomeRun tuner that turns your Plex, Jellyfin or Emby library into live channels

The gap Tunarr fills between a media library and a TV guide

A Plex, Jellyfin or Emby library is a catalogue. You pick a title, you press play, the item ends, and nothing follows it. Tunarr inserts a schedule between the catalogue and the player. The README describes the result as building custom live TV channels out of existing media (movies, TV episodes, music videos, or local files) and streaming them as if they were real broadcast channels. The audience is people who already have a library and a client, and who want the lean-back behaviour of linear television without subscribing to one. The second audience is IPTV tooling: the project advertises M3U output aimed at Dispatcharr, Threadfin, xTeVe or any IPTV client, which means Tunarr can sit underneath an existing proxy stack rather than replace it.

Two output surfaces: a spoofed HDHomeRun tuner and an M3U playlist

The mechanism is protocol emulation. Tunarr presents itself as an HDHomeRun tuner, the network device Plex, Jellyfin and Emby already know how to discover and tune. The README calls this a spoofed HDHR tuner and lists it as the integration path for all three servers. In parallel, Tunarr emits an M3U URL that any IPTV player can consume, with Tivimate and UHF named as examples. Both surfaces point at the same channel definitions, so the scheduling work is done once and exposed twice. Channel lineups are assembled in a drag-and-drop editor, with time-slot and random-slot scheduling tools, filler content between programs (commercials, music videos, prerolls, branding) and per-channel logos. Filler is the part that separates this from a plain playlist: it is what makes the gap between two programmes look intentional rather than like a stall.

Running it: one Compose file, one volume, one port

The README's quick start is a docker-compose.yml with the image chrisbenincasa/tunarr:latest, a port mapping of 8000:8000, TZ set to a timezone, and a bind mount of ./tunarr-data onto /config/tunarr, with restart: unless-stopped. The command is docker compose up -d, after which the README states Tunarr is available at http://localhost:8000. Alternative install paths are listed as standalone binaries for Linux, macOS and Windows, an Unraid Community App Store entry, a Proxmox LXC helper script, and a linux/arm64 Docker image for ARM boards such as Raspberry Pi. The development path is pnpm i followed by pnpm turbo dev, which the README says runs the backend on port 8000 and the frontend at :5173/web. Transcoding is configured separately, and the README points to a transcoding docs page for hardware acceleration rather than inlining the settings. If you want NVENC, VAAPI, QuickSync or VideoToolbox, that page is where the flags live; the README does not reproduce them.

The transcoding layer is where the operational cost lands

Tunarr lists hardware-accelerated transcoding across Nvidia NVENC, VAAPI, Intel QuickSync and macOS VideoToolbox, with multiple transcode profiles configurable per channel. That flexibility has a price the README does not quantify. The container needs access to the relevant device nodes to reach a GPU, and the host needs the matching drivers; a Compose file with only ports, TZ and a volume will not expose them. Per-channel profiles also mean per-channel decisions: a channel that direct-plays costs almost nothing, while one that transcodes every stream consumes CPU or GPU for as long as somebody is watching. The README gives no guidance on concurrent stream limits, no sizing table, and no statement about what happens when the encoder is saturated. Treat capacity as something you measure on your own hardware, not something the project tells you.

Where Tunarr is the wrong tool

Tunarr is not a media server and does not pretend to be one. The README's first line assumes you already have media on Plex, Jellyfin, Emby or local files. If you have none of those, Tunarr has nothing to schedule. It is also not a downloader, a metadata agent or a library organiser; it consumes libraries, it does not build them. The local-files path is the one place where the README is thinnest: it mentions local file libraries and NFO in the repository description, but the quick start and feature list give no worked example of pointing Tunarr at a directory of files without a Plex, Jellyfin or Emby server in front of it. If that is your intended setup, verify it against the documentation before you plan around it. Finally, the project is on a dev release train, with v1.4.0-dev.1 published alongside the stable v1.3.14 and v1.3.13 tags. Running :latest means you are following that train.

How this differs from ErsatzTV

ErsatzTV occupies the same problem space: linear channels generated from a personal media library, exposed to HDHomeRun-aware clients. The practical difference to check is which servers each project reads from and how each one schedules. Tunarr's README is explicit that it connects Plex, Jellyfin, Emby and local files, and that its scheduling surface is a web UI with drag-and-drop lineups plus time-slot and random-slot tools. If your library lives somewhere Tunarr does not list, or if you need a scheduling model the web editor does not express, ErsatzTV is the comparison worth making. The other axis is the output side: Tunarr documents an M3U path aimed at Dispatcharr, Threadfin and xTeVe, so if you already run one of those proxies, Tunarr is designed to slot underneath it rather than compete with it.

Licence, maintenance and what a Zlib release train implies

Tunarr ships under the Zlib licence, a permissive, OSI-approved licence. The practical effect is that you can run it, modify it and redistribute it, with the licence's conditions attached to distributed source; this is a description of the licence family, not legal advice, and anyone embedding Tunarr in a product should read the LICENSE file in the repository. Maintenance cost is the more interesting question. The release history shows a steady cadence: v1.3.13 in mid-August, then v1.3.14 and v1.4.0-dev.1 on the same day in early September. That pattern suggests active development with a stable line and a development line running in parallel. For a self-hosted deployment the cost is not the upgrade itself but the state: channel definitions, logos and the automatic configuration backups the README mentions all live under /config/tunarr in the container, which maps to ./tunarr-data on the host. Back up that directory before pulling a new image, and pin a tag rather than tracking :latest if you want the dev line to stay out of your living room.

Editorial conclusion

Adopt Tunarr if you already run Plex, Jellyfin or Emby and want a linear channel that an existing HDHomeRun-aware client can tune into without new hardware. Do not adopt it if you have no FFmpeg-capable host, no transcode headroom, or no appetite for running a Node service alongside your media server. Before committing, verify three things: that your client accepts a spoofed HDHR tuner, that your host can run the transcoding profile you need, and that ./tunarr-data on the host maps cleanly to /config/tunarr in the container, because that single volume holds your channel definitions and the automatic configuration backups the README mentions.

Official sources

1. chrisbenincasa/tunarr on GitHub
2. License: Zlib
3. Project website
4. README
5. Releases