Skip to content

Commit 59995fb

Browse files
PiratesIRCPiratesIRC
authored
Update README.md
1 parent 56e0f41 commit 59995fb

1 file changed

Lines changed: 50 additions & 240 deletions

File tree

‎README.md‎

Lines changed: 50 additions & 240 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
1-
# Stream Mapparr
1+
# Channel Mapparr
22
A Dispatcharr plugin that standardizes US broadcast (OTA) and premium/cable channel names using FCC network data and curated channel lists.
33

44
## Features
55
* **Dual Database Matching**: Automatically identifies channels using both `networks.json` (OTA) and `channels.txt` (premium/cable).
66
* **Customizable OTA Formatting**: Use tags like `{NETWORK}`, `{STATE}`, `{CITY}`, `{CALLSIGN}` to format broadcast channel names.
77
* **Intelligent Fuzzy Matching**: Handles channel name variations, regional indicators (East/West), quality tags, and country suffixes.
88
* **Configurable Ignored Tags**: Define a custom list of tags (e.g., `[4K]`, `[FHD]`) to be removed from channel names before matching.
9-
* **Advanced OTA Recognition**: Intelligently extracts callsigns from various formats (e.g., `(WMTW-PORTLAND MAINE)`) and handles multiple US/USA prefixes while avoiding false positives.
9+
* **Advanced OTA Recognition**: Intelligently extracts callsigns from complex formats (e.g., `(WMTW-PORTLAND MAINE)`), handles multiple `US`/`USA` prefixes, and avoids false positives.
1010
* **Smarter Matching Logic**: Prevents OTA channels from incorrectly matching premium channels by attempting premium matching only when no broadcast callsign is found.
11-
* **Improved Premium Channel Normalization**: Standardizes regional indicators to appear after the channel name (e.g., `HBO Comedy West (H)`) for better consistency.
11+
* **Improved Premium Channel Normalization**: Standardizes regional indicators to appear after the channel name for better consistency.
1212
* **Logo Management**: Bulk apply default logos to channels without artwork.
1313
* **CSV Export**: Preview changes before applying with detailed dry-run reports.
1414
* **Group Filtering**: Target specific channel groups or process all channels.
@@ -20,18 +20,6 @@ A Dispatcharr plugin that standardizes US broadcast (OTA) and premium/cable chan
2020
* `networks.json` file (FCC broadcast station database) - included
2121
* `channels.txt` file (premium/cable channel list) - included
2222

23-
## Upgrading from Channel Mapparr
24-
If upgrading the plugin, then perform the following:
25-
1. From Dispatcharr's plugin page, delete Channel Mapparr
26-
2. Restart Dispatcharr via Docker or any other method
27-
3. Refresh your web browser (f5)
28-
4. Install Stream Mapparr
29-
30-
## Important Notes
31-
* Refer to the Dispatcharr logs to check the status of 'adding streams to channels'.
32-
* Do not log out when using the plugin.
33-
* For any errors such as "plugin does not exist," refresh your web browser.
34-
3523
## Installation
3624
1. Log in to Dispatcharr's web UI.
3725
2. Navigate to **Plugins**.
@@ -65,11 +53,11 @@ If upgrading the plugin, then perform the following:
6553
* Review the summary showing OTA vs. premium/cable matches.
6654
3. **Preview Changes (Dry Run)**
6755
* Click **Run** on `Preview Changes (Dry Run)`.
68-
* Exports a CSV to `/data/exports/stream_mapparr_preview_YYYYMMDD_HHMMSS.csv`.
56+
* Exports a CSV to `/data/exports/channel_mapparr_preview_YYYYMMDD_HHMMSS.csv`.
6957
* Review proposed changes with database source indicators.
7058
4. **Apply Changes**
7159
* Click **Run** on `Rename Channels` to standardize names.
72-
* A rename report is saved to `/data/exports/stream_mapparr_renamed_YYYYMMDD_HHMMSS.csv`.
60+
* A rename report is saved to `/data/exports/channel_mapparr_renamed_YYYYMMDD_HHMMSS.csv`.
7361
* Optionally run `Add Suffix to Unknown Channels` for unmatched channels.
7462
5. **Apply Logos (Optional)**
7563
* Configure **Default Logo** with a display name from the logo manager.
@@ -79,20 +67,22 @@ If upgrading the plugin, then perform the following:
7967
## Channel Matching Logic
8068

8169
### OTA Channels (`networks.json`)
82-
* Extracts callsigns from channel names (patterns like `(KABC)`, `WXYZ`, etc.).
70+
* Extracts callsigns from channel names, including complex formats like `(WMTW-PORTLAND MAINE)`.
71+
* Handles various `US`/`USA` prefixes.
8372
* Looks up station data in the FCC database.
8473
* Formats using a customizable template with network, location, and callsign.
85-
* Skips channels with "WEST" or "EAST" alone (not valid callsigns).
74+
* Avoids false positive callsigns like `EAST` or `KIDS`.
75+
* Only attempts premium/cable matching if no callsign is found, preventing incorrect matches.
8676

8777
### Premium/Cable Channels (`channels.txt`)
8878
* Two-stage fuzzy matching process:
8979
* High-confidence match (97%+ similarity after normalization).
9080
* Number variation handling (matches "HBO 2" → "HBO2").
91-
* Preserves regional indicators: `(East)`, `(West)`.
92-
* Preserves quality tags: `[HD]`, `[FHD]`, `[SD]`, `[Slow]`.
81+
* Correctly positions regional indicators after the channel name (e.g., `HBO Comedy West (H)`).
82+
* Preserves quality tags: `[HD]`, `[FHD]`, `[SD]`, etc.
9383
* Preserves extra tags: `(CX)`, `(USA)`, etc.
9484
* Removes "USA" suffix except for "USA Network".
95-
* Removes content from the **Ignored Tags** list during matching.
85+
* Removes tags defined in the **Ignored Tags** setting before matching.
9686

9787
## Example Transformations
9888

@@ -104,194 +94,8 @@ If upgrading the plugin, then perform the following:
10494
* **Before:** `HBO 2 (East) [HD]`
10595
* **After:** `HBO2 (East) [HD]`
10696
<br>
107-
* **Before:** `Cinemax Moviemax East [SD]`
108-
* **After:** `MovieMax (East) [SD]`
109-
<br>
110-
* **Before:** `5 Star Max USA [FHD]`
111-
* **After:** `5StarMax [FHD]`
112-
113-
## Action Reference
114-
115-
### Core Actions
116-
| Action | Description |
117-
| :--- | :--- |
118-
| **Load/Process Channels** | Load channels from groups and match against databases. |
119-
| **Preview Changes (Dry Run)** | Export a CSV showing proposed renames with database sources. |
120-
| **Rename Channels** | Apply standardized names to matched channels. |
121-
| **Add Suffix to Unknown Channels**| Tag unmatched channels with the configured suffix. |
122-
| **Apply Default Logos** | Bulk assign a logo to channels without artwork. |
123-
124-
## File Locations
125-
* **Processing Cache**: `/data/stream_mapparr_loaded_channels.json`
126-
* **Preview Export**: `/data/exports/stream_mapparr_preview_YYYYMMDD_HHMMSS.csv`
127-
* **Rename Report**: `/data/exports/stream_mapparr_renamed_YYYYMMDD_HHMMSS.csv`
128-
* **Plugin Files**:
129-
* `/data/plugins/stream_mapparr/plugin.py`
130-
* `/data/plugins/stream_mapparr/networks.json`
131-
* `/data/plugins/stream_mapparr/channels.txt`
132-
133-
## CSV Export Format
134-
135-
| Column | Description |
136-
| :--- | :--- |
137-
| **channel_id** | Internal Dispatcharr channel ID. |
138-
| **channel_number** | Channel number. |
139-
| **channel_group** | Current group name. |
140-
| **current_name** | Original channel name. |
141-
| **new_name** | Proposed/applied name. |
142-
| **status** | `Renamed` or `Skipped`. |
143-
| **dbase** | Database used: `networks.json`, `channels.txt`, or `none`. |
144-
| **reason** | Skip reason if applicable. |
145-
146-
## Logo Management
147-
The plugin uses Dispatcharr's logo manager **display names** (not filenames):
148-
149-
1. Navigate to **Logos** in the Dispatcharr UI.
150-
2. Find your desired default logo.
151-
3. Copy the **display name** (e.g., `abc-logo-2013-garnet-us`).
152-
4. Enter it in the plugin's **Default Logo** setting.
153-
5. Run the **Apply Default Logos** action.
154-
155-
**Note:** Logos are only applied to channels that either have no logo or use the "Default" logo (ID 0).
156-
157-
## Troubleshooting
158-
159-
### Common Issues
160-
* **"Logo not found in logo manager"**
161-
* Use the logo's **display name** from Dispatcharr's Logos page, not the filename.
162-
* Check logs for available logo names (the first 30 are listed).
163-
* Ensure the logo has been uploaded to Dispatcharr.
164-
* **"No suffix configured"**
165-
* If the default value is not working, manually enter ` [Unk]` (with a leading space) in settings.
166-
* Save settings before running actions.
167-
* **"No groups found"**
168-
* Verify channel groups exist in Dispatcharr.
169-
* Check that group names are spelled correctly (case-sensitive).
170-
* Leave the field empty to process all groups.
171-
* **Channels not matching**
172-
* Verify `networks.json` and `channels.txt` are in the plugin directory.
173-
* Check logs for callsign extraction and matching attempts.
174-
* Use the **Preview** export to see which database was attempted.
175-
176-
### Debugging Commands
177-
```bash
178-
# Check plugin files
179-
docker exec dispatcharr ls -la /data/plugins/stream_mapparr/
180-
181-
# Monitor plugin activity
182-
docker logs dispatcharr | grep -i stream_mapparr
183-
184-
# View processing cache
185-
docker exec dispatcharr cat /data/stream_mapparr_loaded_channels.json
186-
```
187-
188-
Markdown
189-
190-
# Stream Mapparr
191-
A Dispatcharr plugin that standardizes US broadcast (OTA) and premium/cable channel names using FCC network data and curated channel lists.
192-
193-
## Features
194-
* **Dual Database Matching**: Automatically identifies channels using both `networks.json` (OTA) and `channels.txt` (premium/cable).
195-
* **Customizable OTA Formatting**: Use tags like `{NETWORK}`, `{STATE}`, `{CITY}`, `{CALLSIGN}` to format broadcast channel names.
196-
* **Intelligent Fuzzy Matching**: Handles channel name variations, regional indicators (East/West), quality tags, and country suffixes.
197-
* **Configurable Ignored Tags**: Define a custom list of tags (e.g., `[4K]`, `[FHD]`) to be removed from channel names before matching.
198-
* **Advanced OTA Recognition**: Intelligently extracts callsigns from various formats (e.g., `(WMTW-PORTLAND MAINE)`) and handles multiple US/USA prefixes while avoiding false positives.
199-
* **Smarter Matching Logic**: Prevents OTA channels from incorrectly matching premium channels by attempting premium matching only when no broadcast callsign is found.
200-
* **Improved Premium Channel Normalization**: Standardizes regional indicators to appear after the channel name (e.g., `HBO Comedy West (H)`) for better consistency.
201-
* **Logo Management**: Bulk apply default logos to channels without artwork.
202-
* **CSV Export**: Preview changes before applying with detailed dry-run reports.
203-
* **Group Filtering**: Target specific channel groups or process all channels.
204-
* **Unknown Channel Tagging**: Mark unmatched channels with configurable suffixes.
205-
206-
## Requirements
207-
* Active Dispatcharr installation
208-
* Admin username and password for API access
209-
* `networks.json` file (FCC broadcast station database) - included
210-
* `channels.txt` file (premium/cable channel list) - included
211-
212-
## Upgrading from Channel Mapparr
213-
If upgrading the plugin, then perform the following:
214-
1. From Dispatcharr's plugin page, delete Channel Mapparr
215-
2. Restart Dispatcharr via Docker or any other method
216-
3. Refresh your web browser (f5)
217-
4. Install Stream Mapparr
218-
219-
## Important Notes
220-
* Refer to the Dispatcharr logs to check the status of 'adding streams to channels'.
221-
* Do not log out when using the plugin.
222-
* For any errors such as "plugin does not exist," refresh your web browser.
223-
224-
## Installation
225-
1. Log in to Dispatcharr's web UI.
226-
2. Navigate to **Plugins**.
227-
3. Click **Import Plugin** and upload the plugin zip file.
228-
4. Enable the plugin after installation.
229-
230-
## Settings Reference
231-
232-
| Setting | Type | Default | Description |
233-
| :--- | :--- | :--- | :--- |
234-
| **Dispatcharr URL** | `string` | - | Full URL of your Dispatcharr instance (e.g., `http://127.0.0.1:9191`). |
235-
| **Dispatcharr Admin Username**| `string` | - | Username for API authentication. |
236-
| **Dispatcharr Admin Password**| `password`| - | Password for API authentication. |
237-
| **Channel Groups** | `string` | - | Comma-separated group names, empty = all groups. |
238-
| **OTA Channel Name Format** | `string` | `{NETWORK} - {STATE} {CITY} ({CALLSIGN})` | Format template for OTA channels. Available tags: `{NETWORK}`, `{STATE}`, `{CITY}`, `{CALLSIGN}`. |
239-
| **Ignored Tags** | `string` | `[4K], [FHD], [HD], [SD], [Unknown], [Unk], [Slow], [Dead]` | Comma-separated list of tags to remove from names before matching (case-insensitive, handles `[]` and `()`). |
240-
| **Suffix for Unknown Channels**| `string` | ` [Unk]` | Suffix to append to unmatched channels (OTA and premium/cable). |
241-
| **Default Logo** | `string` | - | Logo display name from Dispatcharr's logo manager to apply to channels without logos. |
242-
243-
## Usage Guide
244-
245-
### Step-by-Step Workflow
246-
1. **Configure Authentication**
247-
* Enter your Dispatcharr URL, username, and password.
248-
* Optionally specify **Channel Groups** (leave empty to process all).
249-
* Customize OTA format and unknown channel suffix.
250-
* Click **Save Settings**.
251-
2. **Load and Process Channels**
252-
* Click **Run** on `Load/Process Channels`.
253-
* The plugin attempts to match channels using `networks.json` first, then `channels.txt`.
254-
* Review the summary showing OTA vs. premium/cable matches.
255-
3. **Preview Changes (Dry Run)**
256-
* Click **Run** on `Preview Changes (Dry Run)`.
257-
* Exports a CSV to `/data/exports/stream_mapparr_preview_YYYYMMDD_HHMMSS.csv`.
258-
* Review proposed changes with database source indicators.
259-
4. **Apply Changes**
260-
* Click **Run** on `Rename Channels` to standardize names.
261-
* A rename report is saved to `/data/exports/stream_mapparr_renamed_YYYYMMDD_HHMMSS.csv`.
262-
* Optionally run `Add Suffix to Unknown Channels` for unmatched channels.
263-
5. **Apply Logos (Optional)**
264-
* Configure **Default Logo** with a display name from the logo manager.
265-
* Click **Run** on `Apply Default Logos`.
266-
* This only applies to channels without existing logos.
267-
268-
## Channel Matching Logic
269-
270-
### OTA Channels (`networks.json`)
271-
* Extracts callsigns from channel names (patterns like `(KABC)`, `WXYZ`, etc.).
272-
* Looks up station data in the FCC database.
273-
* Formats using a customizable template with network, location, and callsign.
274-
* Skips channels with "WEST" or "EAST" alone (not valid callsigns).
275-
276-
### Premium/Cable Channels (`channels.txt`)
277-
* Two-stage fuzzy matching process:
278-
* High-confidence match (97%+ similarity after normalization).
279-
* Number variation handling (matches "HBO 2" → "HBO2").
280-
* Preserves regional indicators: `(East)`, `(West)`.
281-
* Preserves quality tags: `[HD]`, `[FHD]`, `[SD]`, `[Slow]`.
282-
* Preserves extra tags: `(CX)`, `(USA)`, etc.
283-
* Removes "USA" suffix except for "USA Network".
284-
* Removes content from the **Ignored Tags** list during matching.
285-
286-
## Example Transformations
287-
288-
### OTA Channels
289-
* **Before:** `ABC 7 New York WABC`
290-
* **After:** `ABC - NY New York (WABC)`
291-
292-
### Premium/Cable Channels
293-
* **Before:** `HBO 2 (East) [HD]`
294-
* **After:** `HBO2 (East) [HD]`
97+
* **Before:** `HBO Comedy (H) West`
98+
* **After:** `HBO Comedy West (H)`
29599
<br>
296100
* **Before:** `Cinemax Moviemax East [SD]`
297101
* **After:** `MovieMax (East) [SD]`
@@ -311,13 +115,13 @@ If upgrading the plugin, then perform the following:
311115
| **Apply Default Logos** | Bulk assign a logo to channels without artwork. |
312116

313117
## File Locations
314-
* **Processing Cache**: `/data/stream_mapparr_loaded_channels.json`
315-
* **Preview Export**: `/data/exports/stream_mapparr_preview_YYYYMMDD_HHMMSS.csv`
316-
* **Rename Report**: `/data/exports/stream_mapparr_renamed_YYYYMMDD_HHMMSS.csv`
118+
* **Processing Cache**: `/data/channel_mapparr_loaded_channels.json`
119+
* **Preview Export**: `/data/exports/channel_mapparr_preview_YYYYMMDD_HHMMSS.csv`
120+
* **Rename Report**: `/data/exports/channel_mapparr_renamed_YYYYMMDD_HHMMSS.csv`
317121
* **Plugin Files**:
318-
* `/data/plugins/stream_mapparr/plugin.py`
319-
* `/data/plugins/stream_mapparr/networks.json`
320-
* `/data/plugins/stream_mapparr/channels.txt`
122+
* `/data/plugins/channel_mapparr/plugin.py`
123+
* `/data/plugins/channel_mapparr/networks.json`
124+
* `/data/plugins/channel_mapparr/channels.txt`
321125

322126
## CSV Export Format
323127

@@ -365,48 +169,54 @@ The plugin uses Dispatcharr's logo manager **display names** (not filenames):
365169
### Debugging Commands
366170
```bash
367171
# Check plugin files
368-
docker exec dispatcharr ls -la /data/plugins/stream_mapparr/
172+
docker exec dispatcharr ls -la /data/plugins/channel_mapparr/
369173

370174
# Monitor plugin activity
371-
docker logs dispatcharr | grep -i stream_mapparr
175+
docker logs dispatcharr | grep -i channel_mapparr
372176

373177
# View processing cache
374-
docker exec dispatcharr cat /data/stream_mapparr_loaded_channels.json
178+
docker exec dispatcharr cat /data/channel_mapparr_loaded_channels.json
179+
```
375180

376181
## Data Sources
377-
networks.json Format
182+
183+
### `networks.json` Format
378184
An FCC broadcast station database with fields:
379-
callsign: Station identifier (e.g., KABC-TV)
380-
community_served_city: City name
381-
community_served_state: Two-letter state code
382-
network_affiliation: Network name(s)
383-
tv_virtual_channel: Virtual channel number
384-
facility_id: FCC facility identifier
385-
386-
### channels.txt Format
185+
* `callsign`: Station identifier (e.g., KABC-TV)
186+
* `community_served_city`: City name
187+
* `community_served_state`: Two-letter state code
188+
* `network_affiliation`: Network name(s)
189+
* `tv_virtual_channel`: Virtual channel number
190+
* `facility_id`: FCC facility identifier
191+
192+
### `channels.txt` Format
387193
A plain text file with one channel name per line:
388194
HBO
389195
HBO2
390196
Cinemax
391197
5StarMax
392198
MovieMax
393199

394-
395200
## Performance Notes
396-
Matching is sequential, not parallel.
397-
Pagination support for large logo collections (2500+ logos).
398-
API bulk operations for efficient channel updates.
399-
Automatic M3U refresh triggers GUI updates.
201+
* Matching is sequential, not parallel.
202+
* Pagination support for large logo collections (2500+ logos).
203+
* API bulk operations for efficient channel updates.
204+
* Automatic M3U refresh triggers GUI updates.
205+
206+
## Version History
207+
**v0.1 (Initial Release)**
208+
* Dual database matching (OTA + premium/cable).
209+
* Customizable OTA name formatting.
210+
* Fuzzy matching with regional/quality tag preservation.
211+
* Logo management integration.
212+
* CSV export with database source tracking.
400213

401214
## Contributing
402215
When reporting issues, please include:
403-
Dispatcharr version
404-
Sample channel names that fail to match
405-
Relevant container logs
406-
Contents of the preview CSV (first 10 rows)
216+
* Dispatcharr version
217+
* Sample channel names that fail to match
218+
* Relevant container logs
219+
* Contents of the preview CSV (first 10 rows)
407220

408221
## License
409222
This plugin integrates with Dispatcharr's plugin system and follows its licensing terms.
410-
411-
# View processing cache
412-
docker exec dispatcharr cat /data/stream_mapparr_loaded_channels.json

0 commit comments

Comments
 (0)