iptv/CONTRIBUTING.md

Contributing Guide

Before submitting your contribution, please make sure to take a moment and read through the following guidelines:

• Issue Reporting Guidelines
• Pull Request Guidelines
• Stream Description Scheme
• Project Structure

Issue Reporting Guidelines

Request a Channel

To request a channel, create an issue and complete all details requested. Understand that our community of volunteers will try to help you, but if a public link cannot be found, there is little we can do. (IMPORTANT: the issue should contain a request for only one channel, otherwise it will be closed immediately)

Report a Broken Stream

To report a broadcast that is not working, create an issue with a description of the channel. (IMPORTANT: an issue should contain a report for only one channel, otherwise it will be closed immediately)

Content Removal Request

If you find any content in the repository that you own and you would like us to remove, please create an issue and provide all necessary information. If the request is granted, the specified content will be removed from the repository within one business day.

Pull Request Guidelines

Add or Replace a Stream

If you would like to replace a broken stream or add a new one, please do the following:

• make sure that the link you want to add works by using a program like VLC media player
• check if the channel is working outside your country by using a VPN or use a service like streamtest.in
• find out from which country the channel is being broadcasted. This information can usually be found on lyngsat.com or wikipedia.org. If you are unable to determine which country the channel belongs to, add the channel onto the channels/unsorted.m3u playlist
• find the corresponding ISO_3166-2 code for the country
• open the /streams folder and find the file that has the same code in its name and open it
• if broken, find the broken link in this file and replace it with working one
• if new, at the very end of this file add a link to the channel with a description
• if the broadcast is not available outside of a certain country, add the label [Geo-blocked] to the end of the channel name and list these countries in the tvg-country attribute
• if the broadcast is not available 24 hours a day, add the label [Not 24/7]
• commit all changes and send a pull request

Update README.md

• open .readme/template.md
• make the necessary changes
• commit all changes and send a pull request

Update this Guide

• open .github/CONTRIBUTING.md
• make the necessary changes
• commit all changes and send a pull request

Stream Description Scheme

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

#EXTINF:-1 tvg-id="CHANNEL_ID",CHANNEL_NAME (RESOLUTION) [LABEL]
STREAM_URL

Attribute	Description	Required	Valid values
CHANNEL_ID	Channel ID.	Optional	Full list of supported channels could be found on iptv-org.github.io
CHANNEL_NAME	Full name of the channel. May contain any characters except: ,, (, ), [, ]. It is recommended to use the name listed on lyngsat or wikipedia if possible.	Required	-
RESOLUTION	Maximum stream resolution.	Optional	2160p, 1080p, 720p, 480p, 360p etc
LABEL	Specified in cases where the broadcast for some reason may not be available to some users.	Optional	Geo-blocked or Not 24/7
STREAM_URL	Stream URL.	Required	-

Example:

#EXTINF:-1 tvg-id="ExampleTV.ua",Example TV (720p) [Not 24/7]
https://example.com/playlist.m3u8

Also, if necessary, you can specify custom HTTP User-Agent and Referrer via the #EXTVLCOPT tag:

#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

Each stream also have a status attribute which is updated daily by the iptv-bot. The attribute can have one of the following values:

• online - stream was successfully loaded
• blocked - server returned HTTP code 403 Forbidden
• timeout - request time exceeded 60 seconds
• error - stream could not be loaded for some other reason

Project Structure

• .github/
  • ISSUE_TEMPLATE/: issue templates for the repository.
  • workflows/
    • auto-update.yml: GitHub workflow that launches daily playlist updates (at 0:00 and 12:00 UTC).
    • check.yml: GitHub workflow that checks every pull request for syntax errors and blocked channels.
  • CODE_OF_CONDUCT.md: rules you shouldn't break if you don't want to get banned.
• .readme/
  • config.json: config for the markdown-include package, which is used to compile everything into one README.md file.
  • preview.png: image displayed in the README.md.
  • supported-categories.md: list of supported categories.
  • supported-regions.md: list of supported regions.
  • template.md: template for README.md.
• scripts/: contains all the scripts used in GitHub workflows.
• streams/: contains all streams broken down by the country from which they are broadcast.
  • ...
  • unsorted.m3u: playlist with channels not yet sorted.
• tests/: contains tests to check the scripts.
• CONTRIBUTING.md: file you are currently reading.
• README.md: project description generated from the contents of the .readme/ folder.