Patch 2026.09.2 (#50642)

* Move docs/ to root directory

* Fix file name

* Update scripts.md

* Delete playlist-structure.md

* Create playlists.md

* Update stream-testing.md

* Create geo-blocking.md

* Create stream-id.md

* Update CONTRIBUTING.md

.github/docs/playlist-structure.md

@@ -1,13 +0,0 @@
-# Playlist Structure
-
-All links in the repository are stored in the [streams/](../../streams) folder as [M3U](https://en.wikipedia.org/wiki/M3U) playlists, grouped by the sources from which they are broadcast. They are arranged this way solely for the convenience of moderating links and are not intended for use by end users.
-
-All links undergo automatic filtering and are sorted according to data in our [database](https://github.com/iptv-org/database), so there is no need to sort anything manually. For more info, see [Scripts](./scripts.md).
-
-In order for the scripts to process these files correctly, you must follow a strict structure:
-
-- All files must have the `.m3u` extension
-- The playlist must begin with the header `#EXTM3U`
-- Each link must comply with the [Stream Description Scheme](./stream-description-scheme.md)
-- Lines must end with [CRLF](https://developer.mozilla.org/en-US/docs/Glossary/CRLF)
-- The file encoding must be UTF-8 without BOM

CONTRIBUTING.md

@@ -15,17 +15,18 @@
 You have several options:
 
 1. Create a new request using this [form](https://github.com/iptv-org/iptv/issues/new?assignees=&labels=streams:add&projects=&template=1_streams_add.yml&title=Add%3A+) and, if approved, the link will automatically be added to the playlist on the next update.
-2. Add the link to the playlist directly using a [pull request](https://github.com/iptv-org/iptv/pulls). See [Playlist Structure](./.github/docs/playlist-structure.md).
+2. Add the link to the playlist directly using a [pull request](https://github.com/iptv-org/iptv/pulls). See [Playlists](./docs/playlists.md).
 
 Regardless of which option you choose, please perform the following checks before posting your request:
 
+- Make sure you are using a valid [stream ID](./docs/stream-id.md).
+- Make sure the channel is not on our blocklist. The easiest way to do this is through [iptv-org.github.io](https://iptv-org.github.io/).
 - Make sure the link is not already in the playlist by [searching](https://github.com/search?q=repo%3Aiptv-org%2Fiptv+http%3A%2F%2Fexample.com&type=code) the repository.
-- Make sure the link you want to add is stable and works properly. See [Stream Testing](./.github/docs/stream-testing.md).
-- Make sure the link does not lead to a [Xtream Codes](./.github/docs/xtream-codes.md) server. [Why don't you accept links to Xtream Codes servers?](./FAQ.md#why-dont-you-accept-links-to-xtream-codes-servers).
-- Make sure the link is not [tokenized](./.github/docs/tokenized-links.md).
+- Make sure the link you want to add is stable and works properly. See [Stream Testing](./docs/stream-testing.md).
+- Make sure the link is not [geo-blocked](./docs/geo-blocking.md). If it is, do not forget to mention this in your request.
+- Make sure the link does not lead to a [Xtream Codes](./docs/xtream-codes.md) server. [Why don't you accept links to Xtream Codes servers?](./FAQ.md#why-dont-you-accept-links-to-xtream-codes-servers).
+- Make sure the link is not [tokenized](./docs/tokenized-links.md).
 - Make sure the link leads directly to the broadcast without unnecessary redirects.
-- Make sure the channel is in our database. This can be verified through [iptv-org.github.io](https://iptv-org.github.io/). If your desired channel is not on the list, you first must add it via a [request](https://github.com/iptv-org/database/issues/new?template=01_channels_add.yml).
-- Make sure the channel isn't on our blocklist. This can also be verified through [iptv-org.github.io](https://iptv-org.github.io/).
 
 If the broadcast only works in certain countries or is periodically interrupted, please indicate this in your request.
 
@@ -49,7 +50,7 @@ Fill out this [form](https://github.com/iptv-org/iptv/issues/new?assignees=&labe
 The only thing before publishing your report is to make sure that:
 
 - The link is still in our playlists. You can verify this by [searching](https://github.com/search?q=repo%3Aiptv-org%2Fiptv+http%3A%2F%2Fexample.com&type=code) the repository.
-- The link is completely broken and is not just [geo-blocked](https://en.wikipedia.org/wiki/Geo-blocking). See [Stream Testing](./.github/docs/stream-testing.md).
+- The link is completely broken and is not just [geo-blocked](https://en.wikipedia.org/wiki/Geo-blocking). See [Stream Testing](./docs/stream-testing.md).
 
 **IMPORTANT:** An issue without a valid stream link will be closed immediately.
 
@@ -66,13 +67,13 @@ The channel will also be added to our [blocklist](https://github.com/iptv-org/da
 - `.github/`
   - `DISCUSSION_TEMPLATE/`: Contains discussion templates for the repository.
   - `ISSUE_TEMPLATE/`: Contains issue templates for the repository.
-  - `workflows/`: Contains [GitHub Actions](https://docs.github.com/en/actions/quickstart) workflows. See [Workflows](./.github/docs/workflows.md).
+  - `workflows/`: Contains [GitHub Actions](https://docs.github.com/en/actions/quickstart) workflows. See [Workflows](./docs/workflows.md).
   - `CODE_OF_CONDUCT.md`: Rules you shouldn't break if you don't want to get banned.
 - `.readme/`
   - `preview.png`: Image displayed in the `README.md`.
   - `template.md`: Template configuration for `PLAYLISTS.md`.
-- `scripts/`: Contains internal utility scripts used in the repository. See [Scripts](./.github/docs/scripts.md).
-- `streams/`: Contains internal playlists with all streams. See [Playlist Structure](./.github/docs/playlist-structure.md).
+- `scripts/`: Contains internal utility scripts used in the repository. See [Scripts](./docs/scripts.md).
+- `streams/`: Contains internal playlists with all streams. See [Playlist Structure](./docs/playlist-structure.md).
 - `tests/`: Contains test suites to validate project scripts.
 - `CONTRIBUTING.md`: The file you are currently reading.
 - `PLAYLISTS.md`: Automatically updated list of available playlists.

docs/geo-blocking.md

@@ -0,0 +1,12 @@
+# 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`:
+
+```m3u
+#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](https://check-host.net/check-http) or a [VPN](https://en.wikipedia.org/wiki/Virtual_private_network).

docs/playlists.md

@@ -0,0 +1,51 @@
+# Playlists
+
+The repository uses two types of playlists: internal and public.
+
+## Internal
+
+These playlists are located in the [streams/](../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](https://github.com/iptv-org/epg/blob/master/GUIDES.md) 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](./stream-description-scheme.md)
+- Lines must end with [CRLF](https://developer.mozilla.org/en-US/docs/Glossary/CRLF)
+- The file encoding must be UTF-8 without BOM
+
+## Public
+
+Unlike internal playlists, these playlists are created specifically for regular users.
+
+They are generated automatically using the [playlist:generate](./scripts.md#playlistgenerate) script every day at 00:00 UTC and then placed in a separate branch of [gh-pages](https://github.com/iptv-org/iptv/tree/gh-pages).
+
+The links in these playlists are organized solely based on the channel's description in our [database](https://github.com/iptv-org/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](./stream-id.md), 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](../PLAYLISTS.md).

docs/scripts.md

@@ -10,6 +10,7 @@ For the scripts to work, you must have [Node.js](https://nodejs.org/en) installe
 - [act:validate_issue](#actvalidate_issue)
 - [act:validate_label](#actvalidate_label)
 - [api:load](#apiload)
+- [issue:validate](#issuevalidate)
 - [playlist:format](#playlistformat)
 - [playlist:update](#playlistupdate)
 - [playlist:generate](#playlistgenerate)
@@ -71,6 +72,14 @@ Downloads the latest channel and stream data from the [iptv-org/api](https://git
 npm run api:load
 ```
 
+## issue:validate
+
+Checks the request for errors and, if any are found, saves a list of them to the file `temp/logs/errors.txt`
+
+```sh
+npm run issue:validate --body="### Stream URL..." --labels="streams:add"
+```
+
 ## playlist:format
 
 Formats internal playlists. The process includes [URL normalization](https://en.wikipedia.org/wiki/URI_normalization), duplicate removal, removing invalid IDs, and sorting links by channel name, quality, and label.

docs/stream-id.md

@@ -0,0 +1,32 @@
+# 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
+
+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
+
+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](https://iptv-org.github.io/).
+
+If a particular channel is not on the list, you can always add it using this [form](https://github.com/iptv-org/database/issues/new?template=01_channels_add.yml). Similarly, you can use this [form](https://github.com/iptv-org/database/issues/new?template=04_feeds_add.yml) to add a missing feed.

docs/stream-testing.md

@@ -5,7 +5,6 @@ To make sure a stream link is working properly, just follow these simple steps:
 1. Open it in a media player that supports [HLS](https://en.wikipedia.org/wiki/HTTP_Live_Streaming) or [DASH](https://en.wikipedia.org/wiki/Dynamic_Adaptive_Streaming_over_HTTP) streams. In the examples below, we will use [VLC media player](https://www.videolan.org/vlc/index.html).
 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.
-4. Make sure the stream works for others too. You can verify this by using services like [check-host.net](https://check-host.net/) or a [VPN](https://en.wikipedia.org/wiki/Virtual_private_network).
 
 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`.