Tunarr

Last reviewed Sep 13, 2026 · 904 words

Tunarr exists to solve one problem: you have 400 films and 60 series on a media server and nobody in the house can decide what to watch. It schedules your own library into numbered channels with a programme guide, so you turn on "channel 3" and something is already playing. The 2,573-star project is the spiritual successor to dizqueTV, it is written in TypeScript, and it needs three things you may not have yet: an existing media server, a client that can talk to an HDHomeRun tuner, and a CPU or GPU willing to transcode 24 hours a day.

You are running a TV station, not a media server

Tunarr owns no media. It asks Jellyfin, Plex or Emby for their library, you drag items into a channel, and Tunarr produces a continuous stream that looks like a broadcast: programmes back to back, filler clips between them, a schedule that advances whether or not anyone is watching. It then pretends to be two things clients already understand. To Plex and Jellyfin's Live TV feature it looks like an HDHomeRun network tuner, and to everything else it publishes an M3U playlist plus an XMLTV guide file. Any IPTV app on a phone, TV or set-top box can consume that pair.

The consequence is that Tunarr is always the second server you install, and the quality of your evening depends on the first one. If Jellyfin is not set up well yet, the complete Jellyfin setup is the place to start.

The container is easy, the transcoding budget is not

The default image runs on 512 MB of RAM and stores its database and channel state in one volume:

services:
  tunarr:
    image: chrisbenincasa/tunarr:latest
    ports:
      - "8000:8000"
    volumes:
      - ./tunarr:/config/tunarr
    restart: unless-stopped

Open port 8000, add your media server under Settings with an API key, and the channel editor appears. That part takes 15 minutes. The part that takes longer is ffmpeg. A live channel is a single continuous transport stream, so every programme boundary, resolution change and subtitle burn-in has to be normalised, and Tunarr does that by transcoding. One 1080p channel on a modern x86 CPU costs roughly 1 core of sustained load; 4 channels running simultaneously is a real workload. Use the hardware-accelerated image variants (there are tags for NVIDIA and VAAPI) and pass the GPU device through, or accept that each concurrent channel costs a CPU core. Nobody is watching channels that nothing is tuned to, so idle cost is small, but the moment three TVs pick three channels, the box works.

Channel design is where the fun and the effort live

The editor lets you build a channel three ways: a hand-ordered list of episodes, a random slot schedule ("sitcoms 6 to 8 pm, films after"), or a time-slot grid that mimics a real network. Filler collections fill the gaps between programme lengths so a 43-minute episode does not leave 17 minutes of dead air. Flex time and "shuffle by show" options keep a series channel from playing season 1 forever.

Two habits pay off. Keep channels narrow (one for a specific series, one for 90s action films, one for kids' shows) because broad channels feel like a random playlist, which is the thing you were trying to escape. And set a channel's start time at creation, since Tunarr computes "what is on right now" from the schedule's origin; changing it later shifts the whole guide.

Where it fits against ErsatzTV

The other project in this niche is ErsatzTV, a C# application with a very similar goal. ErsatzTV has been around longer, has deeper scheduling (playout templates, deco blocks, per-channel watermarks) and tends to be the safer choice for people who want fine control and mature docs. Tunarr, the newer of the two, has the friendlier web editor and the nicer first-hour experience, and its Plex and Jellyfin integration is a touch more direct. Both output M3U and XMLTV, both emulate HDHomeRun, and both require the same transcoding budget. If you are the kind of person who reads the scheduling docs before installing, pick ErsatzTV; if you want a channel running tonight, pick Tunarr.

For the playback side, note that Plex's Live TV and DVR feature requires a Plex Pass, while Jellyfin's Live TV is free. On Jellyfin the tuner shows up under Dashboard, Live TV, Add tuner device, HDHomeRun, with the Tunarr URL. If you already run a proxy like Threadfin for real IPTV sources, Tunarr's M3U can be added to it as one more provider.

What I'd do

Run Tunarr on the same host as Jellyfin, with the VAAPI or NVIDIA image and the GPU shared between them, and start with 2 channels: one series you are rewatching anyway and one broad film channel with 5 minutes of trailers as filler. Point Jellyfin's Live TV at it, put the channels on the living-room TV, and see whether the household actually turns them on for a fortnight. If they do, expand the lineup and reserve a core per simultaneous viewer; if they do not, Tunarr costs nothing to leave idle. Tunarr is a genuinely delightful gadget in the media server category, but it is a layer on top of a good library, never a substitute for one.