Live TV API

List channels, start playback, read guide data, and export IPTV-compatible playlists.

Try it with a token

Use a bearer token from the Authentication flow for authenticated playback requests.

Channels

List channels

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

curl -sS \
  -H "Authorization: Bearer $OMNILUX_TOKEN" \
  http://your-server:4000/api/livetv/channels

Response:

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

Admins can create virtual channels with POST /api/livetv/channels. This public page focuses on playback and guide consumption.

Direct external channels and M3U source imports require source provenance, a written rights basis, and explicit authorization attestation. External DVR additionally requires a recording-specific rights basis.

Stream playback

Watch a channel

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

Returns a redirect to the channel HLS playlist when the stream is ready. For cold-start channels, the server can return 202 Accepted while it starts the stream.

curl -i \
  -H "Authorization: Bearer $OMNILUX_TOKEN" \
  http://your-server:4000/api/livetv/watch/1

Starting response:

{
  "ready": false,
  "message": "Stream starting..."
}

Ready response: 302 Found redirect to the HLS playlist.

The watch endpoint also accepts signed stream-access query parameters for external clients:

Parameter	Type	Description
token	string	Stream token
exp	string	Signed URL expiration
sig	string	Signed URL signature
fromStart	string	Start behavior hint
watchSession	string	Optional watch-session identifier

HLS manifest

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

HLS manifests use short segments and a sliding live window. Authentication for playback should use the standard bearer-token flow documented in Authentication, or a signed stream URL generated by the runtime.

EPG

Get EPG data

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

curl -sS \
  -H "Authorization: Bearer $OMNILUX_TOKEN" \
  "http://your-server:4000/api/livetv/epg?from=2026-06-01T00:00:00Z&to=2026-06-02T00:00:00Z&channelId=1"

Query parameters:

Parameter	Type	Description
channelId	number	Optional channel ID filter
channelIds	string	Optional comma-separated channel IDs
from	string	Optional ISO 8601 start time
to	string	Optional ISO 8601 end time

Response:

{
  "entries": [
    {
      "channelId": 1,
      "title": "Die Hard",
      "description": "An NYPD officer visits Los Angeles.",
      "start": "2026-06-01T20:00:00Z",
      "end": "2026-06-01T22:11:00Z",
      "iconUrl": "/artwork/movies/562/poster.jpg"
    }
  ]
}

External IPTV clients

Export an M3U playlist:

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

Export XMLTV guide data:

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

Configured stream tokens or signed stream-access query parameters can be used for clients that cannot send bearer headers. These credentials grant access to a private lineup and must not be published.

Warm enabled channels

POST /api/livetv/warm
Authorization: Bearer <token>

Starts warming enabled channels for faster playback where supported.