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

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 file lives in the root of the 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 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 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, the script expects this exact path:

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

Example Content

A typical entry in 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 (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:

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:

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:

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:

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 file directly:

1. Open 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 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 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 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) would likely fail in most player applications since they execute on the client device, not the server where make_playlist.py runs.

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