How to Add a New Country or Region to the Free-TV IPTV Playlist

To add a new country to the Free-TV IPTV playlist, create a Markdown channel list in the lists/ directory, register the ISO-3166-1 alpha-2 code in make_playlist.py, optionally update flag_order.txt for positioning, and run the playlist generator to produce the updated M3U files.

The Free-TV/IPTV repository automatically aggregates IPTV channels into standardized M3U playlists using a Python-based build system. When you need to add a new country or region to the IPTV playlist, you must follow a specific four-step workflow that integrates with the existing automation in make_playlist.py.

Step 1 — Create the Channel List File

Each geographic region requires a dedicated Markdown file in the lists/ directory (e.g., lists/myland.md). This file must contain a specific HTML heading and table structure that the parser recognizes.

The file must start with an <h1> tag defining the group name, followed by a pipe-delimited table with five columns: #, Channel name, URL, Logo, and EPG.

Required Markdown Format

<h1>Myland TV</h1>

| # | Channel name | URL | Logo | EPG |

|---|--------------|-----|------|-----|
| 1 | Myland News | [>](http://myland.example.com/news.m3u8) | <img src="https://i.imgur.com/NewsLogo.png" width="100"> | |
| 2 | Myland Sports | [>](http://myland.example.com/sports.m3u8) | <img src="https://i.imgur.com/SportLogo.png" width="100"> | |

The URL Marker Syntax

The [>] marker preceding the URL tells make_playlist.py that the stream is valid and should be included in the generated playlist (see line 53 of the script). Logo images typically use Imgur URLs with a width of 100 pixels, while empty EPG cells are acceptable provided the column remains present.

Step 2 — Register the Country Code

The generator assigns the tvg-country attribute using the COUNTRY_CODES dictionary defined at lines 6–92 of make_playlist.py. You must map your new country's filename (without extension) to its ISO-3166-1 alpha-2 code.

Add a new entry following the existing pattern:

COUNTRY_CODES = {
    # ... existing entries ...

    "myland": "ML",
}

The dictionary key must match the lowercase filename of your Markdown list (e.g., "myland" for lists/myland.md). The two-letter value becomes the tvg-country value in the final M3U output.

Step 3 — Update the Flag Ordering (Optional)

To control where your country appears in the README flag grid and the generated playlist order, insert the country's key into flag_order.txt. This file defines the sequence of regions in blocks like "ANGLOSPHERE" (see lines 10–14 of the current file).

Add the lowercase key on its own line where you want it positioned relative to existing entries. The README automatically pulls flag images from hatscripts based on these filenames; you do not need to edit the README manually.

Step 4 — Regenerate the Playlists

Execute the build script to process all Markdown files in lists/ and generate the master playlist.m3u8 plus per-country files:

python3 make_playlist.py

The script iterates through the directory (lines 38–45), parses each channel using the handling logic at lines 51–57, and outputs playlists/playlist_myland.m3u8 alongside the aggregated playlist.

Complete Working Example

Sample lists/myland.md

<h1>Myland TV</h1>

| # | Channel name | URL | Logo | EPG |

|---|--------------|-----|------|-----|
| 1 | Myland News | [>](http://myland.example.com/news.m3u8) | <img src="https://i.imgur.com/NewsLogo.png" width="100"> | |
| 2 | Myland Sports | [>](http://myland.example.com/sports.m3u8) | <img src="https://i.imgur.com/SportLogo.png" width="100"> | |

Sample COUNTRY_CODES Entry

COUNTRY_CODES = {
    # ... existing entries ...

    "myland": "ML",  # Maps lists/myland.md to ISO code ML

}

Running the Generator

$ python3 make_playlist.py
Generating Myland Tv

# ... additional output ...

Summary

• Create a Markdown file in lists/<country>.md with the required table structure and [>] URL markers.
• Register the ISO-3166-1 alpha-2 mapping in COUNTRY_CODES within make_playlist.py.
• Optionally insert the country key into flag_order.txt to control visual ordering.
• Run make_playlist.py to generate playlist.m3u8 and per-country playlists.

Frequently Asked Questions

What file format should the channel list use?

The channel list must be a Markdown file using HTML <h1> tags for the group title and pipe tables for channel data. This specific format allows make_playlist.py to parse the stream URLs and metadata correctly using its internal Markdown table parser.

Where does the tvg-country attribute come from?

The tvg-country attribute is populated from the COUNTRY_CODES dictionary in make_playlist.py (lines 6–92). Each entry maps the filename root to an ISO-3166-1 alpha-2 code, which the script injects into the M3U output during generation.

Do I need to manually edit the README.md?

No. The README automatically generates its flag grid based on flag_order.txt and pulls flag images from hatscripts based on the ISO codes. You only need to modify flag_order.txt if you want to change the country's position in the display order.

How do I validate my new channel list before committing?

Run python3 make_playlist.py locally and verify that the script successfully generates playlists/playlist_<yourcountry>.m3u8 without errors. Check that the output file contains the correct tvg-country attribute and that stream URLs marked with [>] appear in the final playlist.

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