tunarr.com

Tunarr is a self-hosted tool that turns media already on your Plex or Jellyfin server into live TV channels. You configure channels, programs, commercials, and settings in a web UI, then watch them by adding Tunarr's spoofed HDHomeRun tuner to Plex, Jellyfin, or Emby, or by loading a generated M3U file into a third-party IPTV player. It fits best if you already run a media server and want scheduled, channel-style viewing rather than on-demand playback.

What Tunarr actually does

The core idea is that your existing library becomes the source for continuous channels. Tunarr does not replace Plex or Jellyfin; it sits alongside them and presents your media as a tuner source that other apps can consume.

How you watch the channels

There are two supported paths, and the right one depends on your player:

• Plex, Jellyfin, or Emby: add the spoofed Tunarr HDHomeRun tuner to the server. This is the native route if you want channels to appear inside the same app you already use for your library.
• Any third-party IPTV player: use the generated M3U files. This is the flexible route if your player of choice is not one of the three servers above.

Both paths come from the same channel configuration, so you can set up channels once and expose them in either form.

What you can configure

Tunarr's documentation organizes configuration into several areas, which gives a sense of how far the tool goes beyond a simple playlist:

• Media sources: Plex, Jellyfin, Emby, and local media, covering movies, shows, other video, music, and music videos.
• Channels: properties, Flex/EPG, transcoding, and watermarks.
• Programming: library content, filler (with its own rules for how filler is chosen), custom shows, smart collections, and trash.
• Scheduling: concepts, slot editor, time slots, cyclic shuffle, block shuffle, mid-roll breaks, replicate, and consolidate.
• System: backup, logging, and miscellaneous settings.

If your goal is just "play my files in order," much of this is optional. The scheduling and filler features matter when you want channels that behave like real broadcast TV, with breaks and recurring blocks.

Where it came from

Tunarr began as a fork of dizqueTV, which itself was a fork of earlier projects, and has since evolved into a near-complete rewrite. The stated goals are to modernize the backend and frontend, stabilize the program, fix bugs, improve performance, refresh the web UI, and add new features. Practically, that means documentation and behavior reflect the rewritten project rather than the older dizqueTV lineage, so setup instructions should be followed from Tunarr's own docs.

Is it the right tool for you?

Tunarr is a good fit if:

• You already have media organized in Plex or Jellyfin.
• You want scheduled, channel-style viewing with commercials, filler, and time-based programming.
• You are comfortable running a self-hosted service, since installation is offered via Docker or standalone binaries.

It is probably not what you need if you only want on-demand playback of your library, or if you do not already run one of the supported media servers. Before committing, check the Getting Started and Install sections of the documentation for the current setup path, and the Common Issues and Stream Troubleshooter pages if playback does not work as expected.

Tunarr builds a live TV channel by filling a timeline with programming you choose, then exposing that timeline to Plex, Jellyfin, Emby, or an IPTV player through a spoofed HDHomeRun tuner or generated M3U file. Scheduling is the part that decides what plays in each time slot, in what order, and how filler and breaks fit around your shows. You configure it in the Tunarr web UI under a channel's scheduling tools, and the result is a repeating lineup rather than a one-off playlist.

The scheduling model: channels, slots, and filler

A channel is the container. Inside it, the schedule is a sequence of time slots that reference media from your configured sources (Plex, Jellyfin, Emby, or local files) plus filler content. The slot editor is where you arrange that sequence. Filler is not random noise dropped in arbitrarily: Tunarr has a defined process for how filler is chosen, so the clips and commercials you add follow rules you set rather than being scattered at will.

Two ideas matter for predicting what a viewer sees:

• The schedule is a loop. Once the lineup is built, it repeats. A viewer tuning in at an arbitrary moment lands wherever the loop happens to be, which is why ordering and slot length shape the experience as much as the content itself.
• Filler fills the gaps. If a slot's content runs shorter than the slot, filler is used to bridge the difference according to Tunarr's filler-selection rules. This keeps the timeline aligned instead of leaving dead air.

Scheduling modes and what each is for

Tunarr's scheduling tools are built around a few distinct modes. They differ in how much control you keep over order versus how much variety you get automatically.

The practical distinction: cyclic shuffle guarantees coverage of the whole set before it loops, while block shuffle preserves internal grouping and varies the order of the groups. Use time slots when the schedule itself is the point; use shuffle modes when you care about rotation fairness or block variety more than exact clock positions.

Actions that reshape an existing schedule

Beyond the modes, Tunarr provides two schedule-level actions:

• Replicate — duplicates a schedule arrangement, useful when you want a similar lineup on another channel or as a starting point you then edit.
• Consolidate — tightens the schedule, removing gaps so programming sits back-to-back.

These are editing operations on the lineup you have already built, not separate scheduling philosophies. Reach for replicate when you are cloning a working channel, and consolidate when your timeline has holes you want closed.

How scheduling connects to the rest of Tunarr

Scheduling sits between your media and your viewers:

1. Media sources (Plex, Jellyfin, Emby, local) supply the movies, shows, other video, music, and music videos.
2. Library and custom shows / smart collections define the pools of content the scheduler draws from.
3. Scheduling arranges those pools into slots, applying shuffle modes and breaks, with filler chosen per Tunarr's rules.
4. Channel properties (flex, EPG, transcoding, watermarks) shape how the finished channel is presented.
5. Clients — Plex, Jellyfin, Emby via the spoofed tuner, or any third-party IPTV app via M3U — play the result.

So a scheduling change is really a change to what content the channel pulls and in what order, and it only becomes visible to viewers once the channel is consumed through one of those clients.

A concrete example

Suppose you have a library of a sitcom's episodes and want a channel that feels like a classic rerun network. You would add the show to the channel's programming, then choose cyclic shuffle so every episode airs before any repeats, and enable mid-roll breaks so each episode is interrupted by filler the way broadcast TV does it. If you later want a second channel with the same structure but different shows, replicate the schedule and swap the programming. If the timeline shows gaps between episodes, consolidate to close them.

Common points to watch

• Filler rules determine gaps, not guesswork. If a slot looks wrong, check how filler is being chosen before assuming the schedule itself is broken.
• Shuffle mode changes fairness. Cyclic shuffle and block shuffle produce different repeat behavior; pick based on whether you want full-set coverage or block variety.
• The schedule is a loop, so "start time" is relative. Viewers join mid-loop, which is normal for this kind of virtual channel.
• Nothing reaches viewers until a client is connected. Scheduling edits are only observable through Plex, Jellyfin, Emby, or an M3U-based player.

For setup specifics and the exact controls, the Tunarr documentation's Scheduling section (covering Concepts, Slot Editor, Time Slots, Cyclic Shuffle, Block Shuffle, Mid-Roll Breaks, Replicate, and Consolidate) is the authoritative reference.

Start with the Stream Troubleshooter in the documentation for playback failures, then check FAQ and Common Issues for known problems. If you need to dig deeper, use the Logging and Backup pages under System, and consult Development / Contributing only when you want to inspect or report the underlying code. These are the support paths listed in the Tunarr docs; there is no separate help desk described on the site.

Quick routing by symptom

Using the Stream Troubleshooter

The Stream Troubleshooter is the dedicated path for playback problems. Work through it in this order:

1. Confirm the client path. Tunarr exposes channels either as a spoofed Tunarr HDHomeRun tuner added to Plex, Jellyfin, or Emby, or as generated M3U files for third-party IPTV players. Note which one you're using — the troubleshooting steps differ.
2. Reproduce the failure on one channel with one program, and note the time it happens.
3. Check the stream path the troubleshooter describes, comparing your client setup against the documented expectations.
4. Capture logs (System → Logging) around the failure time.
5. Re-test after any change, one variable at a time, so you know what fixed it.

Expected result: you either identify a configuration mismatch (tuner, M3U, or client) or collect enough log detail to describe the fault precisely.

Common sticking points

• Tuner vs. M3U confusion. If the HDHomeRun tuner doesn't appear in Plex/Jellyfin/Emby, verify you added the spoofed Tunarr tuner rather than expecting an M3U to work inside those apps. Conversely, IPTV players need the M3U, not the tuner.
• Media source problems look like stream problems. Channels are built from Plex, Jellyfin, Emby, or Local sources. If a channel is empty or a program is missing, check the Media Sources configuration before blaming playback.
• Scheduling gaps. Missing programming often traces to scheduling (slots, flex, filler) rather than streaming. Review the Scheduling concepts and the relevant slot type.
• Changing things without a backup. Before reconfiguring channels or migrating, take a backup via System → Backup so you can restore a working state.

When to go deeper

If the FAQ and Common Issues don't cover your case and logs point to a defect, the Development → Contributing section is where to look for how the project is structured and how to report or investigate. Tunarr began as a fork of dizqueTV and was largely rewritten, so older dizqueTV guidance may not match current behavior — prefer the current docs.

For first-time setup problems rather than playback, the Getting Started path (Install → Run → Setup) is the right starting point before the troubleshooter.

Tunarr works with Plex, Jellyfin, and Emby on both sides of the setup: you can pull media from those servers as sources, and you can watch Tunarr channels through them by adding Tunarr's spoofed HDHomeRun tuner. If you use a different player, Tunarr also generates M3U files that any third-party IPTV player app can open. Local media files are supported as a source as well, so a media server isn't strictly required to build channels.

Media sources you can connect

Tunarr's configuration docs list four source types:

The practical takeaway: if your library already lives in Plex, Jellyfin, or Emby, you point Tunarr at that server and it reads your existing media. If you keep files outside a media server, the Local source covers that case.

How you watch the channels

Tunarr doesn't replace your media server's player. It exposes channels in two ways:

• Spoofed HDHomeRun tuner — add it to Plex, Jellyfin, or Emby as a tuner, and your channels appear alongside live TV in those apps. This is the path that keeps you inside the media server's own interface and clients.
• Generated M3U files — load these into a third-party IPTV player app. This is the path for players outside the Plex/Jellyfin/Emby ecosystem.

Compatibility depends on the combination

The source and the playback client are separate choices, and they don't have to match. You could source media from Emby and watch through Jellyfin, or source from Plex and watch in an IPTV app via M3U. What matters is:

1. Source side — your media server is one of Plex, Jellyfin, or Emby, or your files are reachable as a Local source.
2. Playback side — your player can either add an HDHomeRun tuner (Plex, Jellyfin, Emby) or open an M3U playlist (IPTV apps).

If your player does neither, Tunarr has no documented way to reach it.

Before you commit

Check that your intended player supports tuner or M3U input, since that determines whether the HDHomeRun route or the M3U route applies to you. The project's Stream Troubleshooter and Common Issues pages are the place to look if a channel connects but won't play. Installation itself is covered separately via Docker or standalone binaries, so confirm your hosting method before wiring up sources and clients.

Tunarr can be installed either with Docker or as a standalone binary, then configured through its web UI by connecting a media source such as Plex, Jellyfin, Emby, or local media. After that first connection, you create channels and schedule programming. The steps below follow the structure documented on tunarr.com; exact menu labels may vary slightly by version, so treat the flow as the guide and the UI as the source of truth.

Before you start

• A running media server (Plex, Jellyfin, or Emby) or media files stored locally if you plan to use the Local source.
• A machine to host Tunarr — Docker is the documented path, with standalone binaries as the alternative.
• Network access between Tunarr and your media server, plus the credentials/URL your media server uses.
• A client to watch on later: Plex, Jellyfin, or Emby can use the spoofed Tunarr HDHomeRun tuner, or any third-party IPTV player can use the generated M3U files.

Step 1: Install Tunarr

Choose one of the two documented installation methods:

The documentation's Getting Started → Install section is the authoritative place for the current commands and image/binary details — use it rather than copying commands from elsewhere, since they change between releases.

Step 2: Run and open the web UI

Start Tunarr using your chosen method, then open the Tunarr web UI in a browser. All configuration — channels, programs, commercials, and settings — happens there, so you should not need to edit config files by hand for the initial setup.

Expected result: the Tunarr UI loads and you can reach the setup/configuration area.

Common snag: if the UI doesn't load, confirm the process/container is actually running and that you're using the correct host and port for your deployment.

Step 3: Complete initial setup and connect your first media source

The Setup page covers initial configuration and connecting your first media source. Tunarr supports these source types:

• Plex
• Jellyfin
• Emby
• Local — for media stored on disk, organized into Movies, Shows, Other Video, Music, and Music Videos

For a network media server, enter the server's address and credentials when prompted, then save. For Local, point Tunarr at your media directories and let it scan.

Expected result: your media source appears as connected and Tunarr can see your libraries.

Common snags:

• Wrong URL or credentials for the media server — re-check the address and account you use to log in to Plex/Jellyfin/Emby directly.
• Local paths that the Tunarr process/container can't read — make sure the directories are mounted or accessible to Tunarr.

Step 4: Create your first channel

With a source connected, go to Channels to create and configure a virtual TV channel. From there you can set channel properties and move into Programming and Scheduling to decide what airs and when. Scheduling tools include concepts like time slots, cyclic and block shuffle, mid-roll breaks, and more — start simple with one channel and a small set of programming, then expand.

Step 5: Watch your channel

Once a channel exists, connect a client:

• Plex, Jellyfin, or Emby: add the spoofed Tunarr HDHomeRun tuner as a tuner in that app.
• Any third-party IPTV player: use the M3U files Tunarr generates.

Expected result: the channel shows up in your player's live TV guide and plays.

Common snag: if playback fails, the docs include a Stream Troubleshooter and a Common Issues FAQ under Misc. — check those before changing your setup.

Where to go next

• Configure → Media Sources to add more libraries or sources.
• Channels → Properties / Flex / EPG / Transcoding / Watermarks to refine how channels look and behave.
• Programming → Library / Filler / Custom Shows / Smart Collections to control content, including how filler is chosen.
• System → Backup / Logging to protect your configuration and diagnose problems.

If you get stuck, the FAQ → Common Issues and Stream Troubleshooter pages are the documented first stops.