Welcome to IPTVTools’s documentation!¶

Installation¶

The simplest way to install is downloading from PyPI:

$ pip install -U iptvtools

If you prefer the latest master branch or want to make some code changes, you can download and install with the following command:

$ git clone https://github.com/huxuan/iptvtools.git
$ cd iptvtools
$ pip install .

Scripts¶

iptv-filter¶

Usage¶

usage: iptv-filter [-h] [--channel-exclude CHANNEL_EXCLUDE]
                   [--channel-include CHANNEL_INCLUDE]
                   [--group-exclude GROUP_EXCLUDE]
                   [--group-include GROUP_INCLUDE] [--min-height MIN_HEIGHT]
                   [-c CONFIG] [-i [INPUTS [INPUTS ...]]] [-I INTERVAL]
                   [-L LOG_LEVEL] [-n] [-o OUTPUT] [-r] [-R]
                   [-s [SORT_KEYS [SORT_KEYS ...]]]
                   [-t [TEMPLATES [TEMPLATES ...]]] [-T TIMEOUT] [-u UDPXY]
                   [-v]

optional arguments:
  -h, --help            show this help message and exit
  --channel-exclude CHANNEL_EXCLUDE
                        Channels to exclude with regex. Note: Blacklist has
                        higher priority than whitelist. (default: None)
  --channel-include CHANNEL_INCLUDE
                        Channels to include with regex. Note: Only channels in
                        the whitelist will be included if set. (default: None)
  --group-exclude GROUP_EXCLUDE
                        Groups to exclude with regex.Note: Blacklist has
                        higher priority than whitelist. (default: None)
  --group-include GROUP_INCLUDE
                        Groups to include with regex.Note: Only groups in the
                        whitelist will be included if set. (default: None)
  --min-height MIN_HEIGHT
                        Minimum height/resolution to accept, 0 means no
                        resolution filtering. (default: 0)
  -c CONFIG, --config CONFIG
                        Configuration file to unify title and id. (default:
                        config.json)
  -i [INPUTS [INPUTS ...]], --inputs [INPUTS [INPUTS ...]]
                        One or more input m3u playlist files/urls. (default:
                        ['https://iptv-org.github.io/iptv/index.m3u'])
  -I INTERVAL, --interval INTERVAL
                        Interval in seconds between successive fetching
                        requests. (default: 1)
  -L LOG_LEVEL, --log-level LOG_LEVEL
                        Log level. (default: INFO)
  -n, --skip-connectivity-check
                        Skip connectivity check. (default: False)
  -o OUTPUT, --output OUTPUT
                        Output file name. (default: iptvtools.m3u)
  -r, --replace-group-by-source
                        Flag to replace the group title with the source name,
                        where the source name is the basename of input
                        files/urls without extension. (default: False)
  -R, --resolution-on-title
                        Flag to append resolution such as 8K, 4K, 1080p, 720p
                        to the title. (default: False)
  -s [SORT_KEYS [SORT_KEYS ...]], --sort-keys [SORT_KEYS [SORT_KEYS ...]]
                        List of keys to sort the channels. Valid options
                        currently supported are `group-title`, `tvg-id`,
                        `template-order`, `height` and `title`. (default:
                        ['group-title', 'tvg-id', 'height', 'title'])
  -t [TEMPLATES [TEMPLATES ...]], --templates [TEMPLATES [TEMPLATES ...]]
                        Template m3u files/urls with well-maintained channel
                        information to replace the matched entries. (default:
                        [])
  -T TIMEOUT, --timeout TIMEOUT
                        Timeout threshold for fetching request. (default: 10)
  -u UDPXY, --udpxy UDPXY
                        UDP Proxy for certain IPTV channels. (default: None)
  -v, --version         show program's version number and exit

Example¶

There is a well-maintained IPTV list only for Beijing Unicom and a well-maintained templates & EPG mainly for China. So for me:

$ iptv-filter \
-i https://gist.githubusercontent.com/sdhzdmzzl/93cf74947770066743fff7c7f4fc5820/raw/11107d2dcfe2f5785e7ada94bb44c0cd349191c5/bj-unicom-iptv.m3u \
-t http://epg.51zmt.top:8000/test.m3u

With UDPXY, it becomes:

$ iptv-filter \
-i https://gist.githubusercontent.com/sdhzdmzzl/93cf74947770066743fff7c7f4fc5820/raw/11107d2dcfe2f5785e7ada94bb44c0cd349191c5/bj-unicom-iptv.m3u \
-t http://epg.51zmt.top:8000/test.m3u \
-u http://192.168.0.1:8888

Just replace http://192.168.0.1:8888 with corresponding UDPXY prefix should be OK.

Selected Parameters¶

Here is some further explanation for those not so obvious parameters.

GROUP_EXCLUDE¶

Filter the playlist depends on the group title with a blacklist (regular expression). Note that, it has higher priority than the whitelist GROUP_INCLUDE.

GROUP_INCLUDE¶

Filter the playlist depends on the group title with a whitelist (regular expression). Note that, if set, only groups match the pattern will be included.

CHANNEL_EXCLUDE¶

Filter the playlist depends on the channel title by a blacklist (regular expression). Note that, it has higher priority than the whitelist CHANNEL_INCLUDE.

CHANNEL_INCLUDE¶

Filter the playlist depends on the channel title by a whitelist (regular expression). Note that, if set, only channels match the pattern will be included.

MIN_HEIGHT¶

HEIGHT is a dominant factor of stream quality, where 1080 in height means 1080p. It is necessary to set this filter if the stream is supposed to be shown on high resolution screens, e.g., a 4K TV.

CONFIG¶

CONFIG is a customized configuration to unify title and id. title is the exact title which will be shown and the id is used for potential match with the template. A general idea is to make the id as simple as possible so they will have a high possibility to match, though there might be some false positive cases. So, id_unifiers can be treated as a further simplification of title_unifier.

For example, entry "-": "" will convert CCTV-1 to CCTV1, entry "＋": "+" will convert CCTV-5＋ to CCTV-5+. A whole replacement is also possible, as "BTV冬奥纪实": "北京纪实" will match the whole of BTV冬奥纪实 and replace it with 北京纪实.

Please be caution about using too many of them since this simplified strategy is just for some basic requirement. Some entries may lead to some unexpected changes. For example, entry "CCTV-1": "中央1套" will convert CCTV-11 to 中央1套1. So, in generally, only keep those necessary entries and keep it as simple as possible.

SORT_KEYS¶

List of keys to sort the channels. Valid options currently supported are tvg-id, height and title. By default, it will work the same as -s tvg-id resolution title, and you can change the order as you want. If you want to have more keys to be supported, just let me know.

TEMPLATES¶

A m3u playlist with well-maintained information to cooperate with EPG. Please refer to Well‐maintained templates & EPGs.

BTW, there is also a list Well‐maintained playlists.

TIMEOUT¶

TIMEOUT is used to check the connectivity. Direct check which only fetch the response header tends to be fast. But it usually takes seconds to probe stream information depends on your network (bandwidth and latency). For me, it is about 3 to 5 seconds.

UDPXY¶

If the IPTV streams is forwarded by UDPXY, setting it will convert all the urls automatically. For examples, with UDPXY http://192.168.0.1:8888/, rtp://123.45.67.89:1234 will be converted to http://192.168.0.1:8888/rtp/123.45.67.89:1234.

SKIP_CONNECTIVITY_CHECK¶

Skip any connectivity check (to be used to just apply title and id unifiers) use in combination with -I 0