iptv Documentation

Technical Documentation: iptv-org/iptv

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

IPTV [](https://github.com/iptv-org/iptv/actions/workflows/update.yml)

Collection of publicly available IPTV (Internet Protocol television) channels from all over the world.

Table of contents Copy Chapter

• 🚀 How to use?
• 📺 Playlists
• 🗓 EPG
• 🗄 Database
• 👨‍💻 API
• 📚 Resources
• 💬 Discussions
• ❓ FAQ
• 🛠 Contribution
• ⚖ Legal
• © License

How to use? Copy Chapter

Simply paste the link to one of the playlists into any video player that supports live streaming and press Open.

Playlists Copy Chapter

The main playlist containing all channels available in the repository can be found at:

https://iptv-org.github.io/iptv/index.m3u

Links to other playlists can be found in the PLAYLISTS.md file.

EPG Copy Chapter

Electronic Program Guide for most of the channels can be downloaded using utilities published in the iptv-org/epg repository.

Database Copy Chapter

All channel data is taken from the iptv-org/database repository. If you find any errors please open a new issue there.

API Copy Chapter

The API documentation can be found in the iptv-org/api repository.

Resources Copy Chapter

Links to other useful IPTV-related resources can be found in the iptv-org/awesome-iptv repository.

Discussions Copy Chapter

If you have a question or idea, welcome to the Discussions.

FAQ Copy Chapter

The answers to the most popular questions can be found in the FAQ.md file.

Contribution Copy Chapter

Please make sure to read the Contributing Guide before sending an issue or making a pull request.

And thank you to everyone who has already contributed!

Backers Copy Section

Contributors Copy Section

Legal Copy Chapter

No video files are stored in this repository. The repository simply contains user-submitted links to publicly available video stream URLs, which to the best of our knowledge have been intentionally made publicly by the copyright holders. If any links in these playlists infringe on your rights as a copyright holder, they may be removed by opening an issue. However, note that we have no control over the destination of the link, and just removing the link from the playlist will not remove its contents from the web. Note that linking does not directly infringe copyright because no copy is made on the site providing the link, and thus this is not a valid reason to send a DMCA notice to GitHub. To remove this content from the web, you should contact the web host that's actually hosting the content (not GitHub, nor the maintainers of this repository).

License Copy Chapter

Geo Blocking (`docs/geo-blocking.md`) Copy Section

Geo-blocking

Sometimes providers block streams from being played in certain countries or regions.

To avoid confusing these links with broken ones, we mark them with the label Geo-blocked:

#EXTINF:-1 tvg-id="ExampleTV.us@SD",Example TV (720p) [Geo-blocked]
https://example.com/playlist.m3u8

The easiest way to make sure the stream works outside your country is to use services like check-host.net or a VPN.

Playlists (`docs/playlists.md`) Copy Section

Playlists

The repository uses two types of playlists: internal and public.

Internal Copy Chapter

These playlists are located in the streams/ folder and contain all links currently available in the repository.

The links in these playlists are grouped by country and by the service from which the stream is broadcast. They are arranged this way solely for the convenience of moderating links.

In its simplest form, an internal playlist looks like this:

#EXTM3U
#EXTINF:-1 tvg-id="ExampleTV.us@SD",Example TV (720p)
https://example.com/playlist.m3u8

If there is a guide for one of the channels in the playlist in our EPG repository, the header will also include a link to it:

#EXTM3U x-tvg-url="https://example.com/guide.xml"

Since these playlists are processed primarily using scripts, we need to follow a few rules when editing them:

• All files must have the .m3u extension
• The playlist must begin with the header #EXTM3U
• Each link must comply with the Stream Description Scheme
• Lines must end with CRLF
• The file encoding must be UTF-8 without BOM

Public Copy Chapter

Unlike internal playlists, these playlists are created specifically for regular users.

They are generated automatically using the playlist:generate script every day at 00:00 UTC and then placed in a separate branch of gh-pages.

The links in these playlists are organized solely based on the channel's description in our database. For example, if a channel's broadcast area is listed as c/IT, the link to its stream will automatically be placed in the countries/it.m3u file.

Another difference from internal playlists is that public playlists include only the best available option for each channel, based on stream quality and labels. The exception is playlists in the raw/ folder.

Additionally, if the link includes a valid stream ID, the channel logo, category, broadcast country and language will be added to the description. For example:

#EXTM3U x-tvg-url="https://example.com/guide.xml”
#EXTINF:-1 tvg-id="ExampleTV.us@SD” tvg-logo="https://example.com/logo.png” group-title="Movies”,Example TV (720p)
https://example.com/playlist.m3u8

A complete list of public playlists can always be found in PLAYLISTS.md.

Scripts (`docs/scripts.md`) Copy Section

Scripts

The repository contains a few scripts created to automate routine processes and make it a bit easier to maintain.

For the scripts to work, you must have Node.js installed on your computer.

• act:check
• act:format
• act:update
• act:validate_issue
• act:validate_label
• api:load
• issue:validate
• playlist:format
• playlist:update
• playlist:generate
• playlist:validate
• playlist:lint
• playlist:test
• playlist:edit
• playlist:export
• readme:update
• report:create
• lint
• test

act:check Copy Chapter

Runs the check workflow locally. Depends on nektos/gh-act.

npm run act:check

act:format Copy Chapter

Runs the format workflow locally. Depends on nektos/gh-act.

npm run act:format

act:update Copy Chapter

Runs the update workflow locally. Depends on nektos/gh-act.

npm run act:update

act:validate_issue Copy Chapter

Runs the validate_issue workflow locally. Depends on nektos/gh-act.

npm run act:validate_issue -- -e .github/mocks/events/issue_opened.json

act:validate_label Copy Chapter

Runs the validate_label workflow locally. Depends on nektos/gh-act.

npm run act:validate_label -- -e .github/mocks/events/issue_approved.json --actor Bob

api:load Copy Chapter

Downloads the latest channel and stream data from the iptv-org/api repository.

npm run api:load

issue:validate Copy Chapter

Checks the request for errors and, if any are found, saves a list of them to the file temp/logs/errors.txt

npm run issue:validate --body="### Stream URL..." --labels="streams:add"

playlist:format Copy Chapter

Formats internal playlists. The process includes URL normalization, duplicate removal, removing invalid IDs, and sorting links by channel name, quality, and label.

# format all playlists in the streams/ directory
npm run playlist:format

# format a specific playlist
npm run playlist:format path/to/playlist.m3u

playlist:update Copy Chapter

Triggers an update of internal playlists. The process involves processing approved requests from issues.

npm run playlist:update

playlist:generate Copy Chapter

Generates all public playlists.

npm run playlist:generate

playlist:validate Copy Chapter

Checks IDs and links in internal playlists for errors.

# check all playlists in the streams/ directory
npm run playlist:validate

# check a specific playlist
npm run playlist:validate path/to/playlist.m3u

playlist:lint Copy Chapter

Checks internal playlists for syntax errors.

# check all playlists in the streams/ directory
npm run playlist:lint

# check a specific playlist
npm run playlist:lint path/to/playlist.m3u

playlist:test Copy Chapter

Tests links in internal playlists.

# check all playlists in the streams/ directory
npm run playlist:test

# check a specific playlist
npm run playlist:test path/to/playlist.m3u

This command will run an automatic check of all links in the playlist and display their status:

/* Detailed source-code truncated for AI context efficiency. */

Also, if you add the --fix option to the command, the script will automatically remove all broken streams it finds from your local copy of the playlists:

npm run playlist:test streams/fr.m3u -- --fix

playlist:edit Copy Chapter

A utility for quick streams mapping.

npm run playlist:edit path/to/playlist.m3u

playlist:export Copy Chapter

Creates a JSON file with all streams for the iptv-org/api repository.

npm run playlist:export

readme:update Copy Chapter

Updates the configuration and list of available streams in PLAYLISTS.md.

npm run readme:update

report:create Copy Chapter

Creates a report on current issues.

npm run report:create

lint Copy Chapter

Checks the utility scripts themselves for syntax errors.

npm run lint

test Copy Chapter

Runs a test of all the scripts described above.

npm test

Stream Description Scheme (`docs/stream-description-scheme.md`) Copy Section

Stream Description Scheme

For a stream to be approved, its description must follow this template:

#EXTINF:-1 tvg-id="STREAM_ID",STREAM_TITLE (QUALITY) [LABEL]
STREAM_URL

Example:

#EXTINF:-1 tvg-id="ExampleTV.us@East",Example TV East (720p) [Geo-blocked]
https://example.com/playlist.m3u8

Also, if necessary, you can specify a custom HTTP User-Agent and HTTP Referrer through the #EXTVLCOPT directive:

#EXTINF:-1 tvg-id="ExampleTV.us",Example TV
#EXTVLCOPT:http-referrer=http://example.com/
#EXTVLCOPT:http-user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64)
http://example.com/stream.m3u8

Stream Id (`docs/stream-id.md`) Copy Section

Stream ID

A stream ID is a unique identifier for a stream that consists of a channel ID and a feed ID separated by the @ symbol.

ExampleTV.us@HD

Channel ID Copy Chapter

This is a unique channel ID that consists of the channel name (without spaces or special characters) followed by the country code, separated by a period.

ExampleTV.us

Feed ID Copy Chapter

The Feed ID is simply the name of the feed with all spaces and special characters removed.

It usually indicates the broadcast quality, time shift, source, or broadcast region. For example:

• HD
• Plus1
• Pluto
• WGTQ
• East
• MENA

A complete list of all channel and feed IDs can always be found on iptv-org.github.io.

If a particular channel is not on the list, you can always add it using this form. Similarly, you can use this form to add a missing feed.

Stream Testing (`docs/stream-testing.md`) Copy Section

Stream Testing

To make sure a stream link is working properly, just follow these simple steps:

1. Open it in a media player that supports HLS or DASH streams. In the examples below, we will use VLC media player.
2. Watch the broadcast for at least a minute. Make sure playback is stable and doesn't stop abruptly (some test streams cut off after 15–30 seconds).
3. Try restarting the stream. Make sure it isn't looping on a repeating segment and remains available.

If the stream isn't playing, try opening the player's error log. You can usually find the exact cause there. In VLC, it is located under Tools -> Messages.

If the stream won't play in your media player but works fine in a web browser, the issue is likely missing HTTP User-Agent and/or HTTP Referrer headers.

In this case, open the stream in your browser. Press F12, go to the Network tab, and filter the requests for m3u or mpd:

Then switch to the Headers tab, scroll down, and copy the User-Agent and Referer values:

Next, open any text editor and paste the link along with the parameters you found, formatted like this:

#EXTM3U
#EXTINF:-1,Example TV
#EXTVLCOPT:http-referrer=https://example.com
#EXTVLCOPT:http-user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64)
https://example.com/playlist.m3u8

Save the file with .m3u extension, then open it in your media player. In most cases, it should work immediately.

To test links that are already in the repository, you can simply run the playlist:test script.

Tokenized Links (`docs/tokenized-links.md`) Copy Section

Tokenized Links

Tokenized links are personalized hyperlinks that contain a unique, machine-generated string of characters (a token) to grant access to an IPTV stream.

Examples:

• https://example.com/index.m3u8?token=9f192891-eca5-2435-b9cb-147f376cdc1e
• https://example.com/index.m3u8?s=aWE0maGFzaF92YWx1
• https://example.com/index.m3u8?wmsAuthSign=c2bWU9Ni8yMC8yMDIVydmVyX3Rp2IDc6MDk6MjAgUmFsaWRtaWE0maGFzaF92YWx1ZTE5SkNSQkhqUG5JZVRRPT0md51dGVzPTMwJmlkPTZhMzZlNT1lRzlsZG4rOXYwZTIzNDk

The tokens in these links are periodically updated by the provider, causing the link to stop working shortly after.

In some cases, the link also includes an expiration date in UNIX timestamp format, which indicates exactly when the link will stop working:

https://example.com/index.m3u8?token=2IDc6MDk6MjAgUmF&e=1813661332 (1813661332 => 2027-06-22T10:48:52.000Z)

Workflows (`docs/workflows.md`) Copy Section

Workflows

To automate running the scripts, we use GitHub Actions workflows.

Each workflow includes its own set of scripts that can be run either manually or in response to a repository event.

check Copy Chapter

Sequentially runs the api:load, playlist:lint, and playlist:validate scripts whenever a new pull request is opened, blocking the merge if it detects any errors.

format Copy Chapter

Sequentially runs the api:load, playlist:format, playlist:lint, and playlist:validate scripts.

update Copy Chapter

Runs every day at 0:00 UTC. It sequentially executes the api:load, playlist:update, playlist:lint, playlist:validate, playlist:generate, playlist:export, and readme:update scripts, then automatically deploys the updated files if successful.

validate_issue Copy Chapter

Runs when an issue is opened or edited. It checks the requests for errors using issue:validate script and, if any are found, the bot posts them in the comments.

validate_label Copy Chapter

Triggers when a new label is added to an issue. It checks the label, and if it's incorrect, the bot deletes it and leaves a comment explaining why.

Xtream Codes (`docs/xtream-codes.md`) Copy Section

Xtream Codes Copy Section

Most Xtream Codes stream links look like this:

http(s)://{hostname}:{port}/{username}/{password}/{channelID} (the port is often 25461)

To make sure a link leads to an Xtream Codes server, copy the hostname, port, username, and password into the URL format below and try opening it in your browser:

http(s)://{hostname}:{port}/panel_api.php?username={username}&password={password}

If the page loads a response, it confirms you are dealing with an Xtream Codes server.

--- METRICS ---

• Files Extracted: 10
• Estimated Token Budget: ~4949 tokens
• Canonical Reference: https://codewiki.google/github.com/iptv-org/iptv