How to Contribute to the IPTV Repository: A Complete Guide for Stream Contributors

You can contribute to the iptv-org/iptv repository by editing .m3u files in the streams/ directory, following the #EXTINF format specification, and passing the automated validation pipeline that tests every URL for reachability.

Learning how to contribute to the iptv repository allows you to help maintain the world's largest collection of publicly available IPTV streams. The project uses a fully automated pipeline to validate submissions, ensuring that only working, properly formatted streams reach the public playlists generated daily.

Understanding the Repository Architecture

The iptv-org/iptv repository organizes its data and automation logic into three primary directories. Understanding this layout is essential before making any changes.

The streams/ Directory

The streams/ folder contains the raw playlist data. Each file represents one country using the ISO 3166-1 alpha-2 code (e.g., streams/us.m3u for United States streams, streams/fr.m3u for France). Every entry within these files must follow the stream description scheme parsed by scripts/core/playlistParser.ts:

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

The scripts/ Directory

Located at scripts/, this directory houses the TypeScript utilities that power the automation. Key files include:

• scripts/commands/playlist/format.ts – Normalizes URLs, removes duplicates, and sorts entries.
• scripts/commands/playlist/validate.ts – Validates channel IDs and URL structures against the database.
• scripts/commands/playlist/test.ts – Probes every stream URL to verify reachability.

The tests/ Directory

The tests/ folder contains Jest test suites that verify the script logic. These run alongside the playlist commands to ensure the formatting and validation utilities themselves remain functional.

How the Automation Pipeline Validates Contributions

When you open a pull request, GitHub Actions execute a strict sequence of checks defined in package.json. These commands ensure that every contribution meets the repository's quality standards before merging.

The pipeline executes four primary stages:

1. npm run playlist:format – Invokes scripts/commands/playlist/format.ts to normalize all URLs, enforce consistent spacing, remove duplicate entries, and alphabetize streams by title.

2. npm run playlist:lint – Checks M3U syntax using the rules defined in m3u-linter.json, catching malformed #EXTINF lines or invalid headers.

3. npm run playlist:validate – Runs scripts/commands/playlist/validate.ts to verify that tvg-id values exist in the iptv-org/database and that URLs follow allowed protocols.

4. npm run playlist:test – Executes scripts/commands/playlist/test.ts to perform HTTP requests against every stream URL, flagging unreachable or dead links.

If any script reports an error, the pull request cannot be merged. This automated enforcement guarantees that the public playlists generated from the streams/ directory contain only working, properly formatted links.

Step-by-Step Guide to Contributing Streams

Follow this workflow to ensure your contribution passes all automated checks and gets merged quickly.

Choose Your Contribution Method

You have two primary paths for contributing:

• Open an Issue: Use the repository's issue templates to request additions or report broken streams without editing files directly.
• Submit a Pull Request: Edit the .m3u files directly for faster integration, which is the recommended path for developers comfortable with Git.

Add or Edit Stream Entries

Locate the correct country file in streams/ using the two-letter country code. If adding a US channel, edit streams/us.m3u. Append your entry using the exact format enforced by scripts/core/playlistParser.ts:

#EXTINF:-1 tvg-id="ExampleChannel.us" tvg-logo="https://example.com/logo.png",Example Channel (1080p) [Geo-blocked]
https://example.com/stream/playlist.m3u8

Key formatting rules:

• The tvg-id must match an entry in the iptv-org/database.
• Quality indicators like (1080p) or (720p) should follow the title.
• Labels like [Geo-blocked] or [Not 24/7] must appear at the end of the title line.

Run Local Validation Checks

Before committing, execute the validation pipeline locally to catch errors early. From the repository root, run:

# Format and normalize the playlist

npm run playlist:format

# Check M3U syntax

npm run playlist:lint

# Validate channel IDs and URLs

npm run playlist:validate

# Test URL reachability for a specific file

npm run playlist:test streams/us.m3u

If the test script reports dead links, you can automatically remove them using the --fix flag:

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

Submit Your Pull Request

Once all local checks pass:

1. Commit your changes with a clear message describing the addition or fix.
2. Push to a new branch on your fork.
3. Open a pull request against the master branch of iptv-org/iptv.
4. Wait for the GitHub Actions workflow to complete. If checks fail, review the logs, fix the issues locally, and push the corrections.

Handling Special Contribution Cases

Certain scenarios require specific procedures beyond standard stream additions.

Reporting Broken Streams

If you encounter a dead stream but do not want to edit files manually, use the "Broken Stream" issue template. This creates a structured report that maintainers can act upon. Alternatively, run the test script locally with the --fix flag to clean your local copy before submitting a removal PR.

Identifying Prohibited Xtream Codes Links

The repository strictly forbids Xtream Codes links, which are proprietary IPTV panel URLs typically containing /get.php?username= patterns. The Contributing Guide provides specific patterns to identify these. Any PR containing such links will be rejected by automated checks or manual review.

Submitting Removal Requests

Only channel owners or authorized representatives may request stream removal. You must use the copyright claim issue form and provide proof of ownership. This process is separate from bug reports or broken stream notifications.

Summary

• The iptv-org/iptv repository stores streams in streams/ as .m3u files, one per country, using a strict #EXTINF format parsed by scripts/core/playlistParser.ts.
• Every contribution must pass four automated checks—format, lint, validate, and test—implemented in scripts/commands/playlist/ and enforced via GitHub Actions.
• Contributors should run npm run playlist:test locally with the --fix flag to remove dead links before submitting, ensuring PRs pass CI on the first attempt.
• Special procedures exist for reporting broken streams, identifying prohibited Xtream Codes links, and submitting copyright removal requests through specific issue templates.

Frequently Asked Questions

What file format should I use when adding streams to the IPTV repository?

You must use the M3U playlist format with specific #EXTINF metadata tags. Each entry requires a line starting with #EXTINF:-1 tvg-id="CHANNEL_ID",Channel Name (Quality) [Label] followed by the stream URL on the next line. This format is strictly enforced by the parser in scripts/core/playlistParser.ts and the formatting script in scripts/commands/playlist/format.ts.

How do I test if my stream URLs work before submitting a contribution?

Run the local validation pipeline using the npm scripts defined in package.json. Execute npm run playlist:format to normalize entries, npm run playlist:lint to check syntax, and npm run playlist:test streams/xx.m3u (replacing xx with the country code) to probe URL reachability. If you want to automatically remove dead links from your local copy, append the --fix flag: npm run playlist:test streams/xx.m3u -- --fix.

Can I contribute streams from any country to the IPTV repository?

Yes, you can contribute streams from any country by editing the corresponding .m3u file in the streams/ directory. Each country uses a two-letter ISO 3166-1 alpha-2 code (e.g., us.m3u for the United States, fr.m3u for France). If a file does not exist for a particular country, you may create it following the naming convention and format specifications outlined in the Contributing Guide.

What happens if my pull request fails the automated checks?

If your pull request fails any of the GitHub Actions workflows, it cannot be merged until the issues are resolved. The CI pipeline runs the same scripts you can execute locally: formatting, linting, validation, and URL testing. Check the Action logs to identify which check failed—common issues include malformed #EXTINF lines, invalid tvg-id values, unreachable URLs, or formatting inconsistencies. Fix the errors locally, commit the changes, and push to your branch; the checks will rerun automatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}