Skip to main content

Plex

Use this guide to connect Plex Live TV & DVR to Headendarr using HDHomeRun tuner emulation and XMLTV guide data.

The recommended setup is the managed Plex integration using PLEX_SERVERS_JSON. That gives Headendarr a direct way to keep Plex tuners, channel mappings, and DVR settings aligned with your Headendarr configuration, which makes ongoing Plex management much easier.

If you do not want to provide a Plex token to the Headendarr container, you can still connect Plex manually. That path works, but you will be responsible for adding tuners and maintaining the setup yourself.

:::warning HLS Proxy Remux Limitation Plex Live TV/DVR can have playback issues with HLS (.m3u8) channel streams. For best compatibility, make sure Plex receives MPEG-TS (.ts) streams for those channels.

For many sources, forcing audio to AAC with an MPEG-TS output improves Plex stability significantly with minimal extra overhead compared with failed tune/retry loops. :::

:::warning Channel Logo Reachability Plex does not cache channel logo images for Live TV/DVR. It keeps using the logo URL that Headendarr publishes.

If your Headendarr base URL or logo URLs point to a local-only IP or hostname, Plex apps that are not on that same network, such as mobile apps on Android, may fail to load channel logos in the DVR or guide views.

For reliable logo loading, use a Headendarr URL that your Plex clients can actually reach. :::

Container configuration​

Set PLEX_SERVERS_JSON in your Headendarr container environment, then restart the container.

This is the preferred Plex setup because it unlocks automatic Plex management inside Headendarr instead of treating Plex as a one-time manual tuner setup.

Example docker-compose.yml snippet:

services:
  headendarr:
    image: ghcr.io/headendarr/headendarr:latest
    environment:
      PLEX_SERVERS_JSON: >-
        [{"name":"Command","base_url":"http://192.168.7.234:32400","token":"YOUR_TOKEN","verify_tls":false}]

What this enables in Headendarr:

  1. A dedicated Plex Settings page appears when PLEX_SERVERS_JSON is valid.
  2. Per Plex server settings control whether tuner sync is enabled, tuner mode, model prefix, and stream profile.
  3. Headendarr can automatically provision and keep Plex tuners in sync:
    • create missing managed tuners
    • update channel mappings after channel/source changes
    • remove stale managed tuners
    • remove managed tuners for enabled sources that currently publish an empty HDHomeRun lineup

:::info Server name matching The name field in each PLEX_SERVERS_JSON entry should match that Plex server's current friendly name. Headendarr currently validates the configured name against the live server identity before applying tuner changes. :::

PLEX_SERVERS_JSON Generator​

Use this form to generate a valid PLEX_SERVERS_JSON environment variable value for one or more Plex servers.

Server 1
Follow this guide to fetch your Plex token.
Server entries 1 are incomplete and excluded from output.

Plex Settings Page​

After PLEX_SERVERS_JSON is valid and the container has restarted, open Plex Settings in Headendarr.

For most users, the most important settings are:

  • Headendarr base URL: the address Plex should use to reach Headendarr's HDHomeRun and XMLTV endpoints
  • Stream user: the Headendarr user whose stream key will be published to Plex
  • Default tuner mode:
    • Per source if you want one managed Plex tuner per Headendarr source
    • Combined if you want one shared managed tuner

Once those are correct, Headendarr can do most of the ongoing Plex maintenance for you.

Each configured Plex server exposes these groups of settings:

  • Connection
    • Enabled: turns automatic tuner reconciliation on or off for that Plex server.
    • Headendarr base URL: the URL Plex should use to reach Headendarr's HDHomeRun and XMLTV endpoints.
    • Stream user: selects which Headendarr user's stream key is published to Plex.
  • Tuner Settings
    • Default tuner mode:
      • Per source publishes one managed tuner per Headendarr source.
      • Combined publishes one combined managed tuner.
    • Stream profile: selects the profile segment used in generated HDHomeRun endpoints.
    • Optional recording-time transcode controls are also available for compatible Plex workflows.
  • DVR Settings
    • Resolution preference, replace-lower-quality behaviour, partial-airing behaviour, guide enrichment, post-processing script, commercial detection mode, and guide refresh cadence.
    • Headendarr also pushes your global DVR start/end padding into Plex's DVR settings during reconcile.

Settings on this page auto-save. Headendarr then queues a Plex reconcile run after Plex settings are saved.

Reconcile Behaviour​

Plex tuner reconciliation runs whenever Plex settings are saved in Headendarr, and otherwise runs on the background scheduler every 5 minutes to keep Plex aligned with the current Headendarr configuration.

In practice, this means you manage channels, guide mappings, and source changes in Headendarr, and Headendarr handles keeping Plex up to date for you.

During reconciliation, Headendarr can:

  • create missing managed tuners
  • attach new tuners to the correct Plex DVR
  • update existing tuners in place when settings change
  • refresh channel mappings after source or channel changes
  • remove stale managed tuners

It also includes safety checks to avoid deleting the last tuner on a Plex DVR, which helps prevent Plex from dropping the whole DVR configuration and protects your existing DVR setup and recordings.

Manual setup​

Use this path only if you do not want to provide a Plex token to the Headendarr container and would rather manage the Plex side manually.

Steps​

Plex works best here when it receives MPEG-TS compatible streams. Before adding the tuner in Plex, use one of these compatibility options:

In Headendarr:​

Option #1 (most reliable)

  1. Enable Route per-source playlists & per-source HDHomeRun via TVHeadend in Application Settings.
  2. This applies to per-source endpoints and makes TVHeadend the stream client for those routes.
  3. For best stability with CSO-backed mux paths, set TVHeadend Settings -> Stream Buffer to CSO.
  4. If you prefer a manual FFmpeg wrapper instead, set TVHeadend Settings -> Stream Buffer to Custom FFmpeg args, for example:
-hide_banner -loglevel error -probesize 10M -analyzeduration 0 -fpsprobesize 0 -i [URL] -c copy -metadata service_name=[SERVICE_NAME] -f mpegts pipe:1

Option #2

  1. Enable Use HLS Proxy and Enable FFmpeg remux on the source in Stream Source Settings so HLS sources are remuxed to MPEG-TS.

In Plex:

  1. Navigate to the Live TV & DVR page in Plex.
  2. Click Set Up Plex Tuner.

Plex add first tuner

  1. Click Don't see your HDHomeRun device? Enter its network address manually to enter the address manually.

  2. In Headendarr, open Show connection details.

  3. Copy either a per-source HDHomeRun URL (best for source limits) or the combined HDHomeRun URL.

  4. Paste that URL into the HDHOMERUN DEVICE ADDRESS field.

Copy HDHomeRun emulator URL

  1. Click Connect. You should now see your tuner with its details and available tuners.
  2. Click Have an XMLTV guide on your server? Click here to use it.

Click to use XMLTV

  1. Copy the XMLTV Guide URL from Show connection details and paste it into the XMLTV GUIDE field.

Copy XMLTV URL

  1. Click Continue. You will see a list of tuner channels and a list of EPG channels. Confirm they are paired correctly.
  2. Click Continue again. Live TV should now be set up and connected to Headendarr.
  3. Click Add Another Device and repeat for each HDHomeRun tuner source. Each source should enforce its own connection limits in Plex Live TV & DVR.

Add additional tuners