Plex Integration

Integrate Dispatcharr with Plex using HDHomeRun emulation for live TV streaming

Overview

Dispatcharr integrates with Plex using HDHomeRun emulation, allowing Plex to discover Dispatcharr as a live TV tuner device. This enables you to:

• Watch live TV channels in Plex
• Use Plex DVR to record programs
• Access your IPTV streams through Plex’s interface
• Organize channels using Plex’s TV guide

How It Works

Dispatcharr emulates an HDHomeRun network tuner device. Plex detects it as a physical TV tuner and can use it to:

1. Discover available channels via the lineup API
2. Stream live TV using channel URLs
3. Fetch EPG data for the TV guide
4. Record programs using Plex DVR

Plex detects HDHomeRun devices automatically on the network. No manual configuration is needed if Dispatcharr and Plex are on the same network.

Setup Instructions

1. Ensure Dispatcharr is Running

   Verify that Dispatcharr is accessible on your network. The default port is 9191.

   Test access by visiting: http://YOUR_SERVER_IP:9191

2. Configure Channels

   Before integrating with Plex, make sure you have:

   • Added at least one M3U/Xtream Codes source
   • Imported channels
   • Configured EPG data
   • Assigned channel numbers (required for Plex)
3. Add HDHomeRun Device to Plex

   In Plex:

   1. Go to Settings → Live TV & DVR
   2. Click Set Up Plex DVR
   3. Plex should automatically detect Dispatcharr as an HDHomeRun device
   4. Select the detected device (will show as “Dispatcharr HDHomeRun”)
   5. Click Continue

   If Plex doesn’t auto-detect Dispatcharr, ensure both are on the same network and that port 9191 is accessible.

4. Select Channels

   Plex will fetch the channel lineup from Dispatcharr:

   1. Review the imported channels
   2. Select which channels you want to include
   3. Map EPG data if needed
   4. Click Continue
5. Configure EPG Source

   Plex will ask for an EPG (Electronic Program Guide) source:

   1. Select Have an XMLTV guide on your server
   2. Enter the EPG URL from Dispatcharr:
      http://YOUR_SERVER_IP:9191/epg
      
   3. Click Continue

   Replace YOUR_SERVER_IP with your Dispatcharr server’s IP address. If using Docker, ensure the containers can communicate.

6. Verify Setup

   1. Go to Live TV in Plex
   2. You should see your channels from Dispatcharr
   3. Click on a channel to test streaming
   4. Check the guide to verify EPG data is loading

Using Channel Profiles

You can create multiple HDHomeRun devices in Plex by using Channel Profiles in Dispatcharr:

Default Profile

http://YOUR_SERVER_IP:9191/hdhr/discover.json
http://YOUR_SERVER_IP:9191/hdhr/lineup.json
http://YOUR_SERVER_IP:9191/epg

This allows you to:

• Create different channel lineups for different Plex users
• Separate channels by category or source
• Manage multiple Plex servers with different content

API Endpoints

Dispatcharr provides the following HDHomeRun-compatible endpoints:

Endpoint	Description	Example
/hdhr/discover.json	Device discovery info	Returns device model, tuner count, base URL
/hdhr/lineup.json	Channel lineup	Lists all available channels with URLs
/hdhr/lineup_status.json	Lineup status	Returns scan status and source type
/hdhr/device.xml	Device XML	XML-formatted device information
/proxy/ts/stream/{channel_uuid}	Stream URL	Actual stream endpoint for each channel

Discovery Response Example

{
  "FriendlyName": "Dispatcharr HDHomeRun",
  "ModelNumber": "HDTC-2US",
  "FirmwareName": "hdhomerun3_atsc",
  "FirmwareVersion": "20200101",
  "DeviceID": "12345678",
  "DeviceAuth": "test_auth_token",
  "BaseURL": "http://YOUR_SERVER_IP:9191/hdhr",
  "LineupURL": "http://YOUR_SERVER_IP:9191/hdhr/lineup.json",
  "TunerCount": 10
}

Lineup Response Example

[
  {
    "GuideNumber": "1",
    "GuideName": "ABC HD",
    "URL": "http://YOUR_SERVER_IP:9191/proxy/ts/stream/abc123-uuid",
    "Guide_ID": "1",
    "Station": "1"
  },
  {
    "GuideNumber": "2",
    "GuideName": "CBS HD",
    "URL": "http://YOUR_SERVER_IP:9191/proxy/ts/stream/cbs456-uuid",
    "Guide_ID": "2",
    "Station": "2"
  }
]

Manual Device Configuration

If Plex doesn’t auto-detect Dispatcharr, you can manually configure it:

1. Enable Custom Connections

   In Plex DVR setup, select Enter custom connection

2. Enter Discovery URL

   Enter the discovery endpoint:

   http://YOUR_SERVER_IP:9191/hdhr/discover.json
   
3. Continue Setup

   Follow the normal channel selection and EPG configuration steps.

Docker Networking Considerations

When running both Dispatcharr and Plex in Docker:

Option 1: Host Network Mode

services:
  dispatcharr:
    image: ghcr.io/dispatcharr/dispatcharr:latest
    network_mode: host

This allows Plex to auto-discover Dispatcharr.

Option 2: Bridge Network with Manual Configuration

services:
  dispatcharr:
    image: ghcr.io/dispatcharr/dispatcharr:latest
    ports:
      - "9191:9191"

Use manual device configuration in Plex with the host IP address.

Option 3: Shared Docker Network

services:
  dispatcharr:
    image: ghcr.io/dispatcharr/dispatcharr:latest
    networks:
      - media
  
  plex:
    image: plexinc/pms-docker:latest
    networks:
      - media

networks:
  media:
    driver: bridge

Reference Dispatcharr by container name: http://dispatcharr:9191

Troubleshooting

Plex Can’t Discover Dispatcharr

1. Check Network Connectivity

   Verify both services are on the same network:

   ping YOUR_SERVER_IP
   curl http://YOUR_SERVER_IP:9191/hdhr/discover.json
   
2. Verify Port Accessibility

   Ensure port 9191 isn’t blocked by a firewall:

   sudo ufw allow 9191
   # or
   sudo firewall-cmd --add-port=9191/tcp --permanent
   
3. Use Manual Configuration

   If auto-discovery fails, use the manual device configuration method described above.

Channels Don’t Appear in Plex

• Verify channels have assigned channel numbers in Dispatcharr
• Check that channels are enabled in the active profile
• Refresh the channel lineup in Plex DVR settings

Streams Don’t Play

• Test the stream directly by opening the stream URL in VLC:
  http://YOUR_SERVER_IP:9191/proxy/ts/stream/CHANNEL_UUID
  
• Check Dispatcharr logs for stream errors
• Verify the original stream source is accessible
• Ensure your stream profile is configured correctly

EPG Data Missing

• Verify EPG sources are configured in Dispatcharr
• Check EPG mapping for channels
• Manually refresh EPG in Plex: Settings → Live TV & DVR → DVR Settings → Refresh Guide
• Test EPG URL directly in a browser:
  http://YOUR_SERVER_IP:9191/epg
  

Recording with Plex DVR

Plex DVR can record programs from Dispatcharr streams:

1. Navigate to Live TV in Plex
2. Select a program from the guide
3. Click Record
4. Configure recording options (single episode, series, etc.)
5. Recordings are stored in your Plex DVR library

Recording quality and reliability depend on the source stream stability. Use failover sources in Dispatcharr for better reliability.

Advanced Configuration

Custom Tuner Count

Dispatcharr reports a tuner count to Plex (default: 10). This can be adjusted in Dispatcharr settings to match your concurrent stream limits.

Multiple Profiles for Different Plex Servers

Create separate channel profiles in Dispatcharr and use different URLs for each Plex server:

• Server 1: http://YOUR_IP:9191/hdhr/sports/discover.json
• Server 2: http://YOUR_IP:9191/hdhr/news/discover.json
• Server 3: http://YOUR_IP:9191/hdhr/entertainment/discover.json

Transcoding Considerations

Plex can transcode streams if needed. For optimal performance:

• Use native Plex supported formats (H.264 video, AAC audio) in your streams
• Configure stream profiles in Dispatcharr to pre-transcode if needed
• Enable hardware transcoding in Plex for better performance

Related Resources

• Emby/Jellyfin Integration
• HDHomeRun Device Emulation
• Channel Management
• EPG Configuration Guide