Plugins

IPTV Checker

Version: 1.26.1421301 Author: PiratesIRC Last Updated: May 22 2026, 14:18 UTC

A Dispatcharr Plugin that goes through a playlist to check IPTV channels

Downloads

Latest Release

Download: iptv-checker-latest.zip
Built: May 22 2026, 14:18 UTC
Source Commit: c53b209

Checksums:

MD5:    49d562cb3128c2335d654a82abd93d7f
SHA256: d6ece367d7f57c3149756d3841d558ccaffc3df0dcf443cb918b923d22c5f03a

All Versions

Version	Download	Built	Commit	MD5	SHA256
`1.26.1421301`	Download	May 22 2026, 14:18 UTC	`c53b209`	49d562cb3128c2335d654a82abd93d7f	d6ece367d7f57c3149756d3841d558ccaffc3df0dcf443cb918b923d22c5f03a
`1.26.1362003`	Download	May 16 2026, 20:45 UTC	`5d5ad16`	a4b56a82858b7b976d87c703f80e163e	820e7db19aeb50460d51e5d9069acacd413bc8f573bf9db2f83cac3dae44ce7b
`1.26.1221101`	Download	May 02 2026, 17:57 UTC	`aa662b3`	e82d4b95df6c089471ca0547e8b2791c	75b2b8379912cd82ca2026a0ab58d875e99af65308253c163adc1557464113f4
`1.26.1161403`	Download	Apr 26 2026, 14:39 UTC	`740b4ee`	cc0be9f97a30b0e9d88119f59e726119	731abcffedf0b4959982109c05649cd30d64aa119193666ba6b2465606f2b75f
`1.26.1081815`	Download	Apr 18 2026, 19:11 UTC	`f7bd820`	004cdba61f06fb24e7cb201e3ddd5568	31027fb0ca94093489d169e853a363f90f6f4cd1fddc50c9a48b45159d558df4
`0.8.0`	Download	Apr 05 2026, 21:33 UTC	`33d258c`	1a6cc492b8003baeac68ab16d21958d9	094436b6389e35bfa80a29ae12e7917d21e816e21aef02a672a819963ea3f17a

Source: Browse Plugin

Metadata: View full manifest

Plugin README

Dispatcharr IPTV Checker Plugin

Check IPTV stream status, analyze stream quality, and manage channels based on results

Top Language Repo Size Last Commit License

Warning: Backup Your Database

Before installing or using this plugin, it is highly recommended that you create a backup of your Dispatcharr database. This plugin makes significant changes to your channel and stream assignments.

Click here for instructions on how to back up your database.

Features

Stream Status Checking: Verify if IPTV streams are alive or dead with smart retry logic
Wildcard Group Matching: Target groups using patterns like US-*, *Sports*, or Movies-??
Automated Scheduler: Schedule stream checks using cron expressions with timezone support
Post-Check Automation: Automatically rename, move, delete, export, and webhook after scheduled checks
Metadata Synchronization: Sync technical stream data (codecs, bitrate, sample rate) back to Dispatcharr
Background Processing: Stream checks run in background threads with cancellation support
Alternative Streams: Option to check backup/alternative streams associated with channels
Technical Analysis: Extract resolution, framerate, and video format information
Configurable FFprobe: Custom path, analysis flags, and analysis duration settings
Direct ORM Integration: Runs inside Dispatcharr with direct database access — no API credentials needed
Channel Management: Automated renaming, moving, and deletion of channels based on results
Group-Based Operations: Work with existing Dispatcharr channel groups
Smart Loading: Asynchronous loading for large channel lists to prevent interface timeouts
Real-Time Progress Tracking: Live ETA calculations with adaptive WebSocket notifications
Smart Retry System: Timeout streams queued and retried after other streams for better success rates
Enhanced Error Categorization: Detailed error types (Timeout, 404, 403, Connection Refused, etc.)
Webhook Notifications: Send HTTP POST notifications after scheduled checks complete
Auto-Delete Dead Channels: Permanently remove dead channels with safety confirmation gate
CSV Exports: Export results with comprehensive statistics and URL masking. Scheduled sessions emit a CSV every time a run ends — including windowed runs that close mid-list — so each window has its own audit record (v1.26.1191257+; the hoist regressed via the subfolder/root sync drift and was re-applied in v1.26.1212238).
Video Bitrate Reporting: Per-stream video_bitrate (kbps) captured via ffprobe per-packet data and stored in Dispatcharr’s stream_stats, so the channel-menu UI can display it. Live MPEG-TS / HLS streams almost never expose container-level bit_rate, so the plugin computes the average from packets[].size / packets[].duration_time for the video stream. Rounded to the nearest whole kbps before write (v1.26.1220052+). Probes that capture fewer than 30 video packets (≈1s of 30fps video) leave video_bitrate unset rather than persist a noisy average — short samples were producing wildly inflated values (observed: 22924 kbps from 2 packets) that polluted the channel-menu display (v1.26.1221035+). The default ffprobe_analysis_duration was bumped from 5 s → 8 s in v1.26.1221101 to give slow-start streams enough room to clear the 30-packet trust gate; verified runs jumped from 97% to 100% bitrate coverage on alive streams with median packet count rising from 200–400 → 662 (default-only change, existing deployments keep their saved value). The default ffprobe_flags was changed to -show_streams,-show_packets,-loglevel error in v1.26.1211342 — passing both -show_frames and -show_packets makes ffprobe emit a combined packets_and_frames array instead of separate packets[], which silently breaks the bitrate calc. If you’ve customized ffprobe_flags, do not include -show_frames.
Window-Aware Retry Pass: When a windowed run closes mid-list, the parallel/sequential retry passes now also bail on _past_window_end() so transient-error retries cannot overshoot the window boundary (v1.26.1212238+; previously observed up to 14 minutes of overrun).
Adaptive Rate-Limit Guard: Detects upstream HTTP 429 responses, classifies them as Skipped (Rate Limited) instead of Dead so destructive actions never act on a throttled stream, and applies an exponentially-doubling cooldown when 429s spike (v1.26.1181025+). The cooldown counter is shared across the whole container — Dispatcharr’s multiple worker processes can no longer reset it independently (v1.26.1181126+).
Single-Scheduler Election: Dispatcharr runs ~9 separate Python processes; a file-based PID lock at /data/iptv_checker_scheduler.pid ensures exactly one of them hosts the cron scheduler. Prior versions could fire each cron N times in parallel (v1.26.1181126+). Module-reload duplicate-thread protection added in v1.26.1191257 (Django/uwsgi could re-import the plugin module within the elected process and spawn additional scheduler threads, defeating the PID lock). Cross-worker UI-restart protection added in v1.26.1220951: any UI button click landed in whichever uwsgi worker the load balancer picked, and update_schedule_action / Plugin.run() previously called _start_background_scheduler directly without checking the PID lock — so non-owner workers spawned rogue scheduler threads (observed: '59 23 * * *' fired twice 27 ms apart on 2026-05-02). Non-owners now write a /data/iptv_checker_scheduler_reload.flag file that the owner’s scheduler loop polls every 30 s; the owner re-reads settings via _fresh_settings and swaps its cron expressions in place.

Requirements

System Dependencies

This plugin requires ffmpeg and ffprobe to be installed in the Dispatcharr container for stream analysis. The scheduler feature requires pytz (usually included).

Default Locations:

ffprobe: /usr/local/bin/ffprobe (plugin default, configurable)
ffmpeg: /usr/local/bin/ffmpeg

Verify Installation:

docker exec dispatcharr which ffprobe
docker exec dispatcharr which ffmpeg

Dispatcharr Setup

Active Dispatcharr installation (v0.20.0+) with configured channels and groups
Channel groups containing IPTV streams to analyze

No API credentials are needed — the plugin runs inside Dispatcharr with direct database access.

Installation

Log in to Dispatcharr’s web UI
Navigate to Plugins
Click Import Plugin and upload the plugin zip file
Enable the plugin after installation

Updating the Plugin

To update the plugin:

Remove Old Plugin
- Navigate to Plugins in Dispatcharr
- Click the trash icon next to the old plugin
- Confirm deletion
Restart Dispatcharr
- Log out of Dispatcharr
- Restart the Docker container:
```
docker restart dispatcharr
```
Install Updated Plugin
- Log back into Dispatcharr
- Navigate to Plugins
- Click Import Plugin and upload the new plugin zip file
- Enable the plugin after installation
Verify Installation
- Check that the plugin appears in the plugin list
- Reconfigure your settings if needed

Settings Reference

Core Settings

Setting	Type	Default	Description
Group(s) to Check	string	(empty = all)	Comma-separated group names. Supports wildcards: `US-`, `Sports*`
Check Alternative Streams	boolean	true	Check all alternative/backup streams for each channel
Connection Timeout	number	10	Seconds to wait for stream connection
Probe Timeout	number	20	Seconds to wait for FFprobe stream analysis
Dead Connection Retries	number	3	Number of retry attempts for failed streams

Channel Management Settings

Setting	Type	Default	Description
Dead Channel Rename Format	string	`{name} [DEAD]`	Format for renaming dead channels
Move Dead Channels to Group	string	`Graveyard`	Group to move dead channels to
Low Framerate Rename Format	string	`{name} [Slow]`	Format for renaming low FPS channels (<30fps)
Move Low Framerate Group	string	`Slow`	Group to move low framerate channels to
Video Format Suffixes	string	`UHD, FHD, HD, SD, Unknown`	Formats to add as suffixes

FFprobe Settings

Setting	Type	Default	Description
FFprobe Path	string	`/usr/local/bin/ffprobe`	Full path to the ffprobe executable
FFprobe Analysis Flags	string	`-show_streams,-show_frames,...`	Comma-separated FFprobe flags
FFprobe Analysis Duration	number	5	Seconds of stream to analyze
Streamlink-Only Hosts	string	`youtube.com, youtu.be, twitch.tv, kick.com`	Comma-separated host suffixes ffprobe cannot validate (served via Streamlink). Streams matching these hosts are marked Skipped instead of Dead, so rename/move/delete actions leave them alone. Blank falls back to defaults.

Parallel Checking

Setting	Type	Default	Description
Enable Parallel Checking	boolean	true	Check multiple streams simultaneously
Number of Parallel Workers	number	2	How many streams to check at once. Keep below your provider’s concurrent-connection limit.
Per-Stream Cooldown (seconds)	number	2	Each worker waits this long after finishing a check before picking up the next. Prevents provider rate-limiting / slot-reuse errors. Retry passes wait 3× this value.

Webhook

Setting	Type	Default	Description
Webhook URL	string	(empty)	HTTP POST URL for notifications after scheduled checks

Scheduler Settings

Setting	Type	Default	Description
Scheduled Check Times	string	(empty)	Cron expression (e.g., `0 4 * * ` for daily at 4 AM). When Use Windowed Schedule* is on, this becomes the window start trigger.
Scheduler Timezone	select	`America/Chicago`	Timezone for the scheduler
Use Windowed Schedule	boolean	false	When on, each cron-fire opens a run window. The check runs until the configured end-of-window, then halts cleanly between streams. The next time the window opens, the run resumes from where it left off — already-checked streams are skipped.
Window End Mode	select	`duration`	`duration` = run for N hours; `time` = run until a specific HH:MM (wraps past midnight if earlier than the start).
Window Duration (hours)	number	4	Used when Window End Mode = duration. Decimals allowed (e.g. 3.5).
Window End Time	string	`04:00`	Used when Window End Mode = time. 24-hour format in the Scheduler Timezone above.
Export CSV for Scheduled Checks	boolean	false	Auto-export results to CSV after scheduled checks
Rename Dead Channels	boolean	false	Auto-rename dead channels after scheduled checks
Rename Low Framerate Channels	boolean	false	Auto-rename slow channels after scheduled checks
Add Video Format Suffix	boolean	false	Auto-add format suffix after scheduled checks
Move Dead Channels	boolean	false	Auto-move dead channels after scheduled checks
Move Low Framerate Channels	boolean	false	Auto-move slow channels after scheduled checks
Delete Dead Channels	boolean	false	Auto-delete dead channels after scheduled checks
Send Webhook Notification	boolean	false	Send webhook after scheduled checks

Destructive Settings

Setting	Type	Default	Description
Auto-Delete Confirmation	string	(empty)	Type `DELETE` to enable auto-delete of dead channels

Usage Guide

Step-by-Step Workflow

Configure Preferences
- Set your Group(s) to Check (supports wildcards like US-*)
- Configure checking preferences (Alternative Streams, Timeouts, Retries)
- Optionally enable Parallel Checking for faster processing
- Click Save Settings
Validate Settings (Recommended)
- Click Run on Validate Settings
- Verifies group names, FFprobe path, and configuration
Configure Schedule (Optional)
- Set Scheduled Check Times using cron format
- Select your Scheduler Timezone
- Enable post-check automation options as desired
- Click Run on Update Schedule to activate
Load Channel Groups
- Click Run on Load Group(s)
- Review available groups and channel counts
- Large lists (>100 channels) load in the background
Check Streams
- Click Run on Start Stream Check
- Processing runs in the background
- Returns immediately with estimated completion time
- Metadata is automatically synced to the database during checks
Monitor Progress
- Click View Check Progress for real-time status with ETA
- Use Cancel Stream Check to stop a running check
- Progress updates continue even if browser times out
View Results
- Click View Last Results for summary when complete
- Shows alive/dead counts and format distribution
- Use View Results Table for detailed tabular format
Manage Channels
- Use channel management actions based on results
- All destructive operations include confirmation dialogs
- GUI automatically refreshes after changes
Export Data
- Click Export Results to CSV to save analysis data
- CSV includes comprehensive header comments with settings and stats

Action Reference

Setup & Validation

Validate Settings: Verify configuration, group names, and FFprobe path
Update Schedule: Apply schedule settings and restart the scheduler
Check Scheduler Status: View current scheduler state and next run time

Core Stream Checking

Load Group(s): Load channels from specified groups (async for large lists)
Start Stream Check: Begin checking all loaded streams in background thread
View Check Progress: View current progress and ETA of the running check
Cancel Stream Check: Stop the currently running stream check (confirmation dialog; queued and in-flight streams abort, already-probed results are kept)
View Last Results: View summary of the last completed stream check

Channel Management

Rename Dead Channels: Apply rename format to dead streams
Move Dead Channels to Group: Relocate dead channels
Delete Dead Channels: Permanently remove dead channels (requires confirmation)
Rename Low Framerate Channels: Apply rename format to slow streams (<30fps)
Move Low Framerate Channels: Relocate slow channels
Add Video Format Suffix: Apply format tags ([UHD], [FHD], [HD], [SD])

Data & Maintenance

View Results Table: Detailed tabular format for copy/paste
Export Results to CSV: Save analysis data with comprehensive statistics
Clear CSV Exports: Delete all CSV files in /data/exports/
Cleanup Orphaned Tasks: Clean up stale background tasks

Advanced Features

Wildcard Group Matching

Use shell-style wildcards in the Group(s) to Check field:

US-* — matches US-Movies, US-Sports, US-News, etc.
*Sports* — matches any group containing “Sports”
Movies-?? — matches Movies-US, Movies-UK, etc.
Multiple patterns: US-*, UK-*, *Sports* (comma-separated)

Automated Scheduling

Cron Support: Configure checks using standard cron syntax (e.g., 0 4 * * *)
Timezone Aware: Schedules run according to your local timezone
Post-Check Automation: Chain any combination of rename, move, delete, export, and webhook actions
Conflict Prevention: Scheduler queues jobs if a manual check is already running

Windowed Schedules with Resume

For overnight or off-peak runs, enable Use Windowed Schedule. The cron expression becomes the window start; the check halts cleanly when the window closes and resumes from the same place the next time the window opens.

Example — Sun–Thu, 00:00 → 04:00 CST:

Setting	Value
Scheduled Check Times	`0 0 * * 0-4`
Scheduler Timezone	`America/Chicago`
Use Windowed Schedule	✅ on
Window End Mode	`duration`
Window Duration (hours)	`4`

What happens:

The window opens at midnight Sun–Thu and runs for 4 hours.
Per-stream progress is persisted to /data/iptv_checker_pending_resume.json.
If the window closes before the channel list is finished, post-check actions (rename / move / delete / webhook) are deferred to the window that completes the list.
If the container restarts mid-window, the original window end is preserved and the check resumes immediately rather than waiting for the next cron fire.
Click Reset Window Progress to wipe pending state and start fresh on the next window.

Metadata Synchronization

Database Sync: Automatically updates Dispatcharr with technical stream details from FFprobe analysis
Synced Fields: Video/Audio Codecs, Resolution, Bitrates, Sample Rates, Audio Channels, Stream Types

Smart Retry System

Timeout streams queued and retried after processing other streams (not immediately)
Provides server recovery time between retry attempts
Retry queue processes every 4 streams to balance throughput and recovery
Multiple retry attempts per stream based on configured retry count
Retry-aware ETA: View Check Progress keeps the percentage and ETA honest through retry passes — it no longer snaps to 100% at the end of the first pass.

Provider Concurrency Limits

Most IPTV providers cap concurrent connections per account (often 1–4). Two settings let you stay under the cap while still running checks in parallel:

Number of Parallel Workers — keep this below your account’s cap. For a 4-stream account, 2 workers leaves headroom for viewing while a check runs.
Per-Stream Cooldown — 2 s by default. Each worker waits this long after finishing before picking up the next stream, so the upstream slot has time to release. Retry passes wait 3× this value.

If you see a lot of “Server Error” or “Stream Unreachable” results that turn alive on retry, raise the cooldown or drop the worker count.

Auto-Delete Dead Channels

Permanently deletes channels with dead streams from the database
Safety gates: Requires typing DELETE in the confirmation field AND confirming via dialog
Can be automated via scheduler with the same confirmation gate

Webhook Notifications

Sends HTTP POST with JSON payload after scheduled checks complete
Configure any URL — works with Discord, Slack, custom endpoints
No additional dependencies (uses Python’s built-in urllib)

Troubleshooting

First Step: Restart Container

For any plugin issues, try refreshing your browser (F5) and then restarting the Dispatcharr container:

docker restart dispatcharr

Common Issues

“Plugin not found” Errors:

Refresh browser page (F5)
Restart Dispatcharr container

Scheduler Not Running:

The scheduler starts automatically on container boot — no UI action needed
Verify pytz is installed in the container
Check cron syntax (5 fields required: minute hour day month weekday)
Use Check Scheduler Status to verify state
Check logs: docker logs dispatcharr | grep -i scheduler
Confirm scheduler started on boot: docker logs dispatcharr | grep "Background scheduler thread started"

Stream Check Failures:

Increase connection timeout and/or probe timeout for slow streams
Adjust retry count for unstable connections
Try enabling parallel mode for better timeout handling
Restart container: docker restart dispatcharr

Progress Stuck or Not Updating:

Stream checking runs in background and continues even if browser times out
Use View Check Progress to check current status
Use Cancel Stream Check if needed
Check container logs for actual processing status

File Locations

Results: /data/iptv_checker_results.json
Loaded Channels: /data/iptv_checker_loaded_channels.json
Progress State: /data/iptv_checker_progress.json
Settings: /data/iptv_checker_settings.json
CSV Exports: /data/exports/iptv_checker_results_YYYYMMDD_HHMMSS.csv

Versioning

This plugin uses calver 1.26.{DDD}{HHMM} (UTC day-of-year + UTC hour-minute), matching the Lineuparr / Channel-Mapparr / EPG-Janitor cohort. Releases prior to 1.26.1081815 used semver (0.X.Y). See the release notes for full changelogs.

Contributing

When reporting issues:

Include Dispatcharr version information
Provide relevant container logs (docker logs dispatcharr | grep "IPTV Checker")
Test with small channel groups first
Document specific error messages and error types
Note current progress from View Last Results

Pull requests welcome. To submit changes:

To this repo (PiratesIRC/Dispatcharr-IPTV-Checker-Plugin)

Bump version: python3 bump_version.py (auto-stamps with current UTC day-of-year + HHMM).
Commit, push, tag, and release:

git tag <version> && git push origin <version>
gh release create <version> --title "v<version>" --notes "..."
gh release upload <version> iptv_checker.zip

To the upstream marketplace (Dispatcharr/Plugins)

Updates also need to be PR’d to Dispatcharr/Plugins so the plugin updates in users’ Dispatcharr UIs. The repo’s GitHub Actions validator enforces strict rules — failing any blocks the merge:

Check	Requirement
PR title	Must match `[iptv-checker]: <description>`. The `validate-title` job fails on any other format. Most common trip-up.
Version bump	`plugin.json` version must be greater than the version on upstream `main` for any code/asset change. Metadata-only edits are exempt.
Required `plugin.json` fields	`name`, `version`, `description`, `author`, `license` (SPDX).
Authorship	PR author’s GitHub username must appear in `author` or `maintainers`, or the `close-unauthorized` job auto-closes the PR.
Folder name	`plugins/iptv-checker/` (lowercase-kebab) — note this differs from the `iptv_checker/` snake_case used inside this repo’s zip.

Workflow:

# In your fork of Dispatcharr/Plugins:
git fetch upstream && git checkout main && git merge upstream/main --ff-only && git push origin main
git checkout -b iptv-checker-v<version>
cp <this-repo>/plugin.{py,json} plugins/iptv-checker/
git commit -am "[iptv-checker]: ..."
git push -u origin iptv-checker-v<version>
gh pr create --repo Dispatcharr/Plugins --base main \
    --title "[iptv-checker]: Bump to v<version> — <summary>" \
    --body "..."

On merge, upstream automation builds the zip + checksums and updates manifest.json on the releases branch — do not touch that branch manually.