What it is

iptv-sources is a TypeScript application that automatically updates IPTV source lists and publishes them as M3U playlists and EPG data. It lives in the IPTV and media-streaming ecosystem, where clients such as Kodi, TVBox, and DIYP-compatible players consume M3U playlists and electronic program guide files. The project collects channel lists from a set of upstream repositories, including iptv-org/iptv, YueChan/Live, YanG-1989/m3u, fanmingming/live, qwerttvv/Beijing-IPTV, joevess/IPTV, and cymz6/AutoIPTV-Hotel, and it gathers EPG data from fanmingming/live, 112114.xyz, and epg.51zmt.top:8000. It is released under the GPL-3.0 license and has accumulated roughly 8,900 stars and 1,500 forks over three years of development.

The concrete problem it solves is playlist decay. Public IPTV lists are scattered across many repositories, each maintained on its own schedule, and any single list can go stale, move, or disappear. A user who points a player at one upstream repository has to track that repository manually and re-point the player whenever the URL changes or the file stops updating. iptv-sources runs the aggregation on a schedule, merges the upstream sources into a consistent output, and serves the result from a stable location, so a player only needs one URL. It also provides a rollback mechanism and an optional channel checker, which address the two failure modes that follow aggregation: upstream outages and dead streams inside otherwise valid lists.

Key capabilities

• Aggregates multiple upstream IPTV repositories into unified M3U output rather than relying on a single list.
• Merges EPG data from several providers into the published guide.
• Runs on an automatic update schedule, so published playlists refresh without manual intervention.
• Supports custom rollback URLs through the ROLLBACK_URLS environment variable.
• Supports a configurable GitHub raw content proxy via CUSTOM_GITHUB_RAW_SOURCE_PROXY_URL, and can disable the built-in source proxy with CLOSE_SOURCE_PROXY.
• Offers an optional IPTV checker, enabled with ENABLE_IPTV_CHECKER and pointed at a checker service through IPTV_CHECKER_URL.
• Ships as a Docker image, herberthe0229/iptv-sources, alongside Node.js and GitHub Pages deployment paths.

Who uses it and how

• Kodi and TVBox users subscribe to the published M3U and EPG URLs as a single playlist source.
• DIYP-style players consume the generated M3U and EPG output for channel and programme listings.
• Self-hosters run the Docker image to publish playlists from their own infrastructure.
• Operators deploy to GitHub Pages or Node.js when a container runtime is not available.
• Users behind restricted networks set a custom GitHub raw proxy so upstream fetches succeed.

Getting started

Deploy with the Docker image herberthe0229/iptv-sources, run it under Node.js, or publish it through GitHub Pages, following the deployment discussions linked in the README. A hosted instance is available at m3u.ibert.me.

When to use it — and when not to

Use it when a stable

# add custom rollback urls, default is empty
# ROLLBACK_URLS=https://xxxx.xxx.com

# close source proxy, default is false
# CLOSE_SOURCE_PROXY=true

# add custom github raw source proxy url
# The custom proxy service you configured MUST supports the request urls, like `${CUSTOM_GITHUB_RAW_SOURCE_PROXY_URL}/https://raw.githubusercontent.com/xxx/xxx`
# If you want to deploy the ghproxy by yourself, see https://github.com/hunshcn/gh-proxy
# CUSTOM_GITHUB_RAW_SOURCE_PROXY_URL=https://ghp.ci/

# enable iptv checker, default is false
# ENABLE_IPTV_CHECKER=true

# add iptv checker url, default is empty
# IPTV_CHECKER_URL=http://[::1]:8081