Stream Mapparr

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

⚠️ Important: 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.

---

🚨 V0.6.0+ Important: Background Operations & Monitoring

Please Read Carefully: Starting with v0.6.0, this plugin uses Background Threading to prevent browser timeouts during long operations. This changes how you interact with the plugin:

1. No "Completed" Pop-up: The frontend will show a green "✅ Started in background" notification immediately. This does NOT mean the task is finished.
2. Buttons Re-enable Immediately: Do not click the button again. The task is running in the background.
3. Check Docker Logs: To see progress and completion status, you must check your Docker logs.

To monitor operations, open your terminal and run: Look for "✅ [ACTION] COMPLETED" or "📄 CSV EXPORT CREATED" in the logs to know when it is done.

---

Features

• Background Processing Engine (NEW v0.6.0): Operations run in background threads to prevent HTTP timeouts and "broken pipe" errors on large datasets.
• Smart Rate Limiting (NEW v0.6.0): Configurable API rate limiting with exponential backoff to prevent server overload and 429/5xx errors.
• Integrated Scheduler (NEW v0.6.0): Configure automated daily runs directly within the plugin settings (supports Timezones and custom HHMM times).
• Token Mismatch Analysis (NEW v0.6.0): CSV exports now analyze why channels didn't match and provide specific recommendations (e.g., "Add 'UK' to ignore tags").
• Advanced Fuzzy Matching: Automatically finds and assigns streams to channels using an advanced fuzzy-matching engine.
• Multi-Country Support: Support for multiple *_channels.json databases (US, UK, CA, etc.).
• Quality Prioritization: Sorts matched streams by quality (4K → FHD → HD → SD).
• Channel Visibility Management: Automatically enables/disables channels based on stream assignments.
• Preview Mode: Dry-run CSV export to review matches before applying changes.

Requirements

• Active Dispatcharr installation
• Admin username and password for API access
• A Channels Profile other than "All"
• Multiple streams of the same channel available in your setup

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 Channel Mapparr from a previous version:

1. Remove Old Version

1. Navigate to Plugins in Dispatcharr.
2. Click the trash icon next to the old Stream Mapparr plugin.
3. Confirm deletion.

2. Restart Dispatcharr

1. Log out of Dispatcharr.
2. Restart the Docker container:

   docker restart dispatcharr
   

3. Install New Version

1. Log back into Dispatcharr.
2. Navigate to Plugins.
3. Click Import Plugin and upload the new plugin zip file.
4. Enable the plugin after installation.

4. Verify Installation

1. Check that the new version number appears in the plugin list.
2. Reconfigure your settings if needed.
3. Run Load/Process Channels to test the update.

Operations & Monitoring Guide

Because this plugin processes potentially thousands of streams, operations can take 5-15+ minutes.

How to Run an Action

1. Open a terminal connected to your server.
2. Run docker logs -f dispatcharr to watch the logs.
3. In the browser, click an action button (e.g., "Add Stream(s) to Channels").
4. You will see a notification: "✅ Operation started in background".
5. Wait. Do not close the browser or restart the container.
6. Watch the terminal logs for updates like:
   • [Stream-Mapparr] Progress: 20%...
   • [Stream-Mapparr] Progress: 50%...
7. The operation is finished when you see:
   • [Stream-Mapparr] ✅ ADD STREAMS TO CHANNELS COMPLETED

Why can't I see progress in the UI?

Dispatcharr's plugin system currently supports synchronous HTTP responses. Because we moved to asynchronous background threads (to fix timeouts), the frontend receives the "Started" signal but cannot listen for the "Completed" signal without core modifications to Dispatcharr. We prioritize successful completion over UI feedback.

Scheduling (New in v0.6.0)

You can now schedule Stream-Mapparr to run automatically without setting up external Celery tasks.

1. Go to Plugin Settings.
2. Timezone: Select your local timezone (e.g., US/Central, Europe/London).
3. Scheduled Run Times: Enter times in 24-hour format, comma-separated (e.g., 0400, 1600).
   • Example: 0400 runs at 4:00 AM.
   • Example: 0400,1600 runs at 4:00 AM and 4:00 PM.
4. Enable CSV Export: Check this to generate a report every time the scheduler runs.
5. Click Update Schedule.

Note: The scheduler runs in a background thread. If you restart the Dispatcharr container, the scheduler restarts automatically.

Settings Reference

Setting	Type	Default	Description
Overwrite Existing Streams	boolean	True	If enabled, removes all existing streams and replaces with matched streams.
Fuzzy Match Threshold	number	85	Minimum similarity score (0-100). Higher = stricter matching.
Dispatcharr URL/Creds	string	-	Connection details for the API.
Profile Name	string	-	Name of the Channel Profile to process.
Channel Groups	string	-	Specific groups to process (empty = all).
Rate Limiting (v0.6.0)	select	Medium	Controls API speed. Use 'High' if experiencing timeouts/errors.
Timezone (v0.6.0)	select	US/Central	Timezone for scheduled runs.
Scheduled Run Times	string	-	Times to run automatically (HHMM format).
Visible Channel Limit	number	1	How many duplicate channels to enable per group.
Ignore Tags	string	-	Tags to strip before matching (e.g., [Dead], (Backup)).

Channel Databases

Stream-Mapparr uses *_channels.json files to improve OTA and cable channel matching.

1. Navigate to Settings.
2. Scroll to Channel Databases.
3. Check the boxes for the countries you want to enable (e.g., Enable US, Enable UK).
4. If you need a custom database, create a JSON file (e.g., CA_channels.json) and place it in /data/plugins/stream_mapparr/.

CSV Reports & Recommendations

When running Preview Changes or Add Streams, the plugin generates a CSV file in /data/exports/.

New in v0.6.0: Open the CSV file in a text editor or spreadsheet. The header contains detailed analysis:

• Threshold Recommendations: "3 additional streams available at lower thresholds. Consider lowering to 75."
• Token Mismatches: "Channel 'BBC One' vs Stream 'UK BBC One'. Mismatched token: 'UK'. Add 'UK' to Ignore Tags."

Troubleshooting

Buttons are clickable but nothing happens? Check the Docker logs. If an operation is already running, the logs will say: ❌ Cannot start... Another operation is already running. Wait for the current operation to finish (lock expires after 10 mins).

"API token expired" in logs The plugin now automatically attempts to refresh tokens. If it fails, check your Username/Password in settings.

System/API is slow during scanning Change the Rate Limiting setting to "High (Slow)". This adds a delay between API calls to reduce load on your server.

How to stop a running operation? Restart the Dispatcharr container: docker restart dispatcharr.

Cleaning up old tasks If you upgraded from an older version, run the "Cleanup Orphaned Tasks" action to remove old Celery schedules that might conflict with the new internal scheduler.

Debugging Commands

# Monitor plugin activity (The most important command!)
docker logs -f dispatcharr | grep "Stream-Mapparr"

# Check generated CSVs
docker exec dispatcharr ls -lh /data/exports/

# Check plugin files
docker exec dispatcharr ls -la /data/plugins/stream_mapparr/
```bash
docker logs -f dispatcharr | grep "Stream-Mapparr"