Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ErsatzTV/legacy/llms.txt

Use this file to discover all available pages before exploring further.

ErsatzTV Legacy includes a built-in HDHomeRun (HDHR) emulation layer that makes it appear as a physical network TV tuner on your local network. DVR software and media servers that know how to find and communicate with HDHomeRun devices — including Plex, Emby, and Channels DVR — can discover ErsatzTV automatically and treat it as a cable or OTA tuner. No extra plugin or adapter is required on the client side.

​
What HDHomeRun Emulation Does

HDHomeRun is a family of network-attached TV tuners made by SiliconDust. Many DVR applications have native support for discovering and recording from these devices. ErsatzTV implements the same HTTP-based discovery and lineup API that real HDHomeRun devices expose, so compatible software finds ErsatzTV alongside any real tuners on the network. When a client discovers ErsatzTV via HDHR, it receives a channel lineup where every enabled channel points to a Transport Stream URL. The emulated device identifies itself as model HDTC-2US with firmware hdhomeruntc_atsc, which is broadly compatible with HDHomeRun-aware applications.

​
HTTP API Endpoints

ErsatzTV exposes four HTTP endpoints that form the HDHR device API:
EndpointDescription
GET /device.xmlUPnP device description XML; identifies ErsatzTV as an HDHomeRun-compatible MediaServer
GET /discover.jsonDevice discovery response; returns device ID, tuner count, firmware info, and lineup URL
GET /lineup_status.jsonReports scan status and source type (Cable)
GET /lineup.jsonFull channel lineup; one entry per enabled channel with stream URL and guide number

​
discover.json Response

{
  "DeviceID": "a1b2c3d4-e5f6-...",
  "FriendlyName": "ErsatzTV",
  "ModelNumber": "HDTC-2US",
  "FirmwareName": "hdhomeruntc_atsc",
  "FirmwareVersion": "20190621",
  "Manufacturer": "ErsatzTV",
  "ManufacturerURL": "https://github.com/ErsatzTV/legacy",
  "TunerCount": 4,
  "LineupURL": "http://ersatztv.local:8409/lineup.json",
  "DeviceAuth": ""
}

​
lineup.json Response

[
  {
    "GuideNumber": "2.0",
    "GuideName": "Movies 24/7",
    "URL": "http://ersatztv.local:8409/iptv/hdhr/channel/2.0.ts"
  },
  {
    "GuideNumber": "5.0",
    "GuideName": "News Loop",
    "URL": "http://ersatztv.local:8409/iptv/hdhr/channel/5.0.ts"
  }
]

​
lineup_status.json Response

{
  "ScanInProgress": 0,
  "ScanPossible": 1,
  "Source": "Cable",
  "SourceList": ["Cable"]
}

​
HDHR Stream URL

All channels in the HDHR lineup use Transport Stream, regardless of how the channel’s streaming mode is individually configured: 
GET  /iptv/hdhr/channel/{channelNumber}.ts
HEAD /iptv/hdhr/channel/{channelNumber}.ts
For channels whose streaming mode is set to Legacy TS (TransportStream), the URL includes ?mode=ts-legacy. All other channels use the standard TS Hybrid mode without a query parameter. HDHR clients always receive a valid Transport Stream — HLS modes are never used in HDHR lineup entries.
The HDHR stream endpoint is part of the IPTV controller and is protected by the same conditional JWT authentication as the rest of the IPTV endpoints. If JWT authentication is enabled, HDHR clients must include a valid token. However, most HDHomeRun-compatible DVR software does not support custom authentication headers, so enabling JWT auth may break HDHR discovery. See Authentication for details.

​
Discovery Protocol

HDHomeRun discovery works at two levels: UDP Broadcast Discovery (port 65001): Clients send a UDP broadcast packet on the local network. ErsatzTV does not implement a UDP responder — discovery via UDP broadcast is not available. Clients that rely exclusively on UDP discovery must be pointed to ErsatzTV’s IP address manually. HTTP-based Discovery: Clients that can be given an explicit IP address or hostname will connect directly to the HTTP endpoints above. This is the primary discovery mechanism for Plex, Emby, and Channels DVR when you provide the ErsatzTV address manually.
Because ErsatzTV does not respond to UDP broadcast discovery, HDHomeRun-compatible clients will not find it automatically by scanning the network. You must enter ErsatzTV’s IP address or hostname explicitly in the client’s tuner setup. The TCP control port referenced in the HDHR specification (65001) is not used by ErsatzTV — all communication goes through the standard HTTP port (8409 by default).

​
HDHomeRun Settings

The HDHR settings are accessible in the ErsatzTV web UI at Settings > HDHR (/settings/hdhr).
SettingDescription
UUIDThe unique device identifier reported in discover.json and device.xml. Read-only; assigned automatically and stable across restarts.
Tuner CountThe number of simultaneous streams reported to clients. Must be greater than zero. Clients use this to limit how many concurrent recordings they attempt.
Set Tuner Count to match the number of channels you expect clients to record simultaneously. ErsatzTV does not enforce any actual tuner limit — the value is advisory and reported to clients only.

​
Use Cases

Plex DVR

Plex Live TV & DVR can discover ErsatzTV as a network tuner. Once configured, Plex shows ErsatzTV channels in its Live TV guide and can schedule recordings using ErsatzTV’s XMLTV EPG.

Emby LiveTV

Emby’s Live TV feature supports HDHomeRun tuners natively. Point Emby to ErsatzTV’s address and it will import all channels and start recording programs from the playout schedule.

Channels DVR

Channels DVR has first-class support for HDHomeRun devices. ErsatzTV can be added as an HDHomeRun source, and Channels DVR will handle recording, time-shifting, and guide data automatically.

Other HDHR Clients

Any application that supports manually entering an HDHomeRun device IP — including some smart TV apps and third-party DVR software — can receive ErsatzTV’s channels via the HDHR emulation endpoints.

​
Configuring Plex DVR

1

Open Plex Live TV Settings

In Plex Web, navigate to Settings > Live TV & DVR. Click Set Up Plex DVR if you have not configured a DVR source before, or Add Device to add a new tuner.
2

Enter the ErsatzTV Address

When Plex asks to scan for devices, it may not find ErsatzTV automatically because UDP broadcast discovery is not supported. Enter the ErsatzTV address manually:
http://ersatztv.local:8409
Plex will connect to /discover.json on that address and retrieve device details.
3

Confirm Device Detection

Plex should display the device as ErsatzTV with model number HDTC-2US and the tuner count you configured in Settings > HDHR. Confirm the device and proceed.
4

Configure the Channel Guide

Plex will ask for a guide data source. Select XMLTV and point it to:
http://ersatztv.local:8409/iptv/xmltv.xml
Plex will import the channel lineup from /lineup.json and populate the guide from the XMLTV feed.
5

Map Channels

Plex may present a channel mapping step. Confirm that ErsatzTV’s channel numbers match the entries in the lineup. Once mapping is complete, ErsatzTV channels appear in the Plex Live TV guide and are available for DVR recording.

​
Configuring Emby LiveTV

1

Open Emby Live TV Settings

In the Emby dashboard, navigate to Settings > Live TV. Under TV Sources, click Add.
2

Select HDHomeRun Tuner

Choose HDHomeRun as the tuner type. Enter the ErsatzTV server address:
ersatztv.local:8409
Emby will connect to the HDHR API endpoints and discover the channel lineup.
3

Add the XMLTV EPG

Under TV Guide Data Providers, click Add and select XMLTV. Set the URL to:
http://ersatztv.local:8409/iptv/xmltv.xml
Save the settings and allow Emby to refresh the guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us