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

> Discover the HTML-enhanced Markdown format for channel definitions used in Free-TV IPTV lists. Learn about geographic headers, technology sections, and pipe-delimited tables with stream URLs, logos, and EPG.

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

---

**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.

```markdown
<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.

```markdown
<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`](https://github.com/Free-TV/IPTV/blob/main/lists/usa.md):**

```markdown
| #   | 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:

```python
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:**

```json
{
  "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`](https://github.com/Free-TV/IPTV/blob/main/lists/usa.md)** – United States channels organized by ATSC, DVB‑S, Pluto, and Other categories
- **[`lists/spain.md`](https://github.com/Free-TV/IPTV/blob/main/lists/spain.md)** – Spanish channel definitions using the same five-column table structure
- **[`lists/zz_vod_it.md`](https://github.com/Free-TV/IPTV/blob/main/lists/zz_vod_it.md)** – Italian on-demand content illustrating the format's flexibility for VOD services
- **[`lists/zz_movies.md`](https://github.com/Free-TV/IPTV/blob/main/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`](https://github.com/Free-TV/IPTV/blob/main/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.