Plugins

Back to All Plugins

Stream-Mapparr

Version: 1.26.2911937 Author: PiratesIRC Last Updated: Oct 18 2026, 19:54 UTC

Automatically add matching streams to channels based on name similarity and quality precedence. Supports unlimited stream matching, channel visibility management, and CSV export cleanup.

License: MIT Repository

Dispatcharr min

Downloads

Latest Release

Checksums:

MD5:    b424c81027fd9bb5052c788b8c8c14df
SHA256: 7cbe5837dbf7b300b86bae06871d8cb4cc2fd31aa9de2708351d4800b4022cc6

All Versions

Version Download Built Commit MD5 SHA256
1.26.2911937 Download Oct 18 2026, 19:54 UTC 79767cd b424c81027fd9bb5052c788b8c8c14df 7cbe5837dbf7b300b86bae06871d8cb4cc2fd31aa9de2708351d4800b4022cc6
1.26.2911353 Download Oct 18 2026, 14:29 UTC 9343daf 521bde132f09bfe6af5dd164fdb88278 33370bba6b6a8c0ef2de1e251d2d3023d69ac942755eee894a766bd9c821f3e2
1.26.2901847 Download Oct 17 2026, 18:59 UTC 3dd79d4 90fddf324b89eb3dfa95e75b1d493751 fe8c68a3581bbdd78ad6cff8f0fe431a642586b1a21d0e32832447f64b72514a
1.26.2901408 Download Oct 17 2026, 14:32 UTC 7479ce2 5f9974c0a7c28477441fc4d9065fd0ee 79d689a7562f9abc93ba9791c75e1452d59c57ee3f92b25fd79f0100fb7cff95
1.26.2841900 Download Oct 11 2026, 19:06 UTC 0bccc7e 4fe6ec6c7461b599338a5bf4f46d3e17 8ad89a5a0b56ece1625966256a66ee7f3e9b9fd2f34233e39fbe7973cba8a450
1.26.2841112 Download Oct 11 2026, 11:19 UTC 6f08b41 ed72bc3989c89dab96253c8715a210a5 fb5e9c578c7ace1f4b2371413288b06f86484b8bc2e33250cac85570d3959448
1.26.2831803 Download Oct 10 2026, 18:09 UTC 3c5624e d6ca7f148ea90ec881221b4a26ea29db 1b2ec53ddd91cf96f2530669144e1910401bcc0b548f2600a761324ae7f28ee2
1.26.2831654 Download Oct 10 2026, 17:01 UTC 4c32a52 bfb74df315f2d88d06616f2290415b70 67498919c93ec2fe676ebb5d2496d1ec83438190a496621ad1fe76c9958ec2de
1.26.2821334 Download Oct 09 2026, 13:42 UTC e32340a 8b48e8b71db4e80ed093642ae45d8bca c53b82949d4190ae5812138fcd9c6463ab61cca30f1ee848169856111879af21
1.26.2681209 Download Sep 25 2026, 12:17 UTC d75dbde 9d2ab683f719c1794cdbaea5104eb3e2 9e4e884e82e7ea5f1f8de37085825834c46087e7ed898a124922b70955aede45

Source: Browse Plugin

Metadata: View full manifest

Plugin README

[!TIP] New to Dispatcharr plugins? Start with the Dispatcharr Plugin Workflow guide. It explains what each plugin and tool does, where they overlap, and what order to use them in.

A Dispatcharr plugin that automatically matches and assigns streams to channels using fuzzy matching, quality prioritization, and OTA callsign recognition.

The Streams Matched and Active Installs badges add up figures sent by every install that keeps “Share anonymous usage counts” ticked; see Anonymous usage counts.

Backup Your Database

Before installing or using this plugin, create a backup of your Dispatcharr database. This plugin modifies channel and stream assignments.

Backup instructions

Requirements

Installation

From the Dispatcharr Plugin Hub (recommended):

  1. In Dispatcharr, go to Settings -> Plugin Hub
  2. Find Stream-Mapparr in the catalog and click Install
  3. Enable the plugin

Manual install:

  1. Download the latest zip from Releases
  2. In Dispatcharr, go to Plugins -> Import Plugin and upload the zip
  3. Enable the plugin

Further reading

Guide What it covers
Regex pre-processing Writing find and replace rules for provider junk in stream names
Notifications and emailed reports Sending HTML and CSV reports through Newsflasharr
Troubleshooting Stuck operations, no matches, slates, useful commands

Features

Matching

East and West feeds

Quality and streams

Automation

How a run reports back

Small jobs run synchronously and the Dispatcharr interface shows the real result, including channel and stream counts and the CSV filename.

Larger jobs run in a background thread. The interface shows a “started in background” notification, and completion arrives by:

While a long operation runs, the plugin pushes a started notification, periodic percentage and estimated-time notifications, and a completion notification.

Buttons re-enable immediately. Do not click again while an operation is running: the operation lock prevents concurrent runs and auto-expires after 10 minutes.

Settings

Setting Type Default Description
Overwrite Existing Streams boolean True Replace existing streams rather than appending. A run matching 0 streams never clears a channel
Match Sensitivity select Normal (80) Relaxed (70), Normal (80), Strict (90), Exact (95)
Channel Profile select - Profile to process channels from
Channel Groups string (all) Groups to process, comma-separated. Empty means all groups
Channel Groups Mode select Only the groups listed Whether the list names the groups to process or the groups to skip. Choosing to skip means a group you create later is processed automatically. Empty list means all groups either way
Stream Groups string (all) Stream groups to draw candidate streams from, comma-separated
Stream Groups Mode select Only the groups listed The same choice for stream groups, resolved separately from the channel-group list
M3U Sources string (all) M3U sources to use, comma-separated. Order sets priority. Only listed sources are used unless the list contains *, which stands for every other source: Free Provider, * puts Free Provider first and keeps all the rest
Custom Aliases string (none) JSON object of extra "channel": ["alias", ...] mappings. Channel names and aliases are both matched case-insensitively, and whitespace around a channel name is ignored
Stream Name Regex Rules string (none) JSON list of [find, replace] pairs applied to stream names before matching. See Regex pre-processing
Prioritize Quality boolean False Sort by quality first, then by M3U source priority
Custom Ignore Tags string (none) Tags to strip before matching, for example [Dead], (Backup)
Wait for IPTV Checker Completion boolean False Hold a scheduled run until IPTV Checker has finished, so matching sees fresh stats
IPTV Checker Max Wait (hours) number 6 How long to wait before running anyway
Run After IPTV Checker Scan boolean False When IPTV Checker finishes a scheduled scan, run the scheduled steps (Fill Mirror Backups, Sort Alternate Streams and Match and Assign, whichever are ticked). IPTV Checker needs its own Trigger Stream-Mapparr setting on
Enable CSV Export boolean True Write a CSV on a scheduled Match and Assign run. A dry run always writes one
Delete CSV Exports Older Than (Days) number 0 Remove this plugin’s older reports after each new one is written. 0, the default, keeps everything. Only files this plugin wrote are ever considered, because that directory is shared with other plugins. The newest report and the one just written always survive
Tag Handling select Strip All Strip All, Keep Regional, or Keep All
Channel Database select US Which channel database to use. You choose this, never your provider’s country prefix, so one database per country serves every provider and none needs duplicating
Visible Channel Limit number 1 Channels per group to enable and assign streams to
Rate Limiting select None None, Low, Medium or High
Filter Dead Streams boolean False Skip 0x0 resolution streams. Requires IPTV Checker
Restrict Matching To Same Country boolean False Only match streams whose detected country matches the channel’s. GB: is accepted as well as UK:, and DR: as well as DO:. An unrecognised prefix is treated as unknown and the stream is kept, never dropped
Stream Prefix Countries string (empty) Tell the country filter what a provider prefix means, as comma-separated PREFIX=COUNTRY entries such as NOW=UK, GO=US. Use it when a prefix names a platform rather than a country, which the plugin cannot know: NOW is Sky’s service in the United Kingdom and also in Italy, so no default is right for everyone. Consulted last, so it fills a gap and never overrules a country the provider stated. Matches only at the start of a name, never a word inside a title
Keep Same-Named Streams From One Source boolean False Enable if your provider publishes several genuinely different feeds under one identical name. By default those are treated as duplicates
Enable EPG-Based Placeholder Matching boolean False Match a placeholder-named channel or stream by the programme currently airing on it, taken from EPG data, instead of by its literal name. For providers that name event slots generically, such as PPV EVENT 04, and put the real event only in the guide. Channel and stream names are never modified
Placeholder Name Patterns string (see plugin) One regex per line. A name is only ever treated as a placeholder if it matches one of these, so nothing else changes behaviour. Press Scan for Placeholder Patterns to find the families your patterns miss
EPG Title Cleanup Rules string (see plugin) JSON list of [find, replace] pairs applied to the raw programme title before it is used for matching, for example stripping a Next Event: X at 6:00AM wrapper down to X
Skip Titles string (see plugin) Comma-separated. If the cleaned programme title matches one of these, the channel keeps its literal name for that pass, because an idle slot carries no useful event
Channel Schedule Suffix Cleanup Rules string (see plugin) JSON list of [find, replace] pairs that strip a schedule annotation such as \| Monday @ 5 from the channel name before it is compared against a programme title
EPG Event Watch Source Streams string (see plugin) Comma-separated names of permanently-named source streams to watch for an event, rather than placeholder-named ones
Send notifications to Newsflasharr boolean False Emit notifications through the Newsflasharr plugin
Email A Report After select Scheduled runs only Which runs email a report: never, scheduled only, or every run
Email Report Format select Both Which file is emailed. One report sends ONE email carrying one attachment, because a notification can carry only one. Both writes both files and emails the HTML page; the email names the file it did not attach
Scheduled Run Times string (none) Times in HHMM, comma-separated, for example 0400,1600
Auto-match after M3U refresh boolean False Run Match and Assign after each successful M3U refresh. A refresh that ends in an error does not trigger it. Requires a Channel Profile. Dispatcharr v0.27+
Dry Run Mode boolean False Preview without making database changes
Enable Throughput-Based Sorting boolean True Add a measured-throughput tier to alternate-stream sorting, falling back to resolution when no probe data exists
Probe Duration (seconds) number 8 Length of each throughput probe
Probe Cache TTL (minutes) number 30 How long a measurement stays fresh. Stale entries sort as unknown
Probe Rate (probes / minute) number 6 Global cap on probes per minute. Also serialized per M3U account
Bitrate Safety Margin string 1.10 Multiplier on nominal bitrate. Below nominal times this is insufficient, below nominal times 1.5 is marginal
Demote Placeholder Streams boolean True Rank a stream last when it claims 720p or higher but carries less video than the floor below. Streams are moved down the order, never removed, and one with no measured bitrate is never affected
Placeholder Bitrate Floor (kbps) number 300 The floor for the setting above. Standard definition is never checked. Where two bitrate figures disagree the higher is used, so a disagreement keeps the stream
Audio Channels Priority string ”” Audio layouts, most preferred first, for example 7.1, 5.1, stereo. Ranked before codec. Blank disables it
Audio Codec Priority string ”” Audio codecs, most preferred first, for example eac3, ac3, aac. Ranked after layout. Blank disables it
Share anonymous usage counts boolean True Sends this plugin’s Streams Matched total and a random id to the plugin author’s counter. See Anonymous usage counts.

Actions

Action Description
Validate Settings Check configuration, profiles, groups and databases
Test Regex Rules Preview what your regex rules would change, with before and after samples and invisible characters made visible. Writes the full readout to /config/stream-mapparr/test-regex-rules.txt, since a notification shows only about 280 characters
Check Stream Country Labels Compare each stream’s group country against its EPG identifier suffix and report where they disagree. Reads two database columns, opens no provider connection and changes nothing. A disagreement is not automatically a fault: a channel carried in one country and made in another is ordinary
Scan for Placeholder Patterns Group every stream name into a numbered family, by replacing its numbers with a slot, and report the families that no Placeholder Name Pattern covers, each with a regex to paste. The largest families come first. Each one says how many of its streams carry an EPG identifier, and a family where most of them do is marked, because that is more likely to be an ordinary numbered channel lineup, where a pattern replaces a name that is already matching. A digit followed by K is left alone, since 4K is a resolution tag rather than a slot number. Writes the full readout to /config/stream-mapparr/placeholder-name-scan.txt. Reads one database column, opens no provider connection and changes nothing
Load/Process Channels Load channel and stream data from the database
Preview Changes Dry run with a CSV export
Match & Assign Streams Fuzzy match and assign streams to channels
Match US OTA Only Match US broadcast channels by callsign
Sort Alternate Streams Re-sort existing streams by quality, and by throughput tier where probe data exists
Probe Stream Throughput Measure sustained throughput for assigned streams. Run this before Sort Alternate Streams
Fill Mirror Backups For M3U accounts placed in one Dispatcharr server group that carry the same streams from different provider hosts, add to each channel the matching stream, found by provider stream id, from every other active account whose host the channel has no stream from yet. Two accounts on the same host count as one, and inactive accounts are skipped. New streams go after the existing provider streams and before any custom stream. Adds only and never removes. In live mode it first saves each changed channel’s previous stream order to /data/stream_mapparr_snapshots/, and changes nothing if that save fails. Writes every addition to /config/stream-mapparr/fill-mirror-backups.txt
Manage Channel Visibility Enable or disable channels based on stream count
View Check Progress Show the running operation’s percentage and estimated time
View Last Results Show a summary of the last completed operation
Clear CSV Exports Delete plugin CSV files, skipping any written in the last 40 minutes
Cleanup Orphaned Tasks Remove scheduled task entries left by an older version
Report a Bug or Request a Feature Write a ready-to-paste report with your settings, secrets masked

Scheduling

  1. Set Scheduled Run Times in 24-hour format, for example 0400,1600. Times use Dispatcharr’s global timezone; there is no plugin timezone setting
  2. Choose which steps run: Schedule: Match & Assign Streams, on by default, Schedule: Sort Streams, off by default, and Schedule: Fill Mirror Backups, off by default. They are independent, so a schedule can run any of them alone or together. Fill Mirror Backups runs before Sort Streams, so the mirrors it adds are sorted in the same run
  3. Enable CSV Export if you want one
  4. Click Update Schedule

The scheduler runs in a background thread and re-arms when the container restarts. Across multiple worker processes, a shared on-disk claim makes sure the job runs once per slot rather than once per worker.

Event-driven alternative (Dispatcharr v0.27+): Auto-match after M3U refresh runs Match and Assign the moment a refresh finishes successfully, instead of or as well as fixed times. Because Dispatcharr fires that event once per M3U account, runs are coalesced under a lock and a follow-up pass catches any account that finishes mid-match. A multi-account refresh therefore produces one effective match rather than one per account.

After an IPTV Checker scan: Run After IPTV Checker Scan runs the same steps the fixed times run (Fill Mirror Backups, Sort Alternate Streams and Match and Assign, whichever are ticked) when the IPTV Checker plugin finishes a scheduled scan that reached the end of its channel list. IPTV Checker calls this plugin directly, so its own Trigger Stream-Mapparr After Scheduled Check setting must be on as well. A run already in progress is left alone and the next scan tries again. The CSV header for such a run reads Scheduled (after IPTV Checker scan).

CSV Reports

Preview and scheduled exports are saved to /data/exports/ and include:

These are not the files that get emailed. See Notifications for that distinction, which matters because the exports contain your M3U source names.

Versioning

This plugin uses calver, 1.MAJOR.DDDHHMM, being the UTC day of year plus the UTC time. Run python scripts/bump_version.py to bump plugin.json and plugin.py together.

Anonymous usage counts

The Streams Matched and Active Installs badges count every install that leaves the “Share anonymous usage counts” setting (on by default) ticked and runs at least one action or scheduled run. Streams Matched counts the stream-to-channel assignments that Match & Assign Streams and Match US OTA Only write. With Overwrite Existing Streams on, which is the default, a daily schedule that re-matches the same streams counts them again; with it off, a stream already on a channel is not written or counted again. Sort Alternate Streams is not counted.

When an action or a scheduled run finishes, the plugin sends this plugin’s Streams Matched total and a random id for this plugin on this install to the plugin author’s counter at plugin-stats.dpas.workers.dev. It sends at most once an hour, or ten minutes after the last successful send when a run has just assigned streams. A run that finishes inside that gap is not sent later: the total goes out with the first later run that is an hour past the last successful send, or with a later run that assigns streams once ten minutes have passed.

The server stores that id with the total and the date of the last report, and keeps them until this install unticks the setting and the delete succeeds, or until the plugin author removes them by hand. An install that stops reporting still counts toward Streams Matched. The connection shows the server your public IP address; the server uses it only to limit abuse and does not store it in its database, though when an install first registers it keeps a salted one-way hash of it (of its /64 block for IPv6) for up to three days. Cloudflare, which hosts the server, keeps its own request logs. No names, channels, streams, URLs, providers or settings are sent. The figures are self-reported by installs and capped by the server, not verified.

What counts as an active install: an install that sent at least one report in the last 30 UTC days. A badge changes after the server’s hourly recount, which runs at the start of each UTC hour, and Shields may cache the badge for up to an hour more, so a new report can take up to about two hours to show.

The setting is the last one in the settings form, in its own section. Unticking it takes effect when the next action or scheduled run finishes; the plugin then asks the server to delete this install’s figures. Once the server confirms the delete, the plugin forgets its id, and ticking the setting again later starts a new one; if the delete could not reach the server, the plugin keeps the id and retries. The plugin keeps that id and the timing of its reports in /data/plugin_stats/stream-mapparr/ (install_id, sent, backoff, disabled, delete_backoff, lock). To start a new id, untick the setting and let a run finish so the delete succeeds; deleting that folder while the setting is ticked leaves the old figures on the server, and the new id then sends the full total again, so the badge counts those matches twice.

Changelog

See CHANGELOG.md for full version history.

Disclaimer

Stream-Mapparr provides no television content of any kind. It supplies no channels, no playlists, no streams, no electronic programme guide data and no provider accounts, and it contains no list of where to obtain any of those. It matches and orders stream entries that already exist in your Dispatcharr installation, using bundled reference data: curated per-country channel name lists, and a table of United States broadcast station callsigns published by the Federal Communications Commission.

Almost everything the plugin does reads stream names, never the streams themselves. There is one exception, and it is opt-in. Probe Stream Throughput connects to stream URLs already configured in your Dispatcharr installation and reads a few seconds of data from each, in order to measure how fast that source delivers. It measures only the volume and timing of the bytes. It does not decode, record, store, restream or redistribute anything, and the data it reads is discarded. Nothing is fetched unless you run that action or enable throughput sorting.

Emailed reports, if you enable them, are handed to the Newsflasharr plugin, which sends them to destinations you configured.

You are responsible for what you connect Dispatcharr to. Whether a particular provider, subscription, playlist or stream is lawful for you to use depends on your agreement with that provider and on the law where you live. Use only sources you are authorised to use. Nothing in this project is intended to enable, encourage or assist access to content you have no right to access.

All product names, channel names, network names, callsigns, trademarks and registered trademarks mentioned in this project, or appearing in its examples or bundled reference data, are the property of their respective owners. This project is an independent, community-built plugin. It is not affiliated with, endorsed by, or sponsored by any television network, broadcaster, streaming service or IPTV provider, and it is not affiliated with the Dispatcharr project beyond being a plugin written for it.

Contributing

See CONTRIBUTING.md for how to set up, run the tests, and what runs on a pull request.

This plugin is free and always will be. If it saves you time and you would like to support the work, you can sponsor it at github.com/sponsors/PiratesIRC.

Sponsoring buys no priority, no private support and no influence over what gets built. Bug reports and pull requests are just as welcome from everyone.

Security

To report a vulnerability, see SECURITY.md. Please do not include provider credentials, stream URLs or M3U account names in a public issue.

License

MIT

This site is open source. Improve this page.