This commit is contained in:
154
README.md
Normal file
154
README.md
Normal file
@@ -0,0 +1,154 @@
|
||||
# IPTV Checker (iptvc)
|
||||
|
||||
Консольная программа для проверки IPTV-плейлистов в формате m3u или m3u8.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Проект находится на ранней стадии разработки.
|
||||
> Реализован минимально необходимый функционал.
|
||||
> Возможны ошибки, неточности и обратно несовместимые изменения.
|
||||
|
||||
Для дополнительной документации можно обращаться в директорию [docs](./docs).
|
||||
|
||||
## Установка
|
||||
|
||||
Достаточно скачать и распаковать архив с подходящим исполняемым файлом [со страницы релизов](https://git.axenov.dev/IPTV/iptvc/releases):
|
||||
|
||||
| ОС | Архив | Платформа |
|
||||
|---------|----------------------|-----------|
|
||||
| Linux | `linux_amd64.zip` | x64 |
|
||||
| MacOS | `darwin_amd64.zip` | x64 |
|
||||
| Windows | `windows_amd64.zip` | x64 |
|
||||
|
||||
## Компиляция
|
||||
|
||||
Для сборки потребуется golang v1.23.6 и выше.
|
||||
На версиях ниже не проверялось.
|
||||
|
||||
1. Склонировать репозиторий
|
||||
2. Находясь в корне репозитория, следует выполнить `make` или `make help` для получения справки.
|
||||
3. Другой способ -- выполнить `go run .` для быстрого запуска.
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
Открыть терминал в директории, куда распакован исполняемый файл `iptvc`.
|
||||
|
||||
Выполнить `./iptvc help` для получения краткой справки.
|
||||
|
||||
Если был клонирован репозиторий, то вместо `./iptvc` можно запустить `go run .`
|
||||
|
||||
Ниже рассмотрены простые примеры использования программы для проверки плейлистов.
|
||||
|
||||
### Проверка файла плейлиста
|
||||
|
||||
1. Скачать любой файл плейлиста, сохранив его в файл с именем, например, `mypls.m3u`
|
||||
2. Выполнить команду `./iptvc check -f mypls.m3u`
|
||||
|
||||
Можно указывать множество разных файлов (каждый с `-f`) и комбинировать с другими аргументами.
|
||||
|
||||
### Проверка плейлиста по ссылке
|
||||
|
||||
1. Найти прямую ссылку на плейлист в интернете, например, `http://m3u.su/XYZ`
|
||||
2. Выполнить команду `./iptvc check -u http://m3u.su/XYZ`
|
||||
|
||||
Можно указывать множество разных ссылок (каждый с `-u`) и комбинировать с другими аргументами.
|
||||
|
||||
### Проверка плейлиста из ini-списка
|
||||
|
||||
Подробности об ini-файле и его формате можно прочесть здесь: https://git.axenov.dev/IPTV/playlists
|
||||
|
||||
1. Скачать файл [`playlists.ini`](https://git.axenov.dev/IPTV/playlists/raw/branch/master/playlists.ini) или создать локальный файл в аналогичном формате (например, `./test.ini`)
|
||||
2. Выполнить команду `./iptvc check` или `./iptvc check -i playlist.ini` для проверки всех плейлистов из файла `./playlists.ini`
|
||||
3. Выполнить команду `./iptvc check -i test.ini -c ABC`, чтобы проверить только плейлист с кодом `ABC` из файла `./test.ini`
|
||||
|
||||
Аргумент `-i` можно указывать только однажды, но его можно комбинировать с `-f` и `-u`.
|
||||
|
||||
### Другие возможности команды `check`
|
||||
|
||||
* `--json|-j` -- вывести результаты проверки в формате JSON
|
||||
* `--quiet|-q` -- полностью подавить вывод лога (включая отладочную информацию)
|
||||
* `--verbose|-v` -- добавить в лог более подробную отладочную информацию (значительно увеличит количество строк!)
|
||||
* `--tags|-t` -- файл с перечислением тегов (подробности см. [здесь](https://git.axenov.dev/IPTV/playlists#файл-channelsjson))
|
||||
|
||||
Например, можно получить только json с результатами, передать его в `jq` и, отфильтровав результат, вывести названия оффлайн каналов:
|
||||
|
||||
```
|
||||
./iptvc check ... -j -q | jq '.[].channels[] | select(.isOnline == false).title'
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> Набери `./iptvc help` для получения помощи.
|
||||
|
||||
## Результаты проверки
|
||||
|
||||
Программа логирует процесс и результаты своей работы.
|
||||
Рассмотрим лог на примере.
|
||||
|
||||
В рабочей директории лежит файл `playlists.ini`, в котором минимально описано два плейлиста:
|
||||
|
||||
```ini
|
||||
[first]
|
||||
pls='https://example.com/list1.m3u'
|
||||
[second]
|
||||
pls='https://example.com/list2.m3u'
|
||||
```
|
||||
|
||||
Программа запущена следующим образом: `./iptvc check -c first` (чтобы проверить только плейлист с кодом `first` из ini-файла).
|
||||
|
||||
Вывод будет примерно таким:
|
||||
|
||||
```
|
||||
2025/01/02 12:34:00 Loading playlists from ini-file: /home/user/playlists.ini
|
||||
2025/01/02 12:34:00 Loaded 2 playlists
|
||||
2025/01/02 12:34:00 [001/001] Playlist [first]
|
||||
2025/01/02 12:34:00 Fetching... (https://example.com/list1.m3u)
|
||||
2025/01/02 12:34:00 Parsing content...
|
||||
2025/01/02 12:34:00 Parsed, checking channels (114)...
|
||||
2025/01/02 12:34:00 Check parameters calculated: count=114 timeout=8.00s routines=12
|
||||
2025/01/02 12:34:12 Checked successfully! online=101 onlinePercent=88.60% offline=13 offlinePercent=11.40% elapsedTime=12.39s
|
||||
```
|
||||
|
||||
Разберём построчно:
|
||||
1. Загрузка ini-файла
|
||||
2. Файл загружен, в нём 2 плейлиста
|
||||
3. Начало обработки плейлиста `first`
|
||||
4. Скачивание плейлиста `first` по ссылке `https://example.com/list1.m3u` в оперативную память
|
||||
5. Плейлист скачан, начало разбора плейлиста
|
||||
6. Плейлист разобран, начало проверки каналов (114 штук)
|
||||
7. Определены параметры проверки (подробности ниже)
|
||||
8. (спустя время) Проверка успешно завершена: онлайн каналов 101 (88.60% от всех), оффлайн каналов 13 (11.40% от всех), затрачено 12 секунд.
|
||||
|
||||
### Параметры проверки
|
||||
|
||||
Выше в п.7 видно некоторые служебные данные:
|
||||
* `timeout` -- таймаут каждого запроса в секундах (макс. время ожидания ответа канала);
|
||||
* `routines` -- количество одновременных проверок.
|
||||
|
||||
Эти параметры рассчитываются динамически для каждого плейлиста в отдельности, исходя из количества каналов в каждом (`count`).
|
||||
См. [app/checker/checker.go](app/checker/checker.go) для подробностей.
|
||||
|
||||
Идея в том, чтобы найти баланс между скоростью проверки и качеством:
|
||||
* чем ниже коэффициент `k`, тем больше горутин, меньше таймаут, быстрее проверка, хуже результаты;
|
||||
* чем выше коэффициент `k`, тем меньше горутин, больше таймаут, медленнее проверка, лучше результаты.
|
||||
|
||||
На скорость проверки влияют:
|
||||
* количество горутин (чем выше, тем больше каналов проверяется параллельно);
|
||||
* таймаут (тем ниже, тем быстрее закончится проверка канала);
|
||||
* количество каналов (чем больше, тем дольше общий процесс);
|
||||
* скорость ответа сервера (чем выше, тем хуже) и количество данных, которые он отдаёт (чем больше, тем хуже).
|
||||
|
||||
На качество проверки влияет таймаут:
|
||||
* чем выше, тем выше вероятность получить успешный ответ от сервера, транслирующего поток;
|
||||
* чем ниже, тем выше вероятность не дождаться успешного ответа и засчитать канал нерабочим.
|
||||
|
||||
> [!NOTE]
|
||||
> Логика балансирования будет уточняться и корректироваться по мере развития проекта, исходя из реального применения.
|
||||
|
||||
### Коды возврата
|
||||
|
||||
* 0 -- успех
|
||||
* 1 -- общая ошибка, см. вывод
|
||||
* 2 -- команде `check` не переданы параметры `--file`, `--url` и `--code`
|
||||
|
||||
## Лицензия
|
||||
|
||||
ПО распространяется на условиях [лицензии MIT](LICENSE).
|
||||
Reference in New Issue
Block a user