akiralereal/iptv turns scattered live stream links into one managed channel list

A source manager, not a static channel list

The interesting thing about akiralereal/iptv is that it treats live TV links as something you operate rather than something you collect. The project describes itself as a modular IPTV live source management and distribution system aimed at home media users and NAS owners, and the emphasis falls on management: every platform has its own module, with its own switch, its own configuration and its own health state, and you can see the status of a module in the admin panel and turn it off when the platform behind it goes dark.

The default deployment aggregates more than 800 channels. The largest single module is 央视频, which supplies 63 public HD channels plus 10 member channels reachable with your own account, alongside the CCTV set, CGTN in several languages and the main provincial satellite channels. Other modules cover 咪咕 for CCTV, satellite and sports, iQiyi Sports for whatever match is currently on, iPanda for 22 panda camera streams, and scrape modules for Bilibili, Douyin, Huya and Douyu. Regional modules cover provincial and municipal broadcasters across most of the country, and there is a landscape and slow broadcast group built on 央视网 直播中国.

The count is not a fixed promise. The project says the real number changes with platform interface state, regional network conditions and which modules you enable, and that the list keeps growing as modules and event content are added. That honesty about the number is a good sign for how the rest of the documentation is written.

The output side is a playlist and a program guide. The system generates M3U, TXT and EPG output, plus compatibility and full proxy variants for players that need them, and it supports multiple profiles with user tokens so each television or person in the household can have a different channel mix.

Every platform module has a different refresh, auth and proxy strategy

The reason the project needs a proxy layer at all is that most of these platforms do not serve a clean, static stream URL. The 央视频 module, for example, takes a ticket anonymously for the public channels and switches backup CDNs automatically, while the member channels reuse the deployer's own persistent login state, where the web player issues and de-scrambles the stream into local H.264/AAC fMP4 HLS. The stated reason for that work is a concrete failure: a plain player pulling the member stream gets sound but no picture. That is the kind of detail that only appears in a project that has actually looked at the streams.

Other modules work in similar ways but at different depths. The 咪咕 module picks a quality based on account permission, device compatibility and platform interface state. The iPanda module needs no login and no configuration at all, and the 2 general channels and 2 rare animal streams check public availability at playback time and switch upstream CDN. The Guangdong sports module discovers events from the official H5 page at runtime, adds a channel when an event starts and removes it when it ends.

The repository structure reflects this modularity. There is an extractors directory for the per platform parsing, a web directory for the browser admin panel, a utils directory, and JSON files that hold the source definitions: built-in-sources.json, epg-sources.json.example, external-sources.json.example and system-config.json.example. Channels are also shipped as plain IPTV.m3u and IPTV-overseas.m3u files, so the project is usable as a source of links even if you never run the server.

Relay the manifest, let the player fetch the segments

The proxy design is where the engineering judgment shows. For several modules the server relays only the playlist, and the media segments are fetched by the player directly from the upstream CDN. The Guangdong sports module does it that way, and the reason given is concrete: the player connects to the official CDN without the source request headers and without a signature, which is the shape the CDN expects. The Macau lotus channel works the same way, with the signed media segments going direct, while the server re-reads the official site whenever a cached entry expires, and the entry is cached for five minutes.

When direct fetch will not work, the same streams can be fully relayed by adding a query parameter to the address, written as ?relay=2 in the player URL. The same full proxy treatment is applied unconditionally in some modules. The Chongqing broadcast module relays the manifest, the AES key and the media segments entirely, and the Sichuan module fills in the source site anti-hotlink request headers before relaying the manifest, key and segments. The Macau TV module instead asks the official routing interface for a CDN reachable from the current network, caching that for five minutes, and lets the player connect to it.

The trade-off is straightforward and worth understanding before you deploy. Full proxying centralizes traffic and works around header and signature problems at the cost of bandwidth on your server. Manifest only relaying keeps your server light and the CDN happy, but it means the player must be able to reach the upstream itself, which is exactly what the Macau note warns about.

Headless Docker means importing cookies by hand

Login is where a self-hosted setup gets awkward, and the project is unusually clear about it. The desktop 央视频 flow can open a login window directly from source management. On a headless Docker or NAS deployment there is no desktop, so the documented path is to copy the entire Cookie string out of your own browser's developer tools and import it. The documentation even explains the trap: the session cookie is HttpOnly, so a bookmarklet style tool cannot read it, you have to use the developer tools panel.

The same applies to iQiyi Sports, where you log in by scanning a code or entering a text message verification code in the source management window, or import your own cookie request headers and JSON. The Beijing and Sichuan broadcast modules use the same import model, with the Sichuan case offering a bookmarklet that reads the source site token. The 凤凰卫视 module accepts a token or cookie and stores it persistently.

Two things are worth checking. Credentials live only in your own deployment, and for the iQiyi module the documentation states that credentials are kept in a dedicated browser profile and are not included in configuration backups, while the cookie you import for 央视频 is renewed automatically by the server afterwards. The project also states that cookies are only used to obtain the stream, are not written into the subscription and are not sent to the media CDN, and the generated subscription addresses can be protected with an access password so a public link is not handed out accidentally.

The honest summary is that this system is designed for someone who is comfortable pasting a session cookie into a web form, and it is not designed for a shared deployment where several people hold different accounts.

Running it on a NAS with the compose file as it ships

Docker is the recommended deployment, and the image is published as akiralereal/iptv:latest. The compose file in the repository maps a single port and passes configuration through environment variables, which is the part you will actually edit:

services:
  iptv:
    image: akiralereal/iptv:latest
    container_name: iptv
    init: true
    ports:
      - "1905:1905"
    environment:
      - muserId=
      - mtoken=
      - mport=1905
      - mhost=
      - mrateType=3
      - mpass=
      - menableHDR=true
      - menableH265=true
      - mupdateInterval=6

mport must match the port mapping, and mrateType selects quality, where 2 is 480p, 3 is 720p and 4 is 1080p and requires a VIP account. mpass adds a password to the access path, mupdateInterval sets how often program information is refreshed in hours, and mhost is the external address. Several content switches are available as well, including mblank for a blank deployment, menableMigu for the 咪咕 source that carries CCTV, satellite and sports, and menableBuiltInSources and menableBuiltInSubscriptions.

The image is built on node:22-alpine. Chromium is installed for the web scraping features, and the build sets PUPPETEER_SKIP_DOWNLOAD=true with PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium so Puppeteer uses the system browser instead of downloading its own. tini is installed as the init process because Node as PID 1 does not reap the Chromium child processes it leaves behind. The data directory defaults to /iptv/data and both /iptv/data and the older /migu/data are declared as volumes, and a utility detects the old path and keeps using it when data already lives there, so upgrades do not lose your configuration.

For a first use, start with the default configuration and the free public channels, then add your own account in source management for the platforms where you want better quality.

The announcement group is pinned to the top and cannot be removed

One design decision deserves an explicit mention, because it will surprise anyone who organises their playlist. The first entry of the generated playlist is always the project's own announcement group, containing three self-produced short clips. One shows how to use the project, one is a login tutorial for the 央视频 member channels, and one demonstrates how to subscribe a third party list from the from-the-web repository in the backend.

The group can be hidden item by item from 我的频道, and hidden items can be restored later from the 已隐藏 list. But as long as anything in it is shown, the group is fixed in the first position, and it cannot be deleted, moved, reordered or renamed. That is a deliberate product decision, since the clips explain how the remaining features work, and it is the kind of thing that a self-hosted tool usually has no business enforcing.

If you hand the subscription address to another device, that first group travels with it. Users who want a bare list of channels have to hide those three entries, and the operation has to be repeated per profile if you run several.

The from-the-web directory in the repository is worth a separate look for anyone building their own list, since the announcement tutorial points at it as an example of adding a curated third party source to the custom source section of the backend.

Frequent releases, a GPL licence, and coverage that depends on other people

The repository is not archived and the last push was on 2026-10-19. The release cadence in October 2026 is fast: v4.36.0 on 2026-10-12 added a dedicated configuration profile cleanup and bulk detection of blocked players for 咪咕, v4.33.0 on 2026-10-10 added push notifications to a group bot and tidied the backend settings page, and v4.32.0 on 2026-10-09 added Qingdao five-route live TV channels, the Tiantai Hehe channel, and automatic Huya line switching. Each release notes name a specific fix, which is the useful kind of changelog.

The licence is GPL-3.0-only, so if you modify the code and distribute it, the modified distribution carries the same obligation. Anyone running it as a service for their own household is not affected by that in any practical sense.

The real cost of running this is maintenance and coverage fragility, and the project is unusually forthcoming about it. The Macau television module only opens outside mainland China, so both the server that queries the CDN and the device that plays the video have to reach outside the mainland, and that module ships disabled. The iPanda streams are capped at a genuine 720p, and the overseas and Asia Pacific groups contain fixed lists that were verified once, with a smaller set of channels needing dynamic parsing. Every module is a bet that a third party interface keeps behaving, and the failure mode is a channel that stops playing rather than an error message.

The project also carries an explicit copyright note. It hosts no third party programming itself and only organises publicly reachable addresses and channel metadata, but it states plainly that publicly reachable does not mean public domain, and that copying, rebroadcasting or commercial use need proper authorisation. For a rights holder there is a takedown process described in the project documentation.

Editorial conclusion

akiralereal/iptv is worth adopting if you run a NAS or home server, want a single playlist instead of a folder of bookmarks, and are willing to supply your own account cookies for the platforms that gate high quality streams. It is the wrong tool if you need a guaranteed right-to-play, if you want a low effort install on a machine without a Chromium-capable architecture, or if you cannot accept that upstream interface changes can break a module overnight. Before deploying, read the source table for the platform you care about, check the region limits the project states for the Macau modules, and decide where your own credentials will live, because those cookies are stored only in your deployment.

Frequently asked questions

Official sources

1. akiralereal/iptv on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases