Как выглядит файл XMLTV EPG на самом деле (с примерами)

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

В этом посте показан реальный файл, декодированный тег за тегом, а затем используется это понимание для объяснения наиболее частого отказа руководства.

Честно говоря: Tuneline — это медиаплеер для контента, который вы предоставляете. Он отображает руководство из источника расписания, который вы предоставляете. Он поставляется без руководства и без контента.

Структура в одном предложении

Файл XMLTV содержит ровно два вида элементов: элементы <channel>, которые объявляют то, что существует, и элементы <programme>, которые говорят, что идет и когда.

Вот и всё. Всё остальное — детали.

Минимальный, полный пример

<?xml version="1.0" encoding="UTF-8"?>
<tv generator-info-name="example-grabber">

  <channel id="example.news.us">
    <display-name>Example News</display-name>
    <icon src="http://logos.example/news.png" />
  </channel>

  <programme start="20260806180000 +0000"
             stop="20260806190000 +0000"
             channel="example.news.us">
    <title lang="en">Evening Report</title>
    <desc lang="en">The day's headlines and analysis.</desc>
    <category lang="en">News</category>
  </programme>

</tv>

Это допустимое, полное руководство, описывающее один источник и один час расписания. Реальный файл содержит те же две структуры, повторённые тысячи раз.

Декодировано тег за тегом

Формат временной метки ловит всех

start="20260806180000 +0000"

Читается как YYYYMMDDHHMMSS, за которым следует смещение UTC. Итак, это 6 августа 2026 г., 18:00:00 UTC.

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

Объединение: почему ваше руководство пусто, несмотря на то, что файл загрузился

Вот то, что стоит понять, потому что это объясняет большинство жалоб на руководства.

Ваш плейлист и ваше руководство — это два отдельных файла, которые должны совпадать. Совпадение происходит по ID.

В M3U:

#EXTINF:-1 tvg-id="example.news.us" tvg-logo="…",Example News
http://example.com/news.m3u8

В XMLTV:

<channel id="example.news.us">

tvg-id должен быть равен channel id. Ровно — включая регистр и пунктуацию.

Когда они совпадают, запись показывает своё расписание. Когда они не совпадают, вы получаете запись с пустым руководством, и файл никогда не был виноват. (Часть плейлиста M3U этого.)

Вот почему "Я добавил руководство и ничего не произошло" обычно не вина ни плейлиста, ни руководства. Дело в том, что никто не согласовал идентификаторы. Руководство, охватывающее другой регион, чем ваш плейлист, загрузит тысячи программ, которые не совпадают ни с одной из ваших записей.

Как проверить источник руководства перед тем, как ему доверять

Перед тем, как винить плеер, посмотрите на файл.

1. Сжато ли оно? Многие источники доставляют .xml.gz. Это нормально — большинство плееров это обрабатывают. Если вы проверяете вручную, сначала распакуйте.

2. Содержит ли оно ваши источники? Найдите в файле одно из ваших значений tvg-id. Если его там нет, то руководство не охватывает ваш список, и никакой параметр это не изменит.

curl -s "https://example.com/guide.xml.gz" | gunzip | grep -c "<channel "
curl -s "https://example.com/guide.xml.gz" | gunzip | grep "example.news.us"

Первый говорит вам, сколько источников оно объявляет. Второй говорит вам, является ли ваш один из них.

3. Охватывает ли оно полезный диапазон времени? Проверьте самые ранние и самые поздние значения start. Некоторые бесплатные руководства содержат только 24 часа; некоторые содержат две недели. Руководство, которое закончилось вчера, выглядит идентично сломанному.

4. Какой размер? Полные национальные руководства в распакованном виде занимают десятки или сотни мегабайт. Это нормально, и вот почему первая загрузка может занять минуты на ТВ-боксе. (Бесплатные источники XMLTV.)

Распространённые деформации

Реальные файлы руководств ломаются предсказуемыми способами:

• Страница ошибки HTML, сохранённая как .xml. Откройте её. Если первая строка — <!DOCTYPE html>, загрузка не удалась и ошибка была сохранена.
• Неэкранированные амперсанды. Голый & вместо & в названии является недопустимым XML и может прервать весь анализ. Одно плохое название — вообще никакого руководства.
• Дублирующиеся записи <channel id>. Два объявления одного и того же ID; поведение зависит от плеера.
• Программы без соответствующего канала. Записи расписания, у которых атрибут channel не совпадает ни с одним объявленным <channel id>. Они молча удаляются.
• Отсутствующие времена stop. Некоторые средства извлечения их опускают и ожидают, что начало следующей программы подразумевает конец. Некоторые плееры этого не выводят, оставляя пробелы.

Могу ли я написать или отредактировать один самостоятельно?

Да. Это XML, поэтому подходит любой текстовый редактор, и для небольшой курируемой установки это полностью практично.

Полезные правки:

• Измените <channel id> на соответствие tvg-id, который уже использует ваш плейлист — часто проще, чем редактировать сотни строк плейлиста.
• Обрежьте его. Удалите <channel> и <programme> элементы, которые вам не нужны. Меньший файл загружается намного быстрее на ограниченных устройствах.
• Исправьте смещение, если каждый раз неправильно.

Два правила: сохраняйте в UTF-8 и держите в хорошо сформированном виде — один неэкранированный & может стоить вам всего руководства.

Часто задаваемые вопросы

Как выглядит файл EPG?

Простой XML с двумя видами элементов: <channel> объявляющие каждый источник и <programme> дающие время начала, время остановки и название каждого запланированного элемента.

В каком формате находится XMLTV?

XML, обычно подаётся как .xml или gzip-сжатый .xml.gz. Временные метки — это YYYYMMDDHHMMSS плюс смещение UTC.

Почему моё руководство загружается, но не показывает ничего?

Почти всегда потому, что значения tvg-id вашего плейлиста не совпадают со значениями <channel id> руководства. Файл загрузился нормально; было нечего объединять.

Как я могу проверить, охватывает ли руководство мои источники?

Загрузите его, распакуйте, если необходимо, и найдите одну из ваших строк tvg-id. Если её нет в файле, это руководство не описывает ваш список.

Почему мой файл руководства такой большой?

Национальное руководство с двухнедельным расписанием для сотен источников на самом деле занимает десятки или сотни мегабайт. Это ожидаемо, и вот почему первая загрузка медленная.

Могу ли я отредактировать файл XMLTV?

Да, в любом текстовом редакторе. Сохраняйте как UTF-8 и держите XML в хорошо сформированном виде — один неэкранированный & может разрушить весь анализ.

Главное

• XMLTV содержит ровно два вещи: объявления <channel> и записи <programme>.
• Временные метки — это YYYYMMDDHHMMSS + смещение UTC — неправильное смещение означает правильные данные, неправильное время.
• Руководство объединяется с вашим плейлистом на tvg-id = channel id, ровно. Несоответствие — главная причина пустого руководства.
• Проверяйте перед обвинениями: распакуйте, найдите свой ID, проверьте диапазон дат.
• Один неэкранированный & может сделать весь файл руководства недействительным.

У вас есть плейлист и URL руководства? Загрузите Tuneline — добавьте оба и сетка заполнится. Бесплатно и без реклама.

— Shamir