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

Обзор

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

UniPlayer читает источники M3U/M3U8 (а также Xtream, Stalker, XML и VPortal) и приводит их к единому интерфейсу, поэтому понимание описанного ниже формата пригодится и когда вы составляете плейлист, и когда разбираетесь, почему у канала не отображается программа передач.

M3U, расширенный M3U и HLS .m3u8 — разбираемся в путанице

Расширение .m3u/.m3u8 носят три разные вещи, и их смешение — самый частый источник путаницы.

• Простой M3U — это просто список URL, по одному в строке. Без метаданных.
• Расширенный M3U (#EXTM3U) добавляет строку-хэдер и строки #EXTINF с метаданными (имя, логотип, группа, идентификатор EPG). Именно это на практике и называют «IPTV-плейлистом».
• HLS-манифест тоже использует расширение .m3u8, но описывает сегменты одного видеопотока с помощью тегов #EXT-X-, таких как #EXT-X-VERSION, #EXT-X-TARGETDURATION, #EXT-X-MEDIA-SEQUENCE и #EXT-X-STREAM-INF.

Практическое правило: теги #EXT-X- принадлежат HLS и не являются атрибутами IPTV-плейлиста. IPTV-плейлист ссылается на HLS-потоки (URL канала часто оканчивается на .m3u8), но сам плейлист использует соглашения #EXTINF + tvg-*, а не теги #EXT-X-. Единственная разница между .m3u и .m3u8 как плейлистами — кодировка: .m3u8 сигнализирует о UTF‑8, а он вам нужен для нелатинских названий каналов.

Анатомия записи о канале

Расширенный плейлист начинается с хэдера, а затем повторяет блок из двух или более строк на каждый канал:

#EXTM3U url-tvg="https://example.com/epg.xml.gz"
#EXTINF:-1 tvg-id="bbcone.uk" tvg-name="BBC One HD" tvg-logo="https://example.com/logos/bbc1.png" group-title="UK",BBC One HD
https://provider.example/live/bbc1/index.m3u8

Читаем строку #EXTINF:

• #EXTINF: — директива, открывающая запись о медиа.
• -1 — длительность в секундах. Для живых каналов это -1 (неизвестна/бесконечна); большинство плееров также допускают 0. Для VOD здесь может стоять реальная длительность.
• tvg-id="…" tvg-name="…" … — атрибуты в двойных кавычках, разделённые пробелами (подробно разобраны ниже).
• ,BBC One HD — всё, что идёт после первой запятой, — это отображаемое имя, которое видит пользователь. Оно может отличаться от tvg-name.
• Следующая строка — это URL потока (HTTP/HTTPS для HLS/TS либо udp:// / rtp:// для мультикаста в локальной сети).

Между строкой #EXTINF и URL могут находиться необязательные вспомогательные строки (#EXTGRP, #EXTVLCOPT, #KODIPROP, #EXTHTTP) — они относятся к этому каналу. Исключение — #EXTGRP: в Kodi он переносится и на последующие каналы (см. ниже).

Атрибуты хэдера (строка #EXTM3U)

Они задают значения по умолчанию для всего плейлиста. Одноимённый атрибут у конкретного канала переопределяет значение из хэдера.

Атрибут	Значение
url-tvg / x-tvg-url	URL файла программы передач XMLTV для всего плейлиста (.xml, .xml.gz или .xz). Эти два имени — синонимы, и Kodi читает оба; url-tvg чаще встречается в TiviMate/OTT Navigator. Некоторые плееры принимают несколько URL через запятую.
url-logo	Базовый URL, который подставляется перед относительными значениями tvg-logo.
tvg-shift	Сдвиг времени EPG по умолчанию (в часах) для всех каналов (см. раздел про EPG).
catchup, catchup-source, catchup-days, catchup-correction	Настройки catch-up по умолчанию для всех каналов (см. раздел про архив).
refresh / refresh_at	Как часто плееру следует перезагружать плейлист (интервал либо явные дата и время в формате ISO‑8601).
m3uautoload	1 указывает некоторым плеерам автоматически загружать EPG при открытии плейлиста.
max-conn	Число одновременных подключений, которое разрешает провайдер (позволяет плееру открыть «картинку в картинке» и т. п.).
billed-till / billed-msg	Временная метка окончания оплаченного периода / произвольное текстовое сообщение, которое провайдер может показать пользователю.

#EXTM3U x-tvg-url="https://example.com/epg.xml.gz" tvg-shift="0" catchup="shift" catchup-days="7" catchup-correction="0"

Атрибуты канала (строка #EXTINF)

Ни один из них не входит в формальный стандарт — это широко соблюдаемые соглашения. Префикс tvg- исторически означает «TV Guide» (телепрограмма).

Основные, почти универсальные

Атрибут	Значение
tvg-id	Уникальный идентификатор канала, по которому канал сопоставляется со своей программой передач. Должен совпадать с id элемента <channel> в XMLTV. Именно этот атрибут заставляет программу передач появиться.
tvg-name	Имя канала в том виде, как оно записано в EPG. Используется как запасной вариант при сопоставлении с EPG, а иногда и для отображения.
tvg-logo	URL логотипа/иконки канала. Если он относительный, к нему подставляется url-logo, а при отсутствии расширения добавляется .png.
group-title	Категория/папка, к которой относится канал (например, Sports, News). Некоторые плееры принимают несколько групп через ;.
tvg-chno / ch-number	Номер канала для отображения (LCN). Иначе плееры могут нумеровать каналы по порядку в плейлисте.

Частые дополнительные

Атрибут	Значение
tvg-shift	Сдвиг времени EPG для конкретного канала, в часах (например, -3.5). Значения за пределами -12..12 некоторые плееры трактуют как секунды.
radio	radio="true" помечает поток как только аудио.
tvg-language / tvg-country	Язык вещания / страна происхождения (используются для фильтрации, а не для воспроизведения).
tvg-rec	1 означает, что у канала есть архив. Избыточен, если присутствует атрибут catchup; значения >1 некоторые плееры читают как псевдоним catchup-days.
parent-code / adult	Помечает канал как ограниченный/взрослый, чтобы его можно было скрыть за PIN-кодом.
audio-track / video-track	Автоматически выбрать N-ю аудио-/видеодорожку (некоторые плееры также принимают разрешение, например 1920x1080).
type="playlist" (он же content-type="playlist")	URL «канала» — это включение: плеер встраивает другой плейлист прямо в этот. Удобно для сборки больших списков.
catchup, catchup-source, catchup-days, catchup-correction, timeshift	Переопределения catch-up для конкретного канала (см. ниже).

Замечание о переносимости: тег, который один плеер игнорирует, другой может использовать. Плееры обычно пропускают нераспознанные атрибуты, поэтому неизвестные атрибуты можно безопасно оставлять на месте.

Вспомогательные строки: заголовки, user-agent, referrer и DRM

Когда потоку нужны нестандартные HTTP-заголовки или DRM, эта информация передаётся рядом с каналом. Механизмов несколько, и они пересекаются.

Прямо в URL (синтаксис с вертикальной чертой). Дописывайте поля заголовков после |:

https://provider.example/live/cnn.m3u8|user-agent=MyPlayer/1.0&referer=https://provider.example/

Kodi поддерживает таким способом фиксированный набор стандартных имён заголовков (в их числе referer), а также особые поля cookie, cookies, seekable и user-agent; нестандартные заголовки нужно предварять !.

#EXTVLCOPT: (опции в стиле VLC). По одной паре key=value в строке. Две самые важные распознаются многими плеерами и превращаются в HTTP-заголовки запроса:

#EXTVLCOPT:http-user-agent=Mozilla/5.0
#EXTVLCOPT:http-referrer=https://provider.example/

#EXTHTTP: (заголовки в JSON). JSON-объект с произвольными заголовками, который понимают OTT Navigator и другие:

#EXTHTTP:{"User-Agent":"Mozilla/5.0","X-Token":"abc123"}

#KODIPROP: (свойства плеера, включая DRM). По одной паре key=value в строке. Помимо выбора inputstream, именно так передаются DRM ClearKey/Widevine/PlayReady:

#KODIPROP:inputstream.adaptive.license_type=clearkey
#KODIPROP:inputstream.adaptive.license_key=https://license.example/getkey

#EXTGRP:Название категории тоже назначает группу, но учитывайте разницу: в Kodi это открывающая директива — каждый канал после неё наследует эту группу, пока её не сбросит пустой #EXTGRP или атрибут group-title. В OTT Navigator, наоборот, это просто псевдоним group-title для одного канала. Если значение должно относиться ровно к одному каналу, предпочитайте group-title.

Привязка программы передач (XMLTV)

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

Как на самом деле работает сопоставление

Укажите плейлисту на программу передач через url-tvg/x-tvg-url — и плееры начнут разрешать каждый канал по XMLTV в фиксированном порядке (это логика, которую использует Kodi IPTV Simple Client, а остальные её повторяют):

1. По id — совпадает ли tvg-id канала с <channel id="…"> в XMLTV? Если да, готово.
2. По имени — совпадает ли <display-name> (как есть либо с пробелами, заменёнными на подчёркивания) с tvg-name канала?
3. По отображаемому имени — совпадает ли <display-name> с отображаемым именем канала (текстом после запятой)?

Побеждает первое совпадение. Вывод: задавайте tvg-id и делайте его в точности равным id из XMLTV. Запасной вариант по имени ненадёжен (регистр, суффиксы «HD», пробелы).

Структура XMLTV

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

  <programme start="20260612200000 +0000" stop="20260612210000 +0000" channel="bbcone.uk">
    <title>The Nine O'Clock News</title>
    <desc>The day's headlines.</desc>
    <category>News</category>
    <episode-num system="onscreen">S12E04</episode-num>
  </programme>
</tv>

• Атрибуты start/stop элемента <programme> используют формат YYYYMMDDHHMMSS ±HHMM. Всегда указывайте смещение часового пояса.
• Программу передач можно отдавать без сжатия, в gzip (.gz) или в xz (.xz).
• Необязательный нестандартный атрибут catchup-id у <programme> несёт специфичный для провайдера идентификатор, который требуется некоторым URL архива (см. {catchup-id} ниже).

Сдвиг времени

Если временные метки вашей программы передач не совпадают с каналом — обычно это ретранслируемый из другого часового пояса фид, — исправьте это атрибутом tvg-shift (в часах) на уровне канала или хэдера, а не правкой самой программы передач.

Catch-up / архив: полная картина

Catch-up (он же архив, повтор, таймшифт) позволяет посмотреть уже прошедшую в эфире передачу. Провайдер хранит скользящее окно записи — скажем, 7 дней, — а плеер конструирует URL с временной меткой для той передачи, которую вы выбрали в программе передач. Размер этого окна объявляется через catchup-days.

Этот раздел описывает соглашения в том виде, в каком их реализует экосистема в целом. Если вы провайдер и хотите знать, какие именно из них читает UniPlayer, то контракт, под который стоит строить, — это спецификация «Архив и Catch-up».

Атрибуты catch-up

Атрибут	Значение
catchup (псевдоним catchup-type)	Режим — как строить URL архива. Значения приведены ниже.
catchup-source	Шаблон URL (с плейсхолдерами). В режиме default это полный URL; в режиме append — только та часть запроса, которая дописывается к URL живого потока. Опустите его, чтобы режимы вроде flussonic/xc сгенерировали URL автоматически.
catchup-days	На сколько дней назад простирается архив.
catchup-correction	Поправка времени в часах, применяемая при генерации URL, — лекарство для архивов, которые воспроизводят не то время из-за рассогласования часовых поясов.
catchup-time	Устаревшее: окно архива в секундах (предпочитайте catchup-days).
timeshift	Устаревший тег SIPTV, объединяющий сдвиг и число дней в одном поле.

Режимы catch-up

Режим (и псевдонимы)	Что делает плеер
default	Трактует catchup-source как полный URL архива (с плейсхолдерами). Если источник не задан, откатывается к append.
append	Дописывает catchup-source (строку запроса с плейсхолдерами) к URL живого канала.
shift (SIPTV)	Автоматически дописывает ?utc={utc}&lutc={lutc} к URL живого потока — или &utc=…&lutc=…, если URL уже содержит ?. Источник не нужен.
flussonic / flussonic-hls · flussonic-ts / fs	Автоматически строит URL архива Flussonic из URL живого потока. Это не просто псевдонимы — написание выбирает контейнер: flussonic и flussonic-hls дают HLS (.m3u8), а flussonic-ts и fs — MPEG‑TS (.ts). OTT Navigator добавляет ещё flussonic-dash.
xc	Автоматически строит URL таймшифта Xtream Codes из URL живого потока. xc — единственное написание, которое принимают плееры: xtream не распознаётся.
vod	Трактует запись как видео по запросу с ключом {catchup-id}; передача воспроизводится как обычное видео с началом и концом.

Спецификаторы формата (плейсхолдеры)

Эти токены, подставляемые в момент воспроизведения, — сердце catch-up. Список ниже следует реализации Kodi, за которой близко следуют остальные плееры.

Токен	Во что разворачивается
{utc} / ${start}	Время начала передачи, секунды Unix в UTC.
{lutc} / ${now} / ${timestamp}	Текущее время, секунды Unix в UTC.
{utcend} / ${end}	Время начала плюс {duration}.
{Y} {m} {d} {H} {M} {S}	Год / месяц / день / час / минута / секунда времени начала.
{duration}	Длительность передачи (плюс буфер до/после, если он задан).
{duration:X}	Длительность, делённая на X секунд, — например, {duration:60} для минут. X должно быть положительным целым.
{offset:X}	(сейчас − начало), делённое на X секунд, — например, {offset:1} для «секунд назад».
{catchup-id}	Идентификатор конкретной передачи, взятый из <programme catchup-id="…"> в XMLTV.

Два уточнения, о которых стоит знать:

• Токены времени принимают аргумент формата. {utc:Ymd-H-M} или ${end:YmdHM} форматируют время прямо на месте с помощью букв Y m d H M S — удобно, когда провайдер хочет 2026-06-12, а не число Unix.
• OTT Navigator добавляет именованные части даты: ${start-year}, ${start-mon}, ${start-day}, ${start-hour}, ${start-min}, ${start-sec} — те же значения, но словами.

Разобранные шаблоны:

?utc={utc}&lutc={lutc}
&t={Y}-{m}-{d}-{H}-{M}-{S}
?start={utc:YmdHM}&end=${end:YmdHM}
?offset={offset:1}

Построение URL архива по типу сервера

Режимы с автогенерацией существуют потому, что доминируют две серверные платформы, у каждой из которых своя фиксированная грамматика URL.

Flussonic. Все временные метки — секунды Unix в UTC. Из URL живого потока вида http://host/STREAM/index.m3u8 получаются такие формы архива:

Назначение	Вид URL
Catch-up (HLS)	http://host/STREAM/archive-{start}-{duration}.m3u8
Catch-up (MPEG‑TS)	http://host/STREAM/archive-{start}-{duration}.ts
Catch-up (DASH)	http://host/STREAM/archive-{start}-{duration}.mpd
Скачать фрагмент	http://host/STREAM/archive-{start}-{duration}.mp4
Событие (без явного конца)	http://host/STREAM/archive-{start}-now.m3u8
Абсолютный таймшифт	http://host/STREAM/timeshift_abs-{start}.ts (или .m3u8)
Относительный таймшифт	http://host/STREAM/timeshift_rel-{seconds_ago}.ts
Скользящее окно перемотки	http://host/STREAM/rewind-{window_seconds}.m3u8 — здесь число это длина окна манифеста, а не отступ в прошлое.

Обратите внимание, что именно генерирует режим flussonic: не форму archive-, а URL таймшифта — …/timeshift_abs-${start}.ts для TS-вариантов и …/timeshift_rel-{offset:1}.m3u8 для HLS-вариантов. Формы archive-… из таблицы выше — это то, что вы пишете руками сами в режиме default, например …/archive-{utc}-{duration}.m3u8 для часовой передачи. (Добавьте ?ignore_gaps=true к запросу timeshift_abs-…m3u8, если в записи были перерывы и вы хотите, чтобы воспроизведение пропускало дыры.)

Xtream Codes. Две равнозначные формы. Длительность указывается в минутах, а время начала — это местное «настенное» время в формате YYYY-MM-DD:HH-MM: плееры формируют его в часовом поясе устройства, а панель читает в своём, и именно отсюда обычно берётся «архив играет со сдвигом на час».

http://host:port/timeshift/USER/PASS/{duration_min}/{YYYY-MM-DD:HH-MM}/{stream_id}.ts
http://host:port/timeshift/USER/PASS/{duration_min}/{YYYY-MM-DD:HH-MM}/{stream_id}.m3u8

либо форма со скриптом:

http://host:port/streaming/timeshift.php?username=USER&password=PASS&stream={stream_id}&start={YYYY-MM-DD:HH-MM}&duration={duration_min}

Режим xc строит их автоматически из живого URL Xtream (…/live/USER/PASS/STREAM.ts); для каналов с .m3u8 он выдаёт вариант с .m3u8. Поскольку формат ожидает местное время, а EPG отдаёт UTC, catchup-correction требуется довольно часто.

Как это связано с API Xtream Codes

Логин Xtream Codes — это не файл M3U, а API. Но он экспортирует такой файл. Запрос …/get.php?username=USER&password=PASS&type=m3u_plus&output=ts (документированные значения output — ts, m3u8 и rtmp) возвращает обычный расширенный M3U с описанными выше атрибутами tvg-*, а …/player_api.php?…&action=get_live_streams возвращает тот же каталог в JSON. Каналы, у которых в записи API стоит tv_archive=1, поддерживают catch-up через URL таймшифта из предыдущего раздела. Иными словами: Xtream — это механизм доставки, который сводится к тем же соглашениям M3U. Поэтому плеер может относиться к «URL плейлиста M3U» и к «логину Xtream» как к двум дверям в одну и ту же модель.

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

#EXTM3U x-tvg-url="https://example.com/epg.xml.gz" catchup-days="7"

# Обычный HLS-канал с полной привязкой к EPG и логотипом
#EXTINF:-1 tvg-id="bbcone.uk" tvg-name="BBC One HD" tvg-logo="https://example.com/logos/bbc1.png" group-title="UK",BBC One HD
https://provider.example/live/bbc1/index.m3u8

# Канал, которому нужны свои User-Agent и Referrer
#EXTINF:-1 tvg-id="cnn.us" tvg-logo="cnn" group-title="News",CNN
#EXTVLCOPT:http-user-agent=Mozilla/5.0
#EXTVLCOPT:http-referrer=https://provider.example/
https://provider.example/live/cnn/index.m3u8

# Catch-up Flussonic, URL генерирует сам плеер
#EXTINF:-1 tvg-id="sport1.de" group-title="Sports" catchup="flussonic" catchup-days="5",Sport 1
http://host:8080/sport1/index.m3u8

# Catch-up Xtream Codes, URL генерируется из ссылки на живой поток
#EXTINF:-1 tvg-id="film.fr" group-title="Movies" catchup="xc" catchup-days="3",Cinema FR
http://host:8080/live/user/pass/40521.ts

# Catch-up в режиме append с явным шаблоном запроса и поправкой часового пояса
#EXTINF:-1 tvg-id="news.it" group-title="News" catchup="append" catchup-source="&cutv={Y}-{m}-{d}T{H}:{M}:{S}" catchup-correction="-1.0",News IT
http://host:8080/live/newsit/index.m3u8

# Канал, защищённый DRM (ClearKey)
#EXTINF:-1 tvg-id="drm.demo" group-title="Premium",DRM Demo
#KODIPROP:inputstream.adaptive.license_type=clearkey
#KODIPROP:inputstream.adaptive.license_key=https://license.example/getkey
https://provider.example/drm/demo/manifest.mpd

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

• Первой строкой должна быть #EXTM3U — именно самой первой, без пустой строки над ней.
• Используйте UTF‑8 (.m3u8) для нелатинских названий; следите, чтобы перед #EXTM3U не затесалась метка порядка байтов (BOM).
• Никаких пустых строк внутри блока канала — URL должен идти сразу за строкой #EXTINF и вспомогательными строками.
• Заключайте значения атрибутов в кавычки единообразно и держите их в одной строке #EXTINF.
• tvg-id должен в точности совпадать с id из XMLTV — это причина номер один отсутствующей программы передач.
• Не путайте tvg-name с отображаемым именем — отображаемое имя идёт после запятой, а tvg-name нужен для сопоставления с EPG.
• Следите за часами архива — у Flussonic это UTC, у Xtream — местное время и минуты; прежде чем винить поток, вспомните про catchup-correction.
• Избавляйтесь от дублей — некоторые провайдеры меняют URL потоков; сопоставление по имени при обновлении может создать дубликаты, если изменились имена или ссылки.

Замечание о совместимости плееров

Поскольку управляющего стандарта нет, поддержка различается. Kodi IPTV Simple Client, TiviMate, OTT Navigator и Perfect Player реализуют пересекающиеся, но не идентичные наборы атрибутов и используют псевдонимы для одного и того же понятия (catchup и catchup-type, url-tvg и x-tvg-url, tvg-chno и ch-number) — при этом некоторые похожие пары псевдонимами вовсе не являются (flussonic и fs выбирают разный контейнер, а xtream — просто несуществующий режим). Составляя плейлист, ориентируйтесь на атрибуты, которые ваши плееры действительно читают, предпочитайте tvg-id плюс аккуратный XMLTV для программы передач и проверяйте результат в реальном приложении, прежде чем выпускать большой список.

UniPlayer относится к вашему плейлисту именно как к вашему. Он воспроизводит источники M3U/M3U8 и Xtream (а также Stalker, XML и VPortal), права на которые есть у вас, — так же, как VLC открывает файл, который вы ему дали. Он не предоставляет, не размещает и не продаёт каналы.