Why Free-TV/IPTV Generates Separate Country-Specific Playlists in the Playlists Directory

The repository generates separate country-specific playlists to enable region-aware filtering, reduce file sizes for lightweight clients, and allow users to download only the channels they need.

The Free-TV/IPTV repository maintains a curated collection of public IPTV channels organized by country. The build system processes markdown source files and outputs separate country-specific playlists in the playlists directory, ensuring each territory has its own optimized .m3u8 file with proper metadata tags.

How Country-Specific Playlists Are Generated

The automation logic resides in make_playlist.py, which treats each markdown file in the lists folder as a distinct country catalog.

Scanning Source Files

The script iterates through the lists directory to discover every *.md file (e.g., spain.md, hong_kong.md). According to the source code in make_playlist.py (lines 138-144), this scan identifies which countries need playlist generation.

Mapping to ISO Country Codes

For each file found, the script derives a country key by stripping the .md extension (country_key = filename[:-3]). It then looks up the corresponding ISO-2 code in the COUNTRY_CODES mapping (lines 144-146), ensuring standardized country identification.

Writing Dedicated Playlist Files

The script creates a dedicated output file named playlist_<country>.m3u8 inside the playlists directory (lines 142-149). Each file receives the same global header containing EPG URLs, followed by channel entries tagged with tvg-country="{self.country_code}" (lines 148-158).

Design Benefits of Separate Country-Specific Playlists

The architecture serves several technical and user-experience goals:

Region-aware playback. Many IPTV clients filter channels by the tvg-country attribute. By embedding ISO-2 codes (e.g., ES for Spain) in each channel line, the playlists work immediately with clients that restrict content to specific territories.

Smaller, more manageable files. A single global playlist aggregating every country would become prohibitively large. Separate files keep each playlist lightweight, reducing load times and memory usage on low-power devices like Android TV boxes or Raspberry Pi media centers.

Convenient distribution. Users can download only the playlist they need (e.g., playlist_spain.m3u8) rather than fetching the entire global catalog. This reduces bandwidth consumption and makes updates more granular.

Simplified maintenance. Adding or removing a country requires only editing its markdown source in lists/. The build script automatically creates or deletes the corresponding playlist without manual file management.

Clear organization. The playlists/ directory mirrors the lists/ source structure, making it immediately obvious which file belongs to which country.

Working with the Generated Playlists

To generate all playlists including country-specific variants:

# From the repository root

python3 make_playlist.py

After execution, the playlists/ directory contains:

playlists/
├── playlist.m3u8          # Master playlist (all channels)

├── playlist_spain.m3u8    # Spain-specific playlist

├── playlist_hong_kong.m3u8
└── … (one file per country)

To stream a country-specific playlist in VLC:

vlc https://example.com/playlists/playlist_spain.m3u8

Inspecting the generated tvg-country attribute in playlist_spain.m3u8 reveals the ISO tagging:

#EXTINF:-1 tvg-name="RTVE" tvg-logo="http://example.com/logo.png" tvg-chno="101" tvg-country="ES" group-title="Spain",RTVE
http://stream.example.com/rtve.m3u8

Key Source Files

File	Role
make_playlist.py	Core script that parses markdown lists and writes per-country .m3u8 playlists.
lists/*.md	Markdown source files, each representing a country's channel list.
playlists/playlist_*.m3u8	Output files generated by the script.
epglist.txt	List of EPG URLs referenced in the header of every generated playlist.

Summary

• The make_playlist.py script generates one .m3u8 file per country found in the lists/ directory.
• Each playlist contains the tvg-country attribute with an ISO-2 code for client-side filtering.
• Separate files improve performance by reducing download sizes and memory usage.
• The architecture enables granular updates and simplifies repository maintenance.
• Users can reference individual playlists directly or use the global playlist.m3u8.

Frequently Asked Questions

What is the difference between playlist.m3u8 and the country-specific files?

The playlist.m3u8 file contains all channels from every country, while playlist_<country>.m3u8 files contain only channels for that specific territory. The country-specific variants include the same EPG header but filter entries using the tvg-country attribute.

How does the script know which country code to use?

The script derives the country key from the markdown filename (e.g., spain.md becomes spain) and maps it to an ISO-2 code using the COUNTRY_CODES dictionary defined in make_playlist.py. This ensures standardized two-letter codes like ES or HK appear in the output.

Can I generate playlists for only specific countries?

Currently, make_playlist.py processes all markdown files in the lists/ directory. To generate specific country playlists, you would need to temporarily move unwanted .md files out of the directory or modify the script to accept a filter argument.

Why do all playlists share the same EPG header?

Every generated playlist includes the same global header referencing epglist.txt because electronic program guide data is aggregated across all sources. This ensures that even country-specific playlists can display scheduling information if the EPG provider supports multi-territory data.

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