Полный справочник по формату XMLTV (EPG) для IPTV: каналы, передачи и все элементы

Если плейлист M3U говорит, какие каналы существуют и откуда их транслировать, то XMLTV говорит, что идёт в эфире. Это открытый формат XML, стоящий практически за любой IPTV-программой передач: текстовый список каналов и передач, которые на них выходят. Здесь есть настоящая спецификация — опубликованный DTD, поддерживаемый проектом XMLTV, — что делает XMLTV куда более строгим, чем вольный конвенциональный формат M3U. Этот справочник разбирает каждый элемент и атрибут, точный формат даты, нумерацию эпизодов, рейтинги и изображения, а также то, как программа передач привязывается к вашему плейлисту.

UniPlayer загружает программы передач XMLTV и накладывает их на каналы вашего собственного плейлиста, поэтому изложенные ниже правила — ровно те же, что определяют, отобразится ли ваша программа передач корректно.

Главная идея: программа передач, написанная для зрителя

XMLTV создан в 1999 году Эдом Эвисом (Ed Avis) и поддерживается проектом XMLTV. Его определяющее проектное решение в том, что он написан с точки зрения зрителя, а не вещателя. Вместо того чтобы вкладывать передачи в каналы, а каналы — в дни, документ XMLTV представляет собой по сути плоский список: сначала каналы, затем все передачи вперемешку, причём каждая передача несёт время выхода в эфир и канал в виде атрибутов. Передачи одного канала даже не обязаны идти подряд. Именно поэтому формат чисто масштабируется до тысяч каналов и именно поэтому программы передач «просто объединяются».

Скелет документа

Каждый файл XMLTV — это корректно оформленный XML-документ такого вида:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tv SYSTEM "xmltv.dtd">
<tv generator-info-name="MyGrabber 1.0" source-info-name="Example Source">
  <!-- сначала каналы -->
  <channel id="bbcone.uk">
    <display-name>BBC One</display-name>
    <icon src="https://example.com/logos/bbc1.png"/>
  </channel>

  <!-- затем передачи -->
  <programme start="20260618200000 +0000" stop="20260618210000 +0000" channel="bbcone.uk">
    <title lang="en">The Nine O'Clock News</title>
    <desc lang="en">The day's headlines.</desc>
  </programme>
</tv>

• Корневой элемент — всегда <tv>, и его модель содержимого строга: сначала каналы, затем передачи.
• Пролог XML с объявлением кодировки настоятельно рекомендуется; UTF‑8 — современное значение по умолчанию и единственный безопасный выбор для нелатинских названий каналов и передач.
• Файлы обычно отдают сжатыми. Обычный .xml и gzip (.xml.gz) поддерживаются почти всюду; некоторые источники также отдают архивы .zip, .tar или .xz, хотя .xz (LZMA2) сжимает сильнее, но распаковывается не каждым плеером. Держите программы передач сжатыми — XMLTV многословен и ужимается кардинально.

Формат даты и времени (прочитайте дважды)

Каждая временная метка в XMLTV использует один формат, вольно основанный на ISO 8601:

YYYYMMDDHHMMSS ±HHMM

например 20260618200000 +0000. Ключевые правила и вытекающие из них подводные камни:

• Частичные подстроки допустимы. 202606 (год + месяц) или 20260618 (только дата) корректны там, где полная точность неизвестна.
• Часовой пояс — это смещение в конце после пробела: +0000, +0300, -0500. Именованные зоны вроде BST встречаются в старых данных, но не рекомендуются.
• Отсутствие смещения означает UTC. Если вы опустите пояс, потребители сочтут время за UTC — и ваша программа передач молча сдвинется, если время на самом деле было местным.
• Лучшая практика: всегда пишите полную 14-значную временную метку с явным смещением. Это снимает всякую двусмысленность и именно этого ждут надёжные плееры. Если ваша программа передач и канал разъезжаются на фиксированное число часов, чините это на стороне плейлиста атрибутом tvg-shift, а не переписыванием временных меток.

Корневой элемент <tv>

<tv> несёт необязательные метаданные о происхождении. Ни один из них не влияет на воспроизведение, но это хорошая гигиена и подспорье при отладке того, какой источник сформировал программу передач.

Атрибут	Значение
date	Когда расписание было изначально сформировано (в формате даты XMLTV).
source-info-name / source-info-url	Человекочитаемое имя и URL источника данных.
source-data-url	URL собственно данных, которые были обработаны.
generator-info-name / generator-info-url	Программа, сгенерировавшая этот файл, и её домашняя страница.

Элемент <channel>

Каналы объявляются один раз, и каждая передача ссылается на них по id.

<channel id="bbctwo.uk">
  <display-name lang="en">BBC Two HD</display-name>
  <display-name lang="en">BBC Two</display-name>
  <display-name>102</display-name>
  <icon src="https://example.com/logos/bbc2.png" width="240" height="240"/>
  <url system="official">https://www.bbc.co.uk/bbctwo</url>
</channel>

Часть	Правила
id (атрибут, обязателен)	Уникальный идентификатор. Спецификация предлагает форму, похожую на DNS-имя по RFC 2838 (например, bbcone.uk). Именно с этим значением должен совпадать tvg-id в вашем плейлисте.
<display-name> (один или несколько)	Имя (имена) для человека. Можно указать несколько — для разных языков (lang) или несколько имён для одного языка. Более ранние имена считаются более каноничными. Допустим и просто номер канала.
<icon>	Логотип канала: src (обязателен), необязательные width/height.
<url>	Информационная ссылка (официальный сайт, фан-страница). Необязательный system уточняет вид/источник.

Порядок каналов в файле не имеет значения — каналы ищутся по id, а не по позиции (хотя сортировка по id делает диффы чище).

Элемент <programme>

Здесь и живёт расписание. Каждая передача — один слот вещания.

<programme start="20260618200000 +0000" stop="20260618210000 +0000" channel="bbctwo.uk">
  ...
</programme>

Атрибуты передачи

Атрибут	Значение
start (обязателен)	Начало вещания, в формате даты XMLTV.
stop	Конец вещания. По спецификации необязателен, но настоятельно рекомендуется: без него сеточные интерфейсы не могут задать размер слота.
channel (обязателен)	Должен совпадать с id элемента <channel>.
clumpidx	Когда две передачи делят один слот («clump»), например 0/2 и 1/2. По умолчанию 0/1.
pdc-start / vps-start	Сигналы управления временем от вещателя (PDC/VPS) для точной записи.
showview / videoplus	Устаревшие коды записи ShowView/VideoPlus.

Дочерние элементы передачи — и их порядок

DTD фиксирует порядок дочерних элементов. Если вы выдадите их не по порядку, строгие валидаторы отвергнут файл. Полная последовательность:

title+, sub-title*, desc*, credits?, date?, category*, keyword*,
language?, orig-language?, length?, icon*, url*, country*,
episode-num*, video?, audio?, previously-shown?, premiere?,
last-chance?, new?, subtitles*, rating*, star-rating*, review*, image*

Ниже — по назначению.

Описательное содержимое

Элемент	Примечания
<title> (один или несколько)	Название передачи (например, «Симпсоны»). Повторяйте с разными lang для переводов.
<sub-title>	Название эпизода / «подзаголовок».
<desc>	Свободное текстовое описание (абзац). Допускаются несколько вариантов с разными lang.
<category>	Жанр (например, «News», «Drama»). Допускается несколько; плееры обычно используют первый. lang поддерживается.
<keyword>	Произвольные ключевые слова. lang поддерживается.
<date>	Год завершения передачи/фильма (часто год копирайта), например 2026 или 20260711.
<language> / <orig-language>	Язык звучания и язык оригинала. Используйте двухбуквенный код или название.
<length>	Реальный хронометраж без рекламы. Требует `units=“seconds
<icon>	Изображение/миниатюра передачи (src, необязательные width/height).
<url>	Информационная ссылка о передаче; необязательный system.
<country>	Страна производства. lang поддерживается.

Состав (credits)

<credits> оборачивает актёров и съёмочную группу в этом фиксированном порядке: director, actor, writer, adapter, producer, composer, editor, presenter, commentator, guest. Каждый может встречаться несколько раз.

<credits>
  <director>Jane Doe</director>
  <actor role="Detective Smith">John Roe</actor>
  <actor role="Narrator" guest="yes">Sam Lee</actor>
  <presenter>Graham Norton</presenter>
</credits>

<actor> поддерживает атрибут role и guest="yes|no". Любой элемент состава может сам содержать <image> (фото человека или персонажа) и <url> (например, страницу профиля).

Нумерация эпизодов

<episode-num> несёт сезон/эпизод, а атрибут system задаёт систему (по умолчанию onscreen). Две предопределённые системы плюс самая распространённая сторонняя:

• xmltv_ns — структурированная машиночитаемая схема. Три части через точку: сезон . эпизод . часть, каждая с отсчётом от нуля, и каждую можно записать как X/Y, чтобы выразить «X из Y всего». Неизвестную часть опускайте (но точки сохраняйте). Примеры:
  • 1 . 0 . 0/1 → сезон 2, эпизод 1, состоит из одной части. (Помните: отсчёт от нуля, поэтому «1» — это второй сезон.)
  • 0 . 12/13 . 0/3 → сезон 1, эпизод 13 из 13, часть 1 из 3.
  • 0 . . → известно, что это сезон 1, эпизод и часть неизвестны.
• onscreen — копируйте то, что показано на экране, например S01E02. Обрамляющие слова отбрасывайте: надпись на экране «Episode #FFEE» записывается как #FFEE.
• dd_progid — распространённая нестандартная система, несущая идентификатор передачи Schedules Direct / Gracenote (например, EP000000060087). В спецификацию не входит, но широко встречается в североамериканских программах передач.

<episode-num system="xmltv_ns">0 . 11 . 0/1</episode-num>
<episode-num system="onscreen">S01E12</episode-num>

Технические детали вещания

• <video> содержит present (yes/no), colour (yes/no), aspect (например, 16:9), quality (например, HDTV, 1080p).
• <audio> содержит present (yes/no) и stereo, допустимые значения которого — mono, stereo, dolby, dolby digital, bilingual, surround. (bilingual здесь означает, что левый и правый каналы несут разные моноязыки.)
• <subtitles> имеет type="teletext|onscreen|deaf-signed" и необязательный дочерний <language>. Может повторяться.

<video><colour>yes</colour><aspect>16:9</aspect><quality>HDTV</quality></video>
<audio><stereo>surround</stereo></audio>
<subtitles type="teletext"><language>en</language></subtitles>

Флаги жизненного цикла

• <previously-shown> (пустой элемент) помечает повтор. Необязательные start (когда шло в прошлый раз) и channel (где). Его отсутствие не гарантирует, что передача совершенно новая.
• <premiere> и <last-chance> — элементы-абзацы (с необязательным lang); их точный смысл зависит от вещателя, поэтому они существуют в основном чтобы воспроизвести то, что было бы написано в печатной программе. Оба могут быть пустыми (<premiere/>).
• <new> (пустой элемент) отмечает первый выпуск совершенно нового шоу — такого, которое раньше никогда не выходило в эфир. Это не означает «новый эпизод» или «новый сезон»: после показа первого выпуска последующие уже не считаются <new>, а второй сезон давно идущего шоу не является <new> никогда.

Рейтинги, рецензии и изображения

• <rating> — это возрастной/контентный рейтинг: обязательный <value> плюс необязательные <icon>, с атрибутом system (например, MPAA, BBFC, код страны).
• <star-rating> — оценка качества в виде <value>, записанного как N/M (например, 3/5), с необязательными system и <icon>.
• <review> несёт рецензию критика; type="text|url" обязателен, плюс необязательные source, reviewer, lang.
• <image> (более позднее добавление) — более богатая ссылка на изображение, чем <icon>: type="poster|backdrop|still|person|character", size="1|2|3" (маленькое/среднее/большое по наибольшей стороне), orient="P|L" (портрет/ландшафт) и system для указания источника (imdb, tmdb, …).

<rating system="MPAA"><value>PG-13</value></rating>
<star-rating><value>4/5</value></star-rating>
<image type="poster" size="3" orient="P" system="tmdb">https://image.tmdb.org/.../poster.jpg</image>

Расширение для IPTV-архива: catchup-id

Есть один широко используемый атрибут, который не входит в спецификацию XMLTV, но крайне важен для IPTV: catchup-id у <programme>. Некоторым провайдерам нужен идентификатор конкретной передачи, чтобы построить URL архива, и плееры считывают его в плейсхолдер {catchup-id}, применяемый в шаблонах catchup-source в M3U.

<programme start="20260618200000 +0000" channel="footv" catchup-id="episode-44871">
  <title>The Match</title>
</programme>

Это мост к воспроизведению архива, описанному в справочнике по формату M3U: когда режим catch-up у канала равен vod, {catchup-id} из сопоставленной передачи подставляется в URL воспроизведения. Провайдерам, которые объявляют архив именно для UniPlayer, стоит следовать спецификации «Архив и Catch-up».

Многоязычные программы передач

XMLTV поддерживает локализацию почти везде через атрибут lang. Вы можете предоставить несколько элементов <title>, <sub-title>, <desc> и <category>, каждый со своим языком, и плеер выберет предпочитаемый пользователем. <orig-language> фиксирует язык оригинала передачи отдельно от <language> (языка транслируемой версии).

<title lang="en">The Bear</title>
<title lang="ru">Медведь</title>
<desc lang="en">A chef returns home to run a sandwich shop.</desc>
<desc lang="ru">Шеф-повар возвращается домой управлять кафе.</desc>

Привязка XMLTV к вашему плейлисту M3U

Программа передач бесполезна, пока она не соединена с каналами. Соединение происходит на стороне плейлиста:

1. В строке #EXTM3U укажите на программу передач через url-tvg (или его синоним x-tvg-url).
2. В строке #EXTINF каждого канала задайте tvg-id, равный <channel id="…"> в программе передач.

Дальше плееры разрешают каждый канал по XMLTV в фиксированном порядке — сначала сопоставляют tvg-id с id канала, затем откатываются к сравнению tvg-name и отображаемого имени канала с каждым <display-name>. Самая надёжная практика: задайте tvg-id и сделайте его идентичным id из XMLTV. Сопоставление по именам хрупко из-за суффиксов «HD», регистра и пробелов. (Полный алгоритм сопоставления и атрибут сдвига времени tvg-shift см. в справочнике по формату M3U.)

Как это делает UniPlayer. UniPlayer сопоставляет по tvg-id и откатывается к имени канала, поэтому одну универсальную коллекцию XMLTV можно привязать к нескольким разным плейлистам, и нужные каналы всё равно оживут — даже когда в этих плейлистах идентификаторы заданы непоследовательно. (Сегодня UniPlayer привязывает один источник EPG к плейлисту; более широкая поддержка нескольких EPG — в планах.)

Доставка, обновление и валидация

• Отдавайте сжатым. Gzip (.xml.gz) универсален и заметно меньше. .zip и .tar тоже распространены; .xz сжимает ещё сильнее, но распаковывается не каждым плеером, так что взвешивайте размер против совместимости.
• Обновляйте разумно. Большинство программ передач обновляются каждые несколько часов; сообщайте частоту на стороне плейлиста (refresh/m3uautoload), а не рассчитывайте, что плеер догадается сам.
• Проверяйте по DTD. Поскольку у XMLTV есть настоящий DTD, вы можете проверить структуру и порядок элементов до публикации — это ловит те самые ошибки с порядком дочерних элементов, которые отвергают строгие плееры.

Как это делает UniPlayer. UniPlayer читает программы передач XMLTV как обычный .xml и как архивы .gz, .zip и .tar. Он также не делает лишней работы: если на один и тот же источник EPG ссылаются несколько плейлистов, UniPlayer загружает его один раз, а не скачивает одну и ту же программу передач повторно, — благодаря чему память и трафик остаются экономными даже с большими общими программами передач.

Чек-лист проверки и частые ошибки

• Объявляйте UTF‑8 в прологе и сохраняйте файл в UTF‑8 (без случайной BOM).
• Держите дочерние элементы в порядке DTD — title перед desc, desc перед credits и т. д. Нарушенный порядок не проходит строгую валидацию.
• Всегда указывайте stop, чтобы сеточные интерфейсы могли задать размер слотов.
• Используйте полные временные метки с явным смещением. Пропуск пояса молча означает UTC.
• Делайте id каналов стабильными и уникальными и в точности сопоставляйте их с tvg-id в плейлисте.
• Не раздувайте программу передач. Публикуйте только нужные дни и жмите gzip; многомегабайтные несжатые программы передач замедляют каждого клиента.
• У <category>/<title> побеждает первый. Плееры обычно берут первый из повторяющихся элементов, поэтому осознанно упорядочивайте языковые и жанровые варианты.

Полный пример с пояснениями

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tv SYSTEM "xmltv.dtd">
<tv source-info-name="Example EPG" generator-info-name="MyGrabber 1.0">

  <channel id="bbcone.uk">
    <display-name lang="en">BBC One HD</display-name>
    <display-name lang="en">BBC One</display-name>
    <icon src="https://example.com/logos/bbc1.png"/>
  </channel>

  <programme start="20260618200000 +0000" stop="20260618210000 +0000" channel="bbcone.uk" catchup-id="ep-44871">
    <title lang="en">Sherlock</title>
    <sub-title lang="en">A Study in Pink</sub-title>
    <desc lang="en">A modern update finds the famous sleuth solving crimes in London.</desc>
    <credits>
      <director>Paul McGuigan</director>
      <actor role="Sherlock Holmes">Benedict Cumberbatch</actor>
      <actor role="Dr John Watson">Martin Freeman</actor>
    </credits>
    <date>2010</date>
    <category lang="en">Drama</category>
    <category lang="en">Crime</category>
    <language>en</language>
    <length units="minutes">88</length>
    <country>GB</country>
    <episode-num system="xmltv_ns">0 . 0 . 0/1</episode-num>
    <episode-num system="onscreen">S01E01</episode-num>
    <video><colour>yes</colour><aspect>16:9</aspect><quality>HDTV</quality></video>
    <audio><stereo>stereo</stereo></audio>
    <previously-shown start="20100725" />
    <subtitles type="teletext"><language>en</language></subtitles>
    <rating system="BBFC"><value>12</value></rating>
    <star-rating><value>5/5</value></star-rating>
    <image type="poster" size="3" orient="P" system="tmdb">https://image.tmdb.org/.../sherlock.jpg</image>
  </programme>

</tv>

Замечание о расширениях и совместимости

У XMLTV есть настоящая спецификация, но экосистема всё равно добавляет нестандартные атрибуты там, где спецификации не хватает: catchup-id для IPTV-архива, dd_progid для североамериканских идентификаторов передач, display-number/repeat-programs у Android TV. Потребители игнорируют непонятные им атрибуты и элементы, поэтому такие расширения можно безопасно включать. Составляя программу передач, проверяйте её по DTD, предпочитайте номера эпизодов xmltv_ns и стабильные идентификаторы каналов, а перед публикацией проверяйте результат в реальном плеере.

UniPlayer читает стандартные программы передач XMLTV и связывает их с каналами вашего собственного плейлиста по tvg-id, с откатом к имени. Он также предлагает своим пользователям встроенную программу передач, собранную из общедоступных источников, — но не публикует файлы XMLTV и публичные ссылки на программы передач, не размещает каналы и не продаёт контент. Плейлист приносите вы, а программу передач выбираете сами: оставить встроенную в UniPlayer или подключить свою.