Joren/Stream-Mapparr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Revise README for improved clarity and detail

Browse Source 
Updated README to enhance clarity and detail regarding plugin features, installation, and usage instructions.
This commit is contained in:
Pirates IRC
2025-10-31 16:06:00 -05:00
committed by GitHub
parent faa35afebe
commit b296babff2
1 changed files with 142 additions and 202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
README.md
View File

@@ -1,33 +1,38 @@
# Stream Mapparr
A Dispatcharr plugin that automatically matches and assigns streams to channels based on intelligent name matching, quality prioritization, and timezone filtering.
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/PiratesIRC/Stream-Mapparr)
A Dispatcharr plugin that automatically matches and assigns streams to channels based on advanced fuzzy matching, quality prioritization, and OTA callsign recognition.
## Recommendation
It is strongly recommended to use the **[Channel Maparr Plugin](https://github.com/PiratesIRC/Dispatcharr-Channel-Maparr-Plugin)** before using this plugin. Running Channel Maparr first to standardize your channel names will significantly improve matching accuracy.
## ⚠️ 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.](https://dispatcharr.github.io/Dispatcharr-Docs/troubleshooting/?h=backup#how-can-i-make-a-backup-of-the-database)**
## Features
* **Intelligent Stream Matching**: Automatically finds and assigns streams to channels using sophisticated name-matching algorithms
* **Unlimited Stream Support**: Fetches and processes ALL available streams regardless of quantity (no 10,000 stream limit)
* **OTA Callsign Matching**: Direct callsign extraction and matching for Over-The-Air broadcast channels
* **Multiple Streams Per Channel**: Assigns all matching streams to each channel, sorted by quality
* **Quality Prioritization**: Sorts matched streams by quality (4K → FHD → HD → (H) → (F) → (D) → SD → Slow)
* **Channel Visibility Management**: Automatically enables/disables channels based on stream assignments and duplicate detection
* **Timezone Filtering**: Automatically excludes West/Pacific coast feeds unless explicitly requested
* **Networks.json Integration**: FCC broadcast station database for OTA channel validation
* **Channels.txt Integration**: Distinguishes between similar channel names (e.g., FX vs FXX vs FX Movie Channel)
* **Customizable Ignore Tags**: Filter out unwanted tags during matching
* **Profile & Group Filtering**: Target specific channel profiles and groups
* **Preview Mode**: Dry-run CSV export to review matches before applying changes
* **CSV Export Management**: Built-in cleanup tool to delete old export files
* **Real-time Updates**: WebSocket-based frontend refresh for immediate visual feedback
* **Comprehensive Logging**: Detailed matching logic and debug information
* **Advanced Fuzzy Matching**: Automatically finds and assigns streams to channels using an advanced fuzzy-matching engine (`fuzzy_matcher.py`).
* **Unlimited Stream Support**: Fetches and processes ALL available streams regardless of quantity (no 10,000 stream limit).
* **Enhanced OTA Callsign Matching**: Uses a robust `*_channels.json` database for superior callsign extraction and matching for Over-The-Air broadcast channels.
* **Multi-Stream Assignment**: Assigns **all** matching streams to each channel (e.g., 4K, FHD, HD versions), sorted by quality.
* **Quality Prioritization**: Sorts matched streams by quality (4K → FHD → HD → (H) → (F) → (D) → SD → Slow).
* **Channel Visibility Management**: Automatically enables/disables channels based on stream assignments and duplicate detection.
* **Channel Database Integration**: Uses `*_channels.json` files for robust OTA and cable channel identification.
* **Customizable Ignore Tags**: Filter out unwanted tags during matching.
* **Profile & Group Filtering**: Target specific channel profiles and groups.
* **Preview Mode**: Dry-run CSV export to review matches before applying changes.
* **CSV Export Management**: Built-in cleanup tool to delete old export files.
* **Real-time Updates**: WebSocket-based frontend refresh for immediate visual feedback.
* **Comprehensive Logging**: Detailed matching logic and debug information.
## Requirements
* Active Dispatcharr installation
* Admin username and password for API access
* **A Channels Profile other than "All"** ([Profile Documentation](https://dispatcharr.github.io/Dispatcharr-Docs/user-guide/#channels_1))
* Multiple streams of the same channel available in your setup
* `channels.txt` file (curated channel list) - included
* `networks.json` file (FCC broadcast station database) - included for OTA support
## Recommendation
It is recommended to use the [Channel Mapparr Plugin](https://github.com/PiratesIRC/Dispatcharr-Channel-Maparr-Plugin) before using this plugin to standardize channel names. Standardized channel names significantly improve matching accuracy.
* `fuzzy_matcher.py` (matching engine) - included
* `*_channels.json` files (channel database) - included
## Installation
1. Log in to Dispatcharr's web UI
@@ -38,24 +43,26 @@ It is recommended to use the [Channel Mapparr Plugin](https://github.com/Pirates
## Settings Reference
| Setting | Type | Default | Description |
|:--------|:-----|:--------|:------------|
|:---|:---|:---|:---|
| **Fuzzy Match Threshold** | `number` | 85 | Minimum similarity score (0-100) for fuzzy matching. Higher values require closer matches. |
| **Dispatcharr URL** | `string` | - | Full URL of your Dispatcharr instance (e.g., `http://192.168.1.10:9191`) |
| **Dispatcharr Admin Username** | `string` | - | Username for API authentication |
| **Dispatcharr Admin Password** | `password` | - | Password for API authentication |
| **Profile Name** | `string` | - | Name of an existing Channel Profile to process (e.g., "Primary", "Sports") |
| **Channel Groups** | `string` | - | Comma-separated group names to process, or leave empty for all groups |
| **Ignore Tags** | `string` | - | Comma-separated tags to ignore during matching (e.g., `4K, [4K], [Dead]`) |
| **Visible Channel Limit** | `number` | 1 | Number of channels per callsign group that will be visible and have streams added |
| **Visible Channel Limit** | `number` | 1 | Number of channels per matching group that will be visible and have streams added |
## Usage Guide
### Step-by-Step Workflow
1. **Configure Settings**
* Enter your Dispatcharr URL, username, and password
* Adjust the **Fuzzy Match Threshold** slider (85 is a good default)
* Specify an existing **Profile Name** (cannot be "All")
* Optionally specify **Channel Groups** (leave empty to process all)
* Optionally configure **Ignore Tags** to filter out unwanted tags
* Set **Visible Channel Limit** (default: 1 channel per callsign group)
* Optionally configure **Ignore Tags**
* Set **Visible Channel Limit** (default: 1 channel per matching group)
* Click **Save Settings**
2. **Load and Process Channels**
@@ -73,17 +80,16 @@ It is recommended to use the [Channel Mapparr Plugin](https://github.com/Pirates
4. **Add Streams to Channels**
* Click **Run** on `Add Stream(s) to Channels`
* Adds all matched streams to each channel (sorted by quality)
* Adds **all** matched streams to each channel (sorted by quality)
* Only updates channels within the visible channel limit
* Enables updated channels in the profile
* Triggers real-time frontend refresh via WebSocket
* Exports results to `/data/exports/stream_mapparr_results_YYYYMMDD_HHMMSS.csv`
* Exports results to `/data/exports/stream_mapparr_update_YYYYMMDD_HHMMSS.csv`
5. **Manage Channel Visibility (Optional)**
* Click **Run** on `Manage Channel Visibility`
* Disables all channels in the profile
* Enables only channels with 0-1 streams (not attached to other channels)
* Enables only the highest priority channel per callsign group
* Enables only the single highest-priority, eligible channel from each matching group
* Useful for cleaning up duplicate channels
* Triggers real-time frontend refresh via WebSocket
* Exports visibility report to `/data/exports/stream_mapparr_visibility_YYYYMMDD_HHMMSS.csv`
@@ -95,43 +101,21 @@ It is recommended to use the [Channel Mapparr Plugin](https://github.com/Pirates
* Useful for cleaning up old reports and freeing disk space
## Matching Logic
Stream-Mapparr v0.4 uses a new `FuzzyMatcher` engine and a channel database for all matching.
### OTA Channel Matching (Priority Method)
For broadcast channels like "CBS - IN South Bend (WSBT) [HD]":
1. **Channel Grouping**: Channels are grouped by a 'group key'.
* **OTA Channels**: Grouped by callsign (e.g., `OTA_WSBT`).
* **Standard Channels**: Grouped by their cleaned name (e.g., `HBO`).
1. **Callsign Extraction**: Parses channel name BEFORE any cleaning to extract callsign
* Pattern: `NETWORK - STATE City (CALLSIGN) [Quality]`
* Example: `CBS - IN South Bend (WSBT) [HD]` → Callsign: `WSBT`
2. **Channel Prioritization**: Within each group, channels are sorted by quality tags (e.g., `[4K]` > `[HD]`) and then by channel number (ascending).
2. **Direct Callsign Matching**: Searches all streams for the exact callsign using word boundaries
* Matches: `US CBS 22 (WSBT) South Bend/Elkhart Area (H)`
* Matches: `CBS: IN SOUTH BEND WSBT`
* Excludes: `WSBTV` (different callsign)
3. **Matching**: The plugin uses the **highest priority** channel from the group (e.g., `CBS - IN South Bend (WSBT) [4K]` or `HBO [4K]`) as the "search query".
* **OTA Matching**: If the channel is OTA, the `FuzzyMatcher` looks up its callsign (`WSBT`) in the `*_channels.json` database and searches all streams for that callsign.
* **Standard Matching**: If not OTA, the `FuzzyMatcher` cleans the channel name (e.g., to `HBO`) and uses advanced fuzzy matching (token sorting, similarity ratios) to find the best match from the stream list (e.g., matching `HBO` to `HBO US`).
3. **Fallback to Networks.json**: If direct matching fails, validates against FCC database
* Confirms network affiliation
* Validates state and callsign combination
* Searches streams for validated callsign
4. **Multi-Stream Collection**: Once a match is found (e.g., stream name "HBO US"), the plugin gathers **all** quality variations of that matched stream (e.g., `HBO US [4K]`, `HBO US [HD]`, `HBO US [SD]`).
4. **Quality Sorting**: All matched streams sorted by quality precedence
### Standard Channel Matching
For non-OTA channels, the plugin uses a multi-stage process:
1. **Exact Match After Cleaning**: Matches channel names after removing quality tags
* Example: "TBS [FHD]" → "TBS" matches "US: TBS"
2. **Word Boundary Matching**: Ensures complete word matches to avoid false positives
* Example: "FX" matches "US: FX" but NOT "FXX" or "WFXR"
3. **Longer Channel Filtering**: Uses `channels.txt` to distinguish similar names
* Example: "FX" does NOT match "FX Movie Channel" (different channel)
4. **Call Sign Filtering**: Excludes local TV station call signs
* Example: "FX" does NOT match "WBKB FX (WBKBDT4)" (local FOX affiliate)
5. **Timezone Filtering**: Automatically excludes West/Pacific feeds
* Example: "SYFY [HD]" matches "US NBC SYFY (East)" but NOT "US NBC SYFY (West)"
5. **Assignment**: These collected streams are sorted by quality and assigned to the high-priority channel(s) in the group, up to the **Visible Channel Limit**.
### Channel Grouping and Priority
Channels are grouped by callsign (OTA) or cleaned name (regular):
@@ -149,91 +133,63 @@ Matched streams are automatically sorted by quality precedence:
* **Other**: `(F)`, `(D)`
* **Slow**: `Slow`, `[Slow]`, `(Slow)`
## Example Transformations
### OTA Channels (Callsign Matching)
**Channel**: `CBS - IN South Bend (WSBT) [HD]`
**Matched Streams**: `US CBS 22 (WSBT) South Bend/Elkhart Area (H)`, `US CBS 22 (WSBT) South Bend/Elkhart Area (F)`, `CBS: IN SOUTH BEND WSBT`
**Channel**: `CBS - CA Monterey (KION) [FHD]`
**Matched Streams**: `US CBS 46 (KION) Monterey (H)`, `US CBS 46 (KION) Monterey (F)`, `CBS: CA MONTEREY KION`, `US: FOX Monterey (KION)`
**Channel**: `CBS - NM Albuquerque (KRQE) [HD]`
**Matched Streams**: `US FOX (KRQE) Albuquerque Santa Fe (H)`, `US CBS 13 (KRQE) Albuquerque Santa Fe (H)`, `US FOX (KRQE) Alburquerque (F)`, `US CBS (KRQE) Albuquerque (F)`, `CBS: NM ALBUQUERQUE KRQE`, `FOX: ALBUQUERQUE NM KRQE`, `US: CBS 13 Albuquerque (KRQE)`, `US: FOX 13 Albuquerque (KRQE)`
### Standard Channels
**Channel**: `TBS [FHD]`
**Matched Streams**: `USA: TBS`, `US: TBS`, `US: TBS`
**Channel**: `FX (East) [HD]`
**Matched Streams**: `US: FX`, `US: FX`, `US FX (East) (S)`, `US FX (East) (H)`, `US FX (East) (A)`, `US (F2) FX (East)`
**Excluded**: `US: FX Movie Channel`, `(US) (FOX1) WBKB FX (WBKBDT4)`
**Channel**: `SYFY [HD]`
**Matched Streams**: `USA SYFY`, `US: SYFY`, `US: SYFY`, `US NBC SYFY (East) (D)`
**Excluded**: `US NBC SYFY (West) (D)`
### Duplicate Channel Handling
**Channels in Profile**:
* `CBS - AL Birmingham (WIAT) [FHD]` ← Highest priority (enabled, receives streams)
* `CBS - AL Birmingham (WIAT) [HD]` ← Lower priority (skipped)
* `CBS - AL Birmingham (WIAT) [Slow] [HD]` ← Lower priority (skipped)
**Result**: Only the `[FHD]` channel receives streams and is visible
**Result**: With `Visible Channel Limit` set to 1, only the `[FHD]` channel receives streams and is visible.
## Action Reference
| Action | Description |
|:-------|:------------|
|:---|:---|
| **Load/Process Channels** | Load channels from specified profile/groups and fetch all available streams (unlimited) |
| **Preview Changes (Dry Run)** | Export CSV showing which streams will be matched to each channel |
| **Add Stream(s) to Channels** | Apply matched streams to channels, enabling highest priority channels in each group |
| **Manage Channel Visibility** | Disable all channels, then enable only channels with 0-1 streams (excluding duplicates and attached channels) |
| **Add Stream(s) to Channels** | Apply **all** matched streams to channels, enabling highest priority channels in each group |
| **Manage Channel Visibility** | Disable all channels, then enable only the single highest-priority, eligible channel from each matching group |
| **Clear CSV Exports** | Delete all CSV export files created by this plugin to free up disk space |
## File Locations
* **Processing Cache**: `/data/stream_mapparr_processed.json`
* **Preview Export**: `/data/exports/stream_mapparr_preview_YYYYMMDD_HHMMSS.csv`
* **Results Report**: `/data/exports/stream_mapparr_results_YYYYMMDD_HHMMSS.csv`
* **Results Report**: `/data/exports/stream_mapparr_update_YYYYMMDD_HHMMSS.csv`
* **Visibility Report**: `/data/exports/stream_mapparr_visibility_YYYYMMDD_HHMMSS.csv`
* **Plugin Files**:
* `/data/plugins/stream_mapparr/plugin.py`
* `/data/plugins/stream_mapparr/__init__.py`
* `/data/plugins/stream_mapparr/channels.txt`
* `/data/plugins/stream_mapparr/networks.json`
* `/data/plugins/stream_mapparr/fuzzy_matcher.py` (Matching Engine)
* `/data/plugins/stream_mapparr/*_channels.json` (Channel Database)
## CSV Export Format
### Preview CSV
### Preview CSV (`stream_mapparr_preview_...csv`)
| Column | Description |
|:-------|:------------|
| **channel_id** | Internal Dispatcharr channel ID |
| **channel_name** | Channel name |
| **channel_number** | Channel number |
| **matched_streams_count** | Number of streams matched |
| **stream_names** | Pipe-separated list of matched stream names |
| **stream_ids** | Comma-separated list of matched stream IDs |
|:---|:---|
| **will_update** | `Yes` if channel will be updated, `No` if skipped |
### Results CSV
| Column | Description |
|:-------|:------------|
| **channel_id** | Internal Dispatcharr channel ID |
| **channel_name** | Channel name |
| **channel_name_cleaned** | The cleaned name used for matching |
| **channel_number** | Channel number |
| **matched_streams_count** | Number of streams added |
| **stream_names** | Pipe-separated list of added stream names |
| **stream_ids** | Comma-separated list of added stream IDs |
| **will_update** | `Yes` if channel was updated, `No` if skipped |
| **status** | `Updated`, `Skipped (over limit)`, `No matches`, or error details |
| **matched_streams** | Number of streams matched |
| **match_reason** | How the match was found (e.g., `Fuzzy match (exact, score: 100)`) |
| **stream_names** | Semicolon-separated list of matched stream names |
### Visibility Report CSV
### Results CSV (`stream_mapparr_update_...csv`)
| Column | Description |
|:-------|:------------|
|:---|:---|
| **channel_name** | Channel name that was updated |
| **stream_names** | Semicolon-separated list of added stream names |
| **matched_streams** | Number of streams added |
### Visibility Report CSV (`stream_mapparr_visibility_...csv`)
| Column | Description |
|:---|:---|
| **channel_id** | Internal Dispatcharr channel ID |
| **channel_name** | Channel name |
| **stream_count** | Number of streams attached to channel |
| **reason** | Why channel was enabled/disabled |
| **reason** | Why channel was enabled/disabled (e.g., `2+ streams`, `Duplicate`, `Attached`) |
| **enabled** | `Yes` if channel is visible, `No` if hidden |
## Troubleshooting
@@ -254,23 +210,23 @@ Matched streams are automatically sorted by quality precedence:
* Verify channel name format: `NETWORK - STATE City (CALLSIGN)`
* Example: `CBS - IN South Bend (WSBT) [HD]`
* Check that callsign exists in stream names
* Review logs for "Extracted callsign" and "Found callsign match" messages
* Ensure `networks.json` contains the station data (fallback method)
* Review logs for `FuzzyMatcher` and `callsign` messages
* Ensure `*_channels.json` files are present in the plugin directory
**Too many duplicate channels visible**
* Run "Manage Channel Visibility" action
* Adjust "Visible Channel Limit" setting (default: 1)
* Only highest priority channels per callsign group will remain visible
* Only highest priority channels per matching group will remain visible
**Channels not matching streams**
* Run Channel Mapparr first to standardize channel names
* Adjust the **"Fuzzy Match Threshold"** slider (try a lower value like 80)
* Check that streams exist for your channels
* Use Preview mode to see matching details in logs
* Verify `channels.txt` contains your channel names
**Too many false positives**
* Add entries to `channels.txt` to distinguish similar names
* Use Ignore Tags to filter out quality indicators
* Increase the **"Fuzzy Match Threshold"** slider (try 90 or 95)
* Use Ignore Tags to filter out common unwanted words
* Check logs for matching logic details
**Frontend not updating after changes**
@@ -323,19 +279,10 @@ To update Stream-Mapparr from a previous version:
* This automatically standardizes channel names across your entire setup
* Provides consistent naming that Stream-Mapparr can reliably match
**Option 2: Edit channels.txt manually**
* Navigate to `/data/plugins/stream_mapparr/channels.txt`
* Add standardized channel names (one per line)
* Example entries:
```
TBS
FX
FX Movie Channel
SYFY
USA Network
```
* This helps the plugin distinguish between similar channel names
* Restart the plugin after editing
**Option 2: Adjust Fuzzy Match Threshold**
* Navigate to the plugin settings
* If you are missing matches, try a **lower** value (e.g., `80`).
* If you are getting bad/incorrect matches, try a **higher** value (e.g., `90` or `95`).
### How many streams can the plugin handle?
@@ -353,8 +300,8 @@ With a limit of 1, only the highest priority channel (`[FHD]`) receives streams
### What happens to existing stream assignments?
When you run "Add Stream(s) to Channels", the plugin:
* Removes all existing stream assignments from matched channels
* Adds the new matched streams (sorted by quality)
* Removes **all** existing stream assignments from matched channels
* Adds **all** the new matched streams (sorted by quality)
* Only affects channels within the Visible Channel Limit
Channels outside the limit or without matches are left unchanged.
@@ -383,18 +330,11 @@ docker logs -f dispatcharr | grep -i stream_mapparr
# View processing cache
docker exec dispatcharr cat /data/stream_mapparr_processed.json | jq
# Check OTA callsign extraction
docker logs -f dispatcharr | grep "Extracted callsign"
# Check fuzzy matching activity
docker logs -f dispatcharr | grep -i "FuzzyMatcher"
# Check stream matches
docker logs -f dispatcharr | grep "Found callsign match"
# Check match type and score
docker logs -f dispatcharr | grep "match_type"
# Check CSV exports
docker exec dispatcharr ls -lh /data/exports/stream_mapparr_*
```
## Performance Notes
* **No Stream Limit**: Version 0.3 removes the previous 10,000 stream limitation
* **Automatic Pagination**: Plugin handles API pagination automatically, fetching all available streams
* **Large Libraries**: Successfully tested with 10,000+ streams
* **WebSocket Updates**: Real-time frontend refresh eliminates need for manual page refresh after changes