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

> Discover why Free-TV/IPTV creates country-specific playlists. Learn about region-aware filtering and optimized downloads for a better viewing experience.

- Repository: [Free TV/IPTV](https://github.com/Free-TV/IPTV)
- Tags: internals
- Published: 2026-06-17

---

**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`](https://github.com/Free-TV/IPTV/blob/main/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`](https://github.com/Free-TV/IPTV/blob/main/spain.md), [`hong_kong.md`](https://github.com/Free-TV/IPTV/blob/main/hong_kong.md)). According to the source code in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/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:

```bash

# From the repository root

python3 make_playlist.py

```

After execution, the `playlists/` directory contains:

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

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

```

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

```text
#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`](https://github.com/Free-TV/IPTV/blob/main/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`](https://github.com/Free-TV/IPTV/blob/main/epglist.txt) | List of EPG URLs referenced in the header of every generated playlist. |

## Summary

- The [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/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`](https://github.com/Free-TV/IPTV/blob/main/spain.md) becomes `spain`) and maps it to an ISO-2 code using the `COUNTRY_CODES` dictionary defined in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/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`](https://github.com/Free-TV/IPTV/blob/main/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`](https://github.com/Free-TV/IPTV/blob/main/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.