Hospitality Integration Guide

Version: September 2026 (MicroCMS 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 MicroCMS",
  "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.

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.
• API keys: when the operator enables key mode, feed requests need the key the operator hands out; without it the feeds are open on the property network.
• 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. Nothing else: protection switches are invisible to you.