Hospitality Integration Guide

Version: September 2026 (Kylone Headend v4). Replace headend in the examples with the headend's host name or address.

---

1. What the headend gives you

A Kylone headend takes DVB, IP, SRT, HLS or file sources and publishes every channel in a fixed set of forms. You pick the ones your devices can play.

Every channel keeps one stable identity: its channel number, its service name and its service id do not change when the headend switches the channel to a protection source (see section 7). Your line-up is built once.

2. Discover what is published

Start at the manifest. It says which lists exist, how many entries each has, when they were generated, and where the guide is.

GET https://headend/feeds/index.json
                                                    

{
  "generator": "Kylone Headend",
  "base": "https://headend/feeds",
  "generated": "2026-09-10T15:02:11Z",
  "channels": [
    { "file": "channels.m3u",       "transport": "http-ts",       "entries": 38, "url": "https://headend/feeds/channels.m3u" },
    { "file": "channels-mcast.m3u", "transport": "udp-multicast", "entries": 38, "url": "https://headend/feeds/channels-mcast.m3u" },
    { "file": "channels-hls.m3u",   "transport": "hls",           "entries": 12, "url": "https://headend/feeds/channels-hls.m3u" }
  ],
  "logos":       { "path": "logo/", "entries": 13, "url": "https://headend/feeds/logo/" },
  "channel_map": { "file": "channels.json", "url": "https://headend/feeds/channels.json", "entries": 38 },
  "guide":       { "file": "guide.xml", "url": "https://headend/feeds/guide.xml", "gz": "https://headend/feeds/guide.xml.gz", "window_days": 7 }
}
                                                    

The feeds tree is rewritten atomically whenever the operator commits a line-up change, so a list is never half-written when you fetch it. Poll generated_epoch to detect changes; once a minute is plenty.

3. Channel lists (M3U)

Three lists, one per transport, same channels, same attributes. Each .m3u has an identical .m3u8 twin for players that insist on the extension.

#EXTM3U
#EXTINF:0 tvg-id="harbournews" tvg-name="Harbour News HD" tvg-chno="27" tvg-logo="https://headend/feeds/logo/harbournews.png" group-title="News",Harbour News HD
udp://@239.47.31.91:8027
                                                    

The multicast list contains only channels that have a multicast output. Multicast channels are also announced with SAP/SDP on 224.2.127.254:9875 every few seconds (session name, group, port, and the category as a=cat), for devices that discover channels that way.

channels.json is the same line-up as a JSON array (id, name, number, kind), for applications that prefer not to parse M3U.

4. Programme guide (XMLTV)

GET https://headend/feeds/guide.xml
GET https://headend/feeds/guide.xml.gz
                                                    

Standard XMLTV. <channel id> equals the channel's tvg-id. The window is seven days, taken from the EIT the sources carry, refreshed every five minutes and immediately after a line-up commit. Titles and descriptions are UTF-8 with the source's language tag. Channels whose source carries no EIT simply have no <programme> entries.

5. Unicast URL forms

For the record, the URL forms the lists contain:

Use the lists rather than composing URLs: the port numbers are the headend's internal tiers and the operator may move a channel between them.

6. HLS details

Each channel with an HLS output has one master playlist. By default it carries one H.264/AAC variant; the operator can enable up to six encoding profiles on the output, and each becomes an EXT-X-STREAM-INF variant with its own BANDWIDTH and RESOLUTION, so a player on weak Wi-Fi or mobile switches to a lighter variant on its own. Audio and subtitle renditions are shared across variants. What your player sees:

• Segments: 3 s by default, 10 in the live window (a 30 s DVR span); the operator can set 2 s and longer. Every segment starts with an IDR frame and carries PAT/PMT/SDT, and the master carries EXT-X-INDEPENDENT-SEGMENTS.
• Codecs: CODECS="avc1.640029,mp4a.40.2" for the hospitality template (H.264 High, level 4, AAC-LC 48 kHz). BANDWIDTH is within 10 % of the measured rate.
• Audio: all of a channel's audio tracks are muxed into the variant by default (native TV players); the operator can instead publish one rendition per language (EXT-X-MEDIA TYPE=AUDIO with LANGUAGE), or a mix of both.
• Subtitles: WebVTT renditions (EXT-X-MEDIA TYPE=SUBTITLES) with LANGUAGE and NAME per track, when the operator enables them (section 8). Every WebVTT segment carries X-TIMESTAMP-MAP, so cues align with the video on every conformant player.
• HTTP: segments are video/mp2t with Cache-Control: public, max-age=3600; playlists no-cache, max-age=1; Access-Control-Allow-Origin: *. Also served over HTTPS with the operator's certificate.
• Encryption (optional): the operator can enable AES-128 encryption on an HLS output. The playlist then carries a standard key line per segment, EXT-X-KEY:METHOD=AES-128,URI="/portal/?app=hlk&p=<port>&k=<key id>",IV=0x…, and the segments are encrypted whole. The key URI is relative, so the player fetches the key from the same host and scheme as the playlist; every HLS player supports this method, and nothing changes on your side. The operator can rotate keys at any time: the playlist announces the new key id from the next segment on, and the previous key stays available for the live window. Who may fetch a key is described in section 9.

7. What a TV sees during a protection switch

Channels can be protected by a stand-in source (a backup feed, a scheduled filler, a no-signal card). When the headend switches:

• the multicast group, port, service id, service name and channel number stay the same;
• the HLS media sequence continues without an EXT-X-DISCONTINUITY, the encoder is not restarted, and audio/video alignment stays within 20 ms;
• no re-scan, no re-tune, no player reload is needed.

Your application does not have to know a switch happened. If you want to show it, the headend's status feeds expose it; ask the operator.

8. Subtitles and captions

The headend can put text on a channel in several ways. On multicast the text travels as a teletext subtitle page (the form every hospitality TV and set-top box decodes); on HLS the same page becomes a WebVTT rendition.

The generated pages are announced in the service's PMT with their language, so a TV's subtitle menu lists them like any broadcaster page. Speech captions are assistive captions: they follow the dialogue with a short delay and are not a substitute for editorial subtitles.

9. Security and networking notes

• HTTPS: available on the main virtual host with the operator's certificate; the built-in DNS can name the headend on the property network.
• Feeds and playlists are open on the property network; the operator scopes them with HTTPS and network design, not with credentials.
• HLS keys (encrypted outputs only): the key endpoint answers a device the headend's peer policy allows: registered devices by hardware address, allowed address ranges the operator maintains, and, when enabled, devices discovered on the property network. A TV or set-top box on an allowed network needs nothing. An application playing from outside that policy, a guest phone through the hotel app for instance, presents an API key the operator issues for HLS use, appended to the key request as &t=<key>; use HTTPS for that path, since the key travels in the URL. Keys are served with Cache-Control: no-store, and every grant or refusal is logged on the headend.
• Multicast: IGMP snooping must be on in the access switches; the headend joins nothing, it only sends.
• Time: the guide uses UTC with offsets; align devices with the property's NTP.

10. Integration checklist

1. Fetch feeds/index.json; note generated_epoch.
2. Load the list for your transport; key channels by tvg-id, order by tvg-chno.
3. Fetch logos lazily from tvg-logo.
4. Load guide.xml.gz; join on channel id = tvg-id.
5. For HLS clients, play playlist.m3u8 as-is; let the player choose audio and subtitle renditions from the master.
6. Poll the manifest for changes; reload lists when generated_epoch moves.
7. If the operator has enabled encryption on HLS, make sure your devices' network is allowed by the headend's peer policy, or add the HLS API key to key requests in your own player (section 9). Native TV players need no change.
8. Nothing else: protection switches and key rotations are invisible to you.

The management side of the same setup — allowing a player network, turning on encryption, assigning an HLS profile to a channel, rotating an HLS API key — can be scripted through the headend's XML API v2: the guide, a hospitality addendum for exactly these functions, and reference clients are on GitHub. Available from headend v4.1.1.