From d17b1388186d409e8c2269ed3ac960450ea493cd Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:29:44 -0700 Subject: [PATCH 01/13] Add Jellyfin EPG troubleshooting documentation Addresses issue #583 where users reported EPG data not appearing in Jellyfin. The root cause is that Jellyfin prefers descriptive channel IDs (like "BBC1.uk") rather than numeric IDs. - Add new troubleshooting section explaining TVG-ID format requirements - Add tip to Jellyfin setup in getting-started.md linking to troubleshooting - Document the ?tvg_id_source=tvg_id URL parameter workaround Co-Authored-By: Claude Opus 4.5 --- docs/en/getting-started.md | 7 +++++++ docs/en/troubleshooting.md | 17 +++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/docs/en/getting-started.md b/docs/en/getting-started.md index 2a00081..62187e3 100644 --- a/docs/en/getting-started.md +++ b/docs/en/getting-started.md @@ -94,6 +94,13 @@ Create your user account by entering a username and password that you will remem - Choose 'XMLTV' and paste the URL - EPG data will be automatically mapped. +!!! tip "EPG not showing in Jellyfin?" + Jellyfin is particular about channel ID formats. If your guide data isn't appearing: + + 1. Try adding `?tvg_id_source=tvg_id` to your EPG URL + 2. Ensure your channels have proper TVG-IDs set (not just channel numbers) + 3. See [Troubleshooting: Jellyfin EPG](/Dispatcharr-Docs/troubleshooting/#jellyfin-epg-not-importing-or-shows-no-guide-data) for more details. + --- #### Plex diff --git a/docs/en/troubleshooting.md b/docs/en/troubleshooting.md index aefaec4..fd5797d 100644 --- a/docs/en/troubleshooting.md +++ b/docs/en/troubleshooting.md @@ -114,6 +114,23 @@ Additionally, if multiple network interfaces are available, you should add `?loc --- +## Jellyfin EPG not importing or shows "No guide data" + +Jellyfin requires the EPG channel ID to match a specific format. If your EPG data isn't appearing: + +1. **Check the TVG-ID format**: Jellyfin prefers descriptive channel IDs like `BBC1.uk` rather than numeric IDs like `1` +2. In Dispatcharr, go to Channels and set the **TVG-ID Source** to use TVG-ID instead of channel number +3. Alternatively, add `?tvg_id_source=tvg_id` to your EPG URL: + ``` + http://your-dispatcharr:9191/output/epg?tvg_id_source=tvg_id + ``` +4. Refresh your guide data in Jellyfin after making changes + +!!! tip + If channels have no tvg-id set, Dispatcharr will use the channel number by default. Ensure your channels have proper TVG-IDs assigned for best Jellyfin compatibility. + +--- + ## How do I remove all VOD from dispatcharr? 1. In the [M3U & EPG manager](/Dispatcharr-Docs/user-guide/#m3u-epg-manager) page, click the edit icon for any account that provides VOD (only XC account types can provide it) 2. Toggle `Enable VOD Scanning` on From dc059dff4811625d4cc21df88b1186bdec92bf11 Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:30:18 -0700 Subject: [PATCH 02/13] Clarify that M3U Profiles are not for stream failover Addresses issue #710 where users expected M3U Profiles to provide automatic failover between streams when one fails. This is a common misconception. - Add warning box to M3U Profiles section clarifying their purpose - Explain profiles are for connection pooling across multiple accounts - Direct users to Fallback Streams feature for actual failover needs Co-Authored-By: Claude Opus 4.5 --- docs/en/user-guide.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/en/user-guide.md b/docs/en/user-guide.md index 2694ca7..2f3ad03 100644 --- a/docs/en/user-guide.md +++ b/docs/en/user-guide.md @@ -158,7 +158,14 @@ From this page you can add and maintain your M3U accounts and EPGs | Example URL | Search Pattern | Replace Pattern | | --- | --- | --- | | `http://provider.com/live/username1/password1/stream` | `username1/password1` | `username2/password2` | - + + !!! warning "M3U Profiles are NOT for stream failover" + M3U Profiles are designed for managing **multiple accounts from the same provider** to increase your total connection limit. They are NOT used for automatic failover between streams. + + **For stream failover**: Add multiple streams to a single channel. Dispatcharr will automatically switch to the next stream if the current one fails. See [Fallback Streams](/Dispatcharr-Docs/user-guide/#fallback-streams) for details. + + **For connection pooling**: Use M3U Profiles when you have multiple logins for the same provider and want Dispatcharr to use them as a combined pool of connections. + * delete icon to remove the associated M3U account * refresh icon to manually refresh/update the associated M3U account From ef1592ad841388e2f9dbefa47b1882bc18450ce8 Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:30:51 -0700 Subject: [PATCH 03/13] Document workaround for multiple Dispatcharr instances in Plex Addresses issue #734 where users running multiple Dispatcharr instances (e.g., one with VPN) found that Plex hangs when trying to add the second tuner due to device ID conflicts. - Recommend using Channel Profiles as the primary solution - Document M3U-as-source workaround for those who need separate instances - Link to Channel Profiles documentation for setup details Co-Authored-By: Claude Opus 4.5 --- docs/en/troubleshooting.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/en/troubleshooting.md b/docs/en/troubleshooting.md index fd5797d..e091725 100644 --- a/docs/en/troubleshooting.md +++ b/docs/en/troubleshooting.md @@ -131,6 +131,27 @@ Jellyfin requires the EPG channel ID to match a specific format. If your EPG dat --- +## Adding multiple Dispatcharr instances to Plex + +Plex identifies tuners by their device ID. If you're running multiple Dispatcharr instances (e.g., one with VPN, one without), Plex may have trouble distinguishing them or hang during tuner setup. + +**Recommended Solution**: Use Channel Profiles instead of multiple Dispatcharr instances + +1. In Dispatcharr, go to the Channels page +2. Create a new Channel Profile for each "virtual tuner" you need +3. Add each Channel Profile to Plex as a separate HDHR device +4. Each profile generates its own unique HDHR, M3U, and EPG URLs + +**Alternative workaround**: If you must use multiple instances: + +1. Use the M3U output from one instance as an M3U source in the other +2. Add only one instance directly to Plex via HDHR +3. The consolidated instance will contain channels from both + +See [Channel Profiles](/Dispatcharr-Docs/user-guide/#channels) for more details on setting up profiles. + +--- + ## How do I remove all VOD from dispatcharr? 1. In the [M3U & EPG manager](/Dispatcharr-Docs/user-guide/#m3u-epg-manager) page, click the edit icon for any account that provides VOD (only XC account types can provide it) 2. Toggle `Enable VOD Scanning` on From cf65e35d4f97d9c9c4a85e151f4640c3e76f3dfd Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:31:18 -0700 Subject: [PATCH 04/13] Document reverse proxy config for Xtream Codes apps Addresses issue #839 where users found that IPTV apps using the Xtream Codes API (IPTV Smarters, TiviMate, etc.) fail when accessing Dispatcharr through a reverse proxy from outside the local network. - Explain that XC apps use /live/username/password/ URL paths - Provide nginx configuration snippet for the /live/ endpoint - List common symptoms to help users identify this issue - Link to existing reverse proxy documentation Co-Authored-By: Claude Opus 4.5 --- docs/en/troubleshooting.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/en/troubleshooting.md b/docs/en/troubleshooting.md index e091725..b7f3b0e 100644 --- a/docs/en/troubleshooting.md +++ b/docs/en/troubleshooting.md @@ -152,6 +152,39 @@ See [Channel Profiles](/Dispatcharr-Docs/user-guide/#channels) for more details --- +## Xtream Codes apps not working through reverse proxy + +Some IPTV apps using Xtream Codes API (like IPTV Smarters, TiviMate) may fail when accessing Dispatcharr through a reverse proxy, especially from outside your network. + +**Symptoms**: + +* App works on local network but fails remotely +* Login works but channels don't play +* Streams timeout or show connection errors + +**Cause**: These apps construct URLs using `/live/username/password/` paths that your reverse proxy may not be forwarding. + +**Solution**: Update your nginx configuration to include the `/live/` endpoint: + +```nginx +location /live/ { + proxy_pass http://dispatcharr:9191/live/; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Port $server_port; +} +``` + +Make sure you also have the standard proxy location blocks for `/`, `/api/`, `/proxy/`, etc. + +!!! note + The example nginx config in the [Reverse Proxies](/Dispatcharr-Docs/user-guide/#reverse-proxies) section should work for most setups. If you've customized it, ensure all required endpoints are being proxied. + +--- + ## How do I remove all VOD from dispatcharr? 1. In the [M3U & EPG manager](/Dispatcharr-Docs/user-guide/#m3u-epg-manager) page, click the edit icon for any account that provides VOD (only XC account types can provide it) 2. Toggle `Enable VOD Scanning` on From 19bfaba806388de594a67fc187da9c494564c7f5 Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:50:34 -0700 Subject: [PATCH 05/13] Add issue reference to Jellyfin EPG documentation (#583) Link the Jellyfin EPG troubleshooting section and getting-started tip back to the original issue for additional context. Co-Authored-By: Claude Opus 4.5 --- docs/en/getting-started.md | 2 ++ docs/en/troubleshooting.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/en/getting-started.md b/docs/en/getting-started.md index 62187e3..2a18e75 100644 --- a/docs/en/getting-started.md +++ b/docs/en/getting-started.md @@ -101,6 +101,8 @@ Create your user account by entering a username and password that you will remem 2. Ensure your channels have proper TVG-IDs set (not just channel numbers) 3. See [Troubleshooting: Jellyfin EPG](/Dispatcharr-Docs/troubleshooting/#jellyfin-epg-not-importing-or-shows-no-guide-data) for more details. + *Related: [#583](https://github.com/Dispatcharr/Dispatcharr/issues/583)* + --- #### Plex diff --git a/docs/en/troubleshooting.md b/docs/en/troubleshooting.md index b7f3b0e..536141d 100644 --- a/docs/en/troubleshooting.md +++ b/docs/en/troubleshooting.md @@ -129,6 +129,8 @@ Jellyfin requires the EPG channel ID to match a specific format. If your EPG dat !!! tip If channels have no tvg-id set, Dispatcharr will use the channel number by default. Ensure your channels have proper TVG-IDs assigned for best Jellyfin compatibility. +*Related: [#583](https://github.com/Dispatcharr/Dispatcharr/issues/583)* + --- ## Adding multiple Dispatcharr instances to Plex From 038578543cfe705959244758ad997f14ec4996c9 Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:50:47 -0700 Subject: [PATCH 06/13] Add issue reference to M3U Profiles documentation (#710) Link the M3U Profiles failover clarification back to the original issue where users were confused about profiles vs stream failover. Co-Authored-By: Claude Opus 4.5 --- docs/en/user-guide.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/en/user-guide.md b/docs/en/user-guide.md index 2f3ad03..f595c8f 100644 --- a/docs/en/user-guide.md +++ b/docs/en/user-guide.md @@ -166,6 +166,8 @@ From this page you can add and maintain your M3U accounts and EPGs **For connection pooling**: Use M3U Profiles when you have multiple logins for the same provider and want Dispatcharr to use them as a combined pool of connections. + *Related: [#710](https://github.com/Dispatcharr/Dispatcharr/issues/710)* + * delete icon to remove the associated M3U account * refresh icon to manually refresh/update the associated M3U account From b3a974f8ab1422bbd60e50421ded20c7b7802d9b Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:50:56 -0700 Subject: [PATCH 07/13] Add issue reference to multiple Plex instances documentation (#734) Link the multiple Dispatcharr instances troubleshooting back to the original issue about Plex hanging when adding a second tuner. Co-Authored-By: Claude Opus 4.5 --- docs/en/troubleshooting.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/en/troubleshooting.md b/docs/en/troubleshooting.md index 536141d..4555865 100644 --- a/docs/en/troubleshooting.md +++ b/docs/en/troubleshooting.md @@ -152,6 +152,8 @@ Plex identifies tuners by their device ID. If you're running multiple Dispatchar See [Channel Profiles](/Dispatcharr-Docs/user-guide/#channels) for more details on setting up profiles. +*Related: [#734](https://github.com/Dispatcharr/Dispatcharr/issues/734)* + --- ## Xtream Codes apps not working through reverse proxy From a9de261dcbdba25c170ba188ac69e9c985f0dc85 Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:51:06 -0700 Subject: [PATCH 08/13] Add issue reference to XC reverse proxy documentation (#839) Link the Xtream Codes reverse proxy troubleshooting back to the original issue about apps not working through nginx. Co-Authored-By: Claude Opus 4.5 --- docs/en/troubleshooting.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/en/troubleshooting.md b/docs/en/troubleshooting.md index 4555865..2a3a207 100644 --- a/docs/en/troubleshooting.md +++ b/docs/en/troubleshooting.md @@ -187,6 +187,8 @@ Make sure you also have the standard proxy location blocks for `/`, `/api/`, `/p !!! note The example nginx config in the [Reverse Proxies](/Dispatcharr-Docs/user-guide/#reverse-proxies) section should work for most setups. If you've customized it, ensure all required endpoints are being proxied. +*Related: [#839](https://github.com/Dispatcharr/Dispatcharr/issues/839)* + --- ## How do I remove all VOD from dispatcharr? From 9ea8094cfcfb4fcc8afd7f5a287a23e8a3e7cf66 Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:51:18 -0700 Subject: [PATCH 09/13] Add note about Jellyfin categories passing through automatically (#538) Document that EPG categories (Sports, News, etc.) are automatically passed through to Jellyfin if the source EPG includes them - no special configuration needed. Co-Authored-By: Claude Opus 4.5 --- docs/en/troubleshooting.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/en/troubleshooting.md b/docs/en/troubleshooting.md index 2a3a207..71e042e 100644 --- a/docs/en/troubleshooting.md +++ b/docs/en/troubleshooting.md @@ -131,6 +131,9 @@ Jellyfin requires the EPG channel ID to match a specific format. If your EPG dat *Related: [#583](https://github.com/Dispatcharr/Dispatcharr/issues/583)* +!!! note "Jellyfin categories" + Jellyfin categories (Sports, News, Movies, etc.) are passed through automatically if your source EPG includes them—no special configuration is needed in Dispatcharr. ([#538](https://github.com/Dispatcharr/Dispatcharr/issues/538)) + --- ## Adding multiple Dispatcharr instances to Plex From 1ed58ba15d9bee7c530957fd6ae47aa7bd5430c7 Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:51:35 -0700 Subject: [PATCH 10/13] Add EPG off-by-one troubleshooting section (#563) Document the common issue where EPG shows wrong data in clients due to overlapping channel numbers when using Auto Channel Sync. Explains the cause and provides solution for setting unique starting channel numbers per group. Co-Authored-By: Claude Opus 4.5 --- docs/en/troubleshooting.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/en/troubleshooting.md b/docs/en/troubleshooting.md index 71e042e..b2572d3 100644 --- a/docs/en/troubleshooting.md +++ b/docs/en/troubleshooting.md @@ -194,6 +194,26 @@ Make sure you also have the standard proxy location blocks for `/`, `/api/`, `/p --- +## EPG shows wrong data or is "off-by-one" + +If your EPG data appears correct in Dispatcharr but shows the wrong programs in your client (e.g., displaying data from a different channel), this is usually caused by **overlapping channel numbers**. + +**Cause**: When using Auto Channel Sync, the default starting channel number is 1 for all groups. If multiple groups start at 1, channels will have duplicate numbers, confusing clients when matching EPG data. + +**Solution**: + +1. Go to M3U & EPG Manager +2. Edit your M3U account and click "Groups" +3. For each group using Auto Channel Sync, set a unique **Start Channel #** (e.g., Group A starts at 1, Group B at 100, Group C at 200) +4. Save and refresh + +!!! tip + Plan your channel number ranges ahead of time to avoid overlaps. For example, allocate 1-99 for local channels, 100-199 for sports, 200-299 for movies, etc. + +*Related: [#563](https://github.com/Dispatcharr/Dispatcharr/issues/563)* + +--- + ## How do I remove all VOD from dispatcharr? 1. In the [M3U & EPG manager](/Dispatcharr-Docs/user-guide/#m3u-epg-manager) page, click the edit icon for any account that provides VOD (only XC account types can provide it) 2. Toggle `Enable VOD Scanning` on From f07f7de9a6fb3ac9a1d079460c5216b6e20a94d6 Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:51:48 -0700 Subject: [PATCH 11/13] Add Plex VOD limitation note (#470) Document that Plex does not support Video on Demand from Dispatcharr, directing users to Jellyfin or XC-compatible apps for VOD needs. Co-Authored-By: Claude Opus 4.5 --- docs/en/getting-started.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/en/getting-started.md b/docs/en/getting-started.md index 2a18e75..47cf953 100644 --- a/docs/en/getting-started.md +++ b/docs/en/getting-started.md @@ -129,8 +129,11 @@ Create your user account by entering a username and password that you will remem ![Map EPG Plex](assets/map_epg_plex.png){style="height:70vmin"} - Press `Continue` and plex will now load in the channels and EPG data !!! note "Missing logos?" - Add `?cachedlogos=false` to the end of your EPG to bypass logo caching which Plex does not currently support. - + Add `?cachedlogos=false` to the end of your EPG to bypass logo caching which Plex does not currently support. + +!!! warning "Plex does not support VOD" + Plex does not support Video on Demand content from Dispatcharr. If you need VOD, use Jellyfin or an Xtream Codes-compatible app instead. ([#470](https://github.com/Dispatcharr/Dispatcharr/issues/470)) + --- #### ChannelsDVR From 6378b9d6ee8ad6df183e76732a350f39f2cee8df Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:52:00 -0700 Subject: [PATCH 12/13] Add Plex single EPG source limitation (#633) Document that Plex can only use one EPG source at a time (zipcode OTA or XMLTV, not both). Users with both HDHomeRun and IPTV need to provide all EPG data through Dispatcharr. Co-Authored-By: Claude Opus 4.5 --- docs/en/getting-started.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/en/getting-started.md b/docs/en/getting-started.md index 47cf953..48aa83a 100644 --- a/docs/en/getting-started.md +++ b/docs/en/getting-started.md @@ -134,6 +134,9 @@ Create your user account by entering a username and password that you will remem !!! warning "Plex does not support VOD" Plex does not support Video on Demand content from Dispatcharr. If you need VOD, use Jellyfin or an Xtream Codes-compatible app instead. ([#470](https://github.com/Dispatcharr/Dispatcharr/issues/470)) +!!! warning "Plex only supports one EPG source" + Plex can only use one EPG source—either the built-in zipcode-based OTA guide OR an XMLTV file, not both simultaneously. If you have both HDHomeRun OTA channels and IPTV channels, you'll need to provide all EPG data via Dispatcharr's XMLTV output. ([#633](https://github.com/Dispatcharr/Dispatcharr/issues/633)) + --- #### ChannelsDVR From 09e63521bcbe97ca5ae66bf86b93e9b789a8f665 Mon Sep 17 00:00:00 2001 From: Jeff Casimir Date: Sat, 31 Jan 2026 15:52:12 -0700 Subject: [PATCH 13/13] Add Plex/Tunarr conflict warning (#344) Document that users combining Tunarr with Dispatcharr must disable Tunarr's auto-update settings to prevent Plex from losing channel matching. Co-Authored-By: Claude Opus 4.5 --- docs/en/getting-started.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/en/getting-started.md b/docs/en/getting-started.md index 48aa83a..ee1b8b7 100644 --- a/docs/en/getting-started.md +++ b/docs/en/getting-started.md @@ -137,6 +137,9 @@ Create your user account by entering a username and password that you will remem !!! warning "Plex only supports one EPG source" Plex can only use one EPG source—either the built-in zipcode-based OTA guide OR an XMLTV file, not both simultaneously. If you have both HDHomeRun OTA channels and IPTV channels, you'll need to provide all EPG data via Dispatcharr's XMLTV output. ([#633](https://github.com/Dispatcharr/Dispatcharr/issues/633)) +!!! warning "Using Tunarr with Dispatcharr?" + If you use Tunarr alongside Dispatcharr, you must disable "Auto-Update Guide" and "Auto-Update Channels" in Tunarr's Plex source settings. Otherwise, Plex will periodically lose channel matching. ([#344](https://github.com/Dispatcharr/Dispatcharr/issues/344)) + --- #### ChannelsDVR