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

To add a new country or region to the Free-TV IPTV playlist, create a Markdown file in the lists/ directory, register the country key in flag_order.txt, optionally add the ISO-3166 code to make_playlist.py, and run the generator script to produce the M3U8 files.

The Free-TV/IPTV repository maintains a collaborative collection of free IPTV channels organized by geographic region. Adding a new country or region to the playlist requires modifying three distinct layers: the data files containing channel information, the ordering configuration that determines playlist sequence, and the code generation logic that produces the final M3U8 output.

Create the Country-Specific Channel List

Start by creating a new Markdown file in the lists/ directory. The filename (e.g., myland.md) becomes the internal key used by the generator, so use lowercase identifiers without spaces.

The file must follow this structure:

• First line: An <h1> title tag that matches the filename (underscores convert to spaces in display).
• Channel table: A Markdown table with columns ordered as #, Channel, Link, Logo, and EPG id.
• Link markers: Only rows containing [>] in the Link column are included in the final playlist; rows marked with [x] are ignored.

<h1>MyLand</h1>

<h2>Free TV</h2>

| # | Channel | Link | Logo | EPG id |

|:---:|:--------------:|:-----:|:----:|:------:|
| 1 | MyLand News | [>](https://myland.example.com/stream.m3u8) | <img height="20" src="https://i.imgur.com/myland.png"/> | MyLandNews.us |
| 2 | Sports Channel | [x](https://example.com/offline.m3u8) | <img height="20" src="https://i.imgur.com/sports.png"/> | Sports.us |

Save this file as lists/myland.md.

Define the Playback Order

Edit flag_order.txt to specify where the new country appears in the master playlist. Locate the appropriate regional section (e.g., # AFRICA, # MIDDLE EAST, # EUROPE) and insert the country key on its own line.

According to the Free-TV/IPTV source code, the generator reads this file sequentially to determine the order of country-specific playlists in the final output.

# AFRICA

chad
somalia
myland

Map the ISO-3166 Country Code

While optional, adding the country code ensures IPTV clients properly group channels using the tvg-country attribute. Open make_playlist.py and locate the COUNTRY_CODES dictionary (defined around lines 44-46).

Add an entry mapping your country key to its two-letter ISO-3166-1 alpha-2 code:

COUNTRY_CODES = {
    "chad": "TD",
    "somalia": "SO",
    "myland": "ML",  # Replace ML with actual ISO code

}

As implemented in make_playlist.py (lines 23-46), this mapping embeds the country metadata into each channel's EXTINF line during generation.

Regenerate the Playlists

Run the generator script to process your changes. The repository provides make_playlist.py as the primary entry point, which parses all Markdown files, applies the ordering from flag_order.txt, and injects country codes.

python3 make_playlist.py

The script outputs two artifacts:

• Global playlist: playlist.m3u8 (the master list clients typically consume)
• Per-country playlist: playlists/playlist_myland.m3u8 (individual file for the new region)

The generation logic automatically filters out any channels marked with [x] and includes only active streams marked with [>].

Summary

• Store country data in lists/{country_key}.md using the standard table format with #, Channel, Link, Logo, and EPG id columns.
• Only rows with [>] markers in the Link column are included in the generated M3U8 streams.
• Register the country key in flag_order.txt to control its position in the master playlist.
• Add the ISO-3166 code to the COUNTRY_CODES dictionary in make_playlist.py to enable proper tvg-country metadata.
• Execute make_playlist.py to generate both the global playlist.m3u8 and individual country files in the playlists/ directory.

Frequently Asked Questions

What filename should I use for a new country?

Use a lowercase, single-word identifier without spaces (e.g., myland.md). The filename (minus the extension) becomes the internal key referenced by flag_order.txt and the COUNTRY_CODES mapping in make_playlist.py.

How does the generator decide which channels to include?

The script parses the Link column of each table row. Channels marked with [>](url) are included in the final M3U8 output, while those marked with [x](url) are skipped during generation. This allows maintainers to keep offline channels in the source files without exposing them to end users.

Do I need to manually edit the M3U8 files?

No. The playlist.m3u8 file and all per-country files in the playlists/ directory are generated automatically by make_playlist.py. Submit pull requests that modify only the Markdown files in lists/, flag_order.txt, and optionally the COUNTRY_CODES dictionary. The generator will recreate the M3U8 outputs when the maintainer runs the script.

Where should I place the new entry in flag_order.txt?

Insert the country key within the appropriate regional section (e.g., # AFRICA, # ASIA) in the order you want it to appear. The generator processes flag_order.txt sequentially from top to bottom, so the position in this file directly determines the country's placement in the master playlist.

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