How Free-TV/IPTV Ensures UTF-8 Encoding for Output Playlist Files

The make_playlist.py script guarantees UTF-8 encoding by explicitly passing encoding='utf-8' to every open() call when reading source files and writing generated M3U8 playlists.

The Free-TV/IPTV repository aggregates IPTV channels from Markdown source files into standardized playlist files. To ensure international channel names and URLs containing non-ASCII characters render correctly across media players, the build script enforces UTF-8 encoding at every file I/O boundary.

Explicit UTF-8 Declaration in File Operations

The script implements a strict encoding policy in make_playlist.py by specifying the UTF-8 codec for all text file operations. This approach overrides system default locales and ensures consistent Unicode handling regardless of the build environment.

Reading Source Files with UTF-8

When processing input data, the script opens both the EPG list and country-specific Markdown files using UTF-8 encoding. This prevents misinterpretation of special characters in channel metadata.

For example, lines 31-33 read the EPG list with explicit UTF-8 encoding:

with open(os.path.join(base_dir, "epglist.txt"), encoding='utf-8') as epg_file:

Similarly, lines 47-48 demonstrate how Markdown sources are opened with UTF-8:

with open(markup_path, encoding='utf-8') as markup_file, \
     open(country_path, "w", encoding='utf-8') as playlist_country:

Writing Playlist Files with UTF-8

All output playlist generation uses the same explicit encoding parameter. The master playlist and individual country playlists are created with UTF-8 to ensure the M3U8 headers and EXTINF entries support international characters.

Lines 36-38 show the master playlist creation:

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

Practical Code Patterns

The consistent application of encoding='utf-8' appears throughout the file handling logic. Here are the specific patterns used in the Free-TV/IPTV codebase.

Writing the master playlist:

# Write the master playlist (UTF‑8 guaranteed)

with open("playlist.m3u8", "w", encoding="utf-8") as out:
    out.write('#EXTM3U x-tvg-url="https://example.com/epg.xml"\n')

Reading country-specific sources:

# Read a country‑specific list (UTF‑8 guaranteed)

with open("lists/italy.md", encoding="utf-8") as src:
    for line in src:
        # process the line …

        pass

Generating country playlists:

# Write Italy’s playlist (UTF‑8 guaranteed)

with open("playlists/playlist_italy.m3u8", "w", encoding="utf-8") as out:
    out.write('#EXTM3U x-tvg-url="https://example.com/epg.xml"\n')
    out.write('#EXTINF:-1 tvg-name="Rai 1" tvg-logo="..." ...\n')

Why UTF-8 Enforcement Matters

M3U8 playlists frequently contain channel names, logos, and URLs with Unicode characters from various languages. By forcing UTF-8 encoding in make_playlist.py, the repository ensures that:

• Cross-platform compatibility: Works on Windows, Linux, and macOS regardless of system locale
• Standard compliance: M3U8 specification recommends UTF-8 for extended character support
• Data integrity: Special characters in EPG URLs and channel metadata remain intact

Summary

• The make_playlist.py script in Free-TV/IPTV enforces UTF-8 encoding through explicit encoding='utf-8' parameters in all open() calls.
• Source files including epglist.txt and Markdown lists in the lists/ directory are read with UTF-8 to correctly interpret international characters.
• Output playlist files including playlist.m3u8 and country-specific variants are written with UTF-8 encoding to ensure compatibility with media players.
• This implementation spans lines 31-33, 36-38, and 47-48 of the build script.

Frequently Asked Questions

Does the script use UTF-8 with BOM for playlist files?

No, the script uses standard UTF-8 encoding without a Byte Order Mark (BOM). The encoding='utf-8' parameter in Python's open() function writes plain UTF-8, which is the recommended format for M3U8 playlists and ensures maximum compatibility with media players.

What happens if a source file contains invalid UTF-8 sequences?

The script would raise a UnicodeDecodeError when encountering invalid byte sequences, as it opens files in strict mode (Python's default). This behavior ensures data integrity by failing fast rather than silently corrupting channel names or URLs.

Are the generated playlists readable on all operating systems?

Yes, because UTF-8 is a universal encoding standard. By explicitly specifying UTF-8 rather than relying on system defaults, the script produces playlist files that display correctly on Windows, macOS, and Linux systems regardless of regional locale settings.

Where in the codebase is the UTF-8 encoding configured?

The encoding is configured inline within make_playlist.py at three critical points: lines 31-33 for reading epglist.txt, lines 36-38 for creating the master playlist.m3u8, and lines 47-48 for processing country Markdown files and generating their respective playlists.

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