Addon tương thích Stremio

Addon là một dịch vụ web nhỏ, thậm chí chỉ là một thư mục tệp JSON tĩnh, trả lời vài loại yêu cầu HTTP bằng danh mục, thông tin chi tiết và đường dẫn luồng. Giao thức addon là giao thức mở, có tài liệu công khai; TS IPTV dùng được mọi addon tuân theo giao thức này và trả về đường dẫn video thông thường.

TS IPTV không có sẵn kênh nào và cũng không có sẵn addon nào. Ứng dụng không cài sẵn và không giới thiệu addon nào. Addon là dịch vụ của bên thứ ba do bạn tự thêm; bạn chịu trách nhiệm về quyền sử dụng mọi nội dung bạn xem qua chúng.

Giao thức này được tạo ra cho ứng dụng Stremio và được công bố dưới dạng đặc tả mở stremio-addon-sdk. TS IPTV không liên kết với Stremio và không được Stremio bảo trợ; cụm từ “tương thích Stremio” chỉ để mô tả giao thức. Mọi ví dụ dùng addon mẫu của chính TS IPTV trên tsiptv-8bdd6.web.app, phim thuộc phạm vi công cộng trên archive.org, một luồng thử nghiệm công khai, hoặc tên miền giả example.com.

Addon là gì

Mỗi addon được nhận diện bằng đường dẫn tới manifest của nó, một tệp JSON luôn kết thúc bằng /manifest.json. Manifest cho biết addon cung cấp gì: loại nội dung nào (movie, series, tv…), những danh mục nào, và những tài nguyên nào (danh sách, thông tin chi tiết, luồng, phụ đề). Trình phát dựng các đường dẫn tiếp theo từ địa chỉ của manifest và gửi yêu cầu HTTP GET thông thường. Mọi câu trả lời đều là JSON. Không có đăng nhập, phiên làm việc hay giao thức riêng, nên một addon có thể đơn giản chỉ là vài tệp trên một máy chủ web tĩnh.

Addon hữu ích khi bạn muốn đăng bộ sưu tập của riêng mình kèm ảnh bìa, mô tả, mùa và tập: ví dụ máy chủ media tại nhà, một dịch vụ có bản quyền do bạn vận hành, hoặc kho phim thuộc phạm vi công cộng.

Giao thức

Văn bản chuẩn là protocol.md và tài liệu API của SDK. Phần này tóm tắt những gì người viết addon cần biết.

Đường dẫn

Đường dẫn gốc (base URL) là đường dẫn manifest bỏ phần /manifest.json. Mọi yêu cầu khác đều dựng từ đó:

GET {base}/manifest.json
GET {base}/{resource}/{type}/{id}.json
GET {base}/{resource}/{type}/{id}/{extra}.json

Tài nguyên	`type`	`id`	Câu trả lời
`catalog`	loại của danh mục	mã danh mục trong manifest	`{ "metas": [ … ] }`
`meta`	loại của mục	mã mục lấy từ danh mục	`{ "meta": { … } }`
`stream`	loại của mục	mã video (phim lẻ: chính mã của phim; một tập: mã của tập; `tv`: mã kênh)	`{ "streams": [ … ] }`
`subtitles`	loại của mục	mã video	`{ "subtitles": [ … ] }`
`addon_catalog`	lấy từ `addonCatalogs`	lấy từ `addonCatalogs`	`{ "addons": [ … ] }`

Chuỗi truy vấn (query string) trên đường dẫn manifest được giữ lại và gắn sau .json của mọi yêu cầu. Phần đứng trước /manifest.json cũng được giữ nguyên; addon có cấu hình đặt thiết lập của người dùng ở đó, ví dụ https://addon.example.com/eyJsYW5nIjoiZW4ifQ/manifest.json.
Máy chủ dùng SDK trả về 404 {"err":"not found"} cho tài nguyên không có và 500 {"err":"handler error"} khi xử lý lỗi; chúng cũng có thể chuyển hướng bằng mã 307. Máy chủ tĩnh trả về 404 cho mọi tệp không tồn tại.

Mã hoá: các đoạn đường dẫn và `extra`

resource, type và id được mã hoá riêng từng phần giống hàm encodeURIComponent của JavaScript: mọi byte trừ chữ cái, chữ số và - _ . ! ~ * ' ( ) đều thành %XX. Vì vậy tt1234567:1:2 được gửi đi thành tt1234567%3A1%3A2.
extra là các cặp tên=giá-trị nối bằng &, mỗi tên và giá trị được mã hoá cùng cách: search=his%20girl&skip=100. Dấu cách là %20, không bao giờ là +; ký tự & hay = nằm trong giá trị thành %26 hay %3D.
Extra cho phép nhiều giá trị thì lặp lại tên: genre=Action&genre=Comedy. TS IPTV ghi extra theo thứ tự khai báo trong manifest, skip luôn ở cuối, và bỏ hẳn đoạn /{extra} khi không có extra nào.

Manifest

Trường	Bắt buộc	Nghĩa
`id`	có	Mã định danh kiểu tên miền đảo ngược, ví dụ `com.example.myaddon`. Thêm lại cùng mã nghĩa là cập nhật.
`version`	có	Chuỗi phiên bản, thường theo semver (`1.0.0`).
`name`	có	Tên hiển thị.
`description`	có (theo đặc tả)	Một hai câu mô tả.
`types`	có	Loại nội dung: `movie`, `series`, `channel`, `tv`, hoặc chuỗi bất kỳ.
`resources`	có	`"catalog"`, `"meta"`, `"stream"`, `"subtitles"`, `"addon_catalog"`, hoặc đối tượng `{ "name": "stream", "types": ["movie"], "idPrefixes": ["ex_"] }`.
`catalogs`	có (có thể là `[]`)	Danh sách danh mục (xem dưới).
`idPrefixes`	không	Chỉ những mã bắt đầu bằng một trong các tiền tố này mới được gửi tới addon, ví dụ `["ex_"]`.
`addonCatalogs`	không	Danh sách các addon khác (`type`, `id`, `name`).
`behaviorHints`	không	`adult`, `p2p`, `configurable`, `configurationRequired`, `epgProvider`, đều là giá trị đúng/sai.
`logo`, `background`, `contactEmail`	không	Logo (PNG 256×256), ảnh nền, địa chỉ liên hệ.

Mỗi danh mục có dạng { "type", "id", "name", "extra": [ … ] }. Một id có thể dùng cho nhiều loại. Mỗi phần tử extra có dạng { "name", "isRequired", "options", "optionsLimit" }:

Extra	Nghĩa
`search`	Tìm kiếm tự do. `isRequired: true` tạo danh mục chỉ dùng để tìm, không bao giờ hiện thành một hàng.
`genre`	Bộ lọc; các giá trị lấy từ `options`. Thể loại bắt buộc sẽ bắt đầu ở giá trị đầu tiên.
`skip`	Phân trang (xem dưới).
tên khác	Được phép; khai báo theo cùng cách.

Manifest kiểu cũ dùng danh sách chuỗi extraSupported/extraRequired và một danh sách genres riêng; TS IPTV vẫn đọc được, nhưng khi có cả hai thì extra được ưu tiên.

Phân trang

Mỗi trang danh mục chứa tối đa 100 mục. Trang đầu được yêu cầu không có skip; các trang sau dùng skip=100, skip=200, v.v. Theo đặc tả, trang có ít hơn 100 mục là trang cuối. TS IPTV dễ dãi hơn: nó yêu cầu trang tiếp theo với skip bằng số mục đã nhận, và dừng khi gặp trang rỗng, trang không có mục mới, hoặc câu trả lời lỗi ngay sau một trang ngắn (ví dụ 404 của máy chủ tĩnh). Chỉ khai báo skip khi danh mục của bạn có nhiều hơn một trang.

Mục trong danh mục và thông tin chi tiết

Trường	Ở đâu	Nghĩa
`id`, `type`, `name`	cả hai	Bắt buộc.
`poster`, `posterShape`	cả hai	Ảnh bìa; hình dạng `poster` (dọc, mặc định), `square` hoặc `landscape`.
`genres`, `releaseInfo`, `description`, `imdbRating`	cả hai	Chữ hiển thị trên thẻ và trang chi tiết.
`background`, `logo`, `released`, `runtime`, `language`, `country`, `links`	meta	Trường của trang chi tiết. `released` theo ISO 8601; `runtime` là chữ, ví dụ `"92 min"`.
`videos`	meta	Các tập của phim bộ (hoặc video của một kênh). Không có `videos` thì mục có đúng một video, mã video bằng mã mục.
`behaviorHints.defaultVideoId`, `behaviorHints.isLive`	meta	Mở thẳng video này; mục phát trực tiếp (`tv` luôn là trực tiếp).

Mỗi video có dạng { "id", "title", "released", "season", "episode", "thumbnail", "overview" }. Mùa 0 là các tập đặc biệt. Ngày released trong tương lai đánh dấu tập sắp ra mắt. Nếu một video tự mang mảng streams, chỉ những luồng đó được dùng cho nó.

Luồng

Mỗi đối tượng luồng có đúng một nguồn và vài nhãn:

Trường	Nghĩa
`url`	Đường dẫn trực tiếp `https` (hoặc `http`): MP4, MKV, HLS `.m3u8`, DASH `.mpd`.
`externalUrl`	Một trang web để mở trong trình duyệt.
`name`	Nhãn ngắn, ví dụ chất lượng.
`description` (tên cũ: `title`)	Nhãn dài hơn, có thể nhiều dòng.
`behaviorHints.proxyHeaders.request`	Header HTTP cần gửi kèm mọi yêu cầu của luồng này, ví dụ `{ "User-Agent": "…", "Referer": "…" }`. Đặc tả yêu cầu có kèm `notWebReady: true`.
`behaviorHints.notWebReady`	Đường dẫn không phát thẳng được trong trình duyệt web (không phải MP4, là http thường, hoặc cần header).
`behaviorHints.bingeGroup`	Luồng cùng nhóm được ưu tiên cho tập tiếp theo.
`behaviorHints.filename`, `videoSize`	Tên tệp và dung lượng; giúp trình phát đoán định dạng.
`behaviorHints.countryWhitelist`	Mã quốc gia ISO 3166-1 alpha-3 (chữ thường) nơi luồng hoạt động.

Đặc tả còn có các trường nguồn khác; TS IPTV không dùng chúng (xem TS IPTV phát được những gì). Hãy xếp luồng từ chất lượng cao nhất tới thấp nhất.

Phụ đề

GET {base}/subtitles/{type}/{videoId}.json, có thể kèm videoHash, videoSize và filename trong extra, trả về { "subtitles": [ { "id", "url", "lang", "label" } ] }. lang là mã ISO 639-2 như vie hoặc eng; tệp phụ đề là SRT hoặc VTT. TS IPTV hiện chưa dùng addon phụ đề.

Bộ nhớ đệm

Mọi câu trả lời đều có thể kèm cacheMaxAge, staleRevalidate và staleError (tính bằng giây). SDK đổi chúng thành header Cache-Control và vẫn giữ chúng trong JSON. TS IPTV ưu tiên Cache-Control, rồi đến các trường này, rồi đến giá trị mặc định của mình (danh mục 1 giờ, chi tiết 6 giờ, luồng 5 phút), và không bao giờ giữ câu trả lời về luồng quá 5 phút.

Loại và mã

Loại là chuỗi tự do; phổ biến là movie, series, channel và tv. Mã (id) là chuỗi không cần mang nghĩa. Hãy đặt cho mã một tiền tố riêng (ex_news, tspd_his_girl_friday) và khai báo nó trong idPrefixes, để trình phát chỉ hỏi addon của bạn về các mục của bạn. Mỗi tập có mã riêng, ví dụ tspd_superman_s1e1.

Ví dụ đầy đủ: addon mẫu

TS IPTV công bố một addon tĩnh nhỏ, Public Domain Sampler, làm ví dụ trực tiếp và dữ liệu kiểm thử. Nó có một phim lẻ (His Girl Friday, 1940), một loạt phim hoạt hình (Fleischer Superman, 1941–43), cả hai thuộc phạm vi công cộng trên archive.org, và một kênh trực tiếp phát luồng thử nghiệm công khai của Mux (Big Buck Bunny © Blender Foundation, CC BY 3.0). Đường dẫn manifest là https://tsiptv-8bdd6.web.app/examples/stremio-sampler/manifest.json.

Đây là toàn bộ các tệp của nó; mỗi tệp đúng bằng đường dẫn mà trình phát yêu cầu:

manifest.json
catalog/movie/tspd-movie.json
catalog/movie/tspd-movie/genre=Comedy.json
catalog/series/tspd-series.json
catalog/tv/tspd-tv.json
meta/movie/tspd_his_girl_friday.json
meta/series/tspd_superman.json
meta/tv/tspd_test_hls.json
stream/movie/tspd_his_girl_friday.json
stream/series/tspd_superman_s1e1.json
stream/tv/tspd_test_hls.json

`manifest.json`

Tải manifest.json

{
  "id": "org.tsiptv.publicdomain.static",
  "version": "1.0.0",
  "name": "Public Domain Sampler (static)",
  "description": "Public-domain films and cartoons from archive.org, plus a public HLS test channel. Static JSON on GitHub Pages.",
  "resources": ["catalog", "meta", "stream"],
  "types": ["movie", "series", "tv"],
  "idPrefixes": ["tspd_"],
  "catalogs": [
    { "type": "movie",  "id": "tspd-movie",  "name": "Public Domain Movies",
      "extra": [ { "name": "genre", "isRequired": false, "options": ["Comedy"] } ] },
    { "type": "series", "id": "tspd-series", "name": "Public Domain Cartoons" },
    { "type": "tv",     "id": "tspd-tv",     "name": "Test Channels" }
  ],
  "behaviorHints": { "adult": false, "p2p": false }
}

Ba danh mục, mỗi loại một danh mục. Danh mục phim lẻ khai báo extra genre với đúng một giá trị, nên chỉ có một tệp extra: catalog/movie/tspd-movie/genre=Comedy.json (bản sao của danh sách không lọc). idPrefixes là tspd_, và mã dùng _ chứ không dùng :, vì mỗi mã sẽ thành một tên tệp.

`catalog/movie/tspd-movie.json`

Tải tệp

{
  "metas": [
    { "id": "tspd_his_girl_friday", "type": "movie", "name": "His Girl Friday",
      "poster": "https://archive.org/services/img/his_girl_friday",
      "releaseInfo": "1940", "genres": ["Comedy"] }
  ]
}

Được yêu cầu tại …/catalog/movie/tspd-movie.json. Danh mục không khai báo skip, nên trang duy nhất này là toàn bộ danh mục và không có trang nào được yêu cầu thêm.

`meta/series/tspd_superman.json`

Tải tệp

{
  "meta": {
    "id": "tspd_superman", "type": "series", "name": "Fleischer Superman (1941-43)",
    "poster": "https://archive.org/services/img/superman_the_mechanical_monsters",
    "releaseInfo": "1941-1943", "genres": ["Animation"],
    "description": "Fleischer Studios Superman cartoons, public domain.",
    "videos": [
      { "id": "tspd_superman_s1e1", "title": "The Mechanical Monsters",
        "season": 1, "episode": 1, "released": "1941-11-28T00:00:00.000Z",
        "thumbnail": "https://archive.org/services/img/superman_the_mechanical_monsters" }
    ]
  }
}

Phim bộ liệt kê các tập trong videos. Mã tập tspd_superman_s1e1 là mã mà yêu cầu luồng sử dụng.

`stream/movie/tspd_his_girl_friday.json` và `stream/tv/tspd_test_hls.json`

Tải tệp

{
  "streams": [
    { "name": "archive.org", "description": "MP4 · 512kb",
      "url": "https://archive.org/download/his_girl_friday/his_girl_friday_512kb.mp4",
      "behaviorHints": { "filename": "his_girl_friday_512kb.mp4" } }
  ]
}

Tải tệp

{
  "streams": [
    { "name": "HLS", "description": "Mux public test stream",
      "url": "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8",
      "behaviorHints": { "notWebReady": true,
                         "proxyHeaders": { "request": { "User-Agent": "TSIPTV-Example/1.0" } } } }
  ]
}

Luồng của phim lẻ là một url MP4 trực tiếp kèm gợi ý filename. Luồng của kênh trực tiếp là HLS và yêu cầu header User-Agent qua proxyHeaders.request; TS IPTV gửi header này kèm mọi yêu cầu danh sách và đoạn video. Các tệp còn lại theo cùng mẫu: danh mục phim bộ, danh mục tv, chi tiết phim lẻ, chi tiết kênh, luồng của tập phim, tệp thể loại Comedy.

Tự tạo addon

Cách 1: tệp JSON tĩnh (không cần máy chủ)

Tải các tệp mẫu ở trên về một thư mục, giữ nguyên cấu trúc thư mục.
Sửa manifest.json: id mới (tên miền đảo ngược của một tên miền bạn quản lý), name, description, idPrefixes và các danh mục của riêng bạn.
Với mỗi danh mục, viết catalog/{type}/{catalogId}.json. Thêm một tệp cho mỗi giá trị genre (catalog/{type}/{catalogId}/genre={giá-trị}.json) và, nếu có hơn 100 mục, …/skip=100.json, …/skip=200.json.
Với mỗi mục, viết meta/{type}/{id}.json; với mỗi phim lẻ, tập phim hoặc kênh, viết stream/{type}/{videoId}.json.
Giữ mã và giá trị extra an toàn cho URL: chữ cái, chữ số, _ và -. Kiểm tra từng tệp là JSON hợp lệ (VS Code báo lỗi ngay khi gõ).
Thử trên máy: trong thư mục, chạy npx http-server . --cors -c-1 rồi thêm http://127.0.0.1:8080/manifest.json (trình giả lập Android: http://10.0.2.2:8080/manifest.json).

Giới hạn của addon tĩnh: không có tìm kiếm tự do search (vì không thể tạo sẵn mọi truy vấn), mỗi thể loại và mỗi trang là một tệp, và không có : trong mã (máy chủ sẽ tìm một tên tệp chứa :, điều Windows và một số máy chủ không cho phép).

Cách 2: SDK cho Node.js

Với SDK chính thức (Node.js 12 trở lên), bạn viết các hàm xử lý thay vì tệp, nhờ đó có tìm kiếm, danh mục lớn và câu trả lời được tính toán. serveHTTP tự thêm header CORS, và đổi các giá trị cacheMaxAge, staleRevalidate, staleError mà hàm xử lý trả về thành header Cache-Control.

package.json:

{
  "name": "my-publicdomain-addon",
  "version": "1.0.0",
  "main": "addon.js",
  "scripts": { "start": "node addon.js" },
  "dependencies": { "stremio-addon-sdk": "^1.6.10" }
}

addon.js (addon mẫu, có tìm kiếm, lọc thể loại và phân trang):

const { addonBuilder, serveHTTP } = require('stremio-addon-sdk')

const ITEMS = [
  { id: 'tspd_his_girl_friday', type: 'movie', name: 'His Girl Friday',
    releaseInfo: '1940', genres: ['Comedy'],
    poster: 'https://archive.org/services/img/his_girl_friday',
    streams: [{ name: 'archive.org', description: 'MP4 512kb',
      url: 'https://archive.org/download/his_girl_friday/his_girl_friday_512kb.mp4',
      behaviorHints: { filename: 'his_girl_friday_512kb.mp4' } }] },
  { id: 'tspd_superman', type: 'series', name: 'Fleischer Superman (1941-43)',
    releaseInfo: '1941-1943', genres: ['Animation'],
    poster: 'https://archive.org/services/img/superman_the_mechanical_monsters',
    videos: [{ id: 'tspd_superman_s1e1', title: 'The Mechanical Monsters',
      season: 1, episode: 1, released: '1941-11-28T00:00:00.000Z',
      streams: [{ name: 'archive.org', description: 'MP4 512kb',
        url: 'https://archive.org/download/superman_the_mechanical_monsters/superman_the_mechanical_monsters_512kb.mp4' }] }] },
  { id: 'tspd_test_hls', type: 'tv', name: 'HLS Test Channel',
    posterShape: 'square', poster: 'https://archive.org/services/img/his_girl_friday',
    streams: [{ name: 'HLS', description: 'Mux public test stream',
      url: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8',
      behaviorHints: { notWebReady: true,
        proxyHeaders: { request: { 'User-Agent': 'TSIPTV-Example/1.0' } } } }] }
]
const PAGE = 100

const builder = new addonBuilder({
  id: 'org.example.publicdomain', version: '1.0.0', name: 'My Public Domain Addon',
  description: 'Public-domain films and cartoons, plus a public HLS test channel.',
  resources: ['catalog', 'meta', 'stream'], types: ['movie', 'series', 'tv'],
  idPrefixes: ['tspd_'],
  catalogs: ['movie', 'series', 'tv'].map(type => ({
    type, id: 'tspd-' + type, name: 'Public Domain ' + type,
    extra: [{ name: 'search' }, { name: 'genre', options: ['Animation', 'Comedy'] }, { name: 'skip' }]
  })),
  behaviorHints: { adult: false, p2p: false }
})

const preview = i => ({ id: i.id, type: i.type, name: i.name, poster: i.poster,
  posterShape: i.posterShape, genres: i.genres, releaseInfo: i.releaseInfo })

builder.defineCatalogHandler(({ type, id, extra }) => {
  let list = ITEMS.filter(i => i.type === type && id === 'tspd-' + type)
  if (extra.genre) list = list.filter(i => (i.genres || []).includes(extra.genre))
  if (extra.search) list = list.filter(i => i.name.toLowerCase().includes(extra.search.toLowerCase()))
  const skip = parseInt(extra.skip || '0', 10) || 0
  return Promise.resolve({ metas: list.slice(skip, skip + PAGE).map(preview), cacheMaxAge: 3600 })
})

builder.defineMetaHandler(({ type, id }) => {
  const i = ITEMS.find(x => x.id === id && x.type === type)
  if (!i) return Promise.resolve({ meta: null })
  const meta = preview(i)
  if (i.videos) meta.videos = i.videos.map(({ streams, ...v }) => v)
  return Promise.resolve({ meta, cacheMaxAge: 3600 })
})

builder.defineStreamHandler(({ type, id }) => {
  for (const i of ITEMS) {
    if (i.id === id && i.streams) return Promise.resolve({ streams: i.streams, cacheMaxAge: 600 })
    const v = (i.videos || []).find(v => v.id === id)
    if (v) return Promise.resolve({ streams: v.streams, cacheMaxAge: 600 })
  }
  return Promise.resolve({ streams: [] })
})

serveHTTP(builder.getInterface(), { port: process.env.PORT || 7000 })

Chạy npm install, rồi npm start. SDK in ra đường dẫn manifest, http://127.0.0.1:7000/manifest.json.
Thêm đường dẫn đó vào TS IPTV trên cùng máy tính; từ trình giả lập Android dùng http://10.0.2.2:7000/manifest.json; từ điện thoại hoặc TV trong cùng mạng dùng http://<địa chỉ LAN của máy tính>:7000/manifest.json.
Để công bố, triển khai lên bất kỳ dịch vụ lưu trữ Node.js nào có địa chỉ HTTPS, rồi dùng https://<máy chủ của bạn>/manifest.json.

SDK cũng có thể tạo trang cấu hình (config trong manifest) và gắn addon vào một ứng dụng Express có sẵn; xem README của SDK.

Đưa addon lên mạng

HTTPS. Đặc tả yêu cầu HTTPS cho mọi địa chỉ trừ 127.0.0.1. TS IPTV vẫn nhận http://, kèm cảnh báo “Addon này không dùng kết nối mã hoá”.
CORS. Đặc tả yêu cầu header Access-Control-Allow-Origin: * trên mọi đường dẫn, kể cả /manifest.json. TS IPTV là ứng dụng cài đặt nên không cần, nhưng trình phát chạy trên web thì cần, vì vậy hãy thêm nó.
Header bộ nhớ đệm. Cache-Control: public, max-age=600 cho danh mục và chi tiết là mặc định hợp lý; giữ thời gian ngắn cho câu trả lời về luồng nếu đường dẫn có hạn dùng.
Loại nội dung. Gửi tệp .json với application/json, và không chuyển hướng từ /tệp.json sang /tệp.json/.

Nơi lưu trữ	Cần làm gì
GitHub Pages	Đẩy cây thư mục lên một kho mã và bật Pages. Thêm một tệp rỗng `.nojekyll` ở thư mục gốc để tệp được phục vụ nguyên vẹn. Pages đã gửi sẵn `Access-Control-Allow-Origin: *`. Manifest: `https://<user>.github.io/<repo>/manifest.json`.
Firebase Hosting	Thêm một quy tắc header trong `firebase.json`: `{"source": "*/.json", "headers": [{"key": "Access-Control-Allow-Origin", "value": "*"}]}`. Addon mẫu của TS IPTV được lưu trữ theo cách này.
Netlify	Tệp `_headers` ở thư mục gốc, dòng đầu là `/`, dòng sau là `Access-Control-Allow-Origin: `.
Vercel	`vercel.json`: `{"headers": [{"source": "/(.)", "headers": [{"key": "Access-Control-Allow-Origin", "value": ""}]}]}`.
Máy chủ web bất kỳ	Phục vụ thư mục như tệp tĩnh và thêm header CORS, ví dụ với nginx: `add_header Access-Control-Allow-Origin *;`
SDK Node.js	Bất kỳ dịch vụ Node.js nào có HTTPS; `serveHTTP` tự đặt header CORS; `Cache-Control` lấy từ `cacheMaxAge` mà hàm xử lý trả về.

Trang blob/ của GitHub hay trang chia sẻ tệp không phải là addon: đường dẫn manifest phải trả về chính nội dung JSON.

Thêm vào TS IPTV

Điện thoại, máy tính bảng, iOS và máy tính: Hồ sơ → Addon → Thêm addon. Android TV: Cài đặt → Addon → Thêm addon (nhập đường dẫn bằng bàn phím trên màn hình).
Dán đường dẫn manifest (kết thúc bằng /manifest.json). Đường dẫn cài đặt dạng stremio://…/manifest.json cũng dùng được; TS IPTV tự đổi nó thành https://, hoặc http:// với máy trong mạng nội bộ (localhost, 127.0.0.1, 10.x, 192.168.x, 172.16–31.x).
Chọn Tiếp tục. Màn hình xem trước cho biết tên, phiên bản, máy chủ, loại nội dung, số danh mục, addon có cung cấp luồng hay không, và các cảnh báo (không mã hoá, ngang hàng P2P, nội dung người lớn).
Đọc và đồng ý với thông báo (“Addon là dịch vụ của bên thứ ba, không do TS IPTV vận hành…”), rồi chọn Thêm.
Mục Khám phá xuất hiện: trên điện thoại ở giữa Trang chủ và Lịch sử, trên TV ở đầu thanh bên của Trang chủ. Mỗi danh mục là một hàng; mở một nội dung và chọn một luồng để phát.

Nếu manifest có configurationRequired, TS IPTV chưa thêm ngay: chọn Cấu hình để mở trang /configure của addon trong trình duyệt (trên TV, địa chỉ được hiện dưới dạng chữ), hoàn tất ở đó rồi dán đường dẫn nó cung cấp. Quản lý addon (bật, tắt, sắp xếp, cập nhật, gỡ) ngay trên màn hình Addon. Đường dẫn addon có thể chứa thiết lập cá nhân, nên TS IPTV lưu chúng ở dạng mã hoá và chỉ hiển thị tên máy chủ.

Lỗi thường gặp

Lỗi	Biểu hiện	Cách sửa
Đường dẫn không kết thúc bằng `/manifest.json`	“Hãy nhập đường dẫn manifest của addon. Đường dẫn kết thúc bằng /manifest.json.”	Dùng đường dẫn manifest, không phải trang web của addon.
Manifest thiếu trường (`id`, `name`, `version`, `types`, `resources`)	“Đường dẫn này không trả về manifest addon hợp lệ.”	Thêm trường còn thiếu; kiểm tra tệp là JSON hợp lệ.
Dùng `+` thay cho `%20` trong tên tệp tĩnh	Không tìm thấy tệp thể loại hay tìm kiếm	Trình phát gửi `%20`; chỉ đặt tên tệp bằng giá trị an toàn cho URL.
Có `:` trong mã của addon tĩnh	Không tạo được tệp trên Windows, hoặc lỗi 404	Dùng `_` hoặc `-` trong mã.
Mỗi trang chỉ 20 mục	Ứng dụng khác dừng sau trang đầu	Trả về 100 mục mỗi trang; chỉ trang cuối được ngắn hơn.
`idPrefixes` không khớp mã, hoặc thiếu `"stream"` trong `resources`	Chi tiết hoặc luồng không bao giờ được yêu cầu	Khai báo mọi tài nguyên bạn phục vụ và một tiền tố chung cho mọi mã.
Video tự mang `streams`	Không addon nào khác được hỏi về video đó	Chỉ dùng luồng gắn sẵn khi đó là những luồng duy nhất.
`configurationRequired: true`	“Addon này cần được cấu hình trước.”	Cấu hình trong trình duyệt rồi dán đường dẫn đã cấu hình.
Đường dẫn trên `127.0.0.1:11470`	“Địa chỉ này thuộc máy chủ cục bộ của ứng dụng Stremio…”	Máy chủ đó thuộc một ứng dụng khác, không phải addon.
Addon kiểu cũ `/stremio/v1`	“Đây là addon kiểu cũ, TS IPTV không dùng được.”	Chỉ giao thức HTTP hiện tại được hỗ trợ.
Addon chỉ có nguồn khác `url`	“Không tìm thấy luồng phát được cho nội dung này.”	TS IPTV chỉ phát luồng `url`; xem bên dưới.
Không có header CORS	Chạy trong TS IPTV nhưng lỗi trên trình phát web	Thêm `Access-Control-Allow-Origin: *`.
GitHub Pages thiếu `.nojekyll`	Mất các tệp bắt đầu bằng `_`	Thêm tệp rỗng `.nojekyll`.
Lưu đệm lâu đường dẫn luồng có chữ ký hoặc có hạn	Luồng hỏng sau một thời gian	Đặt `cacheMaxAge` ngắn cho câu trả lời về luồng.

TS IPTV phát được những gì

Tính năng	Android	iOS	Máy tính
Luồng `url`: MP4, HLS qua HTTPS/HTTP	Hỗ trợ	Hỗ trợ	Hỗ trợ
Luồng `url`: DASH `.mpd` không có DRM	Hỗ trợ	Hỗ trợ qua trình phát VLC tích hợp; chỉ gửi header User-Agent và Referer	Hỗ trợ
Luồng `url`: MKV	Hỗ trợ	Có thể không phát được	Hỗ trợ
`proxyHeaders.request`	Mọi header	Cố gắng tối đa	Chỉ User-Agent và Referer
`externalUrl`	Mở trong trình duyệt sau khi bạn xác nhận; trên TV không có trình duyệt, đường dẫn được hiện dưới dạng chữ. Liên kết trang `stremio:///…` mở màn hình tương ứng của TS IPTV.
Luồng torrent, Usenet, tệp nén và YouTube	Không hỗ trợ
Danh mục, lọc thể loại, tìm kiếm, phân trang, phim bộ có mùa, mục `tv` trực tiếp	Hỗ trợ
`configurable`, `configurationRequired`	Hỗ trợ Qua trang cấu hình của addon trong trình duyệt.
Gợi ý `adult`, `p2p`	Cảnh báo khi thêm; addon người lớn cần xác nhận đủ 18 tuổi và không xuất hiện trong các hàng của Khám phá hay trong tìm kiếm.
Xem tiếp và phát tiếp phim lẻ, tập phim từ addon	Hỗ trợ
Phụ đề, addon lịch phát sóng (`epgProvider`), danh sách addon (`addon_catalog`), tự phát tập tiếp theo	Chưa có

TS IPTV không có addon cài sẵn và không gợi ý addon nào. Addon chỉ bị tắt từ xa khi có yêu cầu gỡ bỏ bắt buộc.

Stremio-compatible addons

An addon is a small web service, or even a folder of static JSON files, that answers a handful of HTTP requests with catalogues, details and stream links. The addon protocol is open and documented; TS IPTV can use any addon that follows it and returns ordinary video links.

TS IPTV includes no channels and no addons. Nothing is pre-installed and TS IPTV does not recommend any addon. Addons are third-party services that you add yourself; you are responsible for having the rights to what you watch through them.

The protocol was created for the Stremio app and is published as the open stremio-addon-sdk specification. TS IPTV is not affiliated with or endorsed by Stremio; “Stremio-compatible” only describes the protocol. Every example uses TS IPTV's own sample addon on tsiptv-8bdd6.web.app, public-domain films from archive.org, a public test stream or example.com placeholders.

What an addon is

An addon is identified by the link to its manifest, a JSON file that always ends in /manifest.json. The manifest says what the addon offers: which content types (movie, series, tv…), which catalogues, and which resources (catalogue lists, details, streams, subtitles). The player then builds further URLs from the manifest's address and requests them with plain HTTP GET. Every answer is JSON. There is no login, no session and no custom transport, which is why an addon can be as simple as a set of files on a static web host.

Addons are useful for publishing your own collection with posters, descriptions, seasons and episodes, for example a home media server, a licensed service you operate, or an archive of public-domain films.

The protocol

The normative text is the SDK's protocol.md and the API reference. This section summarises what an addon author needs.

URLs

The base URL is the manifest link without /manifest.json. All other requests are built from it:

GET {base}/manifest.json
GET {base}/{resource}/{type}/{id}.json
GET {base}/{resource}/{type}/{id}/{extra}.json

Resource	`type`	`id`	Response
`catalog`	the catalogue's type	the catalogue id from the manifest	`{ "metas": [ … ] }`
`meta`	the item's type	the item id from the catalogue	`{ "meta": { … } }`
`stream`	the item's type	the video id (a film: its own id; an episode: the episode id; `tv`: the channel id)	`{ "streams": [ … ] }`
`subtitles`	the item's type	the video id	`{ "subtitles": [ … ] }`
`addon_catalog`	from `addonCatalogs`	from `addonCatalogs`	`{ "addons": [ … ] }`

A query string on the manifest link is kept and added after .json of every request. Anything before /manifest.json is kept too; configurable addons put the user's settings there, for example https://addon.example.com/eyJsYW5nIjoiZW4ifQ/manifest.json.
SDK servers answer 404 {"err":"not found"} for unknown resources and 500 {"err":"handler error"} when a handler fails; they may also answer with a 307 redirect. Static hosts answer 404 for any file that does not exist.

Encoding: path segments and `extra`

resource, type and id are each encoded like JavaScript's encodeURIComponent: every byte except letters, digits and - _ . ! ~ * ' ( ) becomes %XX. So tt1234567:1:2 is sent as tt1234567%3A1%3A2.
extra is name=value pairs joined with &, each name and value encoded the same way: search=his%20girl&skip=100. A space is %20, never +; a literal & or = inside a value becomes %26 or %3D.
Extras that allow several values repeat the name: genre=Action&genre=Comedy. TS IPTV writes extras in the order the manifest declares them, with skip last, and leaves out the /{extra} segment when there are none.

Manifest

Field	Required	Meaning
`id`	yes	Reverse-DNS identifier, for example `com.example.myaddon`. The same id added again means an update.
`version`	yes	Version string, normally semver (`1.0.0`).
`name`	yes	Display name.
`description`	yes (spec)	One or two sentences.
`types`	yes	Content types: `movie`, `series`, `channel`, `tv`, or any other string.
`resources`	yes	`"catalog"`, `"meta"`, `"stream"`, `"subtitles"`, `"addon_catalog"`, or objects `{ "name": "stream", "types": ["movie"], "idPrefixes": ["ex_"] }`.
`catalogs`	yes (may be `[]`)	List of catalogues (below).
`idPrefixes`	no	Only ids starting with one of these are sent to the addon, for example `["ex_"]`.
`addonCatalogs`	no	Lists of other addons (`type`, `id`, `name`).
`behaviorHints`	no	`adult`, `p2p`, `configurable`, `configurationRequired`, `epgProvider`, all booleans.
`logo`, `background`, `contactEmail`	no	Logo (256×256 PNG), background image, contact address.

A catalogue is { "type", "id", "name", "extra": [ … ] }. The same id may be used for several types. Each extra entry is { "name", "isRequired", "options", "optionsLimit" }:

Extra	Meaning
`search`	Free-text search. `isRequired: true` makes a search-only catalogue that is never shown as a row.
`genre`	Filter; the values come from `options`. A required genre starts on its first option.
`skip`	Paging (below).
other names	Allowed; declare them the same way.

Older manifests use extraSupported/extraRequired string lists and a separate genres list; TS IPTV reads those too, but extra wins when both are present.

Paging

A catalogue page holds up to 100 items. The first page is requested without skip; the following pages with skip=100, skip=200 and so on. The specification says a page with fewer than 100 items is the end. TS IPTV is more lenient: it asks for the next page with skip equal to the number of items received so far and stops at an empty page, a page with no new ids, or an error answer after a short page (a static host's 404). Only declare skip if your catalogue has more than one page.

Catalogue items and details

Field	Where	Meaning
`id`, `type`, `name`	both	Required.
`poster`, `posterShape`	both	Image; shape `poster` (portrait, default), `square` or `landscape`.
`genres`, `releaseInfo`, `description`, `imdbRating`	both	Text shown on cards and on the detail page.
`background`, `logo`, `released`, `runtime`, `language`, `country`, `links`	meta	Detail page fields. `released` is ISO 8601; `runtime` is text such as `"92 min"`.
`videos`	meta	Episodes of a series (or a channel's videos). Without `videos`, the item has one video whose id is the item id.
`behaviorHints.defaultVideoId`, `behaviorHints.isLive`	meta	Open this video directly; a live item (`tv` implies live).

A video is { "id", "title", "released", "season", "episode", "thumbnail", "overview" }. Season 0 means specials. A released date in the future marks an upcoming episode. If a video carries its own streams array, those are the only streams used for it.

Streams

Each stream object has exactly one source and some labels:

Field	Meaning
`url`	A direct `https` (or `http`) link: MP4, MKV, HLS `.m3u8`, DASH `.mpd`.
`externalUrl`	A web page to open in a browser.
`name`	Short label, for example the quality.
`description` (older: `title`)	Longer label, may have several lines.
`behaviorHints.proxyHeaders.request`	HTTP headers to send with every request for this stream, for example `{ "User-Agent": "…", "Referer": "…" }`. The specification requires `notWebReady: true` alongside.
`behaviorHints.notWebReady`	The link cannot play directly in a web browser (not MP4, plain http, or needs headers).
`behaviorHints.bingeGroup`	Streams of the same group are preferred for the next episode.
`behaviorHints.filename`, `videoSize`	File name and size; helps players guess the format.
`behaviorHints.countryWhitelist`	ISO 3166-1 alpha-3 codes (lower case) where the stream works.

Other source fields exist in the specification; TS IPTV does not use them (see What TS IPTV plays). Order streams from highest to lowest quality.

Subtitles

GET {base}/subtitles/{type}/{videoId}.json, optionally with videoHash, videoSize and filename in extra, returns { "subtitles": [ { "id", "url", "lang", "label" } ] }. lang is an ISO 639-2 code such as eng; files are SRT or VTT. TS IPTV does not use subtitle addons yet.

Caching

Any response may carry cacheMaxAge, staleRevalidate and staleError (seconds). The SDK turns them into a Cache-Control header and also keeps them in the JSON. TS IPTV honours Cache-Control first, then these fields, then its own defaults (catalogues 1 hour, details 6 hours, streams 5 minutes), and never keeps stream answers longer than 5 minutes.

Types and ids

Types are free strings; movie, series, channel and tv are the common ones. Ids are opaque. Give your ids a prefix of your own (ex_news, tspd_his_girl_friday) and declare it in idPrefixes, so the player only asks your addon about your items. Episode ids are separate ids, for example tspd_superman_s1e1.

Complete example: the sample addon

TS IPTV publishes a small static addon, the Public Domain Sampler, as a live example and QA fixture. It has one film (His Girl Friday, 1940), one cartoon series (Fleischer Superman, 1941–43), both public domain on archive.org, and one live channel that plays the Mux public test stream (Big Buck Bunny © Blender Foundation, CC BY 3.0). Its manifest link is https://tsiptv-8bdd6.web.app/examples/stremio-sampler/manifest.json.

These are all its files; each one is exactly the URL a player requests:

manifest.json
catalog/movie/tspd-movie.json
catalog/movie/tspd-movie/genre=Comedy.json
catalog/series/tspd-series.json
catalog/tv/tspd-tv.json
meta/movie/tspd_his_girl_friday.json
meta/series/tspd_superman.json
meta/tv/tspd_test_hls.json
stream/movie/tspd_his_girl_friday.json
stream/series/tspd_superman_s1e1.json
stream/tv/tspd_test_hls.json

`manifest.json`

Download manifest.json

{
  "id": "org.tsiptv.publicdomain.static",
  "version": "1.0.0",
  "name": "Public Domain Sampler (static)",
  "description": "Public-domain films and cartoons from archive.org, plus a public HLS test channel. Static JSON on GitHub Pages.",
  "resources": ["catalog", "meta", "stream"],
  "types": ["movie", "series", "tv"],
  "idPrefixes": ["tspd_"],
  "catalogs": [
    { "type": "movie",  "id": "tspd-movie",  "name": "Public Domain Movies",
      "extra": [ { "name": "genre", "isRequired": false, "options": ["Comedy"] } ] },
    { "type": "series", "id": "tspd-series", "name": "Public Domain Cartoons" },
    { "type": "tv",     "id": "tspd-tv",     "name": "Test Channels" }
  ],
  "behaviorHints": { "adult": false, "p2p": false }
}

Three catalogues, one per type. The movie catalogue declares a genre extra with a single option, so exactly one extra file exists: catalog/movie/tspd-movie/genre=Comedy.json (a copy of the unfiltered list). idPrefixes is tspd_, and ids use _, never :, because every id becomes a file name.

`catalog/movie/tspd-movie.json`

Download

{
  "metas": [
    { "id": "tspd_his_girl_friday", "type": "movie", "name": "His Girl Friday",
      "poster": "https://archive.org/services/img/his_girl_friday",
      "releaseInfo": "1940", "genres": ["Comedy"] }
  ]
}

Requested as …/catalog/movie/tspd-movie.json. The catalogue does not declare skip, so this single page is the whole catalogue and no further page is requested.

`meta/series/tspd_superman.json`

Download

{
  "meta": {
    "id": "tspd_superman", "type": "series", "name": "Fleischer Superman (1941-43)",
    "poster": "https://archive.org/services/img/superman_the_mechanical_monsters",
    "releaseInfo": "1941-1943", "genres": ["Animation"],
    "description": "Fleischer Studios Superman cartoons, public domain.",
    "videos": [
      { "id": "tspd_superman_s1e1", "title": "The Mechanical Monsters",
        "season": 1, "episode": 1, "released": "1941-11-28T00:00:00.000Z",
        "thumbnail": "https://archive.org/services/img/superman_the_mechanical_monsters" }
    ]
  }
}

A series lists its episodes in videos. The episode id tspd_superman_s1e1 is what the stream request uses.

`stream/movie/tspd_his_girl_friday.json` and `stream/tv/tspd_test_hls.json`

Download

{
  "streams": [
    { "name": "archive.org", "description": "MP4 · 512kb",
      "url": "https://archive.org/download/his_girl_friday/his_girl_friday_512kb.mp4",
      "behaviorHints": { "filename": "his_girl_friday_512kb.mp4" } }
  ]
}

Download

{
  "streams": [
    { "name": "HLS", "description": "Mux public test stream",
      "url": "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8",
      "behaviorHints": { "notWebReady": true,
                         "proxyHeaders": { "request": { "User-Agent": "TSIPTV-Example/1.0" } } } }
  ]
}

The film's stream is a direct MP4 url with a filename hint. The live channel's stream is HLS and asks for a User-Agent header through proxyHeaders.request; TS IPTV sends it with every playlist and segment request. The remaining files follow the same pattern: series catalogue, tv catalogue, film details, channel details, episode stream, Comedy genre file.

Create your own addon

Option 1: static JSON files (no server)

Download the sample files above into a folder with the same tree.
Edit manifest.json: a new id (reverse-DNS of a domain you control), name, description, your own idPrefixes and catalogues.
For each catalogue, write catalog/{type}/{catalogId}.json. Add one file per genre option (catalog/{type}/{catalogId}/genre={option}.json) and, for more than 100 items, …/skip=100.json, …/skip=200.json.
For each item, write meta/{type}/{id}.json; for each film, episode or channel, stream/{type}/{videoId}.json.
Keep ids and extra values URL-safe: letters, digits, _ and -. Validate each file as JSON (VS Code shows errors as you type).
Test locally: in the folder run npx http-server . --cors -c-1 and add http://127.0.0.1:8080/manifest.json (Android emulator: http://10.0.2.2:8080/manifest.json).

Limits of static hosting: no free-text search (queries cannot be pre-generated), one file per genre and page, and no : in ids (the host would look for a file name with :, which Windows and some hosts do not allow).

Option 2: the Node.js SDK

With the official SDK (Node.js 12 or later) you write handlers instead of files, which allows search, large catalogues and computed answers. serveHTTP adds the CORS headers for you and turns the cacheMaxAge, staleRevalidate and staleError values your handlers return into a Cache-Control header.

package.json:

{
  "name": "my-publicdomain-addon",
  "version": "1.0.0",
  "main": "addon.js",
  "scripts": { "start": "node addon.js" },
  "dependencies": { "stremio-addon-sdk": "^1.6.10" }
}

addon.js (the sample addon with search, genre filter and paging):

const { addonBuilder, serveHTTP } = require('stremio-addon-sdk')

const ITEMS = [
  { id: 'tspd_his_girl_friday', type: 'movie', name: 'His Girl Friday',
    releaseInfo: '1940', genres: ['Comedy'],
    poster: 'https://archive.org/services/img/his_girl_friday',
    streams: [{ name: 'archive.org', description: 'MP4 512kb',
      url: 'https://archive.org/download/his_girl_friday/his_girl_friday_512kb.mp4',
      behaviorHints: { filename: 'his_girl_friday_512kb.mp4' } }] },
  { id: 'tspd_superman', type: 'series', name: 'Fleischer Superman (1941-43)',
    releaseInfo: '1941-1943', genres: ['Animation'],
    poster: 'https://archive.org/services/img/superman_the_mechanical_monsters',
    videos: [{ id: 'tspd_superman_s1e1', title: 'The Mechanical Monsters',
      season: 1, episode: 1, released: '1941-11-28T00:00:00.000Z',
      streams: [{ name: 'archive.org', description: 'MP4 512kb',
        url: 'https://archive.org/download/superman_the_mechanical_monsters/superman_the_mechanical_monsters_512kb.mp4' }] }] },
  { id: 'tspd_test_hls', type: 'tv', name: 'HLS Test Channel',
    posterShape: 'square', poster: 'https://archive.org/services/img/his_girl_friday',
    streams: [{ name: 'HLS', description: 'Mux public test stream',
      url: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8',
      behaviorHints: { notWebReady: true,
        proxyHeaders: { request: { 'User-Agent': 'TSIPTV-Example/1.0' } } } }] }
]
const PAGE = 100

const builder = new addonBuilder({
  id: 'org.example.publicdomain', version: '1.0.0', name: 'My Public Domain Addon',
  description: 'Public-domain films and cartoons, plus a public HLS test channel.',
  resources: ['catalog', 'meta', 'stream'], types: ['movie', 'series', 'tv'],
  idPrefixes: ['tspd_'],
  catalogs: ['movie', 'series', 'tv'].map(type => ({
    type, id: 'tspd-' + type, name: 'Public Domain ' + type,
    extra: [{ name: 'search' }, { name: 'genre', options: ['Animation', 'Comedy'] }, { name: 'skip' }]
  })),
  behaviorHints: { adult: false, p2p: false }
})

const preview = i => ({ id: i.id, type: i.type, name: i.name, poster: i.poster,
  posterShape: i.posterShape, genres: i.genres, releaseInfo: i.releaseInfo })

builder.defineCatalogHandler(({ type, id, extra }) => {
  let list = ITEMS.filter(i => i.type === type && id === 'tspd-' + type)
  if (extra.genre) list = list.filter(i => (i.genres || []).includes(extra.genre))
  if (extra.search) list = list.filter(i => i.name.toLowerCase().includes(extra.search.toLowerCase()))
  const skip = parseInt(extra.skip || '0', 10) || 0
  return Promise.resolve({ metas: list.slice(skip, skip + PAGE).map(preview), cacheMaxAge: 3600 })
})

builder.defineMetaHandler(({ type, id }) => {
  const i = ITEMS.find(x => x.id === id && x.type === type)
  if (!i) return Promise.resolve({ meta: null })
  const meta = preview(i)
  if (i.videos) meta.videos = i.videos.map(({ streams, ...v }) => v)
  return Promise.resolve({ meta, cacheMaxAge: 3600 })
})

builder.defineStreamHandler(({ type, id }) => {
  for (const i of ITEMS) {
    if (i.id === id && i.streams) return Promise.resolve({ streams: i.streams, cacheMaxAge: 600 })
    const v = (i.videos || []).find(v => v.id === id)
    if (v) return Promise.resolve({ streams: v.streams, cacheMaxAge: 600 })
  }
  return Promise.resolve({ streams: [] })
})

serveHTTP(builder.getInterface(), { port: process.env.PORT || 7000 })

Run npm install, then npm start. The SDK prints the manifest link, http://127.0.0.1:7000/manifest.json.
Add that link in TS IPTV on the same computer, or http://10.0.2.2:7000/manifest.json from an Android emulator, or http://<your computer's LAN address>:7000/manifest.json from a phone or TV on the same network.
To publish it, deploy to any Node.js host that gives you an HTTPS address, and use https://<your host>/manifest.json.

The SDK can also generate a configuration page (config in the manifest) and mount the addon in an existing Express app; see the SDK README.

Host it

HTTPS. The specification requires HTTPS for everything except 127.0.0.1. TS IPTV also accepts http://, with the warning “This addon does not use an encrypted connection”.
CORS. The specification requires Access-Control-Allow-Origin: * on every route, including /manifest.json. TS IPTV is an installed app and does not need it, but web-based players do, so add it.
Cache headers. A short Cache-Control: public, max-age=600 on catalogues and details is a good default; keep stream answers short-lived if the links expire.
Content type. Serve .json as application/json. No redirect from /file.json to /file.json/.

Host	What to do
GitHub Pages	Push the file tree to a repository and enable Pages. Add an empty `.nojekyll` file at the root so files are served unchanged. Pages already sends `Access-Control-Allow-Origin: *`. Manifest: `https://<user>.github.io/<repo>/manifest.json`.
Firebase Hosting	Add a header rule in `firebase.json`: `{"source": "*/.json", "headers": [{"key": "Access-Control-Allow-Origin", "value": "*"}]}`. TS IPTV's sample addon is hosted this way.
Netlify	A `_headers` file at the root with `/` and, on the next line, `Access-Control-Allow-Origin: `.
Vercel	`vercel.json`: `{"headers": [{"source": "/(.)", "headers": [{"key": "Access-Control-Allow-Origin", "value": ""}]}]}`.
Any web server	Serve the folder as static files and add the CORS header, for example in nginx: `add_header Access-Control-Allow-Origin *;`
Node.js SDK	Any Node.js host with HTTPS; `serveHTTP` sets the CORS headers itself; `Cache-Control` comes from the `cacheMaxAge` your handlers return.

A GitHub blob/ page or a file-sharing page is not an addon: the manifest link must return the JSON itself.

Add it in TS IPTV

Phone, tablet, iOS and desktop: Profile → Addons → Add addon. Android TV: Settings → Addons → Add addon (type the link with the on-screen keyboard).
Paste the manifest link (it ends with /manifest.json). A stremio://…/manifest.json install link also works; TS IPTV turns it into https://, or http:// for local and LAN hosts (localhost, 127.0.0.1, 10.x, 192.168.x, 172.16–31.x).
Choose Continue. The preview shows the name, version, host, content types, number of catalogues, whether the addon provides streams, and any warning (not encrypted, peer-to-peer, adult content).
Read and accept the notice (“Addons are third-party services, not operated by TS IPTV…”), then choose Add.
Discover appears: on phones between Home and History, on TV at the top of the Home rail. It shows one row per catalogue; open a title and choose a stream to play it.

If the manifest says configurationRequired, TS IPTV does not add it yet: choose Configure to open the addon's /configure page in your browser (on TV the address is shown as text), finish there, and paste the link it gives you. Manage addons (enable, reorder, update, remove) in the same Addons screen. Addon links can contain personal settings, so TS IPTV stores them encrypted and shows only the host.

Common mistakes

Mistake	Symptom	Fix
The link does not end with `/manifest.json`	“Enter the addon's manifest link. It ends with /manifest.json.”	Use the manifest link, not the addon's web page.
A manifest field missing (`id`, `name`, `version`, `types`, `resources`)	“This link did not return a valid addon manifest.”	Add the field; check the file is valid JSON.
`+` instead of `%20` in a static file name	Genre or search file not found	Players send `%20`; name files with URL-safe values only.
`:` in ids of a static addon	Files cannot be created on Windows, or 404s	Use `_` or `-` in ids.
Pages of 20 items	Other apps stop after the first page	Return 100 items per page; only the last page may be shorter.
`idPrefixes` that do not match your ids, or `"stream"` missing from `resources`	Details or streams never requested	Declare every resource you serve and a prefix all your ids share.
A video with its own `streams`	No other addon is asked for that video	Leave inline streams out unless they are the only ones.
`configurationRequired: true`	“This addon must be configured first.”	Configure it in the browser and paste the configured link.
A link on `127.0.0.1:11470`	“This address belongs to the Stremio app's own local server…”	That server belongs to another app; it is not an addon.
An old `/stremio/v1` addon	“This is an old-style addon that TS IPTV cannot use.”	Only the current HTTP protocol is supported.
An addon that offers only sources other than `url`	“No playable stream was found for this title.”	TS IPTV plays `url` streams only; see below.
No CORS header	Works in TS IPTV, fails in web players	Add `Access-Control-Allow-Origin: *`.
GitHub Pages without `.nojekyll`	Files starting with `_` missing	Add an empty `.nojekyll`.
Expired or signed stream links cached for long	Streams fail after a while	Keep `cacheMaxAge` short on stream answers.

What TS IPTV plays

Feature	Android	iOS	Desktop
`url` streams: HTTPS/HTTP MP4, HLS	Supported	Supported	Supported
`url` streams: DASH `.mpd` without DRM	Supported	Supported through the built-in VLC player; only the User-Agent and Referer headers are sent	Supported
`url` streams: MKV	Supported	May not play	Supported
`proxyHeaders.request`	All headers	Best effort	User-Agent and Referer only
`externalUrl`	Opens in your browser after you confirm; on a TV without a browser the link is shown as text. `stremio:///…` page links open the matching TS IPTV screen.
Torrent, Usenet, archive and YouTube streams	Not supported
Catalogues, genre filter, search, paging, series with seasons, live `tv` items	Supported
`configurable`, `configurationRequired`	Supported Through the addon's configuration page in the browser.
`adult`, `p2p` hints	Warnings when adding; adult addons need an 18+ confirmation and are left out of Discover rows and search.
Continue watching and resume for addon films and episodes	Supported
Subtitles, EPG addons (`epgProvider`), addon lists (`addon_catalog`), auto-play of the next episode	Not yet

TS IPTV has no built-in addons and does not suggest any. Addons can be disabled remotely only when a takedown request requires it.

Addon tương thích Stremio

Addon là gì

Giao thức

Đường dẫn

Mã hoá: các đoạn đường dẫn và extra

Manifest

Phân trang

Mục trong danh mục và thông tin chi tiết

Luồng

Phụ đề

Bộ nhớ đệm

Loại và mã

Ví dụ đầy đủ: addon mẫu

manifest.json

catalog/movie/tspd-movie.json

meta/series/tspd_superman.json

stream/movie/tspd_his_girl_friday.json và stream/tv/tspd_test_hls.json

Tự tạo addon

Cách 1: tệp JSON tĩnh (không cần máy chủ)

Cách 2: SDK cho Node.js

Đưa addon lên mạng

Thêm vào TS IPTV

Lỗi thường gặp

TS IPTV phát được những gì

Hướng dẫn liên quan

Stremio-compatible addons

What an addon is

The protocol

URLs

Encoding: path segments and extra

Manifest

Paging

Catalogue items and details

Streams

Subtitles

Caching

Types and ids

Complete example: the sample addon

manifest.json

catalog/movie/tspd-movie.json

meta/series/tspd_superman.json

stream/movie/tspd_his_girl_friday.json and stream/tv/tspd_test_hls.json

Create your own addon

Option 1: static JSON files (no server)

Option 2: the Node.js SDK

Host it

Add it in TS IPTV

Common mistakes

What TS IPTV plays

Related guides

Mã hoá: các đoạn đường dẫn và `extra`

`manifest.json`

`catalog/movie/tspd-movie.json`

`meta/series/tspd_superman.json`

`stream/movie/tspd_his_girl_friday.json` và `stream/tv/tspd_test_hls.json`

Encoding: path segments and `extra`

`manifest.json`

`catalog/movie/tspd-movie.json`

`meta/series/tspd_superman.json`

`stream/movie/tspd_his_girl_friday.json` and `stream/tv/tspd_test_hls.json`