Định dạng TS IPTV Source

TS IPTV Source là một tệp JSON duy nhất mô tả trọn vẹn một bộ sưu tập mang dấu ấn riêng: ai tạo ra nó, màu sắc, bố cục trang chủ, kênh truyền hình và radio, phim lẻ, phim bộ với các mùa và tập, lịch phát sóng, cùng các liên kết tới danh sách phát, lịch phát sóng và addon khác. Định dạng này là định dạng mở, được mô tả đầy đủ trên trang này và được kiểm tra bằng một JSON Schema công khai.

TS IPTV không có sẵn kênh nào và cũng không có sẵn nguồn nào. Một TS IPTV Source chỉ chứa những đường dẫn do người tạo đưa vào; TS IPTV không liệt kê, lưu trữ hay giới thiệu nguồn nào. Mọi ví dụ trên trang này dùng tên miền giả example.com, một luồng thử nghiệm công khai, phim thuộc phạm vi công cộng trên archive.org, hoặc tệp ví dụ của chính TS IPTV trên tsiptv-8bdd6.web.app.

Tệp: JSON Schema (https://tsiptv-8bdd6.web.app/schema/tsiptv-source-v1.json, chuẩn 2020-12) · ví dụ minimal-live, vod-catalog, composed-includes · công cụ kiểm tra trên trình duyệt.

Định dạng này là gì

M3U mô tả một danh sách kênh. TS IPTV Source mô tả cả một bộ sưu tập và cách trang chủ của nó hiển thị. Hãy dùng định dạng này khi bạn muốn có phim lẻ và phim bộ kèm ảnh bìa và các tập, có các mục và màu sắc riêng, có nhiều luồng cho mỗi nội dung, hoặc khi bạn muốn gộp các danh sách M3U, lịch XMLTV, addon tương thích Stremio và các nguồn khác thành một.

Định dạng tuân theo năm nguyên tắc:

Chỉ có dữ liệu, không có mã. Không có script, biểu thức, HTML hay Markdown. Mọi chữ đều là văn bản thuần; TS IPTV không bao giờ chạy thứ gì từ một nguồn.
Chỉ có đường dẫn, không có nội dung. Tệp mang các đường dẫn do người tạo cung cấp. Bản thân định dạng, schema và ứng dụng không kèm nội dung nào.
Dễ viết bằng tay. Tệp hợp lệ nhỏ nhất chỉ có mười dòng. Có cách viết tắt cho các trường hợp thường gặp (url thay cho streams, một chuỗi thường thay cho đối tượng dịch).
Tương thích về sau. Trường không biết sẽ bị bỏ qua và giá trị không biết được thay bằng giá trị dự phòng đã định, nên ứng dụng cũ vẫn đọc được tệp mới. Chỉ thay đổi làm hỏng tương thích mới tăng version.
Cùng ý nghĩa với M3U. Header, DRM và xem lại có đúng ý nghĩa như trong M3U kiểu Kodi, nên một kênh phát giống nhau ở cả hai định dạng.

Trang này là tài liệu tham khảo công khai của phiên bản 1. JSON Schema khắt khe hơn ứng dụng, nên tệp qua được schema gần như luôn được chấp nhận. Ngoại lệ là những điều schema không thấy được: tệp lớn hơn 5 MiB; format nằm sau 64 KiB đầu tiên; ngày không có thật trên lịch như 2026-02-30 (TS IPTV cảnh báo và bỏ qua trường đó); id trùng và tham chiếu tới mục không tồn tại (ứng dụng và công cụ kiểm tra đều phát hiện); và include bị lỗi hoặc tạo vòng lặp (E_INCLUDE, E_INCLUDE_CYCLE, và E_EMPTY nếu không còn gì khác).

Bắt đầu nhanh

Tệp nhỏ nhất dùng được: một kênh phát thật (luồng thử nghiệm công khai của Mux, phim Big Buck Bunny © Blender Foundation, CC BY 3.0).

{
  "$schema": "https://tsiptv-8bdd6.web.app/schema/tsiptv-source-v1.json",
  "format": "tsiptv-source",
  "version": 1,
  "id": "com.example.my-channels",
  "meta": { "name": "My Channels" },
  "channels": [
    { "id": "test-hls", "name": "HLS Test Channel", "url": "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" }
  ]
}

Lưu thành my-channels.tsiptv.json (UTF-8), đưa lên một máy chủ HTTPS bất kỳ rồi thêm đường dẫn vào TS IPTV. Dòng $schema giúp các trình soạn thảo như VS Code kiểm tra tệp và gợi ý tên trường ngay khi bạn gõ.

Định dạng, từng phần một

Tệp

Thuộc tính	Quy tắc
Mã hoá	UTF-8. BOM ở đầu tệp được chấp nhận nhưng không nên ghi.
Cú pháp	JSON: không chú thích, không dấu phẩy thừa. Gốc là một đối tượng.
Nhận dạng	Tệp là TS IPTV Source khi trường `"format"` ở cấp cao nhất là `"tsiptv-source"`. Tên tệp và loại nội dung máy chủ gửi không quan trọng. TS IPTV tìm `format` trong 64 KiB đầu tiên của tệp, nên hãy đặt nó ở gần đầu (ngay sau `$schema`).
Đuôi tệp	Nên dùng `.tsiptv.json` (ví dụ `my-channels.tsiptv.json`).
Kích thước	Tối đa 5 MiB sau khi giải nén, áp dụng cho chính tệp và cho từng nguồn được include.
Nén	Chấp nhận cả `Content-Encoding: gzip` của HTTP lẫn tệp đã nén gzip.

Cấp cao nhất

Trường	Bắt buộc	Nghĩa
`$schema`	không	Đường dẫn schema, dành cho trình soạn thảo. TS IPTV không bao giờ tải nó.
`format`	có	Đúng `"tsiptv-source"`.
`version`	có	`1`. Số lớn hơn nghĩa là “cần TS IPTV mới hơn”.
`id`	có	Mã định danh cố định của nguồn, là một Id. Nên dùng tên miền đảo ngược (`com.example.news`). Cùng `id` từ cùng đường dẫn là một bản cập nhật.
`revision`	không	Số nguyên ≥ 0 mà bạn tăng lên mỗi lần đăng thay đổi (mặc định 0).
`meta`	có	Thông tin về nguồn.
`appearance`	không	Màu sắc và kiểu thẻ.
`layout`	không	Các mục của trang chủ. Không có thì dùng bố cục mặc định.
`channels`	không	Kênh truyền hình và radio, tối đa 10.000.
`movies`	không	Tối đa 5.000.
`series`	không	Tối đa 1.000 (và tổng cộng 20.000 tập).
`epg`	không	Đường dẫn lịch phát sóng XMLTV, tối đa 10.
`includes`	không	Tài liệu từ xa, tối đa 20.

Tệp phải có ít nhất một trong channels, movies, series hoặc includes không rỗng.

Quy tắc chung

Trường x-: mọi trường có tên bắt đầu bằng x- là của bạn (ghi chú, dữ liệu của công cụ). TS IPTV bỏ qua chúng và định dạng sẽ không bao giờ định nghĩa trường nào như vậy. Quy tắc này không áp dụng cho tên header, khoá ngôn ngữ hay mã khoá DRM, vì đó là dữ liệu.
null tương đương với bỏ trống trường đó.
Trường không biết bị ứng dụng bỏ qua, nhưng schema báo lại để bạn phát hiện lỗi gõ.
Chữ được cắt khoảng trắng hai đầu; giá trị rỗng sau khi cắt là không hợp lệ. Độ dài tính theo ký tự (điểm mã Unicode).
Ký tự điều khiển: schema không cho phép trong chữ, trừ xuống dòng trong chữ dài (phần mô tả). TS IPTV dễ dãi hơn: xuống dòng hay ký tự điều khiển trong chữ một dòng được thay bằng dấu cách và chỉ bị báo là cảnh báo, không phải lỗi. URL và nguồn xem lại hoàn toàn không được có; giá trị header chỉ cho phép tab.

`meta`

Trường	Bắt buộc	Nghĩa
`name`	có	Chữ: tên hiển thị của nguồn.
`description`	không	Chữ dài.
`author`	không	`{ "name" (bắt buộc, 1–100), "url"?, "email"? }`.
`logo`	không	URL ảnh vuông, từ 256×256 trở lên.
`homepage`	không	Hiện trong “Giới thiệu nguồn”; TS IPTV hỏi trước khi mở.
`language`	không	Ngôn ngữ của các chữ viết dạng chuỗi thường và ngôn ngữ dự phòng (mặc định `en`).
`languages`	không	Ngôn ngữ của nội dung, để hiển thị (tối đa 20).
`updatedAt`	không	Thời điểm dạng `2026-09-27T10:00:00Z`.
`adult`	không	`true` nếu nguồn có nội dung người lớn. Mọi giá trị không phải `true` hay `false` cũng được coi là người lớn. Khi đó TS IPTV cảnh báo và hỏi “Tôi đủ 18 tuổi trở lên” trước khi nhập.
`license`	không	Giấy phép của danh sách (không phải của luồng), chữ tự do hoặc mã SPDX, tối đa 200 ký tự.

Chữ và bản dịch

Mọi chữ hiển thị là một chuỗi thường, viết bằng ngôn ngữ của meta.language, hoặc một đối tượng ánh xạ mã ngôn ngữ tới chuỗi:

"name": "Movies"
"name": { "en": "Movies", "vi": "Phim lẻ", "zh-CN": "电影" }

Chữ (tên, tiêu đề): 1–200 ký tự, một dòng. Chữ dài (mô tả): 1–5.000 ký tự; được xuống dòng (LF, CR hoặc CRLF).
Mã ngôn ngữ: en, vi, zh-CN, pt-BR (mẫu ^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$); tối đa 30 mã mỗi đối tượng.
TS IPTV chọn theo thứ tự: đúng ngôn ngữ của ứng dụng (zh-CN), rồi ngôn ngữ chính (zh, rồi bất kỳ zh-…), rồi meta.language, rồi en, rồi mục đầu tiên.
Chữ được hiện đúng như viết: không HTML, không Markdown.

Id, URL, header, màu

Kiểu	Quy tắc
Id	`^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`: chữ cái, chữ số, `.`, `_`, `-`, phân biệt hoa thường, không có `:` (dấu hai chấm dành cho mục được include, `includeId:itemId`). Mọi id của kênh, phim lẻ, phim bộ, tập và include phải là duy nhất trong tệp. Id xuất hiện trước được giữ, theo thứ tự: kênh, phim lẻ, phim bộ (mỗi phim bộ kèm các tập của nó), include; mục bị bỏ thì không giữ id của nó.
URL	Tuyệt đối, `http://` hoặc `https://`, tối đa 2.048 ký tự, không khoảng trắng hay ký tự điều khiển. Mọi URL trong tệp (luồng, ảnh, include, máy chủ giấy phép) đều theo quy tắc này; `rtmp:`, `udp:`, `file:`, `data:` và mọi giao thức khác đều không hợp lệ. Nên dùng `https`.
Header	Đối tượng tên header → giá trị, ví dụ `{ "User-Agent": "Mozilla/5.0", "Referer": "https://example.com/" }`. Tối đa 20. Giá trị được gửi đúng như viết (không giải mã URL), tối đa 4.096 ký tự. Cấm `Host`, `Content-Length`, `Connection` và `Transfer-Encoding`. Header đi kèm mọi yêu cầu của luồng (manifest, đoạn video, khoá), không đi kèm yêu cầu giấy phép DRM và không đi kèm tệp phụ đề.
Màu	`#RRGGBB`.

`appearance`

"appearance": {
  "accent": "#FFB300",
  "accentSecondary": "#FF7043",
  "background": { "gradient": ["#101014", "#1C1C24"], "image": "https://example.com/bg.jpg", "imageDim": 0.7 },
  "card": { "style": "poster", "corner": "medium", "showTitles": true }
}

Trường	Mặc định	Nghĩa
`accent`	màu nhấn của ứng dụng	Viền khi chọn, chip đang chọn, nút, thanh tiến độ.
`accentSecondary`	màu nhấn phụ	Chuyển màu trên nút và huy hiệu.
`background.color`	nền của ứng dụng	Nền một màu.
`background.gradient`	không có	2–3 màu, từ trên xuống; thay cho `color`.
`background.image`	không có	Ảnh phía sau trang chủ, dưới một lớp phủ tối.
`background.imageDim`	`0.6`	Độ đậm của lớp phủ, 0,3–1,0.
`card`	`{ "style": "auto" }`	Kiểu thẻ mặc định cho mọi mục.

Kiểu thẻ: style là auto, poster (2:3), landscape (16:9), square, logo (ô logo kênh) hoặc list (một dòng: logo, tên, chương trình đang phát); auto nghĩa là poster cho phim lẻ và phim bộ, logo cho kênh truyền hình, square cho radio, landscape cho các tập, và posterShape riêng của mục với mục lấy từ danh mục của addon tương thích Stremio. corner là none, small, medium hoặc large. showTitles: false ẩn tên trên thẻ (kênh và dạng list luôn hiện tên).

Độ dễ đọc. TS IPTV giữ màu chữ sáng của mình. Nếu màu nền của bạn (hoặc một điểm của dải màu) có độ tương phản dưới 4,5:1 với màu chữ đó, TS IPTV dùng nền của mình (ảnh nền vẫn được giữ). Nếu màu nhấn có độ tương phản dưới 3:1 với nền, cả hai màu nhấn được thay bằng màu của ứng dụng. Giao diện chỉ áp dụng cho trang chủ và trang chi tiết của nguồn; trình phát, hộp thoại và phần cài đặt vẫn giữ giao diện của ứng dụng.

`layout`: trang chủ

layout.home là danh sách 1–30 mục, được vẽ từ trên xuống.

"layout": {
  "home": [
    { "type": "hero", "query": { "from": "movies", "limit": 5 } },
    { "type": "row", "title": { "en": "Continue watching", "vi": "Xem tiếp" }, "query": { "from": "continueWatching" } },
    { "type": "row", "title": "News", "query": { "from": "channels", "groups": ["News"] }, "card": { "style": "logo" } },
    { "type": "grid", "title": "All channels", "query": { "from": "channels", "sort": "number" }, "groupChips": true }
  ]
}

Trường của mục	Nghĩa
`type` (bắt buộc)	`hero` (băng ảnh lớn trượt ngang, 1–10 mục), `row` (một hàng ngang, mặc định 20 mục, tối đa 100) hoặc `grid` (lưới mọi mục phù hợp, tải theo trang).
`id`	Giúp TS IPTV nhớ vị trí cuộn và vị trí chọn của mục.
`title`, `subtitle`	Tiêu đề và dòng phụ nhỏ hơn (hero không hiện tiêu đề).
`query`	Mục hiển thị gì (bắt buộc, trừ hero có `items`).
`items`	Chỉ cho hero: các banner làm tay `{ "image" (16:9, bắt buộc), "title", "subtitle", "target", "autoplay" }`. Một hero có `query` hoặc `items`, không có cả hai.
`card`	Kiểu thẻ cho riêng mục này (hero bỏ qua trường này).
`seeAll`	Chỉ cho row (mặc định `true`): nút “Xem tất cả” mở toàn bộ truy vấn dạng lưới.
`groupChips`	Chỉ cho grid của `channels` hoặc `radio`: các chip lọc theo nhóm phía trên lưới.

Hero dùng truy vấn sẽ lấy backdrop của từng mục, nếu không có thì poster, rồi logo, và bỏ qua mục không có ảnh. target của banner là id của một kênh, phim lẻ, phim bộ hoặc tập phim (mục được include viết dạng includeId:itemId); không có target thì banner chỉ để trang trí. autoplay: true bắt đầu phát nội dung (chỉ với kênh, phim lẻ và tập phim): kênh phát ngay; phim lẻ mở trang chi tiết của nó, tập phim mở trang chi tiết của phim bộ chứa nó, rồi phát luôn, nên bấm Quay lại sẽ về trang chi tiết đó. Banner không thể mở trang web. Mục không tìm thấy nội dung nào sẽ không được vẽ.

Truy vấn

Trường của truy vấn	Nghĩa
`from` (bắt buộc)	`channels`, `radio`, `movies`, `series`, `catalog` (danh mục của một include addon tương thích Stremio), `continueWatching`, `favorites`.
`include`	Chỉ lấy mục từ include có id này. Bắt buộc với `catalog`, khi đó nó là id của include `stremio`.
`catalog`	Cho `from: "catalog"`: `{ "type", "id", "genre"? }` của một danh mục khai báo trong manifest của addon đó.
`ids`	Chỉ những mục này, theo đúng thứ tự (1–500; mục được include viết dạng `includeId:itemId`). Id không tồn tại bị bỏ qua.
`groups`, `genres`, `tags`	Mục có nhóm (kênh), thể loại (phim lẻ, phim bộ) hoặc thẻ chứa một trong các giá trị này; không phân biệt hoa thường.
`sort`	`source` (thứ tự trong tệp; mục được include đứng sau mục của bạn), `name`, `number`, `year`, `yearDesc`, `recent` (Xem tiếp).
`limit`	1–500 mục.

Các bộ lọc kết hợp bằng VÀ giữa các trường và HOẶC trong cùng một trường. Bộ lọc không áp dụng được (ví dụ genres với kênh) bị bỏ qua. Với catalog, chỉ catalog.genre dùng để lọc và thứ tự của addon được giữ nguyên. continueWatching (phim lẻ, tập phim xem dở và kênh vừa xem) và favorites (kênh yêu thích) lấy từ lịch sử của chính người xem, không bao giờ nằm trong tệp; chúng bị ẩn cho tới khi có nội dung.

Bố cục mặc định

Khi không có layout, TS IPTV hiển thị: Xem tiếp; hero từ phim lẻ (chỉ khi có phim có backdrop); Phim lẻ; Phim bộ; Radio; và lưới Kênh xếp theo số kênh, kèm chip nhóm. Mục rỗng được bỏ đi.

Kênh, phim lẻ và phim bộ

Các trường phát, dùng chung cho kênh, phim lẻ và tập phim. Mỗi mục có đúng một trong hai trường url và streams:

Trường	Nghĩa
`url`	Một luồng. Viết tắt của `"streams": [{ "url": … }]`.
`streams`	1–10 lựa chọn, tốt nhất xếp trước. Với kênh, TS IPTV phát luồng đầu tiên mà thiết bị hỗ trợ, và người xem có thể chọn luồng khác ở mục “Luồng” trong “Tuỳ chọn phát” của trình phát (điện thoại: nút cài đặt của trình phát; TV: ▶, hoặc phím MENU, phím phụ đề hay phím Settings). Với phim lẻ hoặc tập phim, trang chi tiết liệt kê các luồng và người xem chọn ở đó; “Tuỳ chọn phát” của chúng chỉ có phụ đề. Trên TV, phần tuỳ chọn chỉ mở khi có gì đó để chọn.
`headers`	Header cho mọi luồng của mục; header riêng của luồng được ưu tiên theo từng tên.
`mimeType`	Gợi ý loại luồng cho mọi luồng.
`drm`	DRM cho mọi luồng; `drm` riêng của luồng thay thế nó.

Kênh

{
  "id": "example-news",
  "name": { "en": "Example News", "vi": "Tin tức Ví dụ" },
  "number": 101,
  "logo": "https://example.com/logos/news.png",
  "groups": ["News", "HD"],
  "epgId": "ExampleNews.us",
  "url": "https://cdn.example.com/news/index.m3u8",
  "headers": { "Referer": "https://example.com/" },
  "catchup": { "mode": "shift", "days": 3 }
}

Trường	Nghĩa
`id`, `name` (bắt buộc)	Id và Chữ.
`type`	`tv` (mặc định) hoặc `radio`.
`number`	0–99.999, hiện trên thẻ và dùng cho `sort: "number"`.
`logo`	URL logo (nên dùng PNG nền trong suốt).
`groups`	0–10 tên nhóm (1–100 ký tự). So khớp không phân biệt hoa thường và hiện đúng như viết; tên nhóm không được dịch.
`epgId`	`<channel id>` XMLTV của kênh. Không có thì lịch được khớp theo tên (không phân biệt hoa thường, dấu và khoảng trắng).
`epgShiftHours`	−12 … +14 giờ cộng vào giờ trong lịch của kênh.
`description`, `tags`	Chữ dài; 0–20 thẻ, mỗi thẻ 1–50 ký tự.
`catchup`	Xem lại.

Phim lẻ

Bắt buộc có id, name và các trường phát. Tuỳ chọn: originalName, poster (2:3), backdrop (16:9, dùng cho hero và trang chi tiết), logo (logo tên phim), description, year (1870–2100), releaseDate (YYYY-MM-DD), runtimeMinutes (1–1.440), genres (0–10), cast (0–50), directors (0–20), countries (mã ISO như US), languages, ageRating (như in trên phim, ví dụ T16), tags, subtitles (0–30).

Phim bộ, mùa, tập

{
  "id": "fleischer-superman",
  "name": "Fleischer Superman",
  "year": 1941,
  "endYear": 1943,
  "seasons": [
    {
      "number": 1,
      "episodes": [
        { "id": "fleischer-superman-s1e1", "number": 1, "name": "The Mechanical Monsters",
          "url": "https://archive.org/download/superman_the_mechanical_monsters/superman_the_mechanical_monsters_512kb.mp4" }
      ]
    }
  ]
}

Phim bộ có id và name (bắt buộc), originalName, poster, backdrop, logo, description, year (năm đầu), endYear (năm cuối, không nhỏ hơn year; không có nghĩa là đang chiếu), genres, cast, countries, languages, ageRating, tags và seasons (1–100). Phim bộ không có trường phát, và không có directors, releaseDate, runtimeMinutes hay subtitles.
Mỗi mùa có number (0–999, không trùng trong phim bộ; 0 là Tập đặc biệt, xếp cuối), tuỳ chọn name, poster, description, và episodes (1–500).
Mỗi tập có id (duy nhất trong cả tệp; dùng để lưu tiến độ xem), number (không trùng trong mùa), name, các trường phát, và tuỳ chọn description, thumbnail (16:9), releaseDate (ngày trong tương lai nghĩa là “sắp ra mắt”, được liệt kê nhưng chưa phát được), runtimeMinutes, subtitles.

Luồng

Trường	Nghĩa
`url` (bắt buộc)	HLS `.m3u8`, DASH `.mpd`, MP4, WebM, MKV, MPEG-TS, hoặc âm thanh (AAC, MP3, Opus).
`name`	Nhãn trong danh sách chọn luồng, như `1080p` hoặc `Dự phòng`.
`headers`, `drm`	Như trên; gộp lên trên, hoặc thay thế, giá trị của mục.
`mimeType`	Khi đường dẫn không có đuôi rõ ràng: `application/x-mpegURL` hoặc `application/vnd.apple.mpegurl` (HLS), `application/dash+xml`, `video/mp4`, `video/mp2t`, `video/webm`, `video/x-matroska`, `audio/aac`, `audio/mpeg`, `audio/ogg`.
`quality`, `language`	Huy hiệu: `HD`, `720p`; mã ngôn ngữ âm thanh.

DRM

"drm": { "system": "widevine", "licenseUrl": "https://license.example.com/widevine", "licenseHeaders": { "X-Example": "1" } }
"drm": { "system": "clearkey", "keys": { "000102030405060708090a0b0c0d0e0f": "00112233445566778899aabbccddeeff" } }

system: widevine, playready (bắt buộc có đường dẫn giấy phép) hoặc clearkey (một đường dẫn giấy phép, hoặc keys: 1–20 cặp mã khoá 32 ký tự hex → khoá 32 ký tự hex).
TS IPTV gửi yêu cầu thô tới licenseUrl và chờ giấy phép thô trả về; licenseHeaders chỉ đi kèm yêu cầu đó. Các giao thức giấy phép bọc hoặc dạng JSON không thuộc phiên bản 1.
Widevine phát trên Android; PlayReady phát trên thiết bị Android có hỗ trợ (có PlayReady CDM, chủ yếu là TV); ClearKey chỉ phát trên Android với luồng DASH. Trên iPhone, iPad và máy tính, kênh bỏ qua luồng có DRM và phát luồng tiếp theo không có DRM; nếu không có, TS IPTV báo “Kênh này được bảo vệ bằng DRM. Thiết bị này không hỗ trợ DRM.” Với phim lẻ hoặc tập phim, chọn một luồng có DRM ở trang chi tiết sẽ hiện đúng thông báo đó, nên hãy cho các mục này thêm một luồng không có DRM.
Chỉ công bố khoá và máy chủ giấy phép mà bạn có quyền chia sẻ.

Xem lại (catch-up)

catchup dùng cùng các chế độ và chỗ trống như xem lại trong M3U kiểu Kodi: { "mode", "source"?, "days"? (1–60, mặc định 7), "correctionHours"? (−24 … +24) }. mode là default (source là mẫu URL đầy đủ, bắt đầu bằng http:// hoặc https://), append (source được nối vào sau đường dẫn phát trực tiếp, ví dụ ?utc={utc}&lutc={lutc}), shift, flussonic, flussonic-ts hoặc xc. Với default và append, source là bắt buộc và không bao giờ được cắt khoảng trắng: có dấu cách hay ký tự điều khiển là không hợp lệ (W_FIELD), phần xem lại bị bỏ và kênh chỉ phát trực tiếp. Các chế độ khác dựng URL từ đường dẫn phát trực tiếp và bỏ qua source. TS IPTV lưu thông tin xem lại; tính năng phát lại chương trình đã phát sẽ có sau.

Phụ đề

{ "url" (WebVTT hoặc SubRip), "language" (bắt buộc), "label"?, "format"? ("vtt" hoặc "srt") }. Phụ đề mặc định Tắt: người xem bật một phụ đề ở mục “Phụ đề” trong “Tuỳ chọn phát” của trình phát (xem luồng). Trên Android, phụ đề không có label hiện tên ngôn ngữ, và tệp phụ đề được tải không kèm header của luồng, nên hãy đặt chúng ở nơi không cần mã truy cập hay Referer. Trên máy tính, phụ đề vẫn tải được, nhưng cách đặt tên và việc có gửi header hay không chưa được kiểm chứng. iPhone và iPad chưa hiện phụ đề.

`epg` và `includes`

epg là danh sách đường dẫn lịch phát sóng XMLTV, mỗi mục là một chuỗi URL hoặc { "url", "refreshHours"? } (1–720, mặc định 24). Lịch có thể nén gzip. Chương trình được khớp với kênh theo epgId; kênh không có epgId được khớp theo tên (không phân biệt hoa thường, dấu và khoảng trắng).

"includes": [
  { "id": "news", "type": "m3u", "url": "https://example.com/playlists/news.m3u", "name": "Partner news" },
  { "id": "guide", "type": "xmltv", "url": "https://example.com/epg/guide.xml.gz", "refreshHours": 12 },
  { "id": "sampler", "type": "stremio", "url": "https://addon.example.com/manifest.json" },
  { "id": "archive", "type": "tsiptv-source", "url": "https://example.com/archive.tsiptv.json" }
]

Trường của include	Nghĩa
`id` (bắt buộc)	Id duy nhất; làm tiền tố cho các mục được include (`news:ExampleTV.us`). Không được bắt đầu bằng `epg-` (dành cho các đường dẫn `epg`).
`type` (bắt buộc)	`m3u`, `xmltv`, `stremio` hoặc `tsiptv-source`.
`url` (bắt buộc)	Với `stremio`, là đường dẫn manifest kết thúc bằng `/manifest.json`.
`name`	Hiện trong “Giới thiệu nguồn” và trong thông báo lỗi.
`refreshHours`	Số giờ tối thiểu giữa hai lần tự tải lại (1–720, mặc định 24).
`headers`	Gửi kèm khi tải tài liệu `m3u`, `xmltv` hoặc `tsiptv-source`; không gửi tới addon hay luồng.

Loại	Đóng góp gì	Id của mục
`m3u`	Kênh (mục radio vào nhóm radio), đọc bằng trình đọc M3U của TS IPTV, kể cả header và DRM; lịch trong `x-tvg-url` của nó được gộp vào bộ lịch.	`includeId:` + `tvg-id` của kênh (hoặc tên), ký tự ngoài tập ký tự Id được thay bằng `_`: `ExampleTV.us@HD` → `live:ExampleTV.us_HD`.
`xmltv`	Chỉ dữ liệu lịch; không dùng được trong truy vấn.	—
`stremio`	Không thêm gì vào các nhóm nội dung; danh mục của nó được hiện bằng `from: "catalog"`. Chỉ luồng `url` phát được (xem addon tương thích Stremio).	Id riêng của addon.
`tsiptv-source`	Kênh, radio, phim lẻ, phim bộ và đường dẫn lịch của nó. `meta`, `appearance` và `layout` của nó bị bỏ qua.	`includeId:` + id của mục (nối tiếp nhau: `archive:partner:item`).

Độ sâu và vòng lặp: tệp gốc ở độ sâu 1; nguồn được include có thể include tiếp tới độ sâu 3. Include thuộc bất kỳ loại nào sâu hơn 3, hoặc có URL đã nằm trên đường đi, sẽ bị từ chối (E_INCLUDE_CYCLE).
Tổng mỗi lần làm mới: tối đa 20 include trong cả cây (không tính đường dẫn lịch), 50 MiB tải về (mọi tài liệu kể cả tệp gốc; câu trả lời 304 tính là 0), và 20.000 kênh, 5.000 phim lẻ, 1.000 phim bộ sau khi gộp. Mỗi include M3U tối đa 20 MiB, XMLTV tối đa 100 MiB, TS IPTV Source tối đa 5 MiB.
Khi tải lỗi: include lỗi không bao giờ làm hỏng nguồn của bạn. TS IPTV giữ bản tải thành công gần nhất; nếu chưa có, các mục dùng include đó bị ẩn.
Nội dung người lớn: nếu một nguồn được include có meta.adult: true (hoặc bất kỳ giá trị nào không phải true/false), hoặc manifest của một addon khai báo nội dung người lớn, TS IPTV hỏi xác nhận 18+ cho cả nguồn trước khi lưu bất cứ thứ gì. Nếu một lần làm mới về sau khiến nguồn bạn chưa xác nhận trở thành nguồn người lớn, nội dung mới của include gây ra điều đó sẽ bị giữ lại (bản cũ vẫn được dùng) cho tới khi bạn xác nhận trong “Giới thiệu nguồn”.

Giới hạn

Mục	Giới hạn
Kích thước tệp	5 MiB mỗi tài liệu sau khi giải nén; 50 MiB mỗi lần làm mới cho cả cây
Số mục	10.000 kênh, 5.000 phim lẻ, 1.000 phim bộ, 20.000 tập mỗi tài liệu; 20.000 / 5.000 / 1.000 sau khi gộp
Phim bộ	100 mùa, 500 tập mỗi mùa
Luồng, phụ đề	10 luồng mỗi mục; 30 phụ đề
Header	20 mỗi bảng (kể cả sau khi gộp header của mục và của luồng); giá trị tối đa 4.096 ký tự
Bố cục	30 mục; 10 banner hero; `limit` và `ids` của truy vấn tối đa 500; một hàng hiện tối đa 100
Include	20 mỗi tài liệu và trong cả cây; độ sâu 3; 10 đường dẫn `epg` mỗi tài liệu
Chữ	200 ký tự (Chữ), 5.000 (chữ dài), 30 ngôn ngữ mỗi chữ; URL 2.048

Bảo mật và quyền riêng tư

TS IPTV không bao giờ chạy, tính toán hay hiển thị như mã đánh dấu bất cứ thứ gì từ một nguồn.
Chỉ đường dẫn http và https mới được mở.
Một nguồn không thể mở trang web, cài đặt hay tải tệp xuống máy. Khi nhập, ứng dụng chỉ tải tệp và các include của nó; ảnh được tải khi hiển thị; luồng chỉ được tải khi người xem bấm phát.
URL và header có thể chứa mã truy cập. TS IPTV không gửi chúng tới dịch vụ phân tích, báo cáo lỗi hay máy chủ của mình, và không ghi chúng vào nhật ký ở bản phát hành.
Máy chủ tại nhà trong mạng nội bộ vẫn dùng được.
Nội dung người lớn luôn cần xác nhận 18+ (ở tệp gốc hay trong include).

Phiên bản và giá trị chưa biết

Trường tuỳ chọn và giá trị mới sẽ dần được thêm vào phiên bản 1, tại cùng đường dẫn schema. Khi gặp một giá trị chưa biết, TS IPTV dùng giá trị dự phòng thay vì báo lỗi:

Giá trị chưa biết ở	Điều gì xảy ra
`type` của mục, `from` của truy vấn	Mục bị bỏ qua.
`sort` của truy vấn	Dùng thứ tự `source`.
`style` / `corner` của thẻ	`auto` / `medium`.
`type` của kênh	Coi như `tv`.
`type` của include	Include bị bỏ qua (`E_INCLUDE`).
`mimeType` của luồng	Bỏ qua gợi ý.
`drm.system`	Luồng không bao giờ được phát khi thiếu DRM; nó không phát được trên thiết bị đó.
`catchup.mode`	Không có xem lại; phát trực tiếp vẫn bình thường.

Thay đổi làm đổi ý nghĩa của các tệp hiện có sẽ là phiên bản 2, với schema mới (tsiptv-source-v2.json); schema phiên bản 1 vẫn được giữ.

Kiểm tra: lỗi và cảnh báo

TS IPTV kiểm tra một nguồn ở ba mức. Lỗi tài liệu khiến tệp bị từ chối. Lỗi mục bỏ mục hoặc trường đó và nhập phần còn lại. Cảnh báo không thay đổi gì nhưng được liệt kê. Mỗi vấn đề được liệt kê dạng đường dẫn — MÃ: giải thích, ví dụ channels[3].url — E_URL: … (phần giải thích là một câu ngắn theo ngôn ngữ của ứng dụng).

Mã	Mức	Khi nào	Người xem thấy gì
`E_NOT_JSON`	tài liệu	Không phải JSON, hoặc gốc không phải đối tượng	“Tệp này không phải JSON hợp lệ.”
`E_NOT_SOURCE`	tài liệu	Thiếu `format` hoặc sai giá trị	“Đây không phải tệp TS IPTV Source.”
`E_VERSION`	tài liệu	Thiếu `version`, không phải số nguyên ≥ 1, hoặc mới hơn ứng dụng	“Nguồn này cần phiên bản TS IPTV mới hơn.”
`E_TOO_LARGE`	tài liệu	Lớn hơn 5 MiB	“Nguồn này lớn hơn 5 MB.”
`E_ID`, `E_META`	tài liệu	Thiếu hoặc sai `id`, `meta` hay `meta.name`	“Nguồn này thiếu id hoặc tên.”
`E_EMPTY`	tài liệu	Không có mục và include nào (hoặc tất cả đều bị bỏ)	“Nguồn này không có nội dung nào TS IPTV hiển thị được.”
`E_ITEM_ID`	mục	Thiếu hoặc sai id; số mùa hay số tập bị thiếu hoặc ngoài khoảng; một phần tử không phải đối tượng	Trước khi nhập: “N mục sẽ bị bỏ qua” kèm Chi tiết. Sau khi nhập: thông báo thành công, ví dụ “Đã thêm nguồn: 3 kênh, 1 phim lẻ, 0 phim bộ”, kèm “Đã bỏ qua N mục”. Khi làm mới: đếm trong “Giới thiệu nguồn” (“Số vấn đề ở lần làm mới gần nhất: N”) và liệt kê trong “Các vấn đề tìm thấy”.
`E_DUPLICATE_ID`	mục	Id (hoặc số mùa, số tập) đã được dùng
`E_ITEM_NAME`	mục	Thiếu hoặc sai `name`
`E_NO_STREAM`	mục	Không có `url`/`streams`, có cả hai, hoặc không còn luồng hợp lệ; phim bộ hay mùa không còn gì hợp lệ bên trong
`E_INCLUDE`	include	Include không hợp lệ, nguồn được include bị từ chối, hoặc tải lỗi (bản tốt gần nhất được giữ)
`E_INCLUDE_CYCLE`	include	Vòng lặp, hoặc sâu hơn 3
`E_URL`	trường / mục	URL không hợp lệ (luồng, ảnh hay banner bị bỏ)	Liệt kê trong Chi tiết; không tính vào “N mục sẽ bị bỏ qua”. Mục vẫn được giữ, trừ khi không còn gì phát được (khi đó là `E_NO_STREAM`).
`E_HEADER_FORBIDDEN`	trường	Tên header bị cấm hoặc không hợp lệ; chỉ header đó bị bỏ
`E_DRM`	luồng	DRM không hợp lệ (thiếu đường dẫn giấy phép, khoá sai); luồng bị bỏ
`W_UNKNOWN_TYPE`	cảnh báo	Một giá trị chưa biết được thay bằng giá trị dự phòng	Liệt kê trong Chi tiết; không có gì bị bỏ, trừ khi ghi rõ.
`W_QUERY_REF`	cảnh báo	Truy vấn trỏ tới include không tồn tại hoặc include `xmltv`, truy vấn `catalog` trỏ tới include không phải `stremio`, hoặc addon không khai báo danh mục đó; mục bị bỏ qua
`W_LIMIT`	cảnh báo	Chạm giới hạn số lượng; các mục thừa bị bỏ
`W_CONTRAST`	cảnh báo	Một màu được thay để dễ đọc
`W_TEXT`	cảnh báo	Chữ quá dài (bị cắt); xuống dòng hay ký tự điều khiển trong chữ một dòng được thay bằng dấu cách; khoá ngôn ngữ không hợp lệ, hoặc có hơn 30 ngôn ngữ (các mục đó bị bỏ qua)
`W_FIELD`	cảnh báo	Trường tuỳ chọn sai kiểu hay ngoài khoảng, giá trị header không hợp lệ, nguồn xem lại không hợp lệ, mục bố cục hỏng, hoặc một cách dùng sai được bỏ qua; trường đó bị bỏ

Công cụ kiểm tra trên trình duyệt chạy JSON Schema và các bước kiểm tra tham chiếu trên tệp của bạn trước khi bạn đăng nó.

Ví dụ đầy đủ

Danh sách kênh tối giản

Một kênh phát thật, một kênh giả có header và mã lịch phát sóng, và một đài radio giả.

Tải minimal-live.tsiptv.json

{
  "$schema": "https://tsiptv-8bdd6.web.app/schema/tsiptv-source-v1.json",
  "format": "tsiptv-source",
  "version": 1,
  "id": "app.tsiptv.examples.minimal-live",
  "meta": {
    "name": "Minimal live list",
    "description": "The smallest useful TS IPTV Source: one public test stream that really plays, one placeholder channel that shows how to send HTTP headers, and one placeholder radio station. Replace the example.com links with your own streams.",
    "language": "en",
    "updatedAt": "2026-09-27T00:00:00Z"
  },
  "channels": [
    {
      "id": "hls-test",
      "name": "HLS Test Channel",
      "number": 1,
      "groups": ["Test"],
      "description": "Mux public HLS test stream. Video: Big Buck Bunny, (c) Blender Foundation, CC BY 3.0.",
      "url": "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
    },
    {
      "id": "example-news",
      "name": "Example News (placeholder)",
      "number": 2,
      "groups": ["News"],
      "logo": "https://example.com/logos/news.png",
      "epgId": "ExampleNews.us",
      "url": "https://cdn.example.com/news/index.m3u8",
      "headers": {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
        "Referer": "https://example.com/"
      }
    },
    {
      "id": "example-radio",
      "type": "radio",
      "name": "Example Radio (placeholder)",
      "groups": ["Radio"],
      "url": "https://radio.example.com/stream.aac",
      "mimeType": "audio/aac"
    }
  ]
}

Không có layout, nên TS IPTV dùng bố cục mặc định: một hàng Radio và một lưới Kênh có chip nhóm.

Phim lẻ và phim bộ, có giao diện và bố cục riêng

Tải vod-catalog.tsiptv.json

{
  "$schema": "https://tsiptv-8bdd6.web.app/schema/tsiptv-source-v1.json",
  "format": "tsiptv-source",
  "version": 1,
  "id": "app.tsiptv.examples.vod-catalog",
  "revision": 1,
  "meta": {
    "name": { "en": "Public Domain Cinema", "vi": "Rạp phim Phạm vi công cộng" },
    "description": {
      "en": "A small movie and series catalog built only from public-domain films on archive.org and a public test stream. It shows a custom appearance and home layout.",
      "vi": "Danh mục phim và phim bộ nhỏ, chỉ gồm phim thuộc phạm vi công cộng trên archive.org và một luồng thử nghiệm công khai. Tệp này minh hoạ giao diện và bố cục trang chủ tuỳ chỉnh."
    },
    "author": { "name": "TS IPTV examples", "url": "https://tsiptv-8bdd6.web.app/guides/tsiptv-source/" },
    "homepage": "https://tsiptv-8bdd6.web.app/guides/tsiptv-source/",
    "language": "en",
    "languages": ["en"],
    "updatedAt": "2026-09-27T00:00:00Z",
    "license": "Listing: CC0-1.0. Films: public domain (see each item)."
  },
  "appearance": {
    "accent": "#FFB300",
    "accentSecondary": "#FF7043",
    "background": { "gradient": ["#101014", "#1C1C24"] },
    "card": { "style": "poster", "corner": "large", "showTitles": true }
  },
  "layout": {
    "home": [
      {
        "type": "hero",
        "id": "featured",
        "items": [
          {
            "image": "https://archive.org/services/img/his_girl_friday",
            "title": "His Girl Friday",
            "subtitle": { "en": "Screwball comedy, 1940", "vi": "Hài kịch, 1940" },
            "target": "his-girl-friday"
          },
          {
            "image": "https://archive.org/services/img/superman_the_mechanical_monsters",
            "title": { "en": "Fleischer Superman", "vi": "Superman của Fleischer" },
            "subtitle": { "en": "Animated shorts, 1941–1943", "vi": "Phim hoạt hình ngắn, 1941–1943" },
            "target": "fleischer-superman"
          }
        ]
      },
      {
        "type": "row",
        "id": "continue",
        "title": { "en": "Continue watching", "vi": "Xem tiếp" },
        "query": { "from": "continueWatching" },
        "card": { "style": "landscape" }
      },
      {
        "type": "row",
        "id": "movies",
        "title": { "en": "Movies", "vi": "Phim lẻ" },
        "query": { "from": "movies", "sort": "yearDesc", "limit": 20 }
      },
      {
        "type": "row",
        "id": "series",
        "title": { "en": "Series", "vi": "Phim bộ" },
        "query": { "from": "series" }
      },
      {
        "type": "grid",
        "id": "comedy",
        "title": { "en": "Comedy", "vi": "Hài" },
        "query": { "from": "movies", "genres": ["Comedy"], "sort": "name" },
        "card": { "style": "landscape", "corner": "small" }
      }
    ]
  },
  "movies": [
    {
      "id": "his-girl-friday",
      "name": "His Girl Friday",
      "poster": "https://archive.org/services/img/his_girl_friday",
      "backdrop": "https://archive.org/services/img/his_girl_friday",
      "description": {
        "en": "Howard Hawks' screwball comedy. Public domain (archive.org item his_girl_friday).",
        "vi": "Phim hài của Howard Hawks. Thuộc phạm vi công cộng (mục his_girl_friday trên archive.org)."
      },
      "year": 1940,
      "releaseDate": "1940-01-18",
      "runtimeMinutes": 92,
      "genres": ["Comedy"],
      "directors": ["Howard Hawks"],
      "countries": ["US"],
      "languages": ["en"],
      "streams": [
        {
          "name": { "en": "archive.org, MP4 512 kb/s", "vi": "archive.org, MP4 512 kb/s" },
          "url": "https://archive.org/download/his_girl_friday/his_girl_friday_512kb.mp4",
          "mimeType": "video/mp4",
          "quality": "SD",
          "language": "en"
        }
      ]
    },
    {
      "id": "big-buck-bunny",
      "name": "Big Buck Bunny",
      "description": {
        "en": "Open movie by the Blender Foundation, CC BY 3.0, streamed from the Mux public HLS test stream.",
        "vi": "Phim mở của Blender Foundation, giấy phép CC BY 3.0, phát từ luồng thử nghiệm HLS công khai của Mux."
      },
      "year": 2008,
      "runtimeMinutes": 10,
      "genres": ["Animation", "Comedy"],
      "url": "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8",
      "mimeType": "application/x-mpegURL"
    }
  ],
  "series": [
    {
      "id": "fleischer-superman",
      "name": { "en": "Fleischer Superman", "vi": "Superman của Fleischer" },
      "poster": "https://archive.org/services/img/superman_the_mechanical_monsters",
      "backdrop": "https://archive.org/services/img/superman_the_mechanical_monsters",
      "description": {
        "en": "Fleischer Studios' Superman cartoons, now in the public domain.",
        "vi": "Loạt phim hoạt hình Superman của Fleischer Studios, nay thuộc phạm vi công cộng."
      },
      "year": 1941,
      "endYear": 1943,
      "genres": ["Animation"],
      "countries": ["US"],
      "seasons": [
        {
          "number": 1,
          "episodes": [
            {
              "id": "fleischer-superman-s1e1",
              "number": 1,
              "name": "The Mechanical Monsters",
              "thumbnail": "https://archive.org/services/img/superman_the_mechanical_monsters",
              "releaseDate": "1941-11-28",
              "runtimeMinutes": 10,
              "url": "https://archive.org/download/superman_the_mechanical_monsters/superman_the_mechanical_monsters_512kb.mp4",
              "mimeType": "video/mp4"
            }
          ]
        }
      ]
    }
  ]
}

Chữ bằng tiếng Anh và tiếng Việt; appearance dùng màu nhấn hổ phách, nền chuyển màu tối và thẻ poster bo góc lớn.
Bố cục: một hero với hai banner làm tay (target mở phim lẻ hoặc phim bộ), Xem tiếp, hàng Phim lẻ xếp mới nhất trước, hàng Phim bộ, và lưới Hài lọc theo thể loại với thẻ ngang.
His Girl Friday có một luồng kèm tên, chất lượng và ngôn ngữ; Big Buck Bunny dùng cách viết tắt url; phim bộ có một mùa với một tập.

Một nguồn ghép từ các include

Tải composed-includes.tsiptv.json

{
  "$schema": "https://tsiptv-8bdd6.web.app/schema/tsiptv-source-v1.json",
  "format": "tsiptv-source",
  "version": 1,
  "id": "app.tsiptv.examples.composed",
  "meta": {
    "name": { "en": "Composed from includes", "vi": "Ghép từ nguồn bên ngoài" },
    "description": {
      "en": "This source contains no items of its own. It pulls an M3U playlist, an XMLTV guide, a Stremio addon and another TS IPTV Source, and places each one in its own section. Every include points at a TS IPTV example file with public test or public-domain streams.",
      "vi": "Nguồn này không tự chứa mục nào. Nó lấy một danh sách M3U, một lịch phát sóng XMLTV, một addon Stremio và một TS IPTV Source khác, rồi đặt mỗi nguồn vào một mục riêng. Mọi nguồn đều trỏ tới tệp ví dụ của TS IPTV, chỉ chứa luồng thử nghiệm công khai hoặc phim thuộc phạm vi công cộng."
    },
    "author": { "name": "TS IPTV examples" },
    "language": "en",
    "updatedAt": "2026-09-27T00:00:00Z"
  },
  "appearance": {
    "accent": "#4FC3F7",
    "background": { "color": "#06121C" },
    "card": { "style": "auto", "corner": "medium" }
  },
  "includes": [
    {
      "id": "live",
      "type": "m3u",
      "url": "https://tsiptv-8bdd6.web.app/examples/playlist.m3u",
      "name": { "en": "Example M3U playlist", "vi": "Danh sách M3U ví dụ" },
      "refreshHours": 24
    },
    {
      "id": "guide",
      "type": "xmltv",
      "url": "https://tsiptv-8bdd6.web.app/examples/guide.xml",
      "name": { "en": "Example XMLTV guide", "vi": "Lịch phát sóng XMLTV ví dụ" },
      "refreshHours": 12
    },
    {
      "id": "sampler",
      "type": "stremio",
      "url": "https://tsiptv-8bdd6.web.app/examples/stremio-sampler/manifest.json",
      "name": { "en": "Public Domain Sampler addon", "vi": "Addon Public Domain Sampler" }
    },
    {
      "id": "cinema",
      "type": "tsiptv-source",
      "url": "https://tsiptv-8bdd6.web.app/examples/vod-catalog.tsiptv.json",
      "refreshHours": 72
    }
  ],
  "layout": {
    "home": [
      {
        "type": "hero",
        "id": "hero",
        "query": { "from": "movies", "include": "cinema", "limit": 3 }
      },
      {
        "type": "row",
        "id": "on-air",
        "title": { "en": "On air", "vi": "Đang phát" },
        "subtitle": { "en": "From the M3U include, with the XMLTV guide", "vi": "Từ danh sách M3U, kèm lịch phát sóng XMLTV" },
        "query": { "from": "channels", "include": "live", "sort": "number" },
        "card": { "style": "list" }
      },
      {
        "type": "row",
        "id": "addon-movies",
        "title": { "en": "From the Stremio addon", "vi": "Từ addon Stremio" },
        "query": { "from": "catalog", "include": "sampler", "catalog": { "type": "movie", "id": "tspd-movie" } },
        "card": { "style": "poster" }
      },
      {
        "type": "row",
        "id": "cinema-series",
        "title": { "en": "Series", "vi": "Phim bộ" },
        "query": { "from": "series", "include": "cinema" }
      },
      {
        "type": "row",
        "id": "picked",
        "title": { "en": "Picked by hand", "vi": "Chọn tay" },
        "query": { "from": "movies", "ids": ["cinema:big-buck-bunny", "cinema:his-girl-friday"] },
        "card": { "style": "landscape" },
        "seeAll": false
      },
      {
        "type": "grid",
        "id": "all-channels",
        "title": { "en": "All channels", "vi": "Tất cả kênh" },
        "query": { "from": "channels", "sort": "number" },
        "groupChips": true
      }
    ]
  }
}

Không có mục riêng: một danh sách M3U (live), một lịch XMLTV (guide), addon mẫu (sampler) và nguồn vod-catalog ở trên (cinema).
Hero hiện phim từ cinema; “Đang phát” liệt kê các kênh M3U dạng danh sách kèm chương trình đang phát; một hàng hiện danh mục phim của addon; ids chọn hai phim bằng id có tiền tố (cinema:big-buck-bunny); lưới cuối hiện mọi kênh kèm chip nhóm.

Tự tạo nguồn của bạn, từng bước

Bắt đầu từ tệp tối giản. Tải minimal-live.tsiptv.json và mở bằng VS Code (dòng $schema cho bạn gợi ý tự động và gạch đỏ dưới lỗi). Đổi id thành tên miền đảo ngược của riêng bạn (com.example.mytv) và đổi meta.name.

Thêm các kênh. Mỗi kênh một đối tượng, có id, name, url, và tuỳ chọn number, logo, groups, epgId, headers:

{ "id": "news-hd", "name": "Example News HD", "number": 10, "groups": ["News"],
  "logo": "https://example.com/logos/news.png", "epgId": "ExampleNews.us",
  "url": "https://cdn.example.com/news/index.m3u8",
  "headers": { "User-Agent": "Mozilla/5.0", "Referer": "https://example.com/" } }

Thêm lịch phát sóng bằng "epg": ["https://example.com/guide.xml.gz"].

Thêm phim lẻ và một phim bộ. Phim lẻ cần id, name và url (hoặc streams); thêm poster, backdrop, year, genres và description để có trang chi tiết đẹp. Phim bộ cần seasons → episodes, mỗi tập có id riêng không trùng, number, name và url.

Thêm giao diện và bố cục. Chọn màu nhấn nổi bật trên nền tối, rồi liệt kê các mục:

"appearance": { "accent": "#FFB300", "card": { "style": "poster", "corner": "large" } },
"layout": { "home": [
  { "type": "hero", "query": { "from": "movies", "limit": 5 } },
  { "type": "row", "title": "News", "query": { "from": "channels", "groups": ["News"] }, "card": { "style": "logo" } },
  { "type": "row", "title": "New movies", "query": { "from": "movies", "sort": "yearDesc" } },
  { "type": "grid", "title": "All channels", "query": { "from": "channels", "sort": "number" }, "groupChips": true }
] }

Dịch. Thay một chuỗi thường bằng { "en": "…", "vi": "…" } ở bất cứ đâu bạn muốn thêm ngôn ngữ, và đặt meta.language là ngôn ngữ của các chuỗi thường.
Kiểm tra. Sửa mọi chỗ VS Code gạch dưới, hoặc dán tệp vào công cụ kiểm tra. Bảo đảm mọi id đều không trùng và không có :.
Đưa tệp lên mạng (phần tiếp theo), thêm vào TS IPTV, rồi đọc màn hình xem trước: các con số, danh sách máy chủ và các mục bị bỏ qua. Khi đăng thay đổi về sau, hãy giữ nguyên đường dẫn và id, và tăng revision.

Đã có sẵn danh sách M3U? Bạn không cần chuyển đổi: hãy thêm nó thành một include m3u rồi sắp xếp kênh của nó bằng truy vấn.

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

Mọi máy chủ HTTPS tĩnh trả về chính nội dung tệp đều dùng được: https://raw.githubusercontent.com/<user>/<repo>/<branch>/my.tsiptv.json, https://<user>.github.io/<repo>/my.tsiptv.json, https://www.example.com/my.tsiptv.json. Trang chia sẻ và đường dẫn blob/ của GitHub không dùng được; xem đưa tệp M3U lên mạng. Bạn cũng có thể không cần đưa lên mạng mà dùng Nhập từ tệp.
HTTPS được khuyến nghị; đường dẫn http vẫn dùng được nhưng không được mã hoá.
Loại nội dung: application/json (hoặc text/plain); dù sao TS IPTV cũng nhận dạng theo nội dung.
Nén: nên dùng Content-Encoding: gzip cho tệp lớn. Giới hạn 5 MiB tính sau khi giải nén.
Bộ nhớ đệm: TS IPTV làm mới tệp gốc như một danh sách phát (khi cũ hơn 24 giờ, hoặc khi bấm Làm mới) và làm mới từng include sau refreshHours của nó. Với chính tệp và với từng include, ứng dụng gửi If-None-Match / If-Modified-Since khi máy chủ của bạn đã trả về ETag hoặc Last-Modified; trả lời 304 Not Modified giúp tiết kiệm băng thông và tính là 0 trong hạn mức 50 MiB.
CORS không cần cho TS IPTV. Chỉ thêm Access-Control-Allow-Origin: * nếu muốn các công cụ web đọc được tệp.
Giữ đường dẫn cố định. Cùng id từ cùng đường dẫn là bản cập nhật; từ đường dẫn khác, TS IPTV sẽ hỏi có thay thế nguồn hiện có không.

Thêm vào TS IPTV

Mở Thêm nguồn IPTV, dán đường dẫn vào Liên kết nguồn rồi chọn Thêm IPTV, hoặc chọn Nhập từ tệp. TS IPTV nhận ra định dạng qua nội dung.
Hộp thoại xem trước “Thêm nguồn này?” mở ra (chưa lưu gì): logo, tên, tác giả, mô tả, số kênh, radio, phim lẻ và phim bộ, “Nguồn này kết nối tới các máy chủ sau” (máy chủ của tệp và của mọi include), “N mục sẽ bị bỏ qua” kèm Chi tiết (mở “Chi tiết nhập”) nếu có mục không hợp lệ, thông báo rằng nguồn do bên thứ ba tạo, và ô “Tôi đủ 18 tuổi trở lên” nếu nguồn được đánh dấu người lớn.
Chọn Nhập. TS IPTV tải các include (“Đang tải 2 trên 4…”). Nếu một include hoá ra có nội dung người lớn, ứng dụng hỏi lại (“Một phần nội dung của nguồn này đến từ nguồn hoặc addon có nội dung người lớn.” kèm “Tôi đủ 18 tuổi trở lên”); chọn Hủy thì không lưu gì. Sau đó ứng dụng lưu mọi thứ, báo ví dụ “Đã thêm nguồn: 3 kênh, 1 phim lẻ, 0 phim bộ” (kèm “Đã bỏ qua N mục” nếu có) rồi mở trang chủ của nguồn. Trên điện thoại, thẻ Trang chủ có hai phần Trang chủ (bố cục của bạn) và Kênh (danh sách kênh quen thuộc); trên TV, thanh bên bắt đầu bằng Trang chủ.
Tìm kiếm, Xem tiếp và kênh yêu thích hoạt động trong phạm vi nguồn. Giới thiệu nguồn (điện thoại: trong menu của trang chủ nguồn; TV: một mục trên thanh bên) hiện tác giả; nút Trang web, hỏi “Mở … trong trình duyệt?” (trên TV không có trình duyệt, đường dẫn được hiện dưới dạng chữ); trạng thái từng include (“Đã cập nhật”, “Không làm mới được — đang hiện bản từ …”, “Không tải được”, hoặc “Đang tạm giữ cho tới khi xác nhận 18+” kèm nút Xác nhận); lần làm mới gần nhất với “Số vấn đề ở lần làm mới gần nhất: N” và nút Chi tiết (“Các vấn đề tìm thấy”); cùng nút Làm mới và Gỡ nguồn.
Nếu làm mới chính tệp nguồn bị lỗi, phần giới thiệu thêm dòng “Lần thử gần nhất: …”; sau khi bạn tự bấm Làm mới, trang chủ còn báo “Không làm mới được nguồn này. Đang hiện bản đã lưu.”. TS IPTV sẽ thử lại theo lịch bình thường.

Nếu tệp có lỗi tài liệu, TS IPTV báo “Không thể thêm nguồn này” với thông báo trong bảng ở trên và nút Chi tiết cho biết mã và đường dẫn. Nếu mọi include đều lỗi và tệp không có mục riêng nào, ứng dụng báo “Không tải được nội dung nào của nguồn này. Hãy thử lại sau.”

Lỗi thường gặp

Lỗi	Biểu hiện	Cách sửa
Có cả `url` và `streams` trong một mục	Mục bị bỏ qua (`E_NO_STREAM`)	Chỉ dùng một: `url` cho một luồng, `streams` cho nhiều lựa chọn.
Có `:` trong id (`news:hd`)	Mục bị bỏ qua (`E_ITEM_ID`; với include là `E_INCLUDE`)	Dùng `-`, `_` hoặc `.`; dấu hai chấm dành cho mục được include.
Một id dùng hai lần (kể cả giữa kênh, phim lẻ, tập và include)	Mục thứ hai bị bỏ qua (`E_DUPLICATE_ID`)	Đặt id không trùng trong cả tệp.
Luồng `rtmp://`, `rtsp://` hay `udp://`	Luồng bị bỏ (`E_URL`); mục chỉ có luồng đó bị bỏ qua (`E_NO_STREAM`)	Ở đây chỉ cho phép http(s). Hãy đưa các kênh đó vào một danh sách M3U và thêm thành include `m3u`; khi đó phát được hay không tuỳ trình phát của từng nền tảng.
Hero có cả `items` và `query`	Dùng `items` (`W_FIELD`)	Chỉ giữ một.
`groupChips` trên lưới phim lẻ hoặc trên một hàng	Không có chip	Chip nhóm chỉ dùng cho lưới `channels` hoặc `radio`.
Màu tương phản thấp (nền sáng, màu nhấn tối)	Màu của bạn bị thay (`W_CONTRAST`)	Dùng nền tối và màu nhấn có độ tương phản ít nhất 3:1 với nền.
Truy vấn trỏ tới id include không tồn tại, hoặc tới include `xmltv`	Mục không hiện (`W_QUERY_REF`)	Dùng đúng `id` của include; lịch phát sóng không thể là một mục.
Gõ sai tên trường (`nmae`)	Ứng dụng bỏ qua trường đó; trường bắt buộc khi đó bị thiếu	Dùng dòng `$schema` hoặc công cụ kiểm tra; chúng báo trường không xác định.
Có chú thích hoặc dấu phẩy thừa	“Tệp này không phải JSON hợp lệ.”	Xoá chúng; dùng trường `x-` để ghi chú.
Ảnh `http://` trên máy chủ chuyển hướng hoặc chặn	Thiếu ảnh bìa	Dùng URL ảnh `https`.
Id của include bắt đầu bằng `epg-`	Include bị bỏ (`E_INCLUDE`)	Tiền tố này dành cho các đường dẫn `epg`.
URL của include `stremio` không có `/manifest.json`	Include bị bỏ (`E_INCLUDE`)	Dùng đường dẫn manifest của addon.
Có dấu cách trong `source` của xem lại (chế độ `default` hoặc `append`)	Mất xem lại, kênh chỉ phát trực tiếp (`W_FIELD`)	Mã hoá dấu cách thành `%20`.

TS IPTV hỗ trợ những gì

Tính năng	Android	iOS	Máy tính
Nhập bằng đường dẫn hoặc tệp, xem trước, bố cục, giao diện, tìm kiếm, Xem tiếp	Hỗ trợ	Chưa kiểm chứng	Hỗ trợ
Kênh, radio, phim lẻ, phim bộ; nhiều luồng mỗi mục (kênh: “Tuỳ chọn phát”; phim lẻ và tập phim: trang chi tiết)	Hỗ trợ	Chưa kiểm chứng	Hỗ trợ
Header	Mọi header	Chưa kiểm chứng	Chỉ User-Agent và Referer
Luồng DASH `.mpd` không có DRM	Hỗ trợ	Chưa kiểm chứng qua trình phát VLC tích hợp; chỉ gửi header User-Agent và Referer	Hỗ trợ
DRM (Widevine, PlayReady; ClearKey cho DASH)	Chỉ Android	Không hỗ trợ	Không hỗ trợ
Phụ đề (VTT, SRT), mặc định tắt	Hỗ trợ	Chưa có	Chưa kiểm chứng
Include: `m3u`, `xmltv`, `stremio`, `tsiptv-source`	Hỗ trợ Addon tương thích Stremio chỉ phát luồng `url`.
Xem lại (catch-up)	Được lưu, phát lại sẽ có sau
Banner mở trang web	Không thuộc định dạng

iOS: phần hỗ trợ TS IPTV Source chưa được build và kiểm tra trên iPhone và iPad, nên các ô đó ghi “Chưa kiểm chứng”. DRM không có trên iOS theo thiết kế. Luồng DASH không có DRM phát được trên iPhone và iPad qua trình phát VLC tích hợp, trình phát này chỉ gửi header User-Agent và Referer; DASH có DRM thì không hỗ trợ trên các thiết bị đó. Máy tính: các tính năng ghi “Hỗ trợ” đã được build, nhưng ứng dụng máy tính chưa được kiểm tra với TS IPTV Source; phụ đề trên máy tính “Chưa kiểm chứng”.

TS IPTV Source format

A TS IPTV Source is one JSON file that describes a complete, branded collection: who made it, its colours, its home screen layout, live TV and radio channels, movies, series with seasons and episodes, programme guides, and links to other playlists, guides and addons. It is open, documented on this page, and checked by a published JSON Schema.

TS IPTV includes no channels and no sources. A TS IPTV Source contains only the links its creator puts in it; TS IPTV does not list, host or recommend any. Every example on this page uses example.com placeholders, a public test stream, public-domain films from archive.org, or TS IPTV's own example files on tsiptv-8bdd6.web.app.

Files: JSON Schema (https://tsiptv-8bdd6.web.app/schema/tsiptv-source-v1.json, draft 2020-12) · examples minimal-live, vod-catalog, composed-includes · browser validator.

What it is

M3U describes a list of channels. A TS IPTV Source describes a whole collection, and how its home screen should look. Use it when you want movies and series with posters and episodes, your own sections and colours, several streams per item, or when you want to combine existing M3U playlists, XMLTV guides, Stremio-compatible addons and other sources into one.

The format follows five rules:

Data, never code. No scripts, expressions, HTML or Markdown. Every text is plain text; TS IPTV never runs anything from a source.
Links, not content. The file carries the links its creator supplies. The format, the schema and the app ship no content.
Easy by hand. The smallest valid file is ten lines. Shorthands cover the common cases (url instead of streams, a plain string instead of a translated object).
Forward compatible. Unknown fields are ignored and unknown values fall back in a defined way, so an older app keeps reading newer files. Only a breaking change raises version.
Same meaning as M3U. Headers, DRM and catch-up mean exactly what they mean in Kodi-style M3U, so a channel plays the same in both formats.

This page is the public reference of version 1. The JSON Schema is stricter than the app, so a file that passes it is almost always accepted. The exceptions are things the schema cannot see: a file larger than 5 MiB; format placed after the first 64 KiB; impossible calendar dates such as 2026-02-30 (TS IPTV warns and ignores the field); duplicate ids and references to missing items (checked by the app and by the validator); and includes that fail or form a cycle (E_INCLUDE, E_INCLUDE_CYCLE, and E_EMPTY if nothing else is left).

Quick start

The smallest useful file: one channel that really plays (the Mux public test stream, Big Buck Bunny © Blender Foundation, CC BY 3.0).

{
  "$schema": "https://tsiptv-8bdd6.web.app/schema/tsiptv-source-v1.json",
  "format": "tsiptv-source",
  "version": 1,
  "id": "com.example.my-channels",
  "meta": { "name": "My Channels" },
  "channels": [
    { "id": "test-hls", "name": "HLS Test Channel", "url": "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8" }
  ]
}

Save it as my-channels.tsiptv.json (UTF-8), put it on any HTTPS host, and add the link in TS IPTV. The $schema line makes editors such as VS Code check the file and suggest fields as you type.

The format, part by part

The file

Property	Rule
Encoding	UTF-8. A leading BOM is tolerated but should not be written.
Syntax	JSON: no comments, no trailing commas. The root is an object.
Detection	A file is a TS IPTV Source when its top-level `"format"` is `"tsiptv-source"`. The file name and the server's content type do not matter. TS IPTV looks for `format` in the first 64 KiB of the file, so put it near the top (right after `$schema`).
Extension	`.tsiptv.json` is suggested (for example `my-channels.tsiptv.json`).
Size	At most 5 MiB after decompression, for the file itself and for every included source.
Compression	HTTP `Content-Encoding: gzip`, or a gzip-compressed file, are both accepted.

Top level

Field	Required	Meaning
`$schema`	no	The schema URL, for editors. TS IPTV never fetches it.
`format`	yes	Exactly `"tsiptv-source"`.
`version`	yes	`1`. A higher number means “needs a newer TS IPTV”.
`id`	yes	Stable identifier of the source, an Id. Reverse-DNS is recommended (`com.example.news`). The same `id` from the same link is an update.
`revision`	no	Integer ≥ 0 that you increase when you publish a change (default 0).
`meta`	yes	Metadata.
`appearance`	no	Colours and card style.
`layout`	no	Home screen sections. Without it, a default layout is used.
`channels`	no	Live TV and radio, at most 10,000.
`movies`	no	At most 5,000.
`series`	no	At most 1,000 (and 20,000 episodes in total).
`epg`	no	XMLTV guide links, at most 10.
`includes`	no	Remote documents, at most 20.

A file must contain at least one non-empty channels, movies, series or includes.

General rules

x- members: any field whose name starts with x- is yours (notes, tool data). TS IPTV ignores it and the format will never define one. This does not apply to header names, language keys or DRM key ids, which are data.
null is the same as leaving the field out.
Unknown fields are ignored by the app, but the schema reports them so you catch typos.
Text is trimmed; a value that is empty after trimming is invalid. Lengths count characters (Unicode code points).
Control characters: the schema allows none in texts, except line breaks in long texts (descriptions). TS IPTV is lenient here: a line break or control character in a one-line text is replaced by a space and reported as a warning, not an error. URLs and catch-up sources must contain none; header values allow only tab.

`meta`

Field	Required	Meaning
`name`	yes	Text: the source's display name.
`description`	no	Long text.
`author`	no	`{ "name" (required, 1–100), "url"?, "email"? }`.
`logo`	no	Square image URL, 256×256 or larger.
`homepage`	no	Shown in “About this source”; TS IPTV asks before opening it.
`language`	no	Language of plain-string texts and the fallback language (default `en`).
`languages`	no	Languages of the content, for display (at most 20).
`updatedAt`	no	Date-time such as `2026-09-27T10:00:00Z`.
`adult`	no	`true` if the source contains adult content. Any value that is not `true` or `false` also counts as adult. TS IPTV then warns and asks “I am 18 or older” before importing.
`license`	no	Licence of the listing (not of the streams), free text or an SPDX id, up to 200 characters.

Texts and translations

Every visible text is either a plain string, in the language of meta.language, or an object that maps language tags to strings:

"name": "Movies"
"name": { "en": "Movies", "vi": "Phim lẻ", "zh-CN": "电影" }

Text (names, titles): 1–200 characters, one line. Long text (descriptions): 1–5,000 characters; line breaks allowed (LF, CR or CRLF).
Language tags: en, vi, zh-CN, pt-BR (pattern ^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$); at most 30 per object.
TS IPTV picks, in order: the app's language exactly (zh-CN), then its main language (zh, then any zh-…), then meta.language, then en, then the first entry.
Texts are shown as written: no HTML, no Markdown.

Ids, URLs, headers, colours

Type	Rule
Id	`^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`: letters, digits, `.`, `_`, `-`, case-sensitive, no `:` (the colon is reserved for included items, `includeId:itemId`). Every id of a channel, movie, series, episode and include must be unique in the file. The first one wins, in this order: channels, movies, series (each followed by its episodes), includes; an item that is dropped does not claim its id.
URL	Absolute `http://` or `https://`, at most 2,048 characters, no spaces or control characters. Every URL in the file (streams, images, includes, licence servers) follows this rule; `rtmp:`, `udp:`, `file:`, `data:` and all other schemes are invalid. Prefer `https`.
Headers	An object of header name → value, for example `{ "User-Agent": "Mozilla/5.0", "Referer": "https://example.com/" }`. At most 20. Values are sent exactly as written (not URL-decoded), up to 4,096 characters. `Host`, `Content-Length`, `Connection` and `Transfer-Encoding` are forbidden. Headers go with every request of the stream (manifests, segments, keys), not with the DRM licence request and not with subtitle files.
Colour	`#RRGGBB`.

`appearance`

"appearance": {
  "accent": "#FFB300",
  "accentSecondary": "#FF7043",
  "background": { "gradient": ["#101014", "#1C1C24"], "image": "https://example.com/bg.jpg", "imageDim": 0.7 },
  "card": { "style": "poster", "corner": "medium", "showTitles": true }
}

Field	Default	Meaning
`accent`	app accent	Focus rings, selected chips, buttons, progress bars.
`accentSecondary`	app secondary	Gradients on buttons and badges.
`background.color`	app background	Solid background.
`background.gradient`	none	2–3 colours, top to bottom; replaces `color`.
`background.image`	none	Image behind the home, under a dark scrim.
`background.imageDim`	`0.6`	Scrim opacity, 0.3–1.0.
`card`	`{ "style": "auto" }`	Default card style for every section.

Card style: style is auto, poster (2:3), landscape (16:9), square, logo (channel logo tile) or list (one line: logo, name, programme now on); auto means poster for movies and series, logo for TV, square for radio, landscape for episodes, and the item's own posterShape for items from a Stremio-compatible catalogue. corner is none, small, medium or large. showTitles hides names on cards when false (channels and lists always show them).

Legibility. TS IPTV keeps its own light text colour. If your background colour (or a gradient stop) gives a contrast below 4.5:1 with that text, TS IPTV uses its own background (a background image is kept). If the accent has a contrast below 3:1 with the background, both accents are replaced by the app's. Appearance applies to the source's home and detail pages only; the player, dialogs and settings keep the app theme.

`layout`: the home screen

layout.home is a list of 1–30 sections, drawn top to bottom.

"layout": {
  "home": [
    { "type": "hero", "query": { "from": "movies", "limit": 5 } },
    { "type": "row", "title": { "en": "Continue watching", "vi": "Xem tiếp" }, "query": { "from": "continueWatching" } },
    { "type": "row", "title": "News", "query": { "from": "channels", "groups": ["News"] }, "card": { "style": "logo" } },
    { "type": "grid", "title": "All channels", "query": { "from": "channels", "sort": "number" }, "groupChips": true }
  ]
}

Section field	Meaning
`type` (required)	`hero` (banner carousel, 1–10 items), `row` (one horizontal line, default 20 items, at most 100) or `grid` (all matching items, loaded in pages).
`id`	Lets TS IPTV remember the scroll and focus position of the section.
`title`, `subtitle`	Heading and smaller line (not shown on a hero).
`query`	What the section shows (required, except a hero with `items`).
`items`	Hero only: hand-made banners `{ "image" (16:9, required), "title", "subtitle", "target", "autoplay" }`. A hero has `query` or `items`, not both.
`card`	Card style for this section (ignored by a hero).
`seeAll`	Row only (default `true`): a “See all” action opening the whole query as a grid.
`groupChips`	Grid of `channels` or `radio` only: group filter chips above the grid.

A hero with a query uses each item's backdrop, else poster, else logo, and skips items without an image. A banner's target is the id of a channel, movie, series or episode (included items as includeId:itemId); without a target the banner is decorative. autoplay: true starts playback of the target (channels, movies and episodes only): a channel plays at once; a movie opens its detail page and an episode opens its series' detail page, and playback starts straight away, so Back returns to that page. Banners cannot open websites. A section that finds no items is not drawn.

Queries

Query field	Meaning
`from` (required)	`channels`, `radio`, `movies`, `series`, `catalog` (a catalogue of a Stremio-compatible addon include), `continueWatching`, `favorites`.
`include`	Only items from the include with this id. Required for `catalog`, where it names the `stremio` include.
`catalog`	For `from: "catalog"`: `{ "type", "id", "genre"? }` of a catalogue declared in that addon's manifest.
`ids`	Only these items, in this order (1–500; included items as `includeId:itemId`). Unknown ids are skipped.
`groups`, `genres`, `tags`	Items whose groups (channels), genres (movies, series) or tags contain any of these; case-insensitive.
`sort`	`source` (file order; included items after your own), `name`, `number`, `year`, `yearDesc`, `recent` (Continue watching).
`limit`	1–500 items.

Filters combine with AND between fields and OR inside a field. A filter that does not apply (for example genres on channels) is ignored. For catalog, only catalog.genre filters and the addon's own order is kept. continueWatching (partly watched movies and episodes, recently played channels) and favorites (favourite channels) come from the viewer's own history, never from the file; they stay hidden until they have items.

Default layout

Without layout, TS IPTV shows: Continue watching; a hero of movies (only if a movie has a backdrop); Movies; Series; Radio; and a grid of Channels sorted by number with group chips. Empty sections are left out.

Channels, movies and series

Playable fields, shared by channels, movies and episodes. An item has exactly one of url and streams:

Field	Meaning
`url`	One stream. Short for `"streams": [{ "url": … }]`.
`streams`	1–10 alternatives, best first. For a channel, TS IPTV plays the first one the device supports, and the viewer can pick another under “Stream” in the player's “Playback options” (phone: the player's settings button; TV: ▶, or the MENU, captions or Settings key). For a movie or episode, the detail page lists its streams and the viewer picks one there; its “Playback options” offer subtitles only. On TV the options open only when there is something to choose.
`headers`	Headers for every stream of the item; a stream's own headers win, name by name.
`mimeType`	Stream type hint for every stream.
`drm`	DRM for every stream; a stream's own `drm` replaces it.

Channel

{
  "id": "example-news",
  "name": { "en": "Example News", "vi": "Tin tức Ví dụ" },
  "number": 101,
  "logo": "https://example.com/logos/news.png",
  "groups": ["News", "HD"],
  "epgId": "ExampleNews.us",
  "url": "https://cdn.example.com/news/index.m3u8",
  "headers": { "Referer": "https://example.com/" },
  "catchup": { "mode": "shift", "days": 3 }
}

Field	Meaning
`id`, `name` (required)	Id and Text.
`type`	`tv` (default) or `radio`.
`number`	0–99,999, shown on cards and used by `sort: "number"`.
`logo`	Logo URL (transparent PNG recommended).
`groups`	0–10 group names (1–100 characters). Matched case-insensitively and shown as written; they are not translated.
`epgId`	The XMLTV `<channel id>` of this channel. Without it, the guide is matched by name (case, accents and spaces are ignored).
`epgShiftHours`	−12 … +14 hours added to this channel's guide times.
`description`, `tags`	Long text; 0–20 tags of 1–50 characters.
`catchup`	Catch-up.

Movie

id and name are required, plus the playable fields. Optional: originalName, poster (2:3), backdrop (16:9, used by heroes and detail pages), logo (title logo), description, year (1870–2100), releaseDate (YYYY-MM-DD), runtimeMinutes (1–1,440), genres (0–10), cast (0–50), directors (0–20), countries (ISO codes such as US), languages, ageRating (as printed, for example PG-13), tags, subtitles (0–30).

Series, seasons, episodes

{
  "id": "fleischer-superman",
  "name": "Fleischer Superman",
  "year": 1941,
  "endYear": 1943,
  "seasons": [
    {
      "number": 1,
      "episodes": [
        { "id": "fleischer-superman-s1e1", "number": 1, "name": "The Mechanical Monsters",
          "url": "https://archive.org/download/superman_the_mechanical_monsters/superman_the_mechanical_monsters_512kb.mp4" }
      ]
    }
  ]
}

A series has id and name (required), originalName, poster, backdrop, logo, description, year (first year), endYear (last year, not before year; absent = ongoing), genres, cast, countries, languages, ageRating, tags and seasons (1–100). It has no playable fields, and no directors, releaseDate, runtimeMinutes or subtitles.
A season has number (0–999, unique in the series; 0 = Specials, listed last), optional name, poster, description, and episodes (1–500).
An episode has id (unique in the whole file; used for watch progress), number (unique in the season), name, the playable fields, and optional description, thumbnail (16:9), releaseDate (a future date means “upcoming”, listed but not playable), runtimeMinutes, subtitles.

Stream

Field	Meaning
`url` (required)	HLS `.m3u8`, DASH `.mpd`, MP4, WebM, MKV, MPEG-TS, or audio (AAC, MP3, Opus).
`name`	Label in the stream picker, such as `1080p` or `Backup`.
`headers`, `drm`	As above; merged over, or replacing, the item's.
`mimeType`	When the URL has no telling extension: `application/x-mpegURL` or `application/vnd.apple.mpegurl` (HLS), `application/dash+xml`, `video/mp4`, `video/mp2t`, `video/webm`, `video/x-matroska`, `audio/aac`, `audio/mpeg`, `audio/ogg`.
`quality`, `language`	Badges: `HD`, `720p`; audio language tag.

DRM

"drm": { "system": "widevine", "licenseUrl": "https://license.example.com/widevine", "licenseHeaders": { "X-Example": "1" } }
"drm": { "system": "clearkey", "keys": { "000102030405060708090a0b0c0d0e0f": "00112233445566778899aabbccddeeff" } }

system: widevine, playready (licence URL required) or clearkey (a licence URL, or keys: 1–20 pairs of 32-hex key id → 32-hex key).
TS IPTV sends the raw challenge to licenseUrl and expects the raw licence back; licenseHeaders go with that request only. Wrapped or JSON licence protocols are not part of version 1.
Widevine plays on Android; PlayReady on Android devices that support it (a PlayReady CDM, mostly TVs); ClearKey on Android for DASH only. On iPhone, iPad and desktop, a channel skips streams with DRM and plays its next stream without DRM; if there is none, TS IPTV shows “This channel is DRM-protected. DRM is not supported on this device.” For a movie or episode, a stream with DRM picked on the detail page shows that same message, so give such items a stream without DRM as well.
Publish only keys and licence servers you are entitled to share.

Catch-up

catchup uses the same modes and placeholders as Kodi M3U catch-up: { "mode", "source"?, "days"? (1–60, default 7), "correctionHours"? (−24 … +24) }. mode is default (source is a full URL template starting with http:// or https://), append (source is appended to the live URL, for example ?utc={utc}&lutc={lutc}), shift, flussonic, flussonic-ts or xc. For default and append, source is required and never trimmed: any space or control character makes it invalid (W_FIELD), the catch-up is dropped and the channel plays live only. The other modes build the URL from the live link and ignore source. TS IPTV stores catch-up information; playback of past programmes comes later.

Subtitles

{ "url" (WebVTT or SubRip), "language" (required), "label"?, "format"? ("vtt" or "srt") }. Subtitles start Off: the viewer turns one on under “Subtitles” in the player's “Playback options” (see streams). On Android, a subtitle without label shows the language name, and subtitle files are requested without the stream's headers, so host them where no token or Referer is needed. On desktop, subtitles load, but how they are labelled and whether headers are sent is not yet verified. iPhone and iPad do not show subtitles yet.

`epg` and `includes`

epg is a list of XMLTV guide links, each a URL string or { "url", "refreshHours"? } (1–720, default 24). Guides may be gzip-compressed. Programmes are matched to channels by epgId; a channel without epgId is matched by name (case, accents and spaces are ignored).

"includes": [
  { "id": "news", "type": "m3u", "url": "https://example.com/playlists/news.m3u", "name": "Partner news" },
  { "id": "guide", "type": "xmltv", "url": "https://example.com/epg/guide.xml.gz", "refreshHours": 12 },
  { "id": "sampler", "type": "stremio", "url": "https://addon.example.com/manifest.json" },
  { "id": "archive", "type": "tsiptv-source", "url": "https://example.com/archive.tsiptv.json" }
]

Include field	Meaning
`id` (required)	Unique Id; prefixes the included items (`news:ExampleTV.us`). Must not start with `epg-` (reserved for `epg` links).
`type` (required)	`m3u`, `xmltv`, `stremio` or `tsiptv-source`.
`url` (required)	For `stremio`, the manifest link ending in `/manifest.json`.
`name`	Shown in “About this source” and in error messages.
`refreshHours`	Minimum hours between automatic fetches (1–720, default 24).
`headers`	Sent when fetching an `m3u`, `xmltv` or `tsiptv-source` document; not sent to addons or streams.

Type	What it adds	Item ids
`m3u`	Channels (radio entries go to radio), read with TS IPTV's M3U reader including headers and DRM; its `x-tvg-url` guides join the guide set.	`includeId:` + the channel's `tvg-id` (or name), characters outside the Id set replaced by `_`: `ExampleTV.us@HD` → `live:ExampleTV.us_HD`.
`xmltv`	Guide data only; cannot be used in a query.	—
`stremio`	Nothing in the pools; its catalogues are shown with `from: "catalog"`. Only `url` streams play (see Stremio-compatible addons).	The addon's own ids.
`tsiptv-source`	Its channels, radio, movies, series and guide links. Its `meta`, `appearance` and `layout` are ignored.	`includeId:` + its item id (chains: `archive:partner:item`).

Depth and cycles: the root is depth 1; included sources may include others down to depth 3. An include of any type below depth 3, or one whose URL is already on the path, is refused (E_INCLUDE_CYCLE).
Totals per refresh: at most 20 includes in the whole tree (guide links not counted), 50 MiB fetched (all documents including the root; a 304 counts 0), and 20,000 channels, 5,000 movies and 1,000 series after merging. An M3U include may be up to 20 MiB, an XMLTV include up to 100 MiB, a TS IPTV Source include up to 5 MiB.
Failures: a failing include never fails your source. TS IPTV keeps the last good copy; without one, sections using that include are hidden.
Adult content: if any included source has meta.adult: true (or any value that is not a boolean), or any addon's manifest declares adult content, TS IPTV asks for the 18+ confirmation for the whole source before storing anything. If a later refresh makes a source you have not confirmed adult, the new content of the include that caused it is held back (the previous copy stays) until you confirm in “About this source”.

Limits

What	Limit
File size	5 MiB per document after decompression; 50 MiB per refresh for the whole tree
Items	10,000 channels, 5,000 movies, 1,000 series, 20,000 episodes per document; 20,000 / 5,000 / 1,000 after merging
Series	100 seasons, 500 episodes per season
Streams, subtitles	10 streams per item; 30 subtitles
Headers	20 per map (also after merging item and stream headers); values up to 4,096 characters
Layout	30 sections; 10 hero items; query `limit` and `ids` up to 500; rows show at most 100
Includes	20 per document and in the tree; depth 3; 10 `epg` links per document
Texts	200 characters (Text), 5,000 (long text), 30 languages per text; URLs 2,048

Security and privacy

TS IPTV never runs, evaluates or renders as markup anything from a source.
Only http and https links are ever opened.
A source cannot open websites, install anything or download files. Importing fetches only the file and its includes; images load when shown; streams load only when the viewer presses play.
URLs and headers may carry tokens. TS IPTV does not send them to analytics, crash reports or its own servers, and does not log them in release builds.
Home servers on your local network are allowed.
Adult content always needs the 18+ confirmation (root or includes).

Versions and unknown values

New optional fields and new values are added to version 1 over time, at the same schema URL. When TS IPTV meets a value it does not know yet, it falls back instead of failing:

Unknown value in	What happens
section `type`, query `from`	The section is skipped.
query `sort`	`source` order.
card `style` / `corner`	`auto` / `medium`.
channel `type`	Treated as `tv`.
include `type`	The include is skipped (`E_INCLUDE`).
stream `mimeType`	The hint is ignored.
`drm.system`	The stream is never played without DRM; it is unplayable on that device.
`catchup.mode`	No catch-up; live playback works.

A change that would alter the meaning of existing files will be version 2, with a new schema (tsiptv-source-v2.json); the version 1 schema stays published.

Validation: errors and warnings

TS IPTV checks a source on three levels. Document errors reject the file. Item errors drop the item or field and import the rest. Warnings change nothing but are listed. Every problem is listed as path — CODE: explanation, for example channels[3].url — E_URL: … (the explanation is a short sentence in the app's language).

Code	Level	When	What the viewer sees
`E_NOT_JSON`	document	Not JSON, or the root is not an object	“This file is not valid JSON.”
`E_NOT_SOURCE`	document	`format` missing or wrong	“This is not a TS IPTV Source file.”
`E_VERSION`	document	`version` missing, not an integer ≥ 1, or newer than the app	“This source needs a newer version of TS IPTV.”
`E_TOO_LARGE`	document	Over 5 MiB	“This source is larger than 5 MB.”
`E_ID`, `E_META`	document	`id`, `meta` or `meta.name` missing or invalid	“This source is missing its id or name.”
`E_EMPTY`	document	No items and no includes (or all were dropped)	“This source has nothing that TS IPTV can show.”
`E_ITEM_ID`	item	Missing or invalid id; season or episode number missing or out of range; an entry that is not an object	Before import: “N items will be skipped” with Details. After import: the success message, for example “Source added: 3 channels, 1 movie, 0 series”, followed by “N items were skipped”. On refresh: counted in “About this source” (“Problems found in the last refresh: N”) and listed under “Problems found”.
`E_DUPLICATE_ID`	item	Id (or season/episode number) already used
`E_ITEM_NAME`	item	Missing or invalid `name`
`E_NO_STREAM`	item	No `url`/`streams`, both, or no valid stream left; a series or season with nothing valid inside
`E_INCLUDE`	include	Invalid include, a rejected included source, or a failed fetch (the last good copy is kept)
`E_INCLUDE_CYCLE`	include	A cycle, or deeper than 3
`E_URL`	field / item	Invalid URL (the stream, image or banner is dropped)	Listed under Details; not counted in “N items will be skipped”. The item stays, unless it has nothing playable left (then `E_NO_STREAM`).
`E_HEADER_FORBIDDEN`	field	Forbidden or invalid header name; only that header is dropped
`E_DRM`	stream	Invalid DRM (missing licence URL, bad key); the stream is dropped
`W_UNKNOWN_TYPE`	warning	An unknown value was replaced by its fallback	Listed under Details; nothing is dropped except where stated.
`W_QUERY_REF`	warning	A query names an unknown include or an `xmltv` include, a `catalog` query names an include that is not `stremio`, or the catalogue is not declared by the addon; the section is skipped
`W_LIMIT`	warning	A count limit was reached; extra items were dropped
`W_CONTRAST`	warning	A colour was replaced for legibility
`W_TEXT`	warning	A text was too long (cut); a line break or control character in a one-line text was replaced by a space; a language key was invalid, or there were more than 30 languages (those entries are ignored)
`W_FIELD`	warning	An optional field had the wrong type or range, an invalid header value, an invalid catch-up source, a broken section, or a tolerated misuse; the field is dropped

The browser validator runs the JSON Schema and the reference checks on your file before you publish it.

Complete examples

Minimal live list

One channel that really plays, one placeholder channel with headers and a guide id, and one placeholder radio station.

Download minimal-live.tsiptv.json

{
  "$schema": "https://tsiptv-8bdd6.web.app/schema/tsiptv-source-v1.json",
  "format": "tsiptv-source",
  "version": 1,
  "id": "app.tsiptv.examples.minimal-live",
  "meta": {
    "name": "Minimal live list",
    "description": "The smallest useful TS IPTV Source: one public test stream that really plays, one placeholder channel that shows how to send HTTP headers, and one placeholder radio station. Replace the example.com links with your own streams.",
    "language": "en",
    "updatedAt": "2026-09-27T00:00:00Z"
  },
  "channels": [
    {
      "id": "hls-test",
      "name": "HLS Test Channel",
      "number": 1,
      "groups": ["Test"],
      "description": "Mux public HLS test stream. Video: Big Buck Bunny, (c) Blender Foundation, CC BY 3.0.",
      "url": "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
    },
    {
      "id": "example-news",
      "name": "Example News (placeholder)",
      "number": 2,
      "groups": ["News"],
      "logo": "https://example.com/logos/news.png",
      "epgId": "ExampleNews.us",
      "url": "https://cdn.example.com/news/index.m3u8",
      "headers": {
        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
        "Referer": "https://example.com/"
      }
    },
    {
      "id": "example-radio",
      "type": "radio",
      "name": "Example Radio (placeholder)",
      "groups": ["Radio"],
      "url": "https://radio.example.com/stream.aac",
      "mimeType": "audio/aac"
    }
  ]
}

No layout, so TS IPTV uses the default: a Radio row and a Channels grid with group chips.

Movies and a series, with appearance and layout

Download vod-catalog.tsiptv.json

{
  "$schema": "https://tsiptv-8bdd6.web.app/schema/tsiptv-source-v1.json",
  "format": "tsiptv-source",
  "version": 1,
  "id": "app.tsiptv.examples.vod-catalog",
  "revision": 1,
  "meta": {
    "name": { "en": "Public Domain Cinema", "vi": "Rạp phim Phạm vi công cộng" },
    "description": {
      "en": "A small movie and series catalog built only from public-domain films on archive.org and a public test stream. It shows a custom appearance and home layout.",
      "vi": "Danh mục phim và phim bộ nhỏ, chỉ gồm phim thuộc phạm vi công cộng trên archive.org và một luồng thử nghiệm công khai. Tệp này minh hoạ giao diện và bố cục trang chủ tuỳ chỉnh."
    },
    "author": { "name": "TS IPTV examples", "url": "https://tsiptv-8bdd6.web.app/guides/tsiptv-source/" },
    "homepage": "https://tsiptv-8bdd6.web.app/guides/tsiptv-source/",
    "language": "en",
    "languages": ["en"],
    "updatedAt": "2026-09-27T00:00:00Z",
    "license": "Listing: CC0-1.0. Films: public domain (see each item)."
  },
  "appearance": {
    "accent": "#FFB300",
    "accentSecondary": "#FF7043",
    "background": { "gradient": ["#101014", "#1C1C24"] },
    "card": { "style": "poster", "corner": "large", "showTitles": true }
  },
  "layout": {
    "home": [
      {
        "type": "hero",
        "id": "featured",
        "items": [
          {
            "image": "https://archive.org/services/img/his_girl_friday",
            "title": "His Girl Friday",
            "subtitle": { "en": "Screwball comedy, 1940", "vi": "Hài kịch, 1940" },
            "target": "his-girl-friday"
          },
          {
            "image": "https://archive.org/services/img/superman_the_mechanical_monsters",
            "title": { "en": "Fleischer Superman", "vi": "Superman của Fleischer" },
            "subtitle": { "en": "Animated shorts, 1941–1943", "vi": "Phim hoạt hình ngắn, 1941–1943" },
            "target": "fleischer-superman"
          }
        ]
      },
      {
        "type": "row",
        "id": "continue",
        "title": { "en": "Continue watching", "vi": "Xem tiếp" },
        "query": { "from": "continueWatching" },
        "card": { "style": "landscape" }
      },
      {
        "type": "row",
        "id": "movies",
        "title": { "en": "Movies", "vi": "Phim lẻ" },
        "query": { "from": "movies", "sort": "yearDesc", "limit": 20 }
      },
      {
        "type": "row",
        "id": "series",
        "title": { "en": "Series", "vi": "Phim bộ" },
        "query": { "from": "series" }
      },
      {
        "type": "grid",
        "id": "comedy",
        "title": { "en": "Comedy", "vi": "Hài" },
        "query": { "from": "movies", "genres": ["Comedy"], "sort": "name" },
        "card": { "style": "landscape", "corner": "small" }
      }
    ]
  },
  "movies": [
    {
      "id": "his-girl-friday",
      "name": "His Girl Friday",
      "poster": "https://archive.org/services/img/his_girl_friday",
      "backdrop": "https://archive.org/services/img/his_girl_friday",
      "description": {
        "en": "Howard Hawks' screwball comedy. Public domain (archive.org item his_girl_friday).",
        "vi": "Phim hài của Howard Hawks. Thuộc phạm vi công cộng (mục his_girl_friday trên archive.org)."
      },
      "year": 1940,
      "releaseDate": "1940-01-18",
      "runtimeMinutes": 92,
      "genres": ["Comedy"],
      "directors": ["Howard Hawks"],
      "countries": ["US"],
      "languages": ["en"],
      "streams": [
        {
          "name": { "en": "archive.org, MP4 512 kb/s", "vi": "archive.org, MP4 512 kb/s" },
          "url": "https://archive.org/download/his_girl_friday/his_girl_friday_512kb.mp4",
          "mimeType": "video/mp4",
          "quality": "SD",
          "language": "en"
        }
      ]
    },
    {
      "id": "big-buck-bunny",
      "name": "Big Buck Bunny",
      "description": {
        "en": "Open movie by the Blender Foundation, CC BY 3.0, streamed from the Mux public HLS test stream.",
        "vi": "Phim mở của Blender Foundation, giấy phép CC BY 3.0, phát từ luồng thử nghiệm HLS công khai của Mux."
      },
      "year": 2008,
      "runtimeMinutes": 10,
      "genres": ["Animation", "Comedy"],
      "url": "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8",
      "mimeType": "application/x-mpegURL"
    }
  ],
  "series": [
    {
      "id": "fleischer-superman",
      "name": { "en": "Fleischer Superman", "vi": "Superman của Fleischer" },
      "poster": "https://archive.org/services/img/superman_the_mechanical_monsters",
      "backdrop": "https://archive.org/services/img/superman_the_mechanical_monsters",
      "description": {
        "en": "Fleischer Studios' Superman cartoons, now in the public domain.",
        "vi": "Loạt phim hoạt hình Superman của Fleischer Studios, nay thuộc phạm vi công cộng."
      },
      "year": 1941,
      "endYear": 1943,
      "genres": ["Animation"],
      "countries": ["US"],
      "seasons": [
        {
          "number": 1,
          "episodes": [
            {
              "id": "fleischer-superman-s1e1",
              "number": 1,
              "name": "The Mechanical Monsters",
              "thumbnail": "https://archive.org/services/img/superman_the_mechanical_monsters",
              "releaseDate": "1941-11-28",
              "runtimeMinutes": 10,
              "url": "https://archive.org/download/superman_the_mechanical_monsters/superman_the_mechanical_monsters_512kb.mp4",
              "mimeType": "video/mp4"
            }
          ]
        }
      ]
    }
  ]
}

Texts in English and Vietnamese; the appearance uses an amber accent, a dark gradient and large-cornered posters.
The layout: a hero with two hand-made banners (target opens the film or the series), Continue watching, a Movies row sorted newest first, a Series row, and a Comedy grid filtered by genre with landscape cards.
His Girl Friday has one stream with a name, quality and language; Big Buck Bunny uses the url shorthand; the series has one season with one episode.

A source built from includes

Download composed-includes.tsiptv.json

{
  "$schema": "https://tsiptv-8bdd6.web.app/schema/tsiptv-source-v1.json",
  "format": "tsiptv-source",
  "version": 1,
  "id": "app.tsiptv.examples.composed",
  "meta": {
    "name": { "en": "Composed from includes", "vi": "Ghép từ nguồn bên ngoài" },
    "description": {
      "en": "This source contains no items of its own. It pulls an M3U playlist, an XMLTV guide, a Stremio addon and another TS IPTV Source, and places each one in its own section. Every include points at a TS IPTV example file with public test or public-domain streams.",
      "vi": "Nguồn này không tự chứa mục nào. Nó lấy một danh sách M3U, một lịch phát sóng XMLTV, một addon Stremio và một TS IPTV Source khác, rồi đặt mỗi nguồn vào một mục riêng. Mọi nguồn đều trỏ tới tệp ví dụ của TS IPTV, chỉ chứa luồng thử nghiệm công khai hoặc phim thuộc phạm vi công cộng."
    },
    "author": { "name": "TS IPTV examples" },
    "language": "en",
    "updatedAt": "2026-09-27T00:00:00Z"
  },
  "appearance": {
    "accent": "#4FC3F7",
    "background": { "color": "#06121C" },
    "card": { "style": "auto", "corner": "medium" }
  },
  "includes": [
    {
      "id": "live",
      "type": "m3u",
      "url": "https://tsiptv-8bdd6.web.app/examples/playlist.m3u",
      "name": { "en": "Example M3U playlist", "vi": "Danh sách M3U ví dụ" },
      "refreshHours": 24
    },
    {
      "id": "guide",
      "type": "xmltv",
      "url": "https://tsiptv-8bdd6.web.app/examples/guide.xml",
      "name": { "en": "Example XMLTV guide", "vi": "Lịch phát sóng XMLTV ví dụ" },
      "refreshHours": 12
    },
    {
      "id": "sampler",
      "type": "stremio",
      "url": "https://tsiptv-8bdd6.web.app/examples/stremio-sampler/manifest.json",
      "name": { "en": "Public Domain Sampler addon", "vi": "Addon Public Domain Sampler" }
    },
    {
      "id": "cinema",
      "type": "tsiptv-source",
      "url": "https://tsiptv-8bdd6.web.app/examples/vod-catalog.tsiptv.json",
      "refreshHours": 72
    }
  ],
  "layout": {
    "home": [
      {
        "type": "hero",
        "id": "hero",
        "query": { "from": "movies", "include": "cinema", "limit": 3 }
      },
      {
        "type": "row",
        "id": "on-air",
        "title": { "en": "On air", "vi": "Đang phát" },
        "subtitle": { "en": "From the M3U include, with the XMLTV guide", "vi": "Từ danh sách M3U, kèm lịch phát sóng XMLTV" },
        "query": { "from": "channels", "include": "live", "sort": "number" },
        "card": { "style": "list" }
      },
      {
        "type": "row",
        "id": "addon-movies",
        "title": { "en": "From the Stremio addon", "vi": "Từ addon Stremio" },
        "query": { "from": "catalog", "include": "sampler", "catalog": { "type": "movie", "id": "tspd-movie" } },
        "card": { "style": "poster" }
      },
      {
        "type": "row",
        "id": "cinema-series",
        "title": { "en": "Series", "vi": "Phim bộ" },
        "query": { "from": "series", "include": "cinema" }
      },
      {
        "type": "row",
        "id": "picked",
        "title": { "en": "Picked by hand", "vi": "Chọn tay" },
        "query": { "from": "movies", "ids": ["cinema:big-buck-bunny", "cinema:his-girl-friday"] },
        "card": { "style": "landscape" },
        "seeAll": false
      },
      {
        "type": "grid",
        "id": "all-channels",
        "title": { "en": "All channels", "vi": "Tất cả kênh" },
        "query": { "from": "channels", "sort": "number" },
        "groupChips": true
      }
    ]
  }
}

No items of its own: an M3U playlist (live), an XMLTV guide (guide), the sample addon (sampler) and the vod-catalog source above (cinema).
The hero shows movies from cinema; “On air” lists the M3U channels as a list with the programme now on; a row shows the addon's movie catalogue; ids picks two films by their namespaced ids (cinema:big-buck-bunny); the last grid shows every channel with group chips.

Create your own, step by step

Start from the minimal file. Download minimal-live.tsiptv.json and open it in VS Code (the $schema line gives you autocompletion and red underlines for mistakes). Change id to a reverse-DNS name of your own (com.example.mytv) and meta.name.

Add your channels. One object each, with id, name, url, and optionally number, logo, groups, epgId and headers:

{ "id": "news-hd", "name": "Example News HD", "number": 10, "groups": ["News"],
  "logo": "https://example.com/logos/news.png", "epgId": "ExampleNews.us",
  "url": "https://cdn.example.com/news/index.m3u8",
  "headers": { "User-Agent": "Mozilla/5.0", "Referer": "https://example.com/" } }

Add the guide with "epg": ["https://example.com/guide.xml.gz"].

Add movies and a series. Movies need id, name and url (or streams); add poster, backdrop, year, genres and description for a good detail page. A series needs seasons → episodes, each episode with its own unique id, a number, a name and a url.

Add appearance and a layout. Pick an accent that stands out on a dark background, then list your sections:

"appearance": { "accent": "#FFB300", "card": { "style": "poster", "corner": "large" } },
"layout": { "home": [
  { "type": "hero", "query": { "from": "movies", "limit": 5 } },
  { "type": "row", "title": "News", "query": { "from": "channels", "groups": ["News"] }, "card": { "style": "logo" } },
  { "type": "row", "title": "New movies", "query": { "from": "movies", "sort": "yearDesc" } },
  { "type": "grid", "title": "All channels", "query": { "from": "channels", "sort": "number" }, "groupChips": true }
] }

Translate. Replace a plain string with { "en": "…", "vi": "…" } wherever you want another language, and set meta.language to the language of your plain strings.
Validate. Fix everything VS Code underlines, or paste the file into the validator. Check that every id is unique and has no :.
Host it (next section), add it in TS IPTV, and read the preview: the counts, the list of servers, and any skipped items. When you publish a change later, keep the same link and id, and increase revision.

Already have an M3U playlist? You do not need to convert it: add it as an m3u include and place its channels with queries.

Host it

Any static HTTPS host that returns the file itself works: https://raw.githubusercontent.com/<user>/<repo>/<branch>/my.tsiptv.json, https://<user>.github.io/<repo>/my.tsiptv.json, https://www.example.com/my.tsiptv.json. Share pages and GitHub blob/ links do not work; see hosting an M3U file. You can also skip hosting and use Import from file.
HTTPS is recommended; http links work but are not encrypted.
Content type: application/json (or text/plain); TS IPTV detects the format by content anyway.
Compression: Content-Encoding: gzip is welcome for large files. The 5 MiB limit applies after decompression.
Caching: TS IPTV refreshes the root like a playlist (when older than 24 hours, or on Refresh) and each include after its refreshHours. For the file itself and for each include it sends If-None-Match / If-Modified-Since when your server gave an ETag or Last-Modified; answering 304 Not Modified saves bandwidth and counts 0 towards the 50 MiB budget.
CORS is not needed by TS IPTV. Add Access-Control-Allow-Origin: * only if web tools should read the file.
Keep the link stable. The same id from the same link is an update; from another link, TS IPTV asks whether to replace the existing source.

Add it in TS IPTV

Open Add IPTV Source, paste the link into Source Link and choose Add IPTV, or choose Import from file. TS IPTV recognises the format by its content.
The preview dialog “Add this source?” opens (nothing is stored yet): logo, name, author, description, the numbers of channels, radio, movies and series, “This source contacts these servers” (the hosts of the file and every include), “N items will be skipped” with Details (opens “Import details”) if some entries are invalid, the notice that the source was made by a third party, and the checkbox “I am 18 or older” if the source is marked adult.
Choose Import. TS IPTV loads the includes (“Loading 2 of 4…”). If an include turns out to be adult, it asks again (“Part of this source’s content comes from a source or addon that says it contains adult content.” with “I am 18 or older”); Cancel stores nothing. Then it stores everything, shows for example “Source added: 3 channels, 1 movie, 0 series” (and “N items were skipped” if any) and opens the source's home. On phones, the Home tab has Home (your layout) and Channels (the usual channel list); on TV the rail starts with Home.
Search, Continue watching and favourites work inside the source. About this source (phone: the Source Home menu; TV: a rail item) shows the author; Homepage, which asks “Open … in your browser?” (on a TV without a browser the link is shown as text); each include's status (“Up to date”, “Couldn’t refresh — showing the copy from …”, “Couldn’t load”, or “Held back until 18+ is confirmed” with Confirm); the last refresh with “Problems found in the last refresh: N” and Details (“Problems found”); Refresh and Remove source.
If refreshing the file itself fails, About adds “Last attempt: …”; after a Refresh you start, Home also shows “Couldn’t refresh this source. The saved copy is shown.”. TS IPTV tries again on the normal schedule.

If the file has a document error, TS IPTV shows “Can’t add this source” with the message from the table above and a Details action with the code and path. If every include fails and the file has no items of its own, it shows “None of this source’s content could be loaded. Try again later.”

Common mistakes

Mistake	Symptom	Fix
`url` and `streams` on the same item	Item skipped (`E_NO_STREAM`)	Use one: `url` for a single stream, `streams` for alternatives.
`:` in an id (`news:hd`)	Item skipped (`E_ITEM_ID`; for an include, `E_INCLUDE`)	Use `-`, `_` or `.`; the colon is reserved for included items.
The same id twice (also across channels, movies, episodes and includes)	The second is skipped (`E_DUPLICATE_ID`)	Make every id unique in the file.
`rtmp://`, `rtsp://` or `udp://` streams	The stream is dropped (`E_URL`); an item whose only stream it was is skipped (`E_NO_STREAM`)	Only http(s) is allowed here. Put such channels in an M3U playlist and add it as an `m3u` include; whether they play then depends on each platform's player.
A hero with both `items` and `query`	`items` are used (`W_FIELD`)	Keep one.
`groupChips` on a movies grid or a row	No chips	Group chips work on grids of `channels` or `radio` only.
Low-contrast colours (a light background, a dark accent)	Your colours are replaced (`W_CONTRAST`)	Use a dark background and an accent with at least 3:1 contrast against it.
A query on an include id that does not exist, or on an `xmltv` include	Section not shown (`W_QUERY_REF`)	Use the include's exact `id`; guides cannot be sections.
A misspelt field (`nmae`)	Ignored by the app; the required field is then missing	Use the `$schema` line or the validator; they report unknown fields.
Comments or trailing commas	“This file is not valid JSON.”	Remove them; use `x-` fields for notes.
`http://` images on hosts that redirect or block them	Missing posters	Use `https` image URLs.
An include id starting with `epg-`	Include dropped (`E_INCLUDE`)	That prefix is reserved for `epg` links.
A `stremio` include URL without `/manifest.json`	Include dropped (`E_INCLUDE`)	Use the addon's manifest link.
Spaces in a catch-up `source` (`default` or `append` mode)	Catch-up dropped, channel plays live (`W_FIELD`)	Encode spaces as `%20`.

What TS IPTV supports

Feature	Android	iOS	Desktop
Import by link or file, preview, layout, appearance, search, Continue watching	Supported	Not yet verified	Supported
Channels, radio, movies, series; several streams per item (channels: “Playback options”; movies and episodes: the detail page)	Supported	Not yet verified	Supported
Headers	All headers	Not yet verified	User-Agent and Referer only
DASH `.mpd` streams without DRM	Supported	Not yet verified through the built-in VLC player; only the User-Agent and Referer headers are sent	Supported
DRM (Widevine, PlayReady; ClearKey for DASH)	Android only	Not supported	Not supported
Subtitles (VTT, SRT), off by default	Supported	Not yet	Not yet verified
Includes: `m3u`, `xmltv`, `stremio`, `tsiptv-source`	Supported Stremio-compatible addons play `url` streams only.
Catch-up	Stored, playback coming later
Links that open websites from banners	Not part of the format

iOS: TS IPTV Source support has not yet been built or tested on iPhone and iPad, so those cells say “Not yet verified”. DRM is not available on iOS by design. DASH streams without DRM play on iPhone and iPad through the built-in VLC player, which sends only the User-Agent and Referer headers; DASH with DRM is not supported there. Desktop: the features marked “Supported” are built, but the desktop app has not yet been tested with TS IPTV Sources; its subtitles are “Not yet verified”.

Định dạng TS IPTV Source

Định dạng này là gì

Bắt đầu nhanh

Định dạng, từng phần một

Tệp

Cấp cao nhất

Quy tắc chung

meta

Chữ và bản dịch

Id, URL, header, màu

appearance

layout: trang chủ

Truy vấn

Bố cục mặc định

Kênh, phim lẻ và phim bộ

Kênh

Phim lẻ

Phim bộ, mùa, tập

Luồng

DRM

Xem lại (catch-up)

Phụ đề

epg và includes

Giới hạn

Bảo mật và quyền riêng tư

Phiên bản và giá trị chưa biết

Kiểm tra: lỗi và cảnh báo

Ví dụ đầy đủ

Danh sách kênh tối giản

Phim lẻ và phim bộ, có giao diện và bố cục riêng

Một nguồn ghép từ các include

Tự tạo nguồn của bạn, từng bước

Đư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

TS IPTV Source format

What it is

Quick start

The format, part by part

The file

Top level

General rules

meta

Texts and translations

Ids, URLs, headers, colours

appearance

layout: the home screen

Queries

Default layout

Channels, movies and series

Channel

Movie

Series, seasons, episodes

Stream

DRM

Catch-up

Subtitles

epg and includes

Limits

Security and privacy

Versions and unknown values

Validation: errors and warnings

Complete examples

Minimal live list

Movies and a series, with appearance and layout

A source built from includes

Create your own, step by step

Host it

Add it in TS IPTV

Common mistakes

What TS IPTV supports

Related guides

`meta`

`appearance`

`layout`: trang chủ

`epg` và `includes`

`meta`

`appearance`

`layout`: the home screen

`epg` and `includes`