Skip to content

Commit 56e0f41

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

1 file changed

Lines changed: 240 additions & 40 deletions

File tree

‎README.md‎

Lines changed: 240 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
1-
# Channel Mapparr
1+
# Stream 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.
7-
* **Intelligent Fuzzy Matching**: Handles channel name variations, regional indicators (East/West), quality tags (`[HD]`/`[FHD]`/`[SD]`), and country suffixes.
7+
* **Intelligent Fuzzy Matching**: Handles channel name variations, regional indicators (East/West), quality tags, and country suffixes.
8+
* **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.
10+
* **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.
812
* **Logo Management**: Bulk apply default logos to channels without artwork.
913
* **CSV Export**: Preview changes before applying with detailed dry-run reports.
1014
* **Group Filtering**: Target specific channel groups or process all channels.
@@ -16,6 +20,18 @@ A Dispatcharr plugin that standardizes US broadcast (OTA) and premium/cable chan
1620
* `networks.json` file (FCC broadcast station database) - included
1721
* `channels.txt` file (premium/cable channel list) - included
1822

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+
1935
## Installation
2036
1. Log in to Dispatcharr's web UI.
2137
2. Navigate to **Plugins**.
@@ -31,6 +47,7 @@ A Dispatcharr plugin that standardizes US broadcast (OTA) and premium/cable chan
3147
| **Dispatcharr Admin Password**| `password`| - | Password for API authentication. |
3248
| **Channel Groups** | `string` | - | Comma-separated group names, empty = all groups. |
3349
| **OTA Channel Name Format** | `string` | `{NETWORK} - {STATE} {CITY} ({CALLSIGN})` | Format template for OTA channels. Available tags: `{NETWORK}`, `{STATE}`, `{CITY}`, `{CALLSIGN}`. |
50+
| **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 `()`). |
3451
| **Suffix for Unknown Channels**| `string` | ` [Unk]` | Suffix to append to unmatched channels (OTA and premium/cable). |
3552
| **Default Logo** | `string` | - | Logo display name from Dispatcharr's logo manager to apply to channels without logos. |
3653

@@ -48,11 +65,11 @@ A Dispatcharr plugin that standardizes US broadcast (OTA) and premium/cable chan
4865
* Review the summary showing OTA vs. premium/cable matches.
4966
3. **Preview Changes (Dry Run)**
5067
* Click **Run** on `Preview Changes (Dry Run)`.
51-
* Exports a CSV to `/data/exports/channel_mapparr_preview_YYYYMMDD_HHMMSS.csv`.
68+
* Exports a CSV to `/data/exports/stream_mapparr_preview_YYYYMMDD_HHMMSS.csv`.
5269
* Review proposed changes with database source indicators.
5370
4. **Apply Changes**
5471
* Click **Run** on `Rename Channels` to standardize names.
55-
* A rename report is saved to `/data/exports/channel_mapparr_renamed_YYYYMMDD_HHMMSS.csv`.
72+
* A rename report is saved to `/data/exports/stream_mapparr_renamed_YYYYMMDD_HHMMSS.csv`.
5673
* Optionally run `Add Suffix to Unknown Channels` for unmatched channels.
5774
5. **Apply Logos (Optional)**
5875
* Configure **Default Logo** with a display name from the logo manager.
@@ -75,7 +92,7 @@ A Dispatcharr plugin that standardizes US broadcast (OTA) and premium/cable chan
7592
* Preserves quality tags: `[HD]`, `[FHD]`, `[SD]`, `[Slow]`.
7693
* Preserves extra tags: `(CX)`, `(USA)`, etc.
7794
* Removes "USA" suffix except for "USA Network".
78-
* Ignores bracketed content and quality indicators during matching.
95+
* Removes content from the **Ignored Tags** list during matching.
7996

8097
## Example Transformations
8198

@@ -105,13 +122,13 @@ A Dispatcharr plugin that standardizes US broadcast (OTA) and premium/cable chan
105122
| **Apply Default Logos** | Bulk assign a logo to channels without artwork. |
106123

107124
## File Locations
108-
* **Processing Cache**: `/data/channel_mapparr_loaded_channels.json`
109-
* **Preview Export**: `/data/exports/channel_mapparr_preview_YYYYMMDD_HHMMSS.csv`
110-
* **Rename Report**: `/data/exports/channel_mapparr_renamed_YYYYMMDD_HHMMSS.csv`
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`
111128
* **Plugin Files**:
112-
* `/data/plugins/channel_mapparr/plugin.py`
113-
* `/data/plugins/channel_mapparr/networks.json`
114-
* `/data/plugins/channel_mapparr/channels.txt`
129+
* `/data/plugins/stream_mapparr/plugin.py`
130+
* `/data/plugins/stream_mapparr/networks.json`
131+
* `/data/plugins/stream_mapparr/channels.txt`
115132

116133
## CSV Export Format
117134

@@ -159,54 +176,237 @@ The plugin uses Dispatcharr's logo manager **display names** (not filenames):
159176
### Debugging Commands
160177
```bash
161178
# Check plugin files
162-
docker exec dispatcharr ls -la /data/plugins/channel_mapparr/
179+
docker exec dispatcharr ls -la /data/plugins/stream_mapparr/
163180

164181
# Monitor plugin activity
165-
docker logs dispatcharr | grep -i channel_mapparr
182+
docker logs dispatcharr | grep -i stream_mapparr
166183

167184
# View processing cache
168-
docker exec dispatcharr cat /data/channel_mapparr_loaded_channels.json
185+
docker exec dispatcharr cat /data/stream_mapparr_loaded_channels.json
169186
```
170187

171-
## Data Sources
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]`
295+
<br>
296+
* **Before:** `Cinemax Moviemax East [SD]`
297+
* **After:** `MovieMax (East) [SD]`
298+
<br>
299+
* **Before:** `5 Star Max USA [FHD]`
300+
* **After:** `5StarMax [FHD]`
301+
302+
## Action Reference
303+
304+
### Core Actions
305+
| Action | Description |
306+
| :--- | :--- |
307+
| **Load/Process Channels** | Load channels from groups and match against databases. |
308+
| **Preview Changes (Dry Run)** | Export a CSV showing proposed renames with database sources. |
309+
| **Rename Channels** | Apply standardized names to matched channels. |
310+
| **Add Suffix to Unknown Channels**| Tag unmatched channels with the configured suffix. |
311+
| **Apply Default Logos** | Bulk assign a logo to channels without artwork. |
312+
313+
## 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`
317+
* **Plugin Files**:
318+
* `/data/plugins/stream_mapparr/plugin.py`
319+
* `/data/plugins/stream_mapparr/networks.json`
320+
* `/data/plugins/stream_mapparr/channels.txt`
321+
322+
## CSV Export Format
323+
324+
| Column | Description |
325+
| :--- | :--- |
326+
| **channel_id** | Internal Dispatcharr channel ID. |
327+
| **channel_number** | Channel number. |
328+
| **channel_group** | Current group name. |
329+
| **current_name** | Original channel name. |
330+
| **new_name** | Proposed/applied name. |
331+
| **status** | `Renamed` or `Skipped`. |
332+
| **dbase** | Database used: `networks.json`, `channels.txt`, or `none`. |
333+
| **reason** | Skip reason if applicable. |
334+
335+
## Logo Management
336+
The plugin uses Dispatcharr's logo manager **display names** (not filenames):
172337

173-
### `networks.json` Format
338+
1. Navigate to **Logos** in the Dispatcharr UI.
339+
2. Find your desired default logo.
340+
3. Copy the **display name** (e.g., `abc-logo-2013-garnet-us`).
341+
4. Enter it in the plugin's **Default Logo** setting.
342+
5. Run the **Apply Default Logos** action.
343+
344+
**Note:** Logos are only applied to channels that either have no logo or use the "Default" logo (ID 0).
345+
346+
## Troubleshooting
347+
348+
### Common Issues
349+
* **"Logo not found in logo manager"**
350+
* Use the logo's **display name** from Dispatcharr's Logos page, not the filename.
351+
* Check logs for available logo names (the first 30 are listed).
352+
* Ensure the logo has been uploaded to Dispatcharr.
353+
* **"No suffix configured"**
354+
* If the default value is not working, manually enter ` [Unk]` (with a leading space) in settings.
355+
* Save settings before running actions.
356+
* **"No groups found"**
357+
* Verify channel groups exist in Dispatcharr.
358+
* Check that group names are spelled correctly (case-sensitive).
359+
* Leave the field empty to process all groups.
360+
* **Channels not matching**
361+
* Verify `networks.json` and `channels.txt` are in the plugin directory.
362+
* Check logs for callsign extraction and matching attempts.
363+
* Use the **Preview** export to see which database was attempted.
364+
365+
### Debugging Commands
366+
```bash
367+
# Check plugin files
368+
docker exec dispatcharr ls -la /data/plugins/stream_mapparr/
369+
370+
# Monitor plugin activity
371+
docker logs dispatcharr | grep -i stream_mapparr
372+
373+
# View processing cache
374+
docker exec dispatcharr cat /data/stream_mapparr_loaded_channels.json
375+
376+
## Data Sources
377+
networks.json Format
174378
An FCC broadcast station database with fields:
175-
* `callsign`: Station identifier (e.g., KABC-TV)
176-
* `community_served_city`: City name
177-
* `community_served_state`: Two-letter state code
178-
* `network_affiliation`: Network name(s)
179-
* `tv_virtual_channel`: Virtual channel number
180-
* `facility_id`: FCC facility identifier
181-
182-
### `channels.txt` Format
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
183387
A plain text file with one channel name per line:
184388
HBO
185389
HBO2
186390
Cinemax
187391
5StarMax
188392
MovieMax
189393

394+
190395
## Performance Notes
191-
* Matching is sequential, not parallel.
192-
* Pagination support for large logo collections (2500+ logos).
193-
* API bulk operations for efficient channel updates.
194-
* Automatic M3U refresh triggers GUI updates.
195-
196-
## Version History
197-
**v0.1 (Initial Release)**
198-
* Dual database matching (OTA + premium/cable).
199-
* Customizable OTA name formatting.
200-
* Fuzzy matching with regional/quality tag preservation.
201-
* Logo management integration.
202-
* CSV export with database source tracking.
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.
203400

204401
## Contributing
205402
When reporting issues, please include:
206-
* Dispatcharr version
207-
* Sample channel names that fail to match
208-
* Relevant container logs
209-
* Contents of the preview CSV (first 10 rows)
403+
Dispatcharr version
404+
Sample channel names that fail to match
405+
Relevant container logs
406+
Contents of the preview CSV (first 10 rows)
210407

211408
## License
212409
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)