README En

中文 | English

</picture>

• ✅ Core Features
• ⚙️ Configuration
• 🚀 Quick Start
  • Configuration and Results Directory
  • Workflow
  • Command Line
  • GUI Software
  • Docker
• 📚 Documentation
• 📖 Detailed Tutorial
• 🗓️ Changelog
• ❤️ Donations
• 👀 Follow
• ⚠️ Disclaimer
• ⚖️ License

Sponsors

[!IMPORTANT]

1. Go to the Govin WeChat public account and reply with cdn to get an acceleration address for subscription sources and channel logos.
2. This project does not provide data sources. Please add your own before generating results. (How to add data sources?)
3. Result quality depends on the data sources and network conditions; adjust the configuration to suit your needs.

Core Features

Config

[!NOTE]
The following configuration items are located in config/config.ini and can be modified via the configuration file or environment variables. Save changes and restart to apply. A standalone configuration reference is also available.

Quick Start

Configuration and Results Directory

iptv-api/                  # Project root directory
├── config                 # Configuration files directory, includes config files, templates, etc.
│   └── hls                # Local HLS streaming files directory, used to store video files named after channel names
│   └── local              # Local source files directory; used to store multiple local source files; supports txt/m3u formats
│   └── config.ini         # Configuration parameters file
│   └── demo.txt           # Channel template
│   └── alias.txt          # Channel aliases
│   └── blacklist.txt      # Interface blacklist
│   └── whitelist.txt      # Interface whitelist
│   └── subscribe.txt      # Channel subscription sources list
│   └── local.txt          # Local source file
│   └── epg.txt            # EPG subscription sources list
└── output                 # Output files directory, includes generated result files, etc.
    └── data               # Result data cache directory
    └── epg                # EPG result directory
    └── ipv4               # IPv4 result directory
    └── ipv6               # IPv6 result directory
    └── result.m3u/txt     # m3u/txt result
    └── hls.m3u/txt        # RTMP hls stream result
    └── log                # Log files directory
        └── log.log        # Runtime log with timestamps, levels, and run IDs
        └── runtime.jsonl  # Structured runtime events
        └── result.log     # Valid result log
        └── speed_test.log # Speed test log
        └── statistic.log  # Statistics result log
        └── unmatch.log    # Unmatched channel records
        └── *.jsonl        # Structured JSON Lines companions

Workflow

Fork this project and initiate workflow updates, detailed steps are available at Detailed Tutorial

Command Line

pip install pipenv

pipenv install --dev

Start update:

pipenv run dev

Start service:

pipenv run service

GUI Software

The desktop GUI is the only supported graphical interface for Windows and macOS. It provides one-click updates, live progress, channel and result management, retesting, RTMP monitoring, source configuration, and task history. Docker deployments use web result pages and do not include this desktop interface.

Install dependencies and start the desktop app:

pipenv install --dev
pipenv run ui

Build a package for the current platform:

pipenv run ui_build

The legacy Tkinter interface is deprecated, retained temporarily for existing users, and scheduled for removal in a future release. It no longer receives maintenance, bug fixes, or new features. During the transition, start it with pipenv run legacy_ui or package it with pipenv run legacy_ui_build. Resolution probing requires FFmpeg. Windows can use the bundled nginx-rtmp runtime. On macOS the app detects an installed nginx build with the RTMP module; IPTV_API_NGINX_PATH and IPTV_API_NGINX_RTMP_MODULE can explicitly select the executable and dynamic module.

Docker

1. Deployment with Compose (recommended)

Download the docker-compose.yml or create one by copying the content (internal parameters can be changed as needed), then run the following command in the path where the file is located:

docker compose up -d

2. Manual deployment with commands

(1) Pull the image

docker pull guovern/iptv-api:latest

🚀 Proxy acceleration (use this command if pulling fails, but it may download an older version):

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

(2) Run the container

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

Environment variables:

When IPv6 is enabled on the host/Docker, the container automatically listens on IPv6 addresses as well, with no extra configuration; in IPv4-only or IPv6-disabled environments it is skipped automatically.

If you need to modify environment variables, add the following parameters after the above run command:

# Recommended: set the complete public URL
-e PUBLIC_URL=https://iptv.example.com

With the repository Compose file, change only the host port through PORT, for example PORT=8088 docker compose up -d. Compose updates both the port mapping and legacy PUBLIC_PORT. An unset or empty PUBLIC_URL does not override public_url in the mounted configuration.

In addition to the environment variables listed above, you can also override the configuration items in the configuration file via environment variables.

Mounts: used to synchronize files between the host and the container. You can edit templates, configs, and access generated result files directly on the host. Append the following options to the run command above:

# Mount config directory
-v /iptv-api/config:/iptv-api/config
# Mount output directory
-v /iptv-api/output:/iptv-api/output

3. Update Results

Log endpoints return the compatible plain-text format by default; add ?format=jsonl for structured JSON Lines. The CLI uses a dynamic multi-task display in interactive terminals and automatically falls back to stable line-oriented output in Docker, CI, redirected output, or when IPTV_API_PLAIN_OUTPUT=1 is set.

RTMP Streaming:

[!NOTE]

1. For server deployments, set the complete public address through PUBLIC_URL; legacy PUBLIC_DOMAIN and PUBLIC_PORT remain supported.
2. When streaming is enabled, obtained interfaces such as subscription sources are streamed by default. Use this only for content you own, are authorized to redistribute, or need for closed/internal testing.
3. To stream local videos, create config/hls and place files named after their channels in it. The program streams them to the corresponding channels.
4. In Mainland China, ensure that content authorization, copyright, network-audiovisual, and broadcasting requirements are satisfied. Do not distribute, relay, or publicly expose unauthorized live streams or program sources.

How to use streaming?

Changelog

Changelog

Follow

GitHub

Follow my GitHub account Guovin to find more useful projects

WeChat public account

WeChat public account search for Govin, or scan the code to receive updates and learn more tips:

Contact Me

Contact via email: [email protected]

Donations

Disclaimer

• This project is provided as a tool/framework only; it does not include, host, cache, or guarantee any live streams, copyrighted programs, or other third-party content. Users must add their own data sources and ensure that the data sources used and their use comply with applicable laws and regulations in their jurisdiction.
• Users are solely responsible for any content obtained, distributed, relayed, or played through this project. Do not use it to distribute, share, relay, or watch copyrighted content without authorization, especially in Mainland China where content authorization, licensing, filing/permit, and other regulatory requirements may apply.
• The RTMP/HLS push features are intended only for owned content, explicitly authorized content, or closed-environment technical testing. If you cannot verify authorization, disable open_rtmp and do not expose the related endpoints to the public internet.
• When using this project, comply with local laws, regulations, and supervisory requirements. The author is not liable for any legal responsibility arising from users' use of this project.
• For commercial, corporate, or production use, consult compliance/legal counsel and complete a review.

License

AGPL-3.0 License © 2024-PRESENT Govin

Note: This project is licensed under AGPL-3.0. If you operate a modified version as a network service (e.g., hosted service or publicly published container/image), you must provide users with the complete corresponding source code (including your modifications). See: https://www.gnu.org/licenses/agpl-3.0.html