iptv-api README

The project's README from github.com/Guovin/iptv-api. As one markdown file: README.md.

IPTV-API logo

IPTV-API

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

Guovin%2Fiptv-api | Trendshift Guovin%2Fiptv-api | Trendshift Star History Rank

English | 中文

IPTV-API 新版桌面端界面
🌓 切换显示模式 IPTV-API 新版桌面端另一主题界面
Windows / macOS 桌面 GUI · 界面直观,操作更高效
目录

赞助商

赞助商 服务介绍
Helodata

Helodata 全球代理网络

Helodata 提供全球代理基础设施,覆盖 195+国家和地区,拥有8000万+ 合规授权住宅 IP,并支持住宅、ISP、移动及数据中心代理等,为 AI、爬虫与自动化应用提供稳定可靠的数据访问。使用优惠码 iptvapi 可享专属折扣。
IPWO

IPWO 住宅代理网络

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 台标地址,仅当订阅源未提供时才回退到台标库

iptv-api (Guovin/iptv-api)

Searching Database…

25.6K ·GitHub
Что это такое?Инструмент для автообновления IPTV-источников: собирает ссылки на live-потоки из разных источников, проверяет их доступность, тестирует скорость и выдаёт готовые плейлисты M3U/TXT или API-эндпоинт, который можно импортировать в любой плеер.
Это десктопная программа, серверный сервис или скрипт, который я запускаю один раз?Есть несколько вариантов: десктопный GUI для Windows/macOS, версия для командной строки, Docker-образы (amd64/arm64/armv7) или полностью автоматическая работа через GitHub Actions workflow. Ядро на Python также может отдавать результаты на странице через порт 8080.
Как запустить и получить первый плейлист?Запустите Docker-образ или десктопный GUI, настройте config/config.ini (или переменные окружения) и дайте ему обновиться — по умолчанию обновление выполняется один раз при старте. Результаты пишутся в output/result.txt плюс файл M3U, их отдаёт встроенный веб-сервис на порту 8080 — просто укажите этот URL в своём плеере.
Нужно ли устанавливать что-то ещё вместе с ним?Docker-образ не требует ничего дополнительного. Для десктопного GUI FFmpeg нужно установить самостоятельно — инструмент вызывает его, чтобы определять разрешение потока и делать контрольные скриншоты при проверке.
Найденные потоки действительно будут нормально играть?Никаких гарантий нет — в README предупреждают, что качество результатов зависит от ваших источников данных и сети, так что настройку конфига придётся подгонять под себя. Инструмент отфильтровывает мёртвые потоки и заглушки с рекламой, а опциональный режим компенсации может добирать каналы, чтобы список не оказался пустым.
Им правда можно бесплатно пользоваться, и в чём подвох лицензии?GitHub помечает лицензию как NOASSERTION — это собственные условия, а не стандартная open-source лицензия, — и в README есть отдельные разделы Disclaimer и License. Там же подчёркивается необходимость работать только в рамках законного доступа и правил целевых сайтов.
Откуда он берёт ссылки на потоки?По умолчанию — из локального файла источников (local.txt) и из подписок — добавленных вами удалённых плейлистов. Нерабочие адреса подписок или EPG определяются и автоматически отключаются, а для загрузки можно задать свой User-Agent.
Как он решает, какие ссылки стоит оставить?Каждый кандидат проходит тест скорости: проверяются задержка, битрейт, разрешение и частота кадров. По умолчанию отсеиваются потоки ниже 1280x720 или 0.5 MiB/s, выбрасываются заглушки без сигнала и рекламные зацикленные ролики, а внутри каждого канала ссылки сортируются по скорости; предпочтения по региону, провайдеру и IPv4/IPv6 настраиваются.
Может ли он обновлять плейлист сам, без моего участия?Да — режимы GUI, CLI и Docker поддерживают обновление по расписанию: по интервалу или в фиксированное время (по умолчанию каждые 12 часов), а результаты могут записываться в реальном времени прямо во время проверки. Развёртывания через GitHub Actions работают по собственному расписанию workflow.
Что есть в готовых плейлистах, кроме самих ссылок?Данные телепрограммы (EPG) для превью передач, логотипы каналов (локальные или из библиотеки логотипов), метки времени обновления и сведения по каждой ссылке — источник, разрешение и т.п. Режим restream перекодирует потоки для слабых сетей и прямого воспроизведения в браузере, также поддерживаются интерфейсы типа replay.
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
Age
2y
Commits · 90 Days