iptv-api README

IPTV-API

⚡️IPTV直播源自动更新工具，支持自动采集、多源聚合、可用性校验、测速筛选与播放列表生成。可通过丰富配置自定义频道结果，并以 M3U、TXT 或 API 接口形式输出，导入播放器即可观看。

English | 中文

🌓 切换显示模式

_{Windows / macOS 桌面 GUI · 界面直观，操作更高效}

✅ 核心特性
⚙️ 配置参数
🚀 快速上手
📚 文档中心
📖 详细教程
🗓️ 更新日志
👀 关注
❤️ 捐赠
⚠️ 免责声明
⚖️ 许可证

赞助商

赞助商	服务介绍
	Helodata 提供全球代理基础设施，覆盖 195+国家和地区，拥有8000万+ 合规授权住宅 IP，并支持住宅、ISP、移动及数据中心代理等，为 AI、爬虫与自动化应用提供稳定可靠的数据访问。使用优惠码 `iptvapi` 可享专属折扣。
	IPWO 提供稳定的住宅代理网络，适用于公开数据采集、接口调试、自动化测试与多地区访问验证等合规场景。支持 HTTP / HTTPS / SOCKS5，优惠码：`0105`。请在合法授权并遵守目标站点条款的前提下使用。

成为赞助商

核心特性

功能	支⁠持⁠状⁠态	说明
自⁠定⁠义⁠模⁠板	✅	生成自己想要的频道菜单
频⁠道⁠别⁠名	✅	已收录 2,769 个频道、7,254 条别名（含 48 条正则）；自动归一化并匹配名称差异
多⁠源⁠聚⁠合	✅	本地源、订阅源（支持设置UA，识别无效地址并自动停用）
推⁠流	✅	改善弱网播放体验，支持浏览器直接播放，自动转码适配
回⁠放⁠类⁠接⁠口	✅	回放类接口的获取与生成
EPG	✅	获取并显示频道预告内容
频⁠道⁠台⁠标	✅	自定义频道台标，支持本地添加或远程库
测⁠速⁠验⁠效	✅	获取延迟、速率、分辨率、帧率，过滤无效接口，支持实时输出结果
播⁠放⁠截⁠图	✅	可选自动截图，辅助验证频道内容，支持 GUI 预览与批量刷新
广⁠告⁠过⁠滤	✅	自动识别并过滤无信号/广告等循环占位源
高⁠级⁠偏⁠好	✅	速率、分辨率、黑/白名单、归属地与运营商自定义过滤
结⁠果⁠管⁠理	✅	结果分类存储与访问、日志记录、未匹配频道记录、统计分析、冻结过滤/解冻回归、数据缓存
定⁠时⁠任⁠务	✅	GUI、命令行与 Docker 可定时或间隔执行，不作用于 GitHub Actions
暂⁠停⁠与⁠继⁠续	✅	桌面端更新过程中可暂停，并从当前进度继续
多⁠平⁠台⁠部⁠署	✅	工作流、命令行、GUI 软件、Docker (amd64/arm64/arm v7)
更⁠多⁠功⁠能	✨	详见配置参数章节

配置

[!NOTE]
以下配置项位于 config/config.ini 文件中，支持通过配置文件或环境变量修改，保存后重启即可生效。也可查看独立的配置参数文档。

[!TIP] 生成结果质量取决于数据源与网络环境等因素，请合理调整配置参数以获取更符合需求的结果。

点击展开查看配置参数

配置项	描述	默认值
open_update	开启更新，用于控制是否更新接口，若关闭则所有工作模式（获取接口和测速）均停止	True
open_unmatch_category	开启未匹配频道分类，未匹配 source_file 的频道会进入该分类并直接写入结果，不参与测速	False
open_empty_category	开启无结果频道分类，自动归类至底部	False
open_update_time	开启显示更新时间	True
open_url_info	开启显示接口说明信息，用于控制是否显示接口来源、分辨率、协议类型等信息，为 $ 符号后的内容，播放软件使用该信息对接口进行描述，若部分播放器（如 PotPlayer）不支持解析导致无法播放可关闭	False
open_epg	开启 EPG 功能，支持频道显示预告内容	True
open_subscribe_epg	开启从订阅源 m3u 头部 url-tvg/x-tvg-url 自动提取 EPG 地址，并入 EPG 源一起合并，无需手动维护 `config/epg.txt`；epg.txt 源优先，订阅源仅补充未覆盖频道；需 open_epg = True	True
open_m3u_result	开启转换生成 m3u 文件类型结果链接，支持显示频道图标	True
output_urls_limit	每个频道最终导出的接口数量；旧版 `urls_limit` 仍兼容	5
update_time_position	更新时间显示位置，需要开启 open_update_time 才能生效，可选值: top、bottom；top: 显示于结果顶部，bottom: 显示于结果底部	top
language	系统语言设置；可选值: zh_CN、en	zh_CN
update_mode	定时执行更新时间模式，不作用于工作流；可选值: interval、time； interval: 按间隔时间执行，time: 按指定时间点执行	interval
update_interval	定时执行更新时间间隔，仅在update_mode = interval时生效，单位小时，设置 0 或空则只运行一次	12
update_times	定时执行更新时间点，仅在update_mode = time时生效，格式 HH:MM，支持多个时间点逗号分隔
update_startup	启动时执行更新，用于控制程序启动后是否立即执行一次更新	True
time_zone	时区，可用于控制定时执行时区或显示更新时间的时区；可选值: Asia/Shanghai 或其它时区编码	Asia/Shanghai
source_file	模板文件路径	config/demo.txt
final_file	生成结果文件路径	output/result.txt
open_realtime_write	开启实时写入结果文件，在测速过程中可以访问并使用更新结果	True
open_service	开启页面服务，用于控制是否启动结果页面服务；如果使用青龙等平台部署，有专门设定的定时任务，需要更新完成后停止运行，可以关闭该功能	True
service_port	HTTP 服务访问端口；桌面版启用推流时由 Nginx 监听，新配置通常只需修改此端口	8080
public_url	推荐的公网完整访问地址，例如 `https://iptv.example.com` 或 `http://host:8088`；用于统一生成播放列表、EPG、台标和服务链接
app_port	高级兼容设置：Flask 内部 API 端口，通常无需修改，也不应作为用户访问端口	5180
public_scheme	高级兼容设置：旧版公网协议，仅在 `public_url` 留空时生效；可选值: http、https	http
public_domain	高级兼容设置：旧版公网 Host，仅在 `public_url` 留空时生效，默认使用本机 IP	127.0.0.1
cdn_url	CDN 代理加速地址，用于订阅源、频道图标等资源的加速访问；支持配置多个（用英文逗号分隔），订阅源与 EPG 按顺序逐个回退拉取，任一镜像成功即停，频道图标使用第一个地址
http_proxy	HTTP 代理地址，仅用于获取订阅源和 EPG 数据；测速、媒体探测和截图保持直连
open_local	开启本地源功能，将使用模板文件与本地源文件（local.txt）中的数据	True
open_subscribe	开启订阅源功能	True
open_auto_disable_source	开启自动停用失效地址，失效项会在 `config/subscribe.txt` 和 `config/epg.txt` 中加 #；Actions 不会提交该变更	False
open_history	开启使用历史更新结果（包含模板与结果文件的接口），合并至本次更新；Actions 仅尝试从短期缓存恢复历史	True
open_headers	开启使用 M3U 内含的请求头验证信息，用于测速等操作，个别播放器可能不支持播放这类含验证信息的接口	True
user_agent	全局请求 User-Agent，用于拉取订阅源、测速以及写入 m3u 结果（无需开启 open_headers），留空则使用内置默认 UA；优先级：接口自带 UA > 订阅地址 UA > 全局 UA > 内置默认 UA
open_speed_test	开启测速功能，获取响应时间、速率、分辨率	True
speed_test_mode	测速工作模式：`quick`、`full` 或 `manual`；`manual` 仅采集候选，测速由 GUI 操作触发	quick
speed_test_target	快速测速每个频道的有效结果目标；设为 `0` 跟随 `output_urls_limit`	0
quick_test_target	`speed_test_target` 的可读别名；非 0 时优先作为快速测速目标	0
open_stream_screenshot	自动为可播放候选接口获取播放截图；会增加 FFmpeg 解码开销和更新时间，关闭时仍可在 GUI 手动获取	False
stream_screenshot_timeout	单个接口截图超时时长，单位秒(s)	5
stream_screenshot_width	播放截图最大宽度，按原始宽高比缩放	640
open_filter_resolution	开启分辨率过滤，低于最小分辨率（min_resolution）的接口将会被过滤，GUI 用户需要手动安装 FFmpeg，程序会自动调用 FFmpeg 获取接口分辨率，推荐开启，虽然会增加测速阶段耗时，但能更有效地区分是否可播放的接口	True
open_filter_speed	开启速率过滤，低于最小速率（min_speed）的接口将会被过滤	True
open_filter_ad	开启广告过滤，自动识别并过滤无信号/广告等循环占位源（含 #EXT-X-ENDLIST 的短循环列表，或片段地址包含广告关键字），复用测速阶段已抓取的播放列表进行判断，不增加额外请求与测速耗时	True
open_full_speed_test	开启全量测速，频道下所有候选接口（白名单除外）都进行测速；关闭时达到 `speed_test_target` 后停止该频道剩余测速	False
open_supply	开启补偿机制模式，用于控制当频道接口数量不足时，自动将不满足条件（例如低于最小速率）但可能可用的接口添加至结果中，从而避免结果为空的情况；开启后，不符合 location/isp 归属地或运营商的接口也不再直接丢弃，而是降权排到该频道结果的末尾作为补充	False
sort_by	结果排序维度，控制每个频道内接口的排序优先级，按从前到后的顺序依次比较，逗号分隔；可选值: speed（速率，高优先）、delay（延迟，低优先）、resolution（分辨率，高优先），例如: resolution,speed	speed
min_resolution	接口最小分辨率，需要开启 open_filter_resolution 才能生效	1280x720
max_resolution	接口最大分辨率，需要开启 open_filter_resolution 才能生效	3840x2160
min_speed	接口最小速率（单位 MiB/s），需要开启 open_filter_speed 才能生效	0.5
resolution_speed_map	分辨率与速率映射关系，用于控制不同分辨率接口的最低速率要求，格式为 resolution:speed，多个映射关系逗号分隔	1280x720:0.2,1920x1080:0.5,3840x2160:1.0
performance_mode	性能模式；`auto` 根据设备或容器的 CPU、内存自动选择，`powersave` 优先降低资源消耗，`balance` 平衡资源与速度，`fast` 充分利用高性能设备	auto
speed_test_limit	测速网络并发高级覆盖值；`0` 表示由性能模式自动决定，大于 `0` 时覆盖自动测速并发，不影响媒体探测和源抓取并发	0
speed_test_timeout	单个接口测速超时时长，单位秒(s)；数值越大测速所需时间越长，能提高获取接口数量，但质量会有所下降；数值越小测速所需时间越短，能获取低延时的接口，质量较好；调整此值能优化更新时间	10
speed_test_filter_host	测速阶段使用 Host 地址进行过滤，相同 Host 地址的频道将共用测速数据，开启后可大幅减少测速所需时间，但可能会导致测速结果不准确	False
request_timeout	查询请求超时时长，单位秒(s)，用于控制查询接口文本链接的超时时长以及重试时长，调整此值能优化更新时间	10
ipv6_support	强制认为当前网络支持 IPv6，跳过检测	False
ipv_type	生成结果中接口的协议类型；可选值: ipv4、ipv6、all	all
ipv_type_prefer	接口协议类型偏好，优先将该类型的接口排在结果前面；可选值: ipv4、ipv6、auto	auto
location	接口归属地，用于控制结果只包含填写的归属地类型，支持关键字过滤，英文逗号分隔，不填写表示不指定归属地，建议使用靠近使用者的归属地，能提升播放体验
isp	接口运营商，用于控制结果中只包含填写的运营商类型，支持关键字过滤，英文逗号分隔，不填写表示不指定运营商
origin_type_prefer	结果偏好的接口来源，结果优先按该顺序进行排序，逗号分隔，例如: local,subscribe；不填写则表示不指定来源，按照接口速率排序
local_num	结果中偏好的本地源接口数量	10
subscribe_num	结果中偏好的订阅源接口数量	10
logo_url	频道台标库地址
logo_type	频道台标文件类型	png
open_subscribe_logo	开启优先使用订阅源 m3u 中自带的 tvg-logo 台标地址，仅当订阅源未提供时才回退到台标库

25.6K ·GitHub

Iptv-api

这是干什么的?

一个 IPTV 源自动更新工具:它从多个来源收集直播流链接,检测可用性并进行测速,输出可直接播放的 M3U/TXT 播放列表或一个 API 接口,可以导入到任何播放器里。

它是桌面软件、服务器服务,还是只需要运行一次的脚本?

有几种方式:Windows/macOS 桌面图形界面、命令行版本、Docker 镜像(amd64/arm64/armv7),或者通过 GitHub Actions 工作流全自动运行。Python 核心还能在内网 8080 端口上把结果作为一个页面提供出来。

我怎么把它跑起来并拿到第一个播放列表?

运行 Docker 镜像或桌面图形界面,调整 config/config.ini(或环境变量),让它执行一次更新——默认启动时就会跑一次。结果输出到 output/result.txt 以及一个 M3U 文件,由内置的页面服务在 8080 端口提供:把你的播放器指向那个地址即可。

除了它本身,我还需要安装别的东西吗?

Docker 镜像不需要任何额外的东西。桌面图形界面则必须自己安装 FFmpeg——工具会调用它来检测流的分辨率并截取验证截图。

它找到的源真的能流畅播放吗?

不保证——README 提醒结果质量取决于你的数据源和网络状况,所以要做好调整配置的准备。它会过滤掉失效的源和广告占位源,另外还有一个可选的补偿模式,可以为原本会空缺的频道补充内容。

它真的可以免费使用吗?许可证里有什么要注意的?

GitHub 把该许可证归类为 NOASSERTION——也就是自定义条款,而不是标准的开源许可证——而且 README 里单独列有免责声明和许可证章节。它还强调要在合法授权范围内使用,并遵守目标网站的条款。

它从哪里获取直播源链接?

默认来自一个本地源文件(local.txt)加上订阅源——也就是你添加的远程播放列表。失效的订阅或 EPG 地址会被检测到并自动停用,抓取时还可以自定义 User-Agent。

它怎么判断哪些链接值得保留?

每个候选链接都会经过测速,检测延迟、速率、分辨率和帧率。默认设置会过滤掉低于 1280x720 或 0.5 MiB/s 的流,丢弃无信号或广告占位的循环画面,并按速度对每个频道排序;地区、运营商和 IPv4/IPv6 偏好都可以配置。

不用我操心,它能自动保持播放列表最新吗?

可以——图形界面、命令行和 Docker 模式都支持定时更新,可以按间隔或固定时间执行(默认每 12 小时一次),而且测试过程中结果可以实时写入。GitHub Actions 部署则按自己的工作流计划运行。

生成的播放列表除了原始链接还包括什么?

包括用于节目预览的 EPG 节目单数据、频道台标(本地图片或来自台标库)、更新时间戳,以及每个链接的附加信息,比如来源和分辨率。还有一种轮播转码模式,可为网络较差的环境转码并支持浏览器直接播放,另外也支持回放类接口。

What are similar projects?

IPTV, Tvlist-awesome-m3u-m3u8, iptv, live, awesome-iptv, IPTV, LibreTV, bug

Which topics is it in?

schedule, speedtest, tvbox, epg, live, ipv4, ipv6, rtmp, m3u, playlist, livestream, m3u8

Creator: Guovin
Size: 1.3 GB
Stars: 25.6K
Updated: CommitOct 14 Release3.1.0Oct 12
Age: 2y
Commits · 90 Days

iptv-api README

IPTV-API

赞助商

核心特性

配置

iptv-api (Guovin/iptv-api)