Settings

The Settings view is the configuration hub for WSDashboard. From here you connect your media servers, manage Live TV across Emby, Jellyfin, and Plex, and tune the behavior of cover art, pause rules, analytics, and transcode cleanup. Settings opens as a flyout panel over the Streaming Dashboard, alongside the Watch Analytics and Activity Logs panels.

Admin only

The Settings view requires administrator privileges and the wsdashboard feature flag enabled in Settings > General > Feature Flags. Regular dashboard users cannot see or change any streaming settings.

What you can configure

Connection Settings

Connect Emby, Jellyfin, and Plex — server URL, access token, and a connection test for each

Live TV Sources (Emby & Jellyfin)

Map Emby and Jellyfin tuner hosts to friendly, color-coded source labels that appear on Live TV sessions

Plex Tuners

View and manage Plex tuner devices classified as active, staged, or orphaned — rename, enable, disable, and remove them

Dispatcharr Live TV Guide

Manage your Dispatcharr connections as guide and Live TV sources for Emby, Jellyfin, and Plex, repair the Plex channel map, and scan for duplicate guide IDs

IPTVBoss Live TV Guide

Add Now / Next / Upcoming programme data to Live TV channel pages, read from your IPTVBoss XMLTV export

Cover Art Providers

Choose between TMDB and TheTVDB artwork with per-category routing, or fall back to native server images

Pause Rules

Automate warnings or stops for idle streams after configurable pause durations

Transcode Cleanup

Automatically purge stale transcode files to reclaim disk space, with safety limits

Connection Settings

Connection Settings is where you tell WSDashboard how to reach each media server. There is one card per server type — Emby, Jellyfin, and Plex — and you can configure all three at once. Each card has the same three controls:

Field	Description
Server URL	The address WSDashboard uses to reach the server on this machine — typically `http://127.0.0.1:8096` for Emby/Jellyfin or `http://127.0.0.1:32400` for Plex
Access token	An API key (Emby/Jellyfin) or `X-Plex-Token` (Plex) that authorizes WSDashboard to read sessions and library data. Tokens are stored securely and are never shown back in full
Test	Verifies the URL and token before you save, so you can confirm the connection works rather than discovering a typo later

After entering a URL and token, click Test to verify the connection, then Save. Once a server is connected, its sessions and library appear throughout WSDashboard.

Plex is often configured automatically

If you install Plex with a claim token (qb install plex -u username -pct '…'), WSDashboard detects the server URL and extracts the X-Plex-Token for you, so the Plex card is already filled in. See the Plex WSDashboard Integration section for manual token setup.

Live TV management

WSDashboard gives you Live TV management for all three media servers, with two cards on the Settings page that reflect how each platform models Live TV:

Live TV Sources — for Emby and Jellyfin, which expose their tuner hosts through a common /LiveTv/TunerHosts interface. You map those tuner hosts to friendly, color-coded labels.
Plex Tuners — for Plex, which models Live TV as DVRs and grabber devices instead of tuner hosts. You manage those devices directly (state, capacity, usage, rename, enable/disable, remove).

The two cards exist because the platforms expose Live TV differently — not because one is favored over another. Each card appears only when at least one matching server is configured.

Live TV Sources (Emby & Jellyfin)

The Live TV Sources card maps Live TV tuner hosts on your Emby and Jellyfin servers to friendly source labels. When a viewer tunes a channel served by a mapped tuner, WSDashboard shows that label as a color-coded badge on the session — so you can tell at a glance whether a stream is coming from your antenna, an IPTV provider, a specific HDHomeRun, and so on.

Expand the card to see your configured sources. Each source row shows its color dot, label, the number of tuner hosts it maps, the server type, and a LIVE indicator when one of its tuners is actively streaming.

Creating a source label mapping

Click Add Source to open the inline form. A mapping has the following fields:

Field	Description
Label	The friendly name shown as a badge on matching Live TV sessions — for example `Antenna`, `Cable`, or `HDHomeRun`
Server Type	Scope the mapping to `Emby`, `Jellyfin`, or `All Servers`. Choosing a server type filters the tuner host list to that server
Badge Color	An optional color for the badge, so different sources are easy to distinguish in the live sessions view
Tuner Hosts	Select one or more tuner hosts to include in this mapping. The list is read live from each server's `/LiveTv/TunerHosts` and groups hosts under Emby and Jellyfin, showing each host's friendly name, URL, and source
Enabled	Toggle the mapping on or off without deleting it

Pick at least one tuner host and enter a label, then click Create Source. Use the Refresh button in the tuner picker to re-read the host list if you have just added a tuner on the server. Existing sources can be edited (pencil) or deleted (trash) from their row.

Tuner hosts come from your Emby/Jellyfin server

The tuner hosts you select are discovered from each media server’s own Live TV configuration. If the picker is empty, add a tuner in Emby or Jellyfin first (Dashboard → Live TV in the server’s own interface), then click Refresh.

What source labels are for

You want to

Tell at a glance which tuner a Live TV stream is using
Distinguish antenna vs IPTV vs a specific HDHomeRun in live sessions
Group several tuner hosts under one human-readable name
Color-code your Live TV sources for quick scanning

Do this

Open Dashboard → Streaming → Settings → Live TV Sources and click Add Source
Give the mapping a clear label and pick the tuner hosts it covers
Assign a distinct badge color so each source stands out
Watch the source badge appear on matching sessions in Live Sessions

Plex Tuners

The Plex Tuners card lists every Plex tuner (grabber device) your server knows about and lets you manage them directly from the dashboard. Plex models Live TV as DVRs and grabber devices rather than tuner hosts, so it has its own card. It appears only when Plex is configured — expand it to load the current tuner list.

This card exists because Plex has no built-in way to clean up unused tuners from a remote interface, and Live TV setups — especially those using Dispatcharr’s HDHomeRun emulation — tend to accumulate leftover and test tuners over time. The Plex Tuners card surfaces them all in one place so you can see what is actually in use and remove what is not.

Tuner states

Every tuner is classified into one of three states, shown as a colored badge:

State	What it means	Typical action
Active (green)	Bound to a working DVR and serving Live TV channels. The row shows the DVR name and channel count	Leave it — this is a tuner in use
Staged (amber)	Registered and reachable, but not yet bound to a DVR — typically a test tuner you set up but never finished wiring in	Bind it in Plex, or remove it if it was a test
Orphaned (red)	Registered but unreachable (dead) — a leftover device that is no longer in use	Safe to remove

Each row also shows a small alive/dead indicator (whether the device currently responds), the device model, and when it was last seen.

Concurrent-stream capacity

A tuner’s number — for example 4 — is the number of simultaneous streams that one tuner can serve, not the number of separate tuner devices. A single Dispatcharr HDHomeRun profile advertising “4” means up to four people can watch Live TV through it at the same time. This is a common point of confusion: one tuner row with a capacity of 4 is not four tuners.

Usage gauge

Each tuner row shows a live usage gauge in the form X / N streams in use, where X is the number of streams currently active on that tuner and N is its concurrent-stream capacity. The gauge updates when you click Refresh. It lets you spot at a glance which tuners are saturated and which are sitting idle — useful for balancing Live TV load or deciding whether a tuner is even being used.

Display name (local rename)

You can give any tuner a friendly display name by clicking the pencil icon on its row, typing a name, and pressing Enter. This is helpful when your tuner titles come from upstream sources (such as an XMLTV lineup name or a Dispatcharr HDHomeRun friendly name) that are not very descriptive.

Display names are a QuickBox-side label only

The display name is stored by QuickBox and overrides the tuner’s title in the dashboard only — it is never pushed back to Plex, because Plex has no API to rename a tuner. When you clear the display name, the row falls back to showing the original Plex title. Hover the renamed tuner to see its original Plex title in a tooltip.

Enable, disable, and remove

Each tuner row has two management actions:

Enable / disable — the toggle switch turns a tuner on or off in Plex without removing it. Disable a tuner to temporarily take it out of service while keeping its configuration.
Remove — the trash icon deletes the tuner device from Plex. This is the way to clean up orphaned and leftover/test tuners.

Removing an active tuner stops its channels

Removing a tuner that is currently active (bound to a DVR) detaches it from that DVR and stops the Live TV channels it serves. The dashboard asks for a stronger confirmation in this case — naming the DVR and channel count — so you do not remove a working tuner by accident. Removing a staged or orphaned tuner uses a standard confirmation.

Removing a tuner is idempotent — if the device has already been removed in Plex, the action still succeeds rather than erroring.

Cleaning up leftover and test tuners

You are seeing this

Multiple Plex tuners listed when you only set up one
A leftover tuner from an old Dispatcharr instance or a test you abandoned
An orphaned (red) tuner that no longer responds
A staged (amber) tuner you never finished binding to a DVR

Do this

Open Dashboard → Streaming → Settings → Plex Tuners and expand the card
Check the alive/dead indicator and state badge to confirm which tuners are unused
Remove orphaned and abandoned test tuners with the trash icon
Leave active tuners alone — they are bound to a working DVR and in use

Dispatcharr Live TV Guide

The Dispatcharr Live TV Guide card manages Dispatcharr as a guide and Live TV source for Emby, Jellyfin, and Plex, and holds the Plex channel-map repair and duplicate guide-ID scan.

Dispatcharr connections

The top of the card is a connections list. Each connection is a Dispatcharr instance that feeds the dashboard’s TV Guide, Live TV session details, and Watch Analytics, for Emby, Jellyfin, and Plex alike. QuickBox builds the list for you:

Detected on this server - every QuickBox Dispatcharr install is found automatically and added as a guide-only connection. No API key is needed for the guide, so these feed the TV Guide and session details out of the box. A row without a key reads Guide only. Add an API key to group this connection’s channels by M3U provider in the TV Guide.
Primary - the admin-seeded Base URL and API key (provisioned at install time) appear as the Primary connection. An API key (Dispatcharr Settings → API Keys) on the Primary connection gives Plex Live TV sessions richer program details, such as season and episode numbers. Without it, Plex sessions are still matched against the Dispatcharr guide.
Added - an admin can add their own connections, including a remote Dispatcharr, up to a total of 8.

Each row has a Label, the Base URL, an optional API key, an enable toggle, and a Test button that reports the EPG, M3U, and API reachability. A connection’s status shows as Connected, Refused, Unreachable, Disabled, or Not checked yet, alongside its channel and programme counts and when it last updated. Click Add connection to add one, Save connections to persist your changes, and Remove to drop one.

A remote Dispatcharr must allow this server

When a connection is Refused, Dispatcharr is rejecting this server. In that Dispatcharr, open Settings > Network Access and add this server’s IP under M3U / EPG Endpoints. A QuickBox Dispatcharr install on the same box is allowed by default and needs no change.

Plex guide tools

Below the connections list, the card keeps two Plex Live TV tools for when your channels come from Dispatcharr: the channel-map repair, the only tool that changes Plex’s own app, and the report-only duplicate guide-ID scan:

Re-sync Plex channel map - repairs Plex’s cached channel map after you renumber channels in Dispatcharr (previews first, backs up before applying)
Check duplicate guide IDs - a report-only scan for channels that share a guide ID

The EPG override has no separate control: it runs from the connections above. Every connection feeds it, and an API key on the Primary connection adds season and episode numbers. It shows the correct channel and program for Plex Live TV sessions in this dashboard and does not change Plex’s own guide.

These tools are Plex-only: Emby and Jellyfin read Dispatcharr’s guide directly and need none of them. They are documented in full on the Dispatcharr page - see Keep Plex’s TV guide correct.

IPTVBoss Live TV Guide

If you run IPTVBoss, the IPTVBoss Live TV Guide card adds a Now / Next / Upcoming TV guide to Live TV channel pages in the Media Portal. The guide is read from the IPTVBoss XMLTV export and works for Emby, Jellyfin, and Plex channels alike, the same three servers the Dispatcharr Live TV Guide card above serves from Dispatcharr.

The card turns on by itself: it becomes active once IPTVBoss is installed and an XMLTV output is enabled in the IPTVBoss editor. A badge at the top of the card tells you where it stands:

Badge	What it means
Active	IPTVBoss is installed and an XMLTV export was found - the guide is live
No export	IPTVBoss is installed, but no XMLTV output is enabled yet in its editor
Not installed	IPTVBoss is not installed on this server

The card has one control and a status line:

Show guide in Media Portal (on by default) - turns the Now / Next / Upcoming panel on Live TV channel pages on or off. It controls only whether the panel is shown; it does not change IPTVBoss itself.
A status line showing how many channels and programmes are in the export and when it last updated, so you can confirm the guide data is fresh.

Enable an XMLTV output in IPTVBoss

A fresh IPTVBoss install has no export until you enable an XMLTV output in the IPTVBoss desktop editor. Until then the card reads No export and channel pages show No guide yet. See the IPTVBoss page for how to reach the editor and enable an output.

Live TV analytics

When a guide source is present, a Live TV analytics card appears below the guide cards. It controls whether the dashboard records what plays on each Live TV channel as programme segments, so individual Live TV programmes show up in Watch Analytics Top Titles and Trending with real per-programme completion. Without it, a Live TV session is one long block with no programme breakdown, so Live TV stays out of those rankings.

The card only appears when at least one guide provider is present: IPTVBoss installed, or at least one enabled Dispatcharr connection. A badge shows whether capture is in effect:

Badge	What it means
Active	Capture is on and a provider is present - Live TV programmes are being recorded as segments
Off	Capture is turned off, so Live TV is not broken down into programmes

The card has one control and a status line:

Capture Live TV programme analytics (off by default) - turns programme-segment capture on. When on, the toggle adds Live TV programmes to Top Titles and Trending.
A status line showing which providers are detected (IPTVBoss, Dispatcharr, or both) and how many programme segments have been captured so far.

Capture is not retroactive

Programme data is captured from the moment you turn this on. Live TV watched before then was recorded as whole sessions without a programme breakdown, so earlier Live TV history has no segments. Leave it on for a while to build up a picture.

Other settings on this page

The Settings view also hosts several configuration cards that are documented on their own pages:

Related settings and behavior

Cover Art Providers

Choose TMDB or TheTVDB artwork with per-category routing and your own API keys

Analytics & Logs

Configure the analytics time range, import historical data, and reset analytics

Live Sessions

Pause rules and session monitoring behavior

Best practices

Do

Click Test before saving any Emby, Jellyfin, or Plex connection so you catch URL or token typos early
On Emby/Jellyfin, give each Live TV Source a clear label and distinct color so streams are easy to identify
On Plex, periodically review the Plex Tuners card and remove orphaned (dead) tuners to keep the list clean
Use display names (Plex) and the usage gauge to confirm a tuner is actually in use before relying on it

Don't

Don't remove an active Plex tuner unless you intend to stop its Live TV channels
Don't expect a Plex display name to appear in Plex — it is a dashboard-only label
Don't read a Plex tuner's number as a device count — 4 means four concurrent streams, not four tuners
Don't paste tokens into a server card without verifying the URL is reachable on this machine first

Troubleshooting

Symptom

The Live TV Sources tuner picker is empty (Emby/Jellyfin)
Source badges do not appear on Live TV sessions
The Plex Tuners card does not appear at all
The Plex tuner list is empty after expanding the card
A Plex tuner shows as orphaned (dead) but you expect it to work

Resolution

Add a tuner in Emby or Jellyfin first, then click Refresh in the picker to re-read the host list
Confirm the source maps the correct tuner host and is enabled — only matched, enabled sources show a badge
Confirm Plex is connected under Connection Settings — the card only shows when Plex is configured
Click Refresh; if still empty, no grabber devices are registered in Plex yet
Check the device's network reachability (for Dispatcharr, confirm the HDHomeRun emulation is running)

FAQ

Because Emby, Jellyfin, and Plex expose Live TV differently. Emby and Jellyfin present their tuners through a common tuner-host interface, so WSDashboard lets you map those hosts to friendly labels in the Live TV Sources card. Plex models Live TV as DVRs and grabber devices instead, so it has its own Plex Tuners card. The split reflects the platforms, not a preference for one over another — all three are fully supported.

A source label maps one or more Emby/Jellyfin tuner hosts to a friendly, color-coded name (such as Antenna or HDHomeRun). When a viewer tunes a channel served by a mapped tuner, that label appears as a badge on the session in the Live Sessions view, so you can immediately see which source a stream is using.

The picker reads tuner hosts directly from your Emby and Jellyfin servers. If it is empty, add a tuner in the server's own Live TV configuration first, then click Refresh in the picker to re-read the host list.

An active tuner is bound to a working DVR and serving Live TV channels (the row shows the DVR name and channel count). A staged tuner is registered and reachable but not yet bound to a DVR — usually a test tuner. An orphaned tuner is registered but unreachable (dead) — a leftover device that is safe to remove.

Yes. Removing a tuner deletes the grabber device from your Plex server through the Plex API. The action is idempotent — if the device is already gone, the removal still reports success. Removing an active tuner detaches it from its DVR and stops the channels it serves, so the dashboard asks for a stronger confirmation in that case.

No. The display name is a QuickBox-side label that overrides the tuner's title in the dashboard only. Plex has no API to rename a tuner, so the name is never pushed back to Plex. Clear the display name to fall back to the original Plex title.

No. That number is the tuner's concurrent-stream capacity — the maximum number of streams that one tuner device can serve at the same time. A single Dispatcharr HDHomeRun profile advertising 4 means up to four people can watch Live TV through it simultaneously.

Both bring a Live TV guide into the dashboard, from different sources. The Dispatcharr Live TV Guide card manages your Dispatcharr connections. Each one feeds the TV Guide, Live TV session details, and Watch Analytics for Emby, Jellyfin, and Plex. Dispatcharr installs on the server are detected automatically and need no API key, and an admin can add a connection for a remote Dispatcharr, up to 8 in total. An API key on the Primary connection gives Plex Live TV sessions richer program details, such as season and episode numbers; without it, Plex sessions are still matched against the Dispatcharr guide. The card also holds two Plex-only tools (channel-map repair and duplicate guide-id scan); the Plex EPG override has no separate control and runs from the connections themselves. The IPTVBoss Live TV Guide card adds a Now / Next / Upcoming panel to Live TV channel pages in the Media Portal, read from your IPTVBoss XMLTV export, also for all three servers; it turns on once IPTVBoss is installed and an XMLTV output is enabled, and the Show guide in Media Portal toggle (on by default) controls whether the panel is shown.