Getting Started with Plunge

Plunge is a media client for Jellyfin, Emby, and Plex servers. It runs entirely in your browser and connects directly to your own server — no cloud accounts, no subscriptions.

What is Plunge?

Plunge is a front-end player for your personal media library. If you run a Jellyfin, Emby, or Plex server at home (or in the cloud), Plunge gives you a clean, fast interface for browsing movies, TV shows, and music — and playing them directly in your browser or on a TV.

Plunge does not host or stream anything itself. It talks to your existing server, which does all the transcoding and delivery. Your media never leaves your infrastructure.

What you need

Before you can use Plunge you need one of the following media servers running and accessible:

• Jellyfin — free and open source. jellyfin.org
• Emby — free tier available. emby.media
• Plex — free Plex Media Server. plex.tv

You also need to know your server's URL (e.g. http://192.168.1.100:8096 for Jellyfin running on your local network, or a public URL if your server is internet-facing) and an API key or token for your account on that server. The setup screen walks you through both.

Connecting to your server

The first time you open Plunge you land on the setup screen. Follow these steps:

1. Select your server type. Tap the Jellyfin, Emby, or Plex button at the top of the setup card. This changes the prompt on the next screen to match what your server calls its token.
2. Enter the server URL. Type or paste the full URL of your server, including the protocol (http:// or https://) and port if non-standard. If you leave out the protocol, Plunge adds https:// automatically.
3. Enter your API key or token. For Jellyfin and Emby: go to your server's admin dashboard, open the API Keys section, and create a new key. Paste it here. For Plex: your X-Plex-Token can be found in your Plex account settings under "Authorized Devices" or by following Plex's token guide.
4. Tap Connect. Plunge validates the credentials against your server. On success it loads your libraries and takes you to the home screen. On failure it shows an error — check the URL (is the server running? reachable from this device?) and the key.

Once connected, Plunge stores your server URL and API key locally in your browser so you do not need to re-enter them on the next visit. Nothing leaves your device.

Browsing your library

After connecting, the left sidebar shows each library your server has — Movies, TV Shows, Music, and any others you have configured. Tap a library name to open it.

Inside a library you see a grid of poster cards. By default the grid is sorted by relevance to your taste profile (see The exploration dial below). You can scroll through the grid or use the search bar at the top to find something specific.

Tap any card to open the detail page for that item. From there you can play it, add it to your queue, or mark it as a favorite.

The Filters button in the library toolbar lets you narrow the grid by genre, decade, content rating, director, cast, studio, resolution, audio language, and watch state. You can also right-click any card to get quick access to Play, Add to Queue, Mark Played, Favorite, and other actions without opening the detail page.

Photo libraries work a little differently: tapping a photo card opens a full-screen photo viewer with navigation, EXIF metadata, and a button to launch an automatic slideshow of the entire album.

Playing media

On any item's detail page, tap the Play button to start playback. The player opens full-screen and begins loading the media from your server.

During playback the controls fade out after a few seconds. Move the mouse or tap the screen to bring them back. Controls include play/pause, seek, previous/next in queue, and a close button that returns you to the previous page.

Plunge reports your playback position back to your server in real time, so your "continue watching" state stays in sync across any other clients you use (Jellyfin Web, Infuse, etc.).

Taste signals

While something is playing you will see two signal buttons in the player controls: a heart and an X.

• Heart — "I Love This" tells Plunge you strongly enjoy this title. It raises the weight of similar content in your taste profile, so things you will likely love surface more prominently when the Exploration dial is set low.
• X — "Not Interested" tells Plunge this is not your kind of thing. It reduces similar content's prominence. The item stays in your library — it just moves to the back of the queue when Plunge is ordering suggestions for you.

Both signals feed directly into the Exploration dial. You do not have to use them — finishing items, replaying them, and marking favorites all contribute to your taste profile too — but they are the fastest way to steer Plunge toward the kind of content you actually want.

The queue

The queue lets you line up content to watch in sequence during a session. It works like a playlist: Plunge plays each item in order and automatically moves to the next when one finishes.

To add something to the queue:

• Right-click any card in the library grid and choose Add to Queue.
• Open the item's detail page and tap the Add to Queue button below the play controls.
• Use the Play Next option to insert an item at the front of the queue rather than the end.

To view and manage the queue, tap the queue icon in the sidebar or navigate directly to #/queue. From the queue view you can remove individual items, clear the entire queue, or drag items to reorder them.

The queue is session-scoped. It lives in memory for the current browser tab only and is cleared when you close the tab, reload the page, or sign out. If you want to resume a queue later, use your server's built-in playlist or collection features instead.

The exploration dial

Every library view has an Exploration dial — a slider from 1 to 11. This controls how the grid is ordered and sized:

• Low values (1-3) show a focused selection of items that closely match your taste profile — things you are likely to enjoy based on what you have played, liked, and finished.
• Mid values (4-7) blend familiar picks with adjacent titles — similar genres and styles, but not just your usual comfort zone.
• High values (8-11) surface unusual or unexpected titles from the edges of your library. Good for when you want something different.

The dial also changes card sizes: items that match your profile closely appear larger. This visual weight makes it easy to see what Plunge thinks you will enjoy most at a glance.

Your taste profile is built from signals you generate naturally while using Plunge: items you finish, items you replay, items you mark as favorites, and items you explicitly like during playback with the heart button. You can adjust the default dial position in Settings.

Searching

The search bar is at the top of every screen once you are connected to a server. Click or tap it to open the search panel. Results appear as you type — Plunge waits a short moment between keystrokes before querying your server, so you will not trigger a search with every letter.

Use the arrow keys to move between results, press Enter or tap a result to navigate to it, and press Escape to close the panel without navigating anywhere. On TV remotes, the D-pad navigates the result list the same way.

Search is powered entirely by your server's search index. The quality and speed of results depends on how your server has indexed your media.

Settings

Open Settings from the sidebar or from the user button at the bottom-left. From here you can:

• Theme — switch between the default dark theme and Crate Dig (a warm amber palette).
• Default exploration scale — set the dial position that every library starts at when you open it.
• Autoplay — turn off autoplay if you want the player to pause between episodes.
• Max bitrate — cap how much bandwidth Plunge asks your server to use for transcoded streams.
• Sign out — disconnect from your server and return to the setup screen.

TV installation

Plunge runs natively on LG TVs (webOS) and Android TV / Google TV devices. The web version works in any modern browser; the TV apps provide D-pad navigation and remote control support out of the box.

LG TV (webOS) — sideloading the IPK

1. Enable Developer Mode on your TV. Install the LG Developer Mode app from the LG Content Store on your TV, then sign in with a free LG Developer account. Enable Developer Mode from within the app. Your TV will reboot.
2. Note the TV's IP address. After reboot, open the Developer Mode app again — it displays the TV's IP address and a passphrase you will need to connect from your computer.
3. Install the webOS CLI (ares-cli) on your computer. Download and install the LG webOS TV SDK from LG's developer site, which includes ares-setup-device and ares-install.
4. Register your TV. Run ares-setup-device, add a new device, and enter the TV's IP address and the passphrase shown in the Developer Mode app.
5. Install the Plunge IPK. Download the Plunge .ipk from your account download link, then run:
   ares-install --device <your-tv-name> plunge.ipk
   Plunge will appear in your TV's app list.

Developer Mode sessions expire after 50 hours and must be renewed via the Developer Mode app. Your installed apps remain after renewal.

Android TV / Google TV — installing the APK

1. Allow installation from unknown sources. On your device, go to Settings → Device Preferences → Security & Restrictions (exact wording varies by manufacturer) and enable Unknown Sources or Install unknown apps for the method you will use below.
2. Transfer the APK to your device. The easiest methods are a USB drive, a file-manager app that can download via URL, or Android Debug Bridge (ADB) over your local network. Download the Plunge .apk from your account download link first.
3. Install via file manager. Open a file manager app on the TV (or the one built in), navigate to the APK, and tap it to install. Accept the permission prompt.
   Or, if using ADB:
   adb connect <tv-ip-address>
adb install plunge.apk
4. Launch Plunge. Find Plunge in your app list or on the home screen. On first launch you will go through the same server setup as the browser version.