README

English | 中文

</picture>

• ✅ 核心特性
• ⚙️ 配置参数
• 🚀 快速上手
  • 配置与结果目录
  • 工作流
  • 命令行
  • GUI 软件
  • Docker
• 📚 文档中心
• 📖 详细教程
• 🗓️ 更新日志
• 👀 关注
• ❤️ 捐赠
• ⚠️ 免责声明
• ⚖️ 许可证

赞助商

[!IMPORTANT]

1. 前往Govin公众号回复cdn获取加速地址，提升订阅源与频道图标等资源的访问速度
2. 本项目不提供数据源，请自行添加后生成结果（如何添加数据源？）
3. 生成结果质量取决于数据源与网络环境等因素，请合理调整配置参数以获取更符合需求的结果

核心特性

配置

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

快速上手

配置与结果目录

iptv-api/                  # 项目根目录
├── config                 # 配置文件目录，包含配置文件、模板文件等
│   └── hls                # 本地HLS推流文件目录，用于存放多个频道名称命名的视频文件
│   └── local              # 本地源文件目录，用于存放多个本地源文件，支持txt/m3u格式
│   └── config.ini         # 配置参数文件
│   └── demo.txt           # 频道模板
│   └── alias.txt          # 频道别名
│   └── blacklist.txt      # 接口黑名单
│   └── whitelist.txt      # 接口白名单
│   └── subscribe.txt      # 频道订阅源列表
│   └── local.txt          # 本地源文件
│   └── epg.txt            # EPG订阅源列表
└── output                 # 结果文件目录，包含生成的结果文件等
    └── data               # 结果数据缓存目录
    └── epg                # EPG结果目录
    └── ipv4               # IPv4结果目录
    └── ipv6               # IPv6结果目录
    └── result.m3u/txt     # m3u/txt结果
    └── hls.m3u/txt        # RTMP hls推流结果
    └── log                # 日志文件目录
        └── log.log        # 带时间、级别和运行 ID 的运行日志
        └── runtime.jsonl  # 结构化运行事件
        └── result.log     # 有效结果日志
        └── speed_test.log # 测速日志
        └── statistic.log  # 统计结果日志
        └── unmatch.log    # 未匹配频道记录
        └── *.jsonl        # 对应日志的结构化 JSON Lines 版本

工作流

Fork 本项目并开启工作流更新，具体步骤请见详细教程

命令行

pip install pipenv

pipenv install --dev

启动更新：

pipenv run dev

启动服务：

pipenv run service

GUI 软件

新版桌面 GUI 是 Windows 与 macOS 当前唯一受支持的图形界面，提供一键更新、实时进度、频道与结果管理、重新测速、RTMP 推流监控、数据源配置及任务历史。Docker 部署使用 Web 结果页，不包含此桌面界面。

安装依赖并启动桌面端：

pipenv install --dev
pipenv run ui

构建当前平台的安装包：

pipenv run ui_build

旧版 Tkinter 界面已弃用，仅为兼容现有用户而临时保留，并将在后续版本中移除。该界面不再维护、修复问题或新增功能；过渡期间仍可通过 pipenv run legacy_ui 启动，并通过 pipenv run legacy_ui_build 打包。分辨率检测需要系统安装 FFmpeg。Windows 可使用随包提供的 nginx-rtmp；macOS 会自动检测系统中带 RTMP 模块的 nginx，也可通过 IPTV_API_NGINX_PATH 和 IPTV_API_NGINX_RTMP_MODULE 指定可执行文件与动态模块。

Docker

1. Compose 部署（推荐）

下载docker-compose.yml或复制内容创建（内部参数可按需更改），在文件所在路径下运行以下命令即可部署：

docker compose up -d

2. 手动命令部署

（1）拉取镜像

docker pull guovern/iptv-api:latest

🚀 代理加速（若拉取失败可以使用该命令，但有可能拉取的是旧版本）：

docker pull docker.1ms.run/guovern/iptv-api:latest

（2）运行容器

docker run -d -p 80:8080 guovern/iptv-api

环境变量：

当宿主机/Docker 已启用 IPv6 时，容器会自动同时监听 IPv6 地址，无需额外配置；纯 IPv4 或禁用 IPv6 的环境则自动跳过。

如果需要修改环境变量，在上述运行命令后添加以下参数：

# 推荐：直接设置完整公网地址
-e PUBLIC_URL=https://iptv.example.com

使用仓库中的 Compose 文件时，只需通过 PORT 修改宿主机端口，例如 PORT=8088 docker compose up -d；Compose 会同时更新端口映射和兼容的 PUBLIC_PORT。 未设置或留空的 PUBLIC_URL 不会覆盖挂载配置文件中的 public_url。

除了以上环境变量，还支持通过环境变量覆盖配置文件中的配置项

挂载： 实现宿主机文件与容器文件同步，修改模板、配置、获取更新结果文件可直接在宿主机文件夹下操作，在上述运行命令后添加以下参数

# 挂载配置目录
-v /iptv-api/config:/iptv-api/config
# 挂载结果目录
-v /iptv-api/output:/iptv-api/output

3. 更新结果

日志接口默认返回兼容的纯文本格式；添加 ?format=jsonl 可获取结构化 JSON Lines。CLI 在交互式终端使用动态多任务进度，Docker、CI、重定向输出或设置 IPTV_API_PLAIN_OUTPUT=1 时自动使用稳定的逐行输出。

RTMP 推流：

[!NOTE]

1. 如果是服务器部署，建议通过 PUBLIC_URL 配置完整公网地址；旧版 PUBLIC_DOMAIN 与 PUBLIC_PORT 仍兼容
2. 开启推流后，默认会将获取到的接口（如订阅源）进行推流；请仅对你有明确授权、可合法分发或仅用于内部测试的内容启用该功能
3. 如果需要对本地视频源进行推流，可在config目录下新建hls文件夹，将以频道名称命名的视频文件放入其中，程序会自动推流到对应的频道中
4. 在中国大陆使用时，请特别确认内容授权、版权、网络视听与广播电视等相关合规要求；不要将本项目用于传播、转发或公开分发未经授权的直播源/节目源

如何使用推流？

更新日志

更新日志

关注

GitHub

关注我的 GitHub 账号 Guovin，获取更多实用项目

微信公众号

微信公众号搜索 Govin，或扫码，接收更新推送、学习更多使用技巧：

联系我

联系邮箱：[email protected]

捐赠

免责声明

• 本项目仅为工具/框架，不包含或提供任何直播源、受版权保护的节目或其他第三方内容，也不托管、缓存或承诺任何可用内容。用户需自行添加数据源，并确保所使用的数据源及其获取、转发、播放行为符合所在地区法律法规。
• 使用者对通过本项目获取、分发或播放的内容独立负责。请勿将本项目用于传播、分发、聚合、转播或观看未经授权的受版权保护内容，尤其是在中国大陆地区使用时，更应确保内容授权、平台资质、备案/许可及其他监管要求均已满足。
• 本项目提供的 RTMP/HLS 推流仅用于自有内容、已获授权内容或封闭环境下的技术测试；如果你无法确认授权状态，请关闭 open_rtmp，不要对公网开放相关接口。
• 在使用本项目时，应遵守当地相关法律法规与监管要求。作者不对因用户使用本项目而产生的任何法律责任承担责任。
• 商业、企业或生产环境使用前建议咨询合规/法律顾问并完成审查。

许可证

AGPL-3.0 License © 2024-PRESENT Govin

注意：本项目采用 AGPL-3.0。若将修改后的程序作为网络服务、公开容器镜像或以其他对外服务方式运行，须向使用者提供包括修改在内的完整源代码。详见：https://www.gnu.org/licenses/agpl-3.0.html