Lịch phát sóng XMLTV

XMLTV là định dạng tệp XML phổ biến nhất cho lịch phát sóng điện tử (EPG): nó liệt kê các kênh và chương trình của từng kênh, với giờ bắt đầu, giờ kết thúc, tiêu đề và mô tả.

TS IPTV không có sẵn kênh hay lịch phát sóng nào. Ứng dụng chỉ đọc các danh sách phát và lịch do bạn thêm vào.

XMLTV là gì

XMLTV xuất phát từ một dự án mã nguồn mở gồm các công cụ thu thập lịch truyền hình; cấu trúc tệp được mô tả trong tệp DTD chính thức. Ngày nay hầu hết trình phát IPTV đều đọc XMLTV. Một danh sách phát cho biết có những kênh nào; tệp XMLTV cho biết kênh đó đang và sắp phát gì.

Cú pháp

Phần tử gốc là <tv>. Bên trong, mọi phần tử <channel> đứng trước, sau đó đến các phần tử <programme>:

<tv>
  <channel id="…">            (không hoặc nhiều)
    <display-name>…</display-name>
    <icon src="…"/>
  </channel>
  <programme start="…" stop="…" channel="…">   (không hoặc nhiều)
    <title>…</title>
    <sub-title>…</sub-title>
    <desc>…</desc>
    <category>…</category>
    <episode-num system="…">…</episode-num>
    <rating system="…"><value>…</value></rating>
  </programme>
</tv>

`<tv>`

Phần tử gốc. Thuộc tính tuỳ chọn: date, generator-info-name, generator-info-url, source-info-name, source-info-url, source-data-url.

`<channel>`

Phần tử / thuộc tính	Bắt buộc	Nghĩa
`id`	có	Mã kênh. Danh sách phát dùng đúng mã này trong `tvg-id`.
`<display-name lang="…">`	ít nhất 1	Tên kênh.
`<icon src="…"/>`	không	Logo kênh.
`<url>`	không	Trang web của kênh.

`<programme>`

Phần tử / thuộc tính	Bắt buộc	Nghĩa
`channel`	có	Phải trùng với một `<channel id>`.
`start`	có	Giờ bắt đầu (xem định dạng thời gian bên dưới).
`stop`	nên có	Giờ kết thúc. TS IPTV cần giá trị này, nên hãy luôn ghi `stop`.
`<title lang="…">`	ít nhất 1	Tên chương trình.
`<sub-title>`	không	Tên tập.
`<desc lang="…">`	không	Mô tả. Đây là phần tử duy nhất được phép xuống dòng.
`<category lang="…">`	không, lặp được	Thể loại.
`<icon src="…"/>`	không	Ảnh của chương trình.
`<credits>`	không	Đạo diễn (`<director>`), diễn viên (`<actor>`)…
`<episode-num system="…">`	không	Số mùa và số tập (xem bên dưới).
`<rating system="…"><value>`	không	Phân loại độ tuổi, ví dụ `system="MPAA"`, `PG`.
`<star-rating><value>`	không	Điểm đánh giá, ví dụ `7 / 10`.

Định dạng thời gian

start và stop có dạng YYYYMMDDhhmmss, theo sau là độ lệch múi giờ: 20260927183000 +0700 là 18:30:00 ngày 27/09/2026 giờ Việt Nam. Theo DTD, thiếu độ lệch nghĩa là giờ UTC; nhưng hiện tại TS IPTV đọc những giờ như vậy theo múi giờ của thiết bị. Vì thế hãy luôn ghi rõ độ lệch. Khoảng thời gian là nửa mở: chương trình bắt đầu đúng lúc start và kết thúc ngay trước stop, nên stop của chương trình này nên bằng start của chương trình kế tiếp.

Số tập: `episode-num`

system="xmltv_ns": mùa.tập.phần, đếm từ 0. 2.4. nghĩa là mùa 3, tập 5. Mỗi phần có thể ghi X/Y: 0.11/12.0/2 là mùa 1, tập 12 trên 12, phần 1 trên 2. Phần chưa biết để trống.
system="onscreen": chữ tự do như trên màn hình, ví dụ S03E05. Đây là giá trị mặc định khi không ghi system.

Lịch liên kết với danh sách phát ra sao

Đường dẫn: danh sách phát M3U trỏ tới lịch bằng #EXTM3U x-tvg-url="https://…/guide.xml" (hoặc tên cũ url-tvg); danh sách JSON dùng trường epgUrl. Có thể ghi nhiều lịch, cách nhau bằng dấu phẩy: TS IPTV tải tối đa 5 lịch và gộp chương trình lại, bỏ các mục trùng.
Mã kênh: kênh tvg-id="ExampleNews.us" trong danh sách phát nhận chương trình của <channel id="ExampleNews.us">. Hãy chép mã y hệt, phân biệt hoa thường.
Lệch giờ: nếu lịch lệch với giờ thật, thêm tvg-shift="+1" (tính bằng giờ) vào kênh, hoặc vào dòng #EXTM3U cho mọi kênh.

Ví dụ đầy đủ

Đây là lịch ví dụ mà danh sách phát M3U ví dụ trỏ tới. Nó có hai kênh: HlsTest.example và ExampleNews.us.

Tải guide.xml

<?xml version="1.0" encoding="UTF-8"?>
<tv generator-info-name="TS IPTV examples">
  <channel id="HlsTest.example">
    <display-name lang="en">HLS Test Channel</display-name>
  </channel>
  <channel id="ExampleNews.us">
    <display-name lang="en">Example News</display-name>
    <icon src="https://example.com/logos/news.png"/>
  </channel>
  <programme start="20251231220000 +0000" stop="20251231230000 +0000" channel="ExampleNews.us">
    <title lang="en">Weekly Magazine</title>
    <sub-title lang="en">Harvest Season</sub-title>
    <desc lang="en">A dated example programme with an episode number and a rating.</desc>
    <category lang="en">Documentary</category>
    <episode-num system="xmltv_ns">2.4.</episode-num>
    <episode-num system="onscreen">S03E05</episode-num>
    <rating system="MPAA"><value>PG</value></rating>
  </programme>
  <programme start="20251231230000 +0000" stop="20260101000000 +0000" channel="ExampleNews.us">
    <title lang="en">Year in Review</title>
    <sub-title lang="en">Part One</sub-title>
    <category lang="en">News</category>
    <episode-num system="xmltv_ns">0.11/12.0/2</episode-num>
    <episode-num system="onscreen">S01E12</episode-num>
    <rating system="MPAA"><value>G</value></rating>
  </programme>
  <programme start="20260101000000 +0000" stop="20301231235959 +0000" channel="HlsTest.example">
    <title lang="en">Test pattern</title>
    <desc lang="en">One long programme, so the guide always shows something on now.</desc>
    <category lang="en">Test</category>
  </programme>
  <programme start="20260101000000 +0000" stop="20301231235959 +0000" channel="ExampleNews.us">
    <title lang="en">Test pattern</title>
    <desc lang="en">One long programme, so the guide always shows something on now.</desc>
    <category lang="en">Test</category>
  </programme>
</tv>

Hai phần tử <channel> đứng trước mọi chương trình, mỗi kênh một <display-name>.
Hai chương trình có ngày giờ cụ thể (tối 31/12/2025, giờ UTC) cho thấy các phần tử tuỳ chọn: sub-title, category, episode-num ở cả hai hệ, và rating.
“Test pattern”: mỗi kênh có một chương trình kéo dài từ 01/01/2026 tới hết năm 2030. Đó là mẹo cho tệp ví dụ: bất cứ lúc nào bạn mở, lịch vẫn có một chương trình “đang phát”. Lịch thật dùng các chương trình ngắn, nối tiếp nhau.

Tự viết một tệp

Phần lớn mọi người không viết XMLTV bằng tay: nhà cung cấp đưa sẵn đường dẫn lịch, hoặc lịch được tạo bằng công cụ thu thập. Với một danh sách nhỏ của riêng bạn, tự viết vẫn dễ:

Chép ví dụ ở trên vào một trình soạn thảo văn bản thuần (Notepad, TextEdit ở chế độ văn bản thuần, VS Code).
Mỗi kênh một <channel id="…">, với mã trùng tvg-id trong danh sách phát.
Thêm các <programme> sau mọi <channel>, luôn có start, stop và độ lệch múi giờ.
Viết & thành &, < thành < trong tiêu đề và mô tả.
Lưu với mã hoá UTF-8, đuôi .xml.
Lịch lớn nên được nén gzip thành guide.xml.gz: dùng lệnh gzip -k guide.xml (macOS, Linux), hoặc 7-Zip › Add to archive › định dạng gzip (Windows). Không dùng .zip: đó là định dạng khác.

Đưa tệp lên mạng

Giống như danh sách phát M3U: mọi đường dẫn HTTPS trả về chính nội dung tệp đều dùng được, ví dụ https://raw.githubusercontent.com/<user>/<repo>/<branch>/guide.xml.gz, https://<user>.github.io/<repo>/guide.xml hoặc https://www.example.com/guide.xml.gz. Trang chia sẻ của Google Drive/OneDrive và đường dẫn blob/ của GitHub không dùng được. Chi tiết: đưa tệp M3U lên mạng.

TS IPTV nhận ra tệp gzip qua nội dung, nên không phụ thuộc máy chủ gửi Content-Type: application/gzip hay Content-Encoding: gzip.
HTTPS được khuyến nghị; CORS không cần cho TS IPTV.
Hãy cập nhật tệp đều đặn: lịch chỉ có các ngày đã qua thì không còn gì để hiển thị.

Thêm vào TS IPTV

Thêm đường dẫn lịch vào dòng đầu tiên của danh sách phát M3U: #EXTM3U x-tvg-url="https://www.example.com/guide.xml.gz" (với JSON: trường epgUrl).
Thêm danh sách phát đó vào TS IPTV (hoặc làm mới nếu đã có). Lịch được tải cùng lúc.
Mở danh sách chương trình của một kênh để xem chương trình đang và sắp phát. Dùng Cập nhật lịch phát sóng để tải lại lịch.

TS IPTV hiện chưa có ô riêng để nhập đường dẫn lịch; lịch luôn đi kèm danh sách phát. Nếu danh sách phát của bạn không có x-tvg-url và bạn không sửa được nó ở nơi lưu trữ, hãy tải tệp về, thêm dòng trên, rồi dùng Nhập từ tệp.

Lỗi thường gặp

Lỗi	Biểu hiện	Cách sửa
Không ghi độ lệch múi giờ ở `start`/`stop`	Lịch lệch vài giờ	Luôn thêm `+hhmm`. Theo DTD giờ thiếu độ lệch là UTC, nhưng TS IPTV hiện đọc nó theo múi giờ của thiết bị.
`channel` không trùng `<channel id>` hoặc `tvg-id`	Lịch trống	Dùng cùng một chuỗi ở cả ba chỗ.
Ký tự `&` chưa được viết thành `&`	Lỗi đọc XML, mất cả lịch	Viết `&`.
`<programme>` đứng trước `<channel>`	Một số trình đọc bỏ qua kênh	Đặt mọi `<channel>` lên trước (đúng thứ tự trong DTD).
Chương trình chồng lên nhau hoặc trùng nhau	Hàng bị nhấp nháy hoặc lặp	Cho `stop` bằng `start` của chương trình sau.
Tệp gzip bị nén hai lần, hoặc nén `.zip`	“Lịch không hợp lệ”	Nén gzip đúng một lần.
Lịch chỉ có các ngày đã qua	“Chưa có lịch phát sóng”	Tạo lại lịch mỗi ngày.

TS IPTV hỗ trợ những gì

Tính năng	Trạng thái
XMLTV `.xml` và nén gzip `.xml.gz`	Hỗ trợ trên mọi nền tảng
Nén XZ `.xml.xz`	Không hỗ trợ
Mọi múi giờ trong `start`/`stop`	Hỗ trợ
Nhiều lịch trong `x-tvg-url` (tối đa 5), gộp và bỏ trùng	Hỗ trợ
`tvg-shift` theo kênh hoặc cho cả danh sách	Hỗ trợ
Hiển thị tiêu đề, mô tả, thể loại, ảnh, đạo diễn và diễn viên	Hỗ trợ
`sub-title`, `episode-num`, `rating`, `star-rating`	Được chấp nhận, chưa hiển thị
Ô riêng để nhập đường dẫn lịch	Chưa có Dùng `x-tvg-url`.

XMLTV programme guides

XMLTV is the most common XML format for electronic programme guides (EPG): it lists channels and each channel's programmes, with start and stop times, titles and descriptions.

TS IPTV includes no channels and no guides. It reads only the playlists and guides you add.

What XMLTV is

XMLTV comes from an open-source project of TV listings tools; the file structure is defined in its official DTD. Today almost every IPTV player reads XMLTV. A playlist says which channels exist; an XMLTV file says what is on them now and next.

Syntax

The root element is <tv>. Inside it, all <channel> elements come first, then the <programme> elements:

<tv>
  <channel id="…">            (zero or more)
    <display-name>…</display-name>
    <icon src="…"/>
  </channel>
  <programme start="…" stop="…" channel="…">   (zero or more)
    <title>…</title>
    <sub-title>…</sub-title>
    <desc>…</desc>
    <category>…</category>
    <episode-num system="…">…</episode-num>
    <rating system="…"><value>…</value></rating>
  </programme>
</tv>

`<tv>`

The root element. Optional attributes: date, generator-info-name, generator-info-url, source-info-name, source-info-url, source-data-url.

`<channel>`

Element / attribute	Required	Meaning
`id`	yes	Channel id. The playlist uses exactly this value in `tvg-id`.
`<display-name lang="…">`	at least 1	Channel name.
`<icon src="…"/>`	no	Channel logo.
`<url>`	no	The channel's website.

`<programme>`

Element / attribute	Required	Meaning
`channel`	yes	Must equal a `<channel id>`.
`start`	yes	Start time (see the time format below).
`stop`	should be present	Stop time. TS IPTV needs it, so always write `stop`.
`<title lang="…">`	at least 1	Programme title.
`<sub-title>`	no	Episode title.
`<desc lang="…">`	no	Description. The only element where line breaks are allowed.
`<category lang="…">`	no, repeatable	Genre.
`<icon src="…"/>`	no	Programme artwork.
`<credits>`	no	Director (`<director>`), actors (`<actor>`) and so on.
`<episode-num system="…">`	no	Season and episode number (see below).
`<rating system="…"><value>`	no	Age rating, for example `system="MPAA"`, `PG`.
`<star-rating><value>`	no	Score, for example `7 / 10`.

Time format

start and stop are YYYYMMDDhhmmss followed by a time-zone offset: 20260927183000 +0700 is 18:30:00 on 27 September 2026 in UTC+7. The DTD says that a time without an offset is UTC, but TS IPTV currently reads such times in the device's time zone. So always write the offset. Intervals are half-open: a programme starts at start and ends just before stop, so one programme's stop should equal the next one's start.

Episode numbers: `episode-num`

system="xmltv_ns": season.episode.part, counted from zero. 2.4. means season 3, episode 5. Each part may be X/Y: 0.11/12.0/2 is season 1, episode 12 of 12, part 1 of 2. Unknown parts are left empty.
system="onscreen": free text as shown on screen, for example S03E05. This is the default when system is omitted.

How a guide links to a playlist

The URL: an M3U playlist points to its guide with #EXTM3U x-tvg-url="https://…/guide.xml" (or the older url-tvg); a JSON playlist uses the epgUrl field. Several guides may be separated by commas: TS IPTV downloads up to 5 and merges their programmes, dropping duplicates.
The channel id: the playlist channel tvg-id="ExampleNews.us" gets the programmes of <channel id="ExampleNews.us">. Copy the id exactly; it is case-sensitive.
Time shift: if the guide is off by some hours, add tvg-shift="+1" (in hours) to the channel, or to the #EXTM3U line for every channel.

Complete example

This is the guide that the example M3U playlist points to. It has two channels: HlsTest.example and ExampleNews.us.

Download guide.xml

<?xml version="1.0" encoding="UTF-8"?>
<tv generator-info-name="TS IPTV examples">
  <channel id="HlsTest.example">
    <display-name lang="en">HLS Test Channel</display-name>
  </channel>
  <channel id="ExampleNews.us">
    <display-name lang="en">Example News</display-name>
    <icon src="https://example.com/logos/news.png"/>
  </channel>
  <programme start="20251231220000 +0000" stop="20251231230000 +0000" channel="ExampleNews.us">
    <title lang="en">Weekly Magazine</title>
    <sub-title lang="en">Harvest Season</sub-title>
    <desc lang="en">A dated example programme with an episode number and a rating.</desc>
    <category lang="en">Documentary</category>
    <episode-num system="xmltv_ns">2.4.</episode-num>
    <episode-num system="onscreen">S03E05</episode-num>
    <rating system="MPAA"><value>PG</value></rating>
  </programme>
  <programme start="20251231230000 +0000" stop="20260101000000 +0000" channel="ExampleNews.us">
    <title lang="en">Year in Review</title>
    <sub-title lang="en">Part One</sub-title>
    <category lang="en">News</category>
    <episode-num system="xmltv_ns">0.11/12.0/2</episode-num>
    <episode-num system="onscreen">S01E12</episode-num>
    <rating system="MPAA"><value>G</value></rating>
  </programme>
  <programme start="20260101000000 +0000" stop="20301231235959 +0000" channel="HlsTest.example">
    <title lang="en">Test pattern</title>
    <desc lang="en">One long programme, so the guide always shows something on now.</desc>
    <category lang="en">Test</category>
  </programme>
  <programme start="20260101000000 +0000" stop="20301231235959 +0000" channel="ExampleNews.us">
    <title lang="en">Test pattern</title>
    <desc lang="en">One long programme, so the guide always shows something on now.</desc>
    <category lang="en">Test</category>
  </programme>
</tv>

Two <channel> elements come before every programme, each with one <display-name>.
Two dated programmes (the evening of 31 December 2025, UTC) show the optional elements: sub-title, category, episode-num in both systems, and rating.
“Test pattern”: each channel has one programme running from 1 January 2026 to the end of 2030. It is a trick for an example file: whenever you open it, the guide has something “on now”. Real guides use short programmes that follow each other.

Create one by hand

Most people do not write XMLTV by hand: the provider gives a guide URL, or the guide is generated by a grabber tool. For a small personal list, writing one is still easy:

Copy the example above into a plain-text editor (Notepad, TextEdit in plain text mode, VS Code).
Add one <channel id="…"> per channel, with an id equal to the playlist's tvg-id.
Add <programme> elements after all the <channel> elements, always with start, stop and a time-zone offset.
Write & as & and < as < in titles and descriptions.
Save as UTF-8 with the extension .xml.
Compress large guides with gzip to guide.xml.gz: gzip -k guide.xml (macOS, Linux), or 7-Zip › Add to archive › format gzip (Windows). Do not use .zip: that is a different format.

Host it

Just like an M3U playlist: any HTTPS link that returns the file itself works, for example https://raw.githubusercontent.com/<user>/<repo>/<branch>/guide.xml.gz, https://<user>.github.io/<repo>/guide.xml or https://www.example.com/guide.xml.gz. Google Drive/OneDrive share pages and GitHub blob/ links do not work. Details: hosting an M3U file.

TS IPTV recognises gzip by its content, so it does not matter whether the server sends Content-Type: application/gzip or Content-Encoding: gzip.
HTTPS is recommended; CORS is not needed for TS IPTV.
Update the file regularly: a guide that only covers past days has nothing to show.

Add it in TS IPTV

Add the guide URL to the first line of your M3U playlist: #EXTM3U x-tvg-url="https://www.example.com/guide.xml.gz" (for JSON: the epgUrl field).
Add that playlist in TS IPTV (or refresh it if it is already there). The guide is downloaded with it.
Open a channel's programme list to see what is on now and next. Use Refresh EPG to download the guide again.

TS IPTV has no separate field for a guide URL yet; the guide always comes with a playlist. If your playlist has no x-tvg-url and you cannot edit it where it is hosted, download the file, add the line above, and use Import from file.

Common mistakes

Mistake	Symptom	Fix
No time-zone offset on `start`/`stop`	Guide shifted by some hours	Always add `+hhmm`. The DTD reads a missing offset as UTC, but TS IPTV currently uses the device's time zone.
`channel` does not equal `<channel id>` or `tvg-id`	Empty guide	Use the same string in all three places.
`&` not written as `&`	XML error, the whole guide is lost	Write `&`.
`<programme>` before `<channel>`	Some readers skip the channels	Put all `<channel>` elements first (DTD order).
Overlapping or duplicate programmes	Flickering or repeated rows	Make `stop` equal the next `start`.
A gzip file compressed twice, or a `.zip`	“Invalid guide”	Compress with gzip exactly once.
The guide only covers past days	“No programme guide”	Regenerate it daily.

What TS IPTV supports

Feature	Status
XMLTV `.xml` and gzip `.xml.gz`	Supported on every platform
XZ `.xml.xz`	Not supported
Any time-zone offset in `start`/`stop`	Supported
Several guides in `x-tvg-url` (up to 5), merged without duplicates	Supported
`tvg-shift` per channel or for the whole playlist	Supported
Shows title, description, category, artwork, director and actors	Supported
`sub-title`, `episode-num`, `rating`, `star-rating`	Accepted, not shown yet
A separate field for a guide URL	Not yet Use `x-tvg-url`.

Lịch phát sóng XMLTV

XMLTV là gì

Cú pháp

<tv>

<channel>

<programme>

Định dạng thời gian

Số tập: episode-num

Lịch liên kết với danh sách phát ra sao

Ví dụ đầy đủ

Tự viết một tệp

Đưa tệp lên mạng

Thêm vào TS IPTV

Lỗi thường gặp

TS IPTV hỗ trợ những gì

Hướng dẫn liên quan

XMLTV programme guides

What XMLTV is

Syntax

<tv>

<channel>

<programme>

Time format

Episode numbers: episode-num

How a guide links to a playlist

Complete example

Create one by hand

Host it

Add it in TS IPTV

Common mistakes

What TS IPTV supports

Related guides

`<tv>`

`<channel>`

`<programme>`

Số tập: `episode-num`

`<tv>`

`<channel>`

`<programme>`

Episode numbers: `episode-num`