Danh sách phát JSON

TS IPTV đọc được hai dạng danh sách kênh JSON: JSON chung (dạng riêng của TS IPTV, rất linh hoạt) và dạng streams.json của iptv-org. Trang này mô tả cả hai.

TS IPTV không có sẵn kênh nào. Ứng dụng chỉ phát các danh sách phát do bạn thêm vào. Trang này chỉ mô tả định dạng, không giới thiệu danh sách nào.

Hai dạng JSON

JSON không có một chuẩn chung cho danh sách kênh; mỗi ứng dụng dùng một dạng riêng. TS IPTV đọc hai dạng:

JSON chung: một đối tượng hoặc mảng chứa các kênh (và có thể có nhóm). Tên trường có vài biến thể được chấp nhận, nên nhiều tệp JSON tự tạo đọc được ngay.
Dạng streams.json của iptv-org: một mảng luồng, mỗi phần tử có channel, title, url và header. Dự án iptv-org dùng dạng này cho dữ liệu công khai của họ.

TS IPTV tự nhận ra dạng: nếu tệp bắt đầu bằng [ và phần tử đầu tiên có channel, url, title mà không có name, đó là dạng iptv-org; mọi tệp khác bắt đầu bằng { hoặc [ là JSON chung.

Cú pháp

JSON chung

Các dạng cấp cao nhất được chấp nhận:

một đối tượng { "name", "epgUrl", "channels": [ … ], "groups": [ … ] } (cũng chấp nhận channel và group);
một đối tượng chỉ có channels, hoặc chỉ có groups;
một mảng các đối tượng kênh: [ { … }, { … } ];
một mảng các đối tượng nhóm.

Trường của danh sách	Bắt buộc	Nghĩa
`name`	không	Tên danh sách phát.
`epgUrl`	không	Đường dẫn lịch phát sóng XMLTV.
`channels` (hoặc `channel`)	không	Mảng kênh không thuộc nhóm nào, hoặc tự khai báo nhóm.
`groups` (hoặc `group`)	không	Mảng nhóm: `{ "id"?, "name", "channels": [ … ] }`.

Trường của kênh	Bắt buộc	Tên khác được chấp nhận	Nghĩa
`id`	có		Mã duy nhất, là chuỗi.
`name`	có		Tên hiển thị.
`url`	có (hoặc `remote_data.url`)	`remote_data: { "url": "…" }`	Đường dẫn luồng.
`logoUrl`	không	`logo`, `image: { "url": "…" }`	Logo.
`groupTitle`	không	`group`	Tên nhóm (khi kênh không nằm trong một `groups`).
`groupId`	không		Mã nhóm; tự tạo từ tên nếu thiếu.
`epgId`	không	`epg`	Mã kênh trong lịch XMLTV (giống `tvg-id` của M3U).
`description`	không		Mô tả.
`attributes`	không		Tập cặp khoá–giá trị (chuỗi), cùng khoá với thuộc tính M3U. `"user-agent"` và `"referrer"` trở thành header HTTP.

Trường không có trong bảng sẽ bị bỏ qua.

Dạng `streams.json` của iptv-org

Một mảng; mỗi phần tử là một luồng:

Trường	Kiểu	Nghĩa
`channel`	chuỗi hoặc null	Mã kênh, ví dụ `ExampleNews.us`.
`feed`	chuỗi hoặc null	Mã bản phát (feed), ví dụ `HD`. Mã luồng đầy đủ là `channel@feed`, ví dụ `ExampleNews.us@HD`.
`title`	chuỗi	Tên luồng.
`url`	chuỗi	Đường dẫn luồng.
`referrer`	chuỗi hoặc null	Header `Referer`.
`user_agent`	chuỗi hoặc null	Header `User-Agent`.
`quality`	chuỗi hoặc null	Chất lượng tối đa, ví dụ `720p`.
`labels`	mảng	Nhãn như `Geo-blocked`, `Not 24/7`.

Ví dụ đầy đủ

JSON chung

Kênh đầu tiên là luồng thử nghiệm công khai của Mux (Big Buck Bunny © Blender Foundation, CC BY 3.0); các kênh khác dùng đường dẫn giả example.com.

Tải playlist.json

{
  "name": "TS IPTV example playlist",
  "epgUrl": "https://tsiptv-8bdd6.web.app/examples/guide.xml",
  "channels": [
    {
      "id": "HlsTest.example",
      "name": "HLS Test Channel",
      "url": "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8",
      "group": "Test",
      "epgId": "HlsTest.example"
    },
    {
      "id": "ExampleRadio.us",
      "name": "Example Radio",
      "url": "https://cdn.example.com/radio/stream.aac",
      "group": "Radio"
    }
  ],
  "groups": [
    {
      "name": "News",
      "channels": [
        {
          "id": "ExampleNews.us",
          "name": "Example News",
          "url": "https://cdn.example.com/news/index.m3u8",
          "logo": "https://example.com/logos/news.png",
          "epgId": "ExampleNews.us",
          "attributes": {
            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
            "referrer": "https://example.com/"
          }
        }
      ]
    }
  ]
}

name và epgUrl: tên danh sách và lịch phát sóng ví dụ.
channels: hai kênh tự khai báo nhóm bằng group (“Test” và “Radio”).
groups: nhóm “News” chứa một kênh có logo, epgId và hai header trong attributes.

Dạng ngắn nhất là một mảng: [{"id":"a","name":"A","url":"https://cdn.example.com/a.m3u8"}].

Dạng iptv-org

Tải iptv-org-streams.json

[
  {
    "channel": "HlsTest.example",
    "feed": null,
    "title": "HLS Test Channel",
    "url": "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8",
    "referrer": null,
    "user_agent": null,
    "quality": null,
    "labels": []
  },
  {
    "channel": "ExampleNews.us",
    "feed": "HD",
    "title": "Example News HD",
    "url": "https://cdn.example.com/news/index.m3u8",
    "referrer": "https://example.com/",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "quality": "1080p",
    "labels": ["Not 24/7"]
  }
]

Phần tử thứ nhất là luồng thử nghiệm của Mux, không có header. Phần tử thứ hai là một đường dẫn giả, có feed, referrer và user_agent; mã luồng của nó là ExampleNews.us@HD.

Tự viết một tệp

Mở một trình soạn thảo văn bản thuần. VS Code tốt nhất vì nó báo lỗi cú pháp JSON ngay khi gõ.
Chép một trong hai ví dụ ở trên và sửa các kênh.
Dùng nháy kép thẳng " cho mọi khoá và chuỗi; id luôn là chuỗi ("7", không phải 7).
Không để dấu phẩy sau phần tử cuối cùng và không viết chú thích //.
Lưu với mã hoá UTF-8 (không BOM), đuôi .json.

Cần header cho từng kênh, DRM hay thông tin xem lại? Hãy dùng M3U hoặc TS IPTV Source. Cần phim lẻ, phim bộ có mùa và tập, nhiều luồng cho mỗi mục, hoặc bố cục trang chủ và màu sắc riêng? Hãy dùng TS IPTV Source, cũng là một định dạng JSON.

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

Giống như M3U: mọi đường dẫn HTTPS trả về chính nội dung tệp đều dùng được (https://raw.githubusercontent.com/<user>/<repo>/<branch>/playlist.json, https://<user>.github.io/<repo>/playlist.json, https://www.example.com/playlist.json, Dropbox với dl=1). Trang hiển thị tệp trên GitHub (github.com/…/blob/…) là trang web, không phải tệp. Máy chủ nên gửi Content-Type: application/json, nhưng TS IPTV tự nhận dạng nội dung. HTTPS được khuyến nghị; TS IPTV không cần CORS. Chi tiết: đưa tệp M3U lên mạng.

Thêm vào TS IPTV

Mở Thêm nguồn IPTV (nút Thêm IPTV).
Nhập Tên nguồn, 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 và chọn tệp .json.
TS IPTV nhận ra dạng JSON và cho biết số kênh tìm thấy. Nếu tệp có epgUrl, lịch phát sóng được tải cùng lúc.

Lỗi thường gặp

Lỗi	Biểu hiện	Cách sửa
Dấu phẩy sau phần tử cuối (`[{…},]`)	Không đọc được tệp	Xoá dấu phẩy thừa.
Chú thích `//` hoặc `/* */`	Không đọc được tệp	JSON không cho phép chú thích; hãy xoá chúng.
`id` là số (`"id": 7`)	TS IPTV vẫn đọc được, nhưng ứng dụng khác có thể từ chối	Viết thành chuỗi: `"id": "7"`.
Nháy cong `“ ”`	Không đọc được tệp	Gõ lại thành nháy thẳng `"`.
Thiếu `name` hoặc `url` ở một kênh	Không đọc được tệp, hoặc kênh không phát	Mỗi kênh cần `id`, `name` và `url`.
Đường dẫn là trang GitHub thay vì tệp gốc	“Đường dẫn này mở một trang web”	Dùng đường dẫn Raw.
Tệp iptv-org có thêm trường `name`	Được đọc như JSON chung; vì JSON chung bắt buộc có `id`, cả tệp không đọc được	Giữ đúng dạng iptv-org, hoặc chuyển hẳn sang JSON chung.

TS IPTV hỗ trợ những gì

Tính năng	Trạng thái
Bốn dạng cấp cao nhất của JSON chung, kể cả mảng	Hỗ trợ trên mọi nền tảng
Nhóm lồng nhau, `remote_data.url`, `image.url`	Hỗ trợ
Header từ `attributes` (JSON chung) và `referrer`/`user_agent` (iptv-org)	Android iOS: cố gắng tối đa Máy tính: chỉ User-Agent và Referer
`epgUrl`	Hỗ trợ
`labels`, `quality` của iptv-org	Được chấp nhận, chưa hiển thị
DRM, xem lại	Không có trong JSON Dùng M3U.

JSON playlists

TS IPTV reads two JSON channel-list shapes: generic JSON (TS IPTV's own, flexible shape) and the iptv-org streams.json shape. This page describes both.

TS IPTV includes no channels. It plays only the playlists you add. This page describes formats only and recommends no list.

Two JSON shapes

There is no common standard for JSON channel lists; every app uses its own shape. TS IPTV reads two:

Generic JSON: an object or array of channels (optionally in groups). Several field-name variants are accepted, so many home-made JSON files read as they are.
The iptv-org streams.json shape: an array of streams, each with channel, title, url and headers. The iptv-org project uses this shape for its public data.

TS IPTV detects the shape: if the file starts with [ and the first element has channel, url and title but no name, it is the iptv-org shape; any other file that starts with { or [ is generic JSON.

Syntax

Generic JSON

Accepted top-level shapes:

an object { "name", "epgUrl", "channels": [ … ], "groups": [ … ] } (channel and group are accepted too);
an object with only channels, or only groups;
an array of channel objects: [ { … }, { … } ];
an array of group objects.

Playlist field	Required	Meaning
`name`	no	Playlist name.
`epgUrl`	no	XMLTV guide URL.
`channels` (or `channel`)	no	Array of channels that are in no group, or that name their own group.
`groups` (or `group`)	no	Array of groups: `{ "id"?, "name", "channels": [ … ] }`.

Channel field	Required	Also accepted	Meaning
`id`	yes		Unique id, a string.
`name`	yes		Display name.
`url`	yes (or `remote_data.url`)	`remote_data: { "url": "…" }`	Stream URL.
`logoUrl`	no	`logo`, `image: { "url": "…" }`	Logo.
`groupTitle`	no	`group`	Group name (when the channel is not inside a `groups` entry).
`groupId`	no		Group id; derived from the name if missing.
`epgId`	no	`epg`	The channel's id in the XMLTV guide (like M3U `tvg-id`).
`description`	no		Description.
`attributes`	no		A string map with the same keys as M3U attributes. `"user-agent"` and `"referrer"` become HTTP headers.

Fields that are not in the table are ignored.

The iptv-org `streams.json` shape

An array; each element is one stream:

Field	Type	Meaning
`channel`	string or null	Channel id, for example `ExampleNews.us`.
`feed`	string or null	Feed id, for example `HD`. The full stream id is `channel@feed`, for example `ExampleNews.us@HD`.
`title`	string	Stream title.
`url`	string	Stream URL.
`referrer`	string or null	`Referer` header.
`user_agent`	string or null	`User-Agent` header.
`quality`	string or null	Maximum quality, for example `720p`.
`labels`	array	Labels such as `Geo-blocked`, `Not 24/7`.

Complete examples

Generic JSON

The first channel is the Mux public test stream (Big Buck Bunny © Blender Foundation, CC BY 3.0); the others use example.com placeholders.

Download playlist.json

{
  "name": "TS IPTV example playlist",
  "epgUrl": "https://tsiptv-8bdd6.web.app/examples/guide.xml",
  "channels": [
    {
      "id": "HlsTest.example",
      "name": "HLS Test Channel",
      "url": "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8",
      "group": "Test",
      "epgId": "HlsTest.example"
    },
    {
      "id": "ExampleRadio.us",
      "name": "Example Radio",
      "url": "https://cdn.example.com/radio/stream.aac",
      "group": "Radio"
    }
  ],
  "groups": [
    {
      "name": "News",
      "channels": [
        {
          "id": "ExampleNews.us",
          "name": "Example News",
          "url": "https://cdn.example.com/news/index.m3u8",
          "logo": "https://example.com/logos/news.png",
          "epgId": "ExampleNews.us",
          "attributes": {
            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
            "referrer": "https://example.com/"
          }
        }
      ]
    }
  ]
}

name and epgUrl: the playlist name and the example guide.
channels: two channels that name their own group with group (“Test” and “Radio”).
groups: a “News” group with one channel that has a logo, an epgId and two headers in attributes.

The shortest form is an array: [{"id":"a","name":"A","url":"https://cdn.example.com/a.m3u8"}].

iptv-org shape

Download iptv-org-streams.json

[
  {
    "channel": "HlsTest.example",
    "feed": null,
    "title": "HLS Test Channel",
    "url": "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8",
    "referrer": null,
    "user_agent": null,
    "quality": null,
    "labels": []
  },
  {
    "channel": "ExampleNews.us",
    "feed": "HD",
    "title": "Example News HD",
    "url": "https://cdn.example.com/news/index.m3u8",
    "referrer": "https://example.com/",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "quality": "1080p",
    "labels": ["Not 24/7"]
  }
]

The first element is the Mux test stream, with no headers. The second is a placeholder with a feed, a referrer and a user_agent; its stream id is ExampleNews.us@HD.

Create one by hand

Open a plain-text editor. VS Code is best because it flags JSON syntax errors as you type.
Copy one of the examples above and edit the channels.
Use straight double quotes " for every key and string; id is always a string ("7", not 7).
No comma after the last element, and no // comments.
Save as UTF-8 (no BOM) with the extension .json.

Need per-channel headers, DRM or catch-up information? Use M3U or TS IPTV Source. Need movies, series with seasons and episodes, several streams per item, or your own home layout and colours? Use TS IPTV Source, which is also JSON.

Host it

Just like M3U: any HTTPS link that returns the file itself works (https://raw.githubusercontent.com/<user>/<repo>/<branch>/playlist.json, https://<user>.github.io/<repo>/playlist.json, https://www.example.com/playlist.json, Dropbox with dl=1). GitHub's file view (github.com/…/blob/…) is a web page, not the file. The server should send Content-Type: application/json, but TS IPTV detects the content anyway. HTTPS is recommended; TS IPTV needs no CORS. Details: hosting an M3U file.

Add it in TS IPTV

Open Add IPTV Source (the Add IPTV button).
Enter a Source Name, paste the link into Source Link and choose Add IPTV; or choose Import from file and pick the .json file.
TS IPTV detects the JSON shape and shows how many channels it found. If the file has an epgUrl, the guide is downloaded with it.

Common mistakes

Mistake	Symptom	Fix
A comma after the last element (`[{…},]`)	The file cannot be read	Remove the extra comma.
`//` or `/* */` comments	The file cannot be read	JSON has no comments; remove them.
A numeric `id` (`"id": 7`)	TS IPTV still reads it, but other apps may reject it	Write it as a string: `"id": "7"`.
Curly quotes `“ ”`	The file cannot be read	Retype them as straight `"`.
A channel without `name` or `url`	The file cannot be read, or the channel does not play	Every channel needs `id`, `name` and `url`.
The link is a GitHub page instead of the raw file	“This link opens a web page”	Use the Raw link.
An iptv-org file with an extra `name` field	Read as generic JSON, which requires `id`, so the whole file cannot be read	Keep the iptv-org shape exactly, or switch fully to generic JSON.

What TS IPTV supports

Feature	Status
All four generic top-level shapes, including arrays	Supported on every platform
Nested groups, `remote_data.url`, `image.url`	Supported
Headers from `attributes` (generic) and `referrer`/`user_agent` (iptv-org)	Android iOS: best effort Desktop: User-Agent and Referer only
`epgUrl`	Supported
iptv-org `labels`, `quality`	Accepted, not shown yet
DRM, catch-up	Not in JSON Use M3U.

Danh sách phát JSON

Hai dạng JSON

Cú pháp

JSON chung

Dạng streams.json của iptv-org

Ví dụ đầy đủ

JSON chung

Dạng iptv-org

Tự viết một tệp

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

Thêm vào TS IPTV

Lỗi thường gặp

TS IPTV hỗ trợ những gì

Hướng dẫn liên quan

JSON playlists

Two JSON shapes

Syntax

Generic JSON

The iptv-org streams.json shape

Complete examples

Generic JSON

iptv-org shape

Create one by hand

Host it

Add it in TS IPTV

Common mistakes

What TS IPTV supports

Related guides

Dạng `streams.json` của iptv-org

The iptv-org `streams.json` shape