Markdown File Format for Channel Definitions in the Free-TV/IPTV Lists Directory

Channel definition files in the lists directory use HTML-enhanced Markdown that combines <h1> geographic headers, <h2> technology sections, and pipe-delimited tables containing stream URLs, logos, and EPG identifiers.

The Free-TV/IPTV repository organizes publicly available IPTV streams into maintainable markdown files. Understanding the markdown file format for channel definitions is essential for contributors adding new stations or developers building parsers to generate M3U playlists from these structured tables.

File Structure Overview

Each file in the lists directory follows a consistent three-tier hierarchy designed for both human readability and automated parsing.

Geographic Headers

Every file begins with an HTML <h1> tag that identifies the country or region. This header serves as the primary delimiter for grouping channels by geographic origin.

<h1>USA</h1>

Technology Sections

Within each geographic block, channels are categorized by delivery technology using HTML <h2> tags. Common sections include ATSC, DVB‑S, Pluto, and Other. These sections allow parsers to filter or sort channels by broadcast standard.

<h2>ATSC</h2>

Channel Data Tables

Following each technology header is a standard Markdown table using pipe (|) syntax. The table header row defines five columns, followed by an alignment row using :---: for center alignment, then data rows for individual channels.

Understanding the Five-Column Table Format

Each row in the channel table represents a single broadcast stream with the following schema:

Column	Description	Format Details
#	Sequential index	Often left empty for readability; center-aligned
Channel	Human-readable station name	May include accessibility icons such as Ⓖ (Google) or Ⓨ (YouTube)
Link	Stream URL	Markdown link using [>](URL) syntax where > indicates "play"
Logo	Channel branding	HTML <img> tag with fixed height attribute (typically 20px–30px) containing the image URL
EPG id	Electronic Program Guide identifier	Dot-separated string ending with country code (e.g., Buzzr.us)

Example row from lists/usa.md:

| #   | Channel        | Link  | Logo | EPG id |

|:---:|:--------------:|:-----:|:----:|:------:|
| 1   | Buzzr Ⓖ        | [>](https://buzzrota-ono.amagi.tv/playlist1080.m3u8) | <img height="20" src="https://upload.wikimedia.org/wikipedia/commons/thumb/d/d6/Buzzr_logo.svg/768px-Buzzr_logo.svg.png"/> | Buzzr.us |
| 2   | Retro TV       | [>](https://bcovlive-a.akamaihd.net/5e531be3ed6c41229b2af2d9bffba88d/us-east-1/6183977686001/profile_1/chunklist.m3u8) | <img height="20" src="https://i.imgur.com/PNTYOgg.png" /> | RetroTVEast.us |

Parsing Channel Data with Python

Downstream processors can parse these tables by splitting lines on pipe delimiters and extracting the embedded URLs. Below is a robust implementation that handles the HTML-enhanced Markdown format:

import re

def parse_channel_row(row: str):
    # Remove surrounding whitespace and split by pipe

    cols = [c.strip() for c in row.strip('|').split('|')]
    # Expected order: #, Channel, Link, Logo, EPG id

    number, name, link_md, logo_html, epg_id = cols
    # Extract URL from markdown link

    url = re.search(r'\(([^)]+)\)', link_md).group(1)
    # Extract logo source URL

    logo_url = re.search(r'src="([^"]+)"', logo_html).group(1)
    return {
        "index": number,
        "name": name,
        "stream_url": url,
        "logo_url": logo_url,
        "epg_id": epg_id,
    }

# Example row from lists/usa.md

row = "| 1   | Buzzr Ⓖ        | [>](https://buzzrota-ono.amagi.tv/playlist1080.m3u8) | <img height=\"20\" src=\"https://upload.wikimedia.org/wikipedia/commons/thumb/d/d6/Buzzr_logo.svg/768px-Buzzr_logo.svg.png\"/> | Buzzr.us |"
print(parse_channel_row(row))

Output:

{
  "index": "1",
  "name": "Buzzr Ⓖ",
  "stream_url": "https://buzzrota-ono.amagi.tv/playlist1080.m3u8",
  "logo_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/d6/Buzzr_logo.svg/768px-Buzzr_logo.svg.png",
  "epg_id": "Buzzr.us"
}

Reference Files in the Repository

The following files demonstrate the consistent application of this markdown schema across different regions and content types:

• lists/usa.md – United States channels organized by ATSC, DVB‑S, Pluto, and Other categories
• lists/spain.md – Spanish channel definitions using the same five-column table structure
• lists/zz_vod_it.md – Italian on-demand content illustrating the format's flexibility for VOD services
• lists/zz_movies.md – Global movie channels showing cross-regional reuse of the table format

Summary

• Channel definitions in the Free-TV/IPTV repository use HTML-enhanced Markdown files stored in the lists directory.
• Each file structure comprises an <h1> geographic header, <h2> technology sections, and pipe-delimited tables with five columns.
• The Link column uses [>](URL) syntax, while the Logo column contains HTML <img> tags with fixed heights.
• EPG ids follow a dot-separated convention ending with country codes (e.g., ChannelName.us).
• The format is optimized for simple parsing by splitting rows on | delimiters and extracting URLs with regular expressions.

Frequently Asked Questions

What is the purpose of the [>](...) link syntax in the channel tables?

The [>](URL) markdown pattern uses the greater-than symbol as link text, which serves as a visual "play button" indicator in raw markdown viewers. According to the Free-TV/IPTV source code, this convention signals streaming endpoints to IPTV front-ends while maintaining valid markdown syntax that parsers can reliably extract using regex patterns like \(([^)]+)\).

How are EPG identifiers structured in the Free-TV/IPTV format?

EPG identifiers are plain text strings that follow a dot-separated notation ending with a lowercase country code. For example, Buzzr.us identifies the Buzzr channel in the United States, while RetroTVEast.us specifies the regional variant. These IDs are consumed by the EPG generator to match channels against electronic program guide data.

Can I use standard Markdown headers instead of HTML tags in the lists directory?

While standard markdown headers (# and ##) would render similarly in most viewers, the Free-TV/IPTV specification explicitly requires HTML <h1> and <h2> tags for country and technology sections. This ensures consistent parsing by downstream automation scripts that may rely on specific HTML tag patterns rather than markdown heading syntax.

Which technology sections are commonly used in the channel definition files?

Based on the repository structure found in lists/usa.md and other regional files, the standard technology sections include ATSC (over-the-air digital TV), DVB‑S (satellite), Pluto (Pluto TV streaming service), and Other (catch-all for miscellaneous sources). These <h2> headings allow parsers to categorize channels by broadcast method when generating specialized playlists.

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