Plugins

Back to All Plugins

IPTV Checker

Version: 1.26.1741204 Author: PiratesIRC Last Updated: Jun 23 2026, 22:27 UTC

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

License: MIT Repository

Dispatcharr min

Downloads

Latest Release

Checksums:

MD5:    e16b4dc3bc9953f27fca31ce4f4569af
SHA256: f55095d46511ecf6f5a759b47d9738c76167690acc52240df14250f23ed53c4c

All Versions

Version Download Built Commit MD5 SHA256
1.26.1741204 Download Jun 23 2026, 22:27 UTC 4de0ece e16b4dc3bc9953f27fca31ce4f4569af f55095d46511ecf6f5a759b47d9738c76167690acc52240df14250f23ed53c4c
1.26.1721834 Download Jun 21 2026, 19:40 UTC 7ae9fe2 ed2f2081ffcde94a28229f838beb91db 280a80ef503627be5ab94c675cb9a757844dea34f4d6daa249d171fc14106dbd
1.26.1582047 Download Jun 08 2026, 00:13 UTC 78654d4 61646995883517cc4fe9caeec47dffb5 e25a02db89ace1b05366b2c361f20c56876deabddba59ee3dd8b3817240dced1
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

Dispatcharr plugin Ask DeepWiki Workflow Guide Discord

GitHub Release Downloads

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

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:

Verify Installation:

docker exec dispatcharr which ffprobe
docker exec dispatcharr which ffmpeg

Dispatcharr Setup

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

Installation

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

Updating the Plugin

To update the plugin:

  1. Remove Old Plugin
    • Navigate to Plugins in Dispatcharr
    • Click the trash icon next to the old plugin
    • Confirm deletion
  2. Restart Dispatcharr
    • Log out of Dispatcharr
    • Restart the Docker container: 
      docker restart dispatcharr
  3. 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
  4. 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*
Group(s) to EXCLUDE string (empty) Comma-separated groups to skip, applied after the include filter. Supports wildcards. With a blank “Group(s) to Check” this means “all groups except these”. If a group matches both fields, exclude wins. (v1.26.1721733+)
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 (excludes black/blank — see below)
Move Dead Channels to Group string Graveyard Group to move dead channels to (excludes black/blank)
Blank-Screen Channel Rename Format string {name} [Blank] Format for renaming channels detected as a blank screen
Move Blank-Screen Channels to Group string Black Screens Group to move blank-screen channels to
Low Framerate Rename Format string {name} [Slow] Format for renaming low FPS channels (<24fps — 25fps PAL and 24fps film are not flagged)
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

Blank-screen is a separate category (v1.26.1721554+). When blank-screen detection is on, blank channels are renamed/moved by the blank actions ([Blank] / Black Screens) and are excluded from the regular Dead rename/move so they aren’t double-tagged. They remain status=Dead, so Delete Dead Channels still deletes them. Existing users who relied on blank streams getting [DEAD]/Graveyard should enable the new blank rename/move toggles (or set the Blank-Screen Rename Format to {name} [DEAD]).

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_packets,-loglevel error Comma-separated FFprobe flags. Do not add -show_frames — it makes ffprobe emit a combined packets_and_frames array that breaks the bitrate calc.
FFprobe Analysis Duration number 8 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.

Blank-Screen Detection

Optional second pass that decodes a few seconds of each alive stream with ffmpeg’s blackdetect filter and marks it Dead (Black Screen) if it is a pure black picture. Off by default. Requires ffmpeg in the container (see Requirements). Adds ~5–10 s per alive stream when enabled; dead/skipped streams are unaffected.

Setting Type Default Description
Detect Blank-Screen Streams boolean false Master toggle. When on, every alive stream is decoded with ffmpeg blackdetect; pure-black streams become Dead with error_type = Black Screen. Fail-open: if ffmpeg is missing or errors, the stream stays Alive. Very-dark-but-not-black “no signal” slates are not detected.
Blank-Screen Sample (seconds) number 6 How many seconds of video to decode when testing for black. Longer = more reliable but slower.
Continuous Blank Required (seconds) number 3 Minimum continuous run of black video (within the sample) required to flag. Keep a few seconds below the sample to allow for connection/keyframe latency.
Blank-Screen ffmpeg Timeout (seconds) number 20 Hard wall-clock cap on the ffmpeg decode (connection + sampling). If exceeded, the stream is left Alive.
FFmpeg Path string /usr/local/bin/ffmpeg Full path to the ffmpeg executable (under Advanced).

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.
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 Dispatcharr’s timezone (see note below).

Timezone (v1.26.1721651+): the scheduler no longer has its own timezone setting — it uses Dispatcharr → Settings → General → Time Zone. Set your timezone there and all scheduled/windowed run times follow it. Falls back to UTC only if Dispatcharr’s timezone can’t be read. (If you previously chose a plugin timezone that differed from Dispatcharr’s, your scheduled times now follow Dispatcharr’s — adjust the Dispatcharr setting if needed.) | Export CSV for Scheduled Checks | boolean | false | Auto-export results to CSV after scheduled checks | | Restore Recovered Channels | boolean | false | Auto-restore channels that are Alive again but were previously marked — strips plugin tags and moves them back to their original group. Runs first, before re-marking. | | 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 | | Rename Blank-Screen Channels | boolean | false | Auto-rename blank-screen 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 | | Move Blank-Screen Channels | boolean | false | Auto-move blank-screen 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 (payload gains a restored count) |

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

  1. Configure Preferences
    • Set your Group(s) to Check (supports wildcards like US-*)
    • Optionally set Group(s) to EXCLUDE to skip groups (applied after the include filter)
    • Configure checking preferences (Alternative Streams, Timeouts, Retries)
    • Optionally enable Parallel Checking for faster processing
    • Click Save Settings
  2. Validate Settings (Recommended)
    • Click Run on Validate Settings
    • Verifies group names, FFprobe path, and configuration
  3. Configure Schedule (Optional)
    • Set Scheduled Check Times using cron format
    • Set your timezone in Dispatcharr → Settings → General → Time Zone (the scheduler uses it automatically)
    • Enable post-check automation options as desired
    • Click Run on Update Schedule to activate
  4. Load Channel Groups
    • Click Run on Load Group(s)
    • Review available groups and channel counts
    • Large lists (>100 channels) load in the background
  5. 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
  6. 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
  7. 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
  8. Manage Channels
    • Use channel management actions based on results
    • All destructive operations include confirmation dialogs
    • GUI automatically refreshes after changes
  9. Export Data
    • Click Export Results to CSV to save analysis data
    • CSV includes comprehensive header comments with settings and stats

Action Reference

Setup & Validation

Core Stream Checking

Channel Management

Data & Maintenance

Advanced Features

Wildcard Group Matching

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

Excluding Groups (v1.26.1721733+)

Use the Group(s) to EXCLUDE field to skip groups that would otherwise be checked. Same comma-separated wildcard syntax. Exclude is applied after the include filter, so it composes:

Automated Scheduling

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 (in Dispatcharr’s timezone):

Setting Value
Scheduled Check Times 0 0 * * 0-4
Dispatcharr Time Zone (Settings → General) America/Chicago
Use Windowed Schedule ✅ on
Window End Mode duration
Window Duration (hours) 4

What happens:

Metadata Synchronization

Smart Retry System

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:

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

Blank-Screen Detection

Restore Recovered Channels (self-healing)

Webhook Notifications

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:

Scheduler Not Running:

Stream Check Failures:

Progress Stuck or Not Updating:

File Locations

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:

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

Pull requests welcome. To submit changes:

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

  1. Bump the version (calver 1.26.{DDD}{HHMM}, UTC) with python bump_version.py — it updates iptv_checker/plugin.json, iptv_checker/plugin.py, and the “Current Version” line in CLAUDE.md in one shot, and verifies they agree.
  2. Validate: python -m pytest tests -q && python -m ruff check .
  3. Commit, tag, and push:
git add -A && git commit -m "v<version> — <summary>"
git tag <version> && git push origin main --tags

CI (.github/workflows/ci.yml) re-runs the checks, builds iptv_checker-v<version>.zip (excluding __pycache__), and attaches it to the GitHub release automatically when the tag lands. See DEVELOPMENT.md for the full workflow.

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.