⚡️IPTV直播源自动更新工具：自动采集、校验、测速并生成可播放结果，支持 M3U/TXT/API 输出、自定义频道、IPv4/IPv6、Docker、GitHub Actions、CLI 与 GUI 多端部署
IPTV-API
⚡️IPTV直播源自动更新工具，支持自动采集、多源聚合、可用性校验、测速筛选与播放列表生成。可通过丰富配置自定义频道结果，并以 M3U、TXT 或 API 接口形式输出，导入播放器即可观看。
目录
- [✅ 核心特性](#核心特性)
- [⚙️ 配置参数](#配置)
- [🚀 快速上手](#快速上手)
- [配置与结果目录](#配置与结果目录)
- [工作流](#工作流)
- [命令行](#命令行)
- [GUI 软件](#gui-软件)
- [Docker](#docker)
- [📚 文档中心](./docs/README.md)
- [📖 详细教程](./docs/tutorial.md)
- [🗓️ 更新日志](./CHANGELOG.md)
- [👀 关注](#关注)
- [❤️ 捐赠](#捐赠)
- [⚠️ 免责声明](#免责声明)
- [⚖️ 许可证](#许可证)
## 赞助商
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` 文件中，支持通过配置文件或环境变量修改，保存后重启即可生效。也可查看独立的[配置参数文档](./docs/config.md)。
> [!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 代理地址，用于获取订阅源等网络请求 | |
| 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_filte