Live TV API

Channel management, stream playback, EPG, DVR, and HDHomeRun emulation.

Channels

List channels

GET /api/livetv/channels
Authorization: Bearer <token>

Response:

[
  {
    "id": 1,
    "name": "Movies",
    "number": 1,
    "sourceType": "virtual",
    "scheduleMode": "shuffle",
    "alwaysOn": false,
    "category": "Movies",
    "logoUrl": "/artwork/channels/1/logo.jpg",
    "enabled": true
  }
]

Create channel

POST /api/livetv/channels
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "Action Movies",
  "number": 5,
  "sourceType": "virtual",
  "scheduleMode": "shuffle",
  "category": "Movies",
  "programs": [
    { "filePath": "/data/movies/Die Hard (1988)/Die Hard (1988).mkv", "title": "Die Hard" },
    { "filePath": "/data/movies/Mad Max Fury Road (2015)/Mad Max Fury Road (2015).mkv", "title": "Mad Max: Fury Road" }
  ]
}

Update channel

PUT /api/livetv/channels/:id
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "Action & Thriller",
  "scheduleMode": "sequential"
}

Delete channel

DELETE /api/livetv/channels/:id
Authorization: Bearer <admin-token>

Stream playback

Watch a channel

GET /api/livetv/watch/:channelId
Authorization: Bearer <token>

Returns an HLS stream URL. For pre-warmed channels, this resolves immediately. For cold-start channels, the server starts the stream and long-polls until ready (up to 5 seconds).

Response: Redirects to live.m3u8.

HLS manifest

GET /api/livetv/watch/:channelId/live.m3u8
Authorization: Bearer <token>

HLS manifest with 6-second segments and a 3-segment sliding window.

Stream token auth

For external IPTV clients that can't use Bearer auth:

GET /api/livetv/watch/:channelId/live.m3u8?token=abc123def456

Warm channels

POST /api/livetv/warm
Authorization: Bearer <token>
Content-Type: application/json

{
  "channelIds": [1, 2, 3]
}

Pre-starts streams for the specified channels. Called by the web UI on page load for instant playback.

Proxy external streams

GET /api/livetv/watch/:channelId/relay.m3u8
Authorization: Bearer <token>

Proxies an external IPTV stream through the OmniLux server (for VPN egress or CORS bypass).

EPG

Get EPG data

GET /api/livetv/epg
Authorization: Bearer <token>

Query parameters:

Parameter	Type	Description
start	string	ISO 8601 start time
end	string	ISO 8601 end time
channelIds	string	Comma-separated channel IDs

Response:

{
  "channels": [
    {
      "id": 1,
      "name": "Movies",
      "programs": [
        {
          "title": "Die Hard",
          "start": "2024-01-01T20:00:00Z",
          "end": "2024-01-01T22:11:00Z",
          "description": "An NYPD officer...",
          "posterUrl": "/artwork/movies/562/poster.jpg"
        }
      ]
    }
  ]
}

IPTV sources

List sources

GET /api/livetv/iptv-sources
Authorization: Bearer <admin-token>

Add source

POST /api/livetv/iptv-sources
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name": "My IPTV Provider",
  "sourceUrl": "https://example.com/playlist.m3u",
  "epgUrl": "https://example.com/epg.xml"
}

DVR

List recordings

GET /api/livetv/recordings
Authorization: Bearer <token>

Record now

POST /api/livetv/recordings
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "channelId": 1,
  "duration": 3600
}

Schedule recording

POST /api/livetv/recordings
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "channelId": 1,
  "startAt": "2024-01-02T20:00:00Z",
  "duration": 7200,
  "name": "Movie Night Recording"
}

Delete recording

DELETE /api/livetv/recordings/:id
Authorization: Bearer <admin-token>

Export

M3U playlist

GET /api/livetv/m3u

Returns an M3U playlist of all enabled channels. For use with external IPTV clients. Requires stream token for authentication.

XMLTV EPG

GET /api/livetv/xmltv

Returns XMLTV-formatted EPG data for a 48-hour window.

HDHomeRun emulation

Device discovery

GET /discover.json

Response:

{
  "FriendlyName": "OmniLux",
  "Manufacturer": "OmniLux",
  "ModelNumber": "HDHR-OL",
  "FirmwareName": "omnilux",
  "TunerCount": 4,
  "DeviceID": "OMNILUX",
  "DeviceAuth": "omnilux",
  "BaseURL": "http://your-server-ip:4000",
  "LineupURL": "http://your-server-ip:4000/lineup.json"
}

Channel lineup

GET /lineup.json

Response:

[
  {
    "GuideNumber": "1",
    "GuideName": "Movies",
    "URL": "http://your-server-ip:4000/api/livetv/watch/1/live.m3u8?token=..."
  }
]

Settings

Get settings

GET /api/livetv/settings
Authorization: Bearer <admin-token>

Update settings

PUT /api/livetv/settings
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "hdhrEnabled": true,
  "hdhrTunerCount": 4,
  "epgRefreshIntervalHours": 12
}