# Structure of epglist.txt and How It Is Processed in IPTV

> Learn the structure of epglist.txt and how make_playlist.py processes it to create M3U8 playlists with the x-tvg-url attribute for IPTV.

- Repository: [Free TV/IPTV](https://github.com/Free-TV/IPTV)
- Tags: how-to-guide
- Published: 2026-06-16

---

**The epglist.txt file is a plain-text list of EPG URLs that the make_playlist.py script reads, filters, comma-joins, and embeds into the x-tvg-url attribute of generated M3U8 playlists.**

The [`epglist.txt`](https://github.com/Free-TV/IPTV/blob/main/epglist.txt) file lives in the root of the [Free-TV/IPTV](https://github.com/Free-TV/IPTV) repository and serves as the central registry for Electronic Program Guide (EPG) sources. Understanding the structure of epglist.txt and how it is processed in IPTV playlist generation is essential for contributors who want to add new TV guide sources or debug playlist builds. The entire workflow is handled by the **[`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py)** script, which converts these URLs into a standard IPTV header attribute recognized by most media players.

## What Is epglist.txt?

### File Location and Basic Structure

Located at the repository root, **[`epglist.txt`](https://github.com/Free-TV/IPTV/blob/main/epglist.txt)** is a UTF-8 encoded plain-text file containing one URL per line. Each URL points to an XMLTV file (often gzip-compressed) that contains television program listings. The file contains no headers, comments, or delimiters—only newline-separated URLs.

According to the source code in [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py), the script expects this exact path:

```python
os.path.join(base_dir, "epglist.txt")

```

### Example Content

A typical entry in [`epglist.txt`](https://github.com/Free-TV/IPTV/blob/main/epglist.txt) looks like this:

```

https://epgshare01.online/epgshare01/epg_ripper_AL1.xml.gz
https://epgshare01.online/epgshare01/epg_ripper_ALJAZEERA1.xml.gz
https://epgshare01.online/epgshare01/epg_ripper_viva-russia.ru.xml.gz

```

Each line represents a distinct EPG source that will be aggregated into the final playlist.

## How make_playlist.py Processes epglist.txt

The processing logic in **[`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py)** (lines 31–35) follows a four-step pipeline to transform the raw text file into a valid IPTV header attribute.

### Step 1: Reading the EPG Source List

The script opens the file using UTF-8 encoding to handle international characters in URLs:

```python
with open(os.path.join(base_dir, "epglist.txt"), encoding='utf-8') as epg_file:
    epg_urls = [line.strip() for line in epg_file if line.strip()]

```

This list comprehension simultaneously reads the file, strips whitespace (including newlines), and filters out any empty lines.

### Step 2: Aggregating URLs into a Single String

After collecting valid URLs, the script concatenates them into a comma-separated string suitable for the `x-tvg-url` attribute:

```python
processed_epg_list = ", ".join(epg_urls)

```

This produces a single string where each URL is separated by a comma and space, matching the de-facto standard for multi-source EPG declarations in IPTV playlists.

### Step 3: Constructing the Playlist Header

The comma-joined string is embedded into the `#EXTM3U` header using Python f-string formatting:

```python
head_playlist = f'#EXTM3U x-tvg-url="{processed_epg_list}"\n'

```

This creates the master header that will be written to every generated playlist file.

### Step 4: Writing to Output Files

The header is written to both the master playlist and per-country playlists:

```python
with open(os.path.join(base_dir, "playlist.m3u8"), "w", encoding='utf-8') as playlist:
    playlist.write(head_playlist)

```

The same header pattern is applied to all `.m3u8` files generated by the script, ensuring consistent EPG attribution across the entire distribution.

## Adding Custom EPG Sources

To extend the EPG coverage, edit the **[`epglist.txt`](https://github.com/Free-TV/IPTV/blob/main/epglist.txt)** file directly:

1. Open [`epglist.txt`](https://github.com/Free-TV/IPTV/blob/main/epglist.txt) in the repository root.
2. Append a new line containing the full URL to your XMLTV file (gzip compression is supported).
3. Save the file.

The next execution of [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) will automatically include the new source in the `x-tvg-url` attribute without requiring any code changes.

## Summary

- **epglist.txt** is a root-level plain-text file containing one EPG URL per line with no headers or comments.
- The **[`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py)** script reads this file at lines 31–35, filtering empty lines and stripping whitespace.
- Valid URLs are comma-joined into a single string and embedded in the `#EXTM3U x-tvg-url` attribute.
- This header is written to all generated `.m3u8` files, providing players with a complete list of program guide sources.
- Adding new EPG feeds requires only appending URLs to [`epglist.txt`](https://github.com/Free-TV/IPTV/blob/main/epglist.txt) and rebuilding the playlists.

## Frequently Asked Questions

### What format does epglist.txt use?

The file uses plain UTF-8 text with one URL per line. It does not support comments, headers, or inline formatting—only newline-separated strings pointing to XMLTV sources (typically `.xml` or `.xml.gz` files).

### How does the script handle empty lines or comments in epglist.txt?

The list comprehension `[line.strip() for line in epg_file if line.strip()]` automatically removes empty lines and whitespace-only lines. Lines containing text with leading or trailing spaces are trimmed. The script does not explicitly support comment syntax, so any line beginning with `#` would be treated as a URL and likely cause errors unless it points to a valid resource.

### Where is the EPG data used after being embedded in the playlist?

The comma-separated URL string is stored in the `x-tvg-url` attribute of the `#EXTM3U` header. IPTV players like VLC, Kodi, and dedicated IPTV apps read this attribute to download and display the Electronic Program Guide data alongside the channel streams.

### Can I use local file paths instead of URLs in epglist.txt?

While the script itself does not validate URL schemes, the `x-tvg-url` attribute in M3U8 playlists typically expects absolute URLs that players can fetch over HTTP/HTTPS. Local file paths (e.g., [`/path/to/guide.xml`](https://github.com/Free-TV/IPTV/blob/main//path/to/guide.xml)) would likely fail in most player applications since they execute on the client device, not the server where [`make_playlist.py`](https://github.com/Free-TV/IPTV/blob/main/make_playlist.py) runs.