How Country Codes Are Mapped to ISO Codes in IPTV Playlists

The Free-TV/IPTV repository maps country identifiers to ISO 3166-1 alpha-2 codes using a centralized COUNTRY_CODES dictionary in make_playlist.py, which translates Markdown filenames into standardized tvg-country attributes for M3U playlist generation.

The Free-TV/IPTV project maintains curated television channel lists organized by country in the lists/ directory. Understanding how country codes are mapped to ISO codes in IPTV playlists is essential for developers customizing the playlist generator or verifying regional metadata accuracy. The mapping occurs through a single Python dictionary that bridges human-readable filenames with machine-standard ISO 3166-1 alpha-2 codes.

The COUNTRY_CODES Dictionary Structure

At the core of the mapping system lies the COUNTRY_CODES dictionary defined in [make_playlist.py](https://github.com/Free-TV/IPTV/blob/master/make_playlist.py) (lines 6–90). This data structure maps lowercase, underscore-separated country identifiers to their corresponding two-letter ISO codes.

The dictionary keys reflect the Markdown filenames stored in the lists/ directory, such as usa, canada, south_korea, or uk. The values provide the standard ISO 3166-1 alpha-2 codes used internationally for region identification.

Common mappings include:

• albania → AL
• canada → CA
• usa → US
• uk → GB
• spain → ES
• turkey → TR

Extracting Country Keys from Filenames

The playlist generator processes each .md file in the lists/ directory by extracting the base filename to create a lookup key. The script removes the file extension and uses the resulting string as the country_key for dictionary access.

# From make_playlist.py (lines 44-46)

country_key = filename[:-3]  # Strips '.md' extension

group = country_key.replace("_", " ").title()
country_code = COUNTRY_CODES.get(country_key, "")

This approach ensures that filenames like south_korea.md are normalized to the key south_korea, which then retrieves the ISO code KR from the dictionary.

Generating the tvg-country Attribute

Once the ISO code is retrieved, the generator injects it into the M3U playlist format through the Channel.to_m3u_line method. According to the source code in make_playlist.py, this method constructs the tvg-country attribute only when a valid country code exists.

# From Channel.to_m3u_line (line 15)

country = f' tvg-country="{self.country_code}"' if self.country_code else ""

This conditional formatting ensures that channels with unrecognized country keys—returning empty strings from the dictionary—do not generate malformed attributes in the final M3U output.

Practical Implementation Example

Developers can import and utilize the COUNTRY_CODES dictionary directly to verify mappings or build custom tooling:

from make_playlist import COUNTRY_CODES

def iso_for_file(filename: str) -> str:
    """Convert Markdown filename to ISO country code."""
    key = filename.rstrip('.md').lower()
    return COUNTRY_CODES.get(key, "")

# Usage examples

print(iso_for_file("usa.md"))          # → US

print(iso_for_file("uk.md"))           # → GB

print(iso_for_file("south_korea.md"))  # → KR

The complete playlist generation workflow combines these elements: file discovery, key extraction, ISO lookup via COUNTRY_CODES.get(country_key, "") (lines 44–46), and M3U line construction with proper attribute formatting.

Summary

• The Free-TV/IPTV repository uses a centralized COUNTRY_CODES dictionary in make_playlist.py to map internal country identifiers to ISO 3166-1 alpha-2 codes.
• Country keys are derived from Markdown filenames by stripping the .md extension and matching against lowercase, underscore-separated keys.
• The COUNTRY_CODES.get(country_key, "") lookup (lines 44–46) provides the ISO code used in the tvg-country attribute.
• The Channel.to_m3u_line method conditionally formats the tvg-country attribute to ensure valid M3U output.

Frequently Asked Questions

Where is the country code mapping defined in the Free-TV/IPTV repository?

The mapping is defined in the COUNTRY_CODES dictionary located in [make_playlist.py](https://github.com/Free-TV/IPTV/blob/master/make_playlist.py) between lines 6 and 90. This dictionary contains all country identifier-to-ISO code translations used during playlist generation.

What happens if a country filename is not in the COUNTRY_CODES dictionary?

If a Markdown filename does not match any key in COUNTRY_CODES, the get() method returns an empty string. The Channel.to_m3u_line method checks for this empty value and omits the tvg-country attribute entirely, preventing invalid M3U syntax.

Why does the UK map to GB instead of UK in the ISO codes?

The repository follows the ISO 3166-1 alpha-2 standard, which assigns GB as the official code for the United Kingdom of Great Britain and Northern Ireland. While UK is reserved and not used, the COUNTRY_CODES dictionary correctly maps the internal uk filename key to the standard GB code.

Can I add custom country codes to the mapping?

Yes, you can extend the COUNTRY_CODES dictionary in make_playlist.py by adding new key-value pairs where the key matches your Markdown filename (lowercase, underscore-separated) and the value is the valid two-letter ISO code. The playlist generator will automatically include these in the tvg-country attributes.

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