Power User Reference

A complete reference for every feature, setting, and behavior in Plunge — for users already comfortable with the basics.

Server backends

Plunge supports three server backends. Each uses a different API but all provide the same features inside Plunge. The backend is selected once at setup and stored alongside your credentials; changing it requires signing out and re-connecting.

Generating an API key — Jellyfin

In your Jellyfin server's admin dashboard, go to Administration › API Keys and create a new key with any name. Copy the generated key and paste it into Plunge's setup screen.

Generating an API key — Emby

In Emby's admin dashboard, go to Advanced › API Keys. Create a key, name it anything (e.g. "Plunge"), copy it, and paste it into setup.

Getting your X-Plex-Token

Plex tokens are tied to your Plex account, not your server. The easiest way to find yours is to sign in to plex.tv, open the web player, inspect a network request, and look for the X-Plex-Token query parameter. Plex's support documentation also covers this in detail.

Exploration system

The exploration system is Plunge's approach to discovery. It is designed around a single question: how adventurous do you want to be right now?

The dial (1-11)

The dial in each library view adjusts how items are scored against your taste profile and how those scores affect card sizing.

• 1-3 (Comfort zone) — items are ranked tightly by profile similarity. Familiar genres, directors, or artists you have interacted with before dominate. Card sizes vary substantially: high-confidence matches appear large.
• 4-6 (Adjacent) — the ranking expands outward. Items that share some signals with your profile (overlapping genres, same decade, related styles) surface alongside your core matches.
• 7-9 (Adventurous) — similarity weighting is relaxed. Unusual or genre-crossing items rise in the grid. Card sizes level out.
• 10-11 (Unpredictable) — the ranking is inverted at the edges. Items you would be least likely to choose based on history appear first. Useful for breaking habits.

How scores are calculated

Each item in a library gets a score based on how many of its metadata signals (genre, year, director, cast, rating) match signals in your taste profile. The dial value determines how the raw score translates into ranking and visual weight:

• At dial 5, the score is used directly — high-scoring items rank first.
• Below 5, the spread between scores is amplified — top matches pull further ahead.
• Above 5, the spread is compressed — all items move closer to a flat ranking.
• At 11, the sort is reversed beyond a threshold — low-scoring items surface first.

The card sizing works the same way: items whose score is above the library's mean appear at the "featured" size; items at or below the mean appear at the "normal" size; items well below appear at the "dimmed" (smaller) size.

Taste profile

Your taste profile is a weighted map of the signals Plunge has inferred from your behavior. It builds up automatically and is stored on your media server alongside your other preferences, so it persists across sessions and devices.

What signals are collected

Resetting your profile

There is no in-app reset button in this version of Plunge. If you want to start fresh, sign in to your media server's native web interface and clear the Plunge preferences stored under your user account.

Playback settings

Autoplay

When autoplay is on (the default), the player automatically advances to the next item in the queue when the current one ends. For TV show episodes, this means episodes play continuously. Turn it off in Settings if you prefer to choose each item manually.

Max bitrate

This sets the highest bitrate Plunge will request from your server for transcoded streams. It has no effect if the file plays directly (Direct Play — your server sends the original file without transcoding). Useful if you are on a metered or slow connection.

Themes

Plunge ships with eight visual themes. Your choice is saved as a preference and applies across sessions. All themes are dark-mode only.

Accent style

Each theme offers two accent modes: Same Shade (the accent is a tint of the base color palette) and Complement (the accent is shifted to the complementary hue). Both options are available in Settings under Appearance.

Settings reference

The Settings view is available from the sidebar or directly at #/settings. All preferences are stored on your media server and sync across sessions and devices.

Appearance

Home

Library

Libraries (per-library customization)

When at least one library is connected, a Libraries section appears with a row for each library. Each row lets you:

• Rename — type a custom display name. Leave blank to use the server's name.
• Icon — pick from a list of icon types (film, TV, music, photo, books, headphones, folder, or auto-detect from library type).
• Hide — toggle the library off so it does not appear in the sidebar. You can still navigate to it via search or a direct link.

Exploration

The Default exploration scale slider (1-11) sets the starting value for the exploration dial in every library view. You can still adjust the dial per-view at any time; this setting just controls where it starts each session. See the Exploration system section for how the dial affects scoring.

Playback

Account

The Account section shows read-only connection details — server URL, connection status, authentication type, and the currently signed-in username. From here you can:

• Sign Out — clears credentials and returns to setup. Your preferences remain on the server.
• Administration — navigates to the admin panel (visible only to admin users).
• Documentation — opens this guide.

Filtering & smart collections

Every library view has a Filters button in the toolbar. When any filter is active, a badge on the button shows the count of active filter dimensions. Below the toolbar a row of dismissible chips appears, one per active filter — click the × on any chip to remove that filter immediately.

Quick filter toggles

At the top of the filter panel are toggle buttons that narrow the library to a specific watch-state. These work across all non-photo library types:

• Unwatched — hides items you have fully played.
• Favorites — shows only items marked as a favorite.
• In Progress — shows only items you have started but not finished. Available for Movies, TV Shows, and Videos libraries only.

Multiple toggles can be active simultaneously — the grid shows only items that pass all active toggles.

Attribute drill-down

Below the quick toggles is a list of filterable attributes. Clicking any attribute opens a submenu showing all values present in the current library. You can select one or more values; items must match at least one selected value in that attribute to be shown (OR within a dimension). Selecting values from multiple attributes applies all dimensions together (AND across dimensions).

Available attributes vary by library type. Photo libraries offer no attribute filters. Music and audiobook libraries offer Genre only. All other library types offer:

Clicking the attribute name in the chip bar dismisses all selected values for that attribute at once.

Advanced filters

The Advanced Filters link at the bottom of the filter panel opens the query builder, which closes the filter panel. The query builder lets you construct precise multi-condition rules that the standard filter panel does not support.

Each rule has three parts: a field, an operator, and a value. The full field list is:

The match mode at the top of the panel controls how rules combine: Match All (default) requires every rule to pass; Match Any shows items that satisfy at least one rule. The result count updates live as rules are added or modified.

Advanced rules stack with standard filter-panel selections — the grid shows only items that pass both the standard filters and the advanced rules simultaneously. Click Clear All inside the filter panel to remove all active filters and advanced rules in one action.

Smart collections

Once you have a useful combination of standard filters and advanced rules active, click Save as Collection in the query builder to give it a name and save it. Saved collections appear in the sidebar directly beneath their source library — clicking one loads that library with the saved filter state pre-applied.

To delete a smart collection, open that collection's library view (filters applied), open the filter panel, and click Delete Collection at the bottom of the panel. This removes the collection from the sidebar without affecting the library itself.

Context menus

Right-clicking any card or library tile opens a context menu with actions relevant to that item. On touch devices, a long press opens the same menu.

Media card context menu

Available on all media cards (movies, episodes, tracks, albums, artists, series):

Library tile context menu

Right-clicking a library name in the sidebar or a library tile on the home screen:

• Open Library — navigates to that library's grid view.
• Scan Library (admin only) — triggers a library scan on the server.

Player context menu

Available from the … (more options) button in the full-screen player:

• View Details — opens the item's detail page without stopping playback.
• Mark Played / Unplayed — videos only (movies, episodes).
• Love This — sends a strong positive taste signal.
• Not Interested — sends a negative taste signal.

Keyboard shortcuts

Plunge is designed to be fully operable with a keyboard or TV remote D-pad. All interactive elements are reachable by tabbing or using arrow key navigation.

Global navigation

Search

Player controls

The player has no dedicated keyboard shortcuts beyond standard focus navigation. All controls — play/pause, skip, volume, subtitle track selection — are reachable via arrow keys and activated with Enter or Space. Moving the mouse, tapping the screen, or pressing any key reveals the controls bar if it is hidden.

Admin panel

The admin panel is accessible to users with administrator privileges only. Navigate to it from Settings › Account › Administration, or directly at #/admin.

Server info

Displays the server name, software version, and operating system as reported by your media server. Information is fetched on mount and shown in read-only rows.

Active sessions

Shows all currently active playback sessions on your server in a table: who is playing what, from which client, and whether the stream is Direct Play or Transcoded. Each row has a Stop button that terminates that session's playback. The list refreshes automatically after a session is stopped.

Library actions

API keys

Lists all API keys registered on the server. Each row shows the key's app name, a truncated token preview, and the creation date. To revoke a key, click Revoke on its row and confirm the dialog. To create a new key, enter an app name in the text field and click Create API Key. The list updates automatically after any change.

User Management link

The Users section in the admin panel contains a Manage Users button that navigates to the full User Management view at #/admin/users.

User management

The User Management view is available at #/admin/users (admin-only). It shows every user on your media server in a list with per-user action buttons.

User list

Each user row displays the username, an Admin badge if they have administrator access, and a Disabled badge if their account is currently suspended. Three action buttons appear on the right of each row:

Inviting a new user

Click Add User at the top of the view to expand the invite panel. Fill in:

• Username — required; must be unique on the server.
• Password — optional; leave blank to create a passwordless account.
• Make admin — checkbox; grants immediate administrator access.
• Library access — leave All libraries checked (default) to grant access to every library, or uncheck it and select specific libraries individually.

Click Create to submit. The new user appears at the top of the list on success. Click Cancel to collapse the panel without creating a user.

Queue

The queue holds items to play in sequence. To add something to your queue, open the item's detail page and tap "Add to queue." The queue persists across page navigations within the current session but clears when you close the browser tab.

During playback, the next and previous buttons in the player controls step through the queue. If autoplay is on and the queue is non-empty, the next item starts automatically when the current one ends.

Photo & slideshow viewer

Photo libraries open a dedicated viewer rather than the standard media player. Navigate to a photo album in your library and tap any photo to open the single-photo view (#/photo/{id}). To launch a full-screen slideshow of the entire album, use the slideshow button at the bottom of the single-photo view or the context menu on the album card.

Single-photo view

The viewer displays the photo full-screen with a bottom bar showing the caption, metadata (capture date, camera model, and other EXIF fields your server exposes), and an action row. From the action row you can launch the album slideshow or see the photo's position in the album (e.g. 7 / 43).

• Navigate between photos in the album with ← / → or the on-screen previous/next buttons.
• Pinch to zoom on touch devices.
• Press Escape or tap the back button to return to the album view.

Slideshow view

The slideshow view (#/slideshow/{albumId}) plays all photos in an album full-screen with a crossfade transition. Photos advance automatically on a configurable interval (default: 5 seconds, adjustable in Settings → Playback → Slideshow interval).

Controls auto-hide after a few seconds of inactivity. Move the mouse or tap the screen to bring them back. While controls are visible you can:

• Play / Pause — toggle auto-advance. Space bar also toggles this.
• Previous / Next — step manually; pauses auto-advance if playing.
• Shuffle — randomise the photo order. Activating shuffle reshuffles the deck while keeping the current photo in view.

On TV (D-pad), the left and right buttons navigate photos, and the OK / Select button toggles play/pause.

Search

The search bar in the top bar is always visible once you are connected to a server. Focusing it opens a floating panel beneath it. Results appear as you type, with a short debounce to avoid firing a query on every keystroke.

Keyboard and D-pad navigation

• Arrow Down from the search bar moves focus into the result list.
• Arrow Up from the first result returns focus to the search bar.
• Enter or Space on a result navigates to that item and closes the panel.
• Escape closes the panel and restores focus to the search bar.

On TV remotes, the D-pad works the same way — down into results, up back to the bar, Back/Escape to close.

Recent searches

When the search bar is focused with no query typed, the panel shows your recent searches. Selecting one restores the term and re-runs the search. Recent searches are stored locally in your browser and are cleared when you switch server or sign out.

Search scope

Search always runs across all of your server's libraries simultaneously. Results are ordered by relevance as scored by your media server — Plunge does not re-rank them.

TV app support

webOS (LG Smart TVs)

Plunge is packaged as a webOS app for LG Smart TVs manufactured after 2015 (webOS 2.0+). Install via the LG Content Store or sideload the IPK package from the releases page. On webOS, the remote Back button navigates within Plunge; a final back press from the home screen closes the app gracefully.

Android TV

The Android TV version is a Progressive Web App (PWA) delivered as a full-screen webview. It responds to D-pad navigation and the Android TV remote's Back button. Install by sideloading the APK or through your TV's browser.

On both TV platforms, focus management and D-pad navigation are handled natively by the browser. If a button is not reachable by remote, use the pointer/cursor mode on your remote.

Offline use

Plunge registers a service worker that caches its own application shell (HTML, CSS, JS) after the first load. If your internet connection drops, the Plunge interface itself remains available. However, media cannot be streamed without a connection to your server. The offline shell shows an error if it cannot reach the configured server URL.