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

> Learn how to contribute to the iptv repository by editing .m3u files and passing validation. Follow our guide to add your streams to iptv-org/iptv.

- Repository: [iptv-org/iptv](https://github.com/iptv-org/iptv)
- Tags: how-to-guide
- Published: 2026-02-25

---

**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`](https://github.com/iptv-org/iptv/blob/main/scripts/core/playlistParser.ts):

```text
#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`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/playlist/format.ts) – Normalizes URLs, removes duplicates, and sorts entries.
- [`scripts/commands/playlist/validate.ts`](https://github.com/iptv-org/iptv/blob/main/scripts/commands/playlist/validate.ts) – Validates channel IDs and URL structures against the database.
- [`scripts/commands/playlist/test.ts`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/m3u-linter.json), catching malformed `#EXTINF` lines or invalid headers.

3. **`npm run playlist:validate`** – Runs [`scripts/commands/playlist/validate.ts`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/scripts/core/playlistParser.ts):

```text
#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:

```bash

# 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:

```bash
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`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/scripts/core/playlistParser.ts) and the formatting script in [`scripts/commands/playlist/format.ts`](https://github.com/iptv-org/iptv/blob/main/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`](https://github.com/iptv-org/iptv/blob/main/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.