How zhimin-dev/iptv-checker works
1. This repository is primarily an IPTV playlist checking product, not just a library. From the files shown, the repo is packaged for three delivery modes: Docker image, Docker Compose, and standalone CLI/binary.
2. The application’s core runtime is a long-lived checker service with a Web management UI on top. The container exposes internal service port 8089, and the README maps it to host port 8081, so the UI/API and background jobs are served by the same process boundary.
3. The main domain subsystem is playlist ingestion and normalization. It accepts M3U, M3U8, and TXT playlists, then standardizes channel metadata such as tvg-name, tvg-id, and group-title, including EPG-based name matching and cleanup of quality suffixes like “4K”.
4. The checking subsystem is the heart of the product. It supports two validation paths: lightweight HTTP checks and stronger FFmpeg-based checks. That implies a split between fast availability probing and more accurate stream verification.
5. Task execution is asynchronous and batch-oriented. The README explicitly calls out concurrent checks, scheduled tasks, and import/export of tasks, so the architecture likely has a job queue or worker pool behind the UI rather than single-request processing.
6. Results are transformed into exportable outputs. The product supports exporting usable channel lists in M3U or TXT format, and can split output by IPv4 vs IPv6. That means the checker is not only validating streams but also acting as a filtering and publishing pipeline.
7. The Web management layer is an operational control plane. It handles task management, configuration editing, backup/restore, and result export, with a dark-mode UI. This UI is the main boundary for human interaction; the actual checking logic runs behind it.
8. Configuration is a first-class subsystem. The README highlights timeout tuning, custom sorting, keyword matching, fastest-stream selection, EPG settings, host management, and group mapping import/export. That suggests the app stores and reuses operational metadata across runs, not just ephemeral check state.
9. External integration is centered on GitHub API access. The app uses GitHub to fetch release-related data and/or assets, and it supports a GitHub token to raise API quota from 60 requests/hour to 5000 requests/hour. It also has fallback behavior to HTML parsing when unauthenticated requests are rate-limited.
10. FFmpeg is an important runtime dependency because it materially changes the architecture of stream validation. The system must spawn or orchestrate media probes in addition to plain HTTP requests, so the deployment environment needs FFmpeg available for full functionality.
11. The repo’s delivery and release pipeline is organized around GitHub Actions and container packaging. The visible workflows include separate build paths for Docker and GitHub releases, plus a release workflow, indicating automated build/test/package publishing rather than manual release steps.
12. Operationally, Docker is the primary deployment boundary. The included docker-compose.yaml and dockerfile show the project is designed to run as a self-contained service, while the standalone binary path is provided for users who prefer CLI execution.
13. From an architecture-diagram perspective, the key data flow is: user uploads or configures playlist/EPG/settings → backend schedules check jobs → checker validates streams via HTTP and/or FFmpeg → results are normalized and filtered → UI exposes them for review/export → optional backup/import/export and release packaging keep state portable.
14. The recent changelog items suggest the architecture has also grown security and portability boundaries: GitHub REST API migration, SSRF and path traversal hardening, connection reuse optimizations, and global host management. Those are important to reflect as cross-cutting concerns in the diagram, even though the source tree is not included here.
Main entry points: workflows Release flow · dockerfile Docker image · Makefile CLI binary · docker-compose.yaml Compose stack
Components 17
Delivery
Ways the checker is packaged and run.
- Docker image · Primary containerized deployment for the service.
dockerfile - Compose stack · Self-contained multi-container or single-service run via Compose.
docker-compose.yaml - CLI binary · Standalone executable path for non-container execution.
Makefile
Runtime
Core service, workflow, and domain subsystems.
- Checker service · Single process boundary hosting the web UI, API, and background jobs.
- Web UI · Operational interface for managing tasks, settings, backups, and exports.
- Task engine · Schedules, queues, and runs concurrent playlist checking work.
- Playlist ingest · Parses M3U, M3U8, and TXT playlists and standardizes channel metadata.
- EPG matcher · Matches EPG names/IDs and cleans noisy channel labels such as quality suffixes.
- Check engine · Performs stream validation and decides channel availability.
- HTTP probe · Lightweight availability validation path using HTTP requests.
- FFmpeg probe · Stronger media-stream verification path using FFmpeg.
- Result pipeline · Normalizes checked channels into usable output lists.
- Exports · Produces filtered M3U or TXT outputs, including IPv4/IPv6 splits.
Operations
Configuration, integrations, and release pipeline.
- Config store · Persists timeouts, sorting, keyword rules, host mapping, and EPG settings.
- GitHub API · Fetches release-related data with token-based quota expansion and fallback parsing.
- Safety guards · Protects against SSRF, path traversal, and other operational attack surfaces.
- Release flow · GitHub Actions and packaging workflow for Docker and releases.
.github/workflows
Connections 22
- Docker image → Checker service: runs · Container starts the checker service.
- Compose stack → Checker service: orchestrates · Compose wires the service runtime and exposed port.
- CLI binary → Checker service: starts · Standalone build launches the same core runtime.
- Checker service → Web UI: serves · The UI is exposed by the main service boundary.
- Checker service → Task engine: hosts · Background jobs run inside the same process boundary.
- Web UI → Config store: edits · Users manage operational settings and persisted state.
- Web UI → Task engine: submits · UI creates import, check, export, and maintenance tasks.
- Task engine → Playlist ingest: feeds · Imported playlists enter normalization before checking.
- Playlist ingest → EPG matcher: normalizes · Metadata cleanup and EPG-based matching standardize channels.
- EPG matcher → Check engine: prepares · Cleaned channel records are handed to the validator.
- Task engine → Check engine: dispatches · Concurrent work batches route channels into validation.
- Check engine → HTTP probe: uses · Fast path for lightweight availability checks.
- Check engine → FFmpeg probe: uses · Deep path for stronger stream verification.
- FFmpeg probe → Result pipeline: yields · Verified stream results flow into filtering and publishing.
- HTTP probe → Result pipeline: yields · Probe outcomes are converted into output candidates.
- Result pipeline → Exports: publishes · Filtered results are emitted as M3U or TXT exports.
- Config store → Task engine: drives · Timeouts, sorting, keywords, and host rules shape execution.
- Config store → Playlist ingest: guides · Mapping and normalization settings affect ingest behavior.
- GitHub API → Release flow: supports · Release data and assets come from GitHub services.
- Safety guards → Checker service: protects · Cross-cutting hardening applies to the runtime boundary.
- Release flow → Docker image: builds · CI packages container artifacts.
- Release flow → CLI binary: builds · CI also publishes standalone binaries.