The unofficial Plexamp plugin for Stream Deck
Ampdeck+ brings Plexamp to your Stream Deck. See your album art, track info, playback time, and rate your tracks on the LCD keys. All updated in real time. Stream Deck+ users get the full experience with a smooth animated progress bar spanning the touch strip and configurable dial controls.
Available Now on the Elgato Marketplace
Ampdeck+.Video.mp4
- "Load Playlists" button on the Playlist Carousel tile — Refresh your carousel with newly added playlists directly from the strip Property Inspector, no restart needed.
- "Show mode label" toggle — Hide the ARTIST / ALBUM / TRACK / TIME label row on any touch strip tile and let the text take over the full available space.
- Progress bar raised and doubled in size — The touch strip progress bar now sits 10px above the bottom edge and is 10px tall (up from 5px), making it clearer at a glance across all strip modes.
- Album Art — Live album art on any LCD key with a pause overlay. Tap to play/pause. When playback is paused, the album art displays with a gray overlay.
- Playlist Button — Dedicated key action to assign playlists. Assign playlists to buttons, allowing you to start your playlists with the press of a button. Enable Start playlist shuffled to shuffle on play.
- Playlist Carousel — Touch strip action that displays your Plex playlists in a scrollable view. Choose between poster art mode (3-up artwork browser) or text mode. Rotate the dial to browse, press to queue and play the selected playlist. Enable Start playlist shuffled to shuffle on play. Click Load Playlists in the tile settings to refresh the carousel with any new playlists you've added in Plexamp.
- Queue (Up Next) browser — Touch strip mode that shows the next 3 upcoming tracks as a live scrollable list with title, artist, and star rating. Rotate the dial to move the cursor, press to remove the focused track from the queue. The first item (pre-buffered by Plexamp) is shown with a lock icon and cannot be removed. Enable Toggle Queue / Playlist with touch in the Playlist Carousel settings to tap between the carousel and queue views without leaving the strip.
- Now Playing Strip — Artist, album, track, or elapsed time on each touch strip panel with auto-scrolling for long text. Clean symmetrical spacing and enlarged text for better readability. Toggle the "Show mode label" checkbox in the tile settings to hide the ARTIST / ALBUM / TRACK label row and expand the text into the full available space.
- Dial Controls — Configurable dial actions: rotate to skip tracks, adjust volume, or rate tracks. Press to play/pause, toggle shuffle, or cycle repeat.
- Star Ratings — Rate your tracks with half-star or full-star increments using the dial or dedicated rating button. Visual feedback shows the rating with stars. Ratings intelligently debounced for smooth server communication.
- Rating Button — Dedicated button showing the current track's star rating. Tap to cycle through ratings with configurable font size and increment mode (full star, half star, or single-star). In single-star mode, tapping cycles through all three Plexamp states: unrated (☆) → liked (★) → disliked (★ with diagonal strikethrough) → unrated. Wraps from 5 stars back to 0 for quick clearing in multi-star modes.
- Touch Strip Controls — Tap anywhere on the strip to play/pause with visual feedback overlays showing the action taken. Symmetrical spacing throughout.
- Spanning Progress Bar — A single progress bar that flows across all 4 dials, with colors extracted from album art.
- Volume Up / Down — Dedicated buttons with a canvas-drawn speaker icon. The icon fills with the album art accent color from the bottom proportional to current volume. Hold Volume Down for 400ms to mute and pause; hold again to restore volume and resume. Enable "Fade Out on hold-to-mute" in the button settings for a gradual fade instead of an instant cut — ideal for streaming. Configure the fade duration from 1–30 seconds (default: 3s).
- Play / Pause — Dedicated button with instant visual feedback.
- Previous / Next — Tap to skip tracks. Hold for 400ms to activate seek mode with animated directional arrows that smoothly travel across the button and wrap around Pac-Man style. Previous arrows move left, Next arrows move right. Configurable icon size (40-72px) with four preset options.
- Paused State Visual Feedback — When playback is paused, all buttons turn gray automatically: Album Art overlay, Navigation buttons, and all other action tiles provide clear visual indication.
- Shuffle — Toggle shuffle on/off with visual state indicator.
- Repeat — Cycle through repeat modes: Off → All → One.
- Track Info — Audio codec, bitrate, and track number at a glance with enlarged, easy-to-read text and symmetrical spacing. Intelligently distinguishes between album and playlist queues: when playing an album (shuffled or not) it shows the track's real position on the album (e.g.
7/14), matching what Plexamp displays; when playing a playlist it shows the track's position within the full playlist (e.g.342/8837). Font auto-shrinks on large playlists so numbers always fit. - Track Title — Dedicated button that displays the current track title in large auto-sized text. Supports up to 3 lines of word-wrapped text, scaling the font automatically to best fill the available space. Dims to gray when Plexamp is disconnected.
- Next Album / Previous Album — Skip forward or back to the first track of the next or previous album in the current playlist queue. Ideal for playlist listeners who want to jump whole albums at a time. Configurable icon size matching the Next/Previous buttons. Silently no-ops when not playing from a playlist queue.
- Time Elapsed — Large elapsed/total time display (42px/40px fonts) with its own progress bar and symmetrical spacing. Tap to toggle between
elapsed / totalandelapsed / -remainingdisplay modes, just like Plexamp. - Dynamic Colors — Progress bar and accent colors adapt to the current album art, or lock to orange if you prefer. Canvas-rendered navigation buttons use dynamic accent colors when active.
- Configurable Text Colors — Choose from White, Light Gray, Orange, Amber, or Black to match your setup.
- Direct Player Communication — Commands go straight to Plexamp's local API for fast, reliable playback control with automatic server fallback.
- Hold-to-Seek with Local Position Tracking — Continuous seeking without API staleness. The plugin tracks position locally and accumulates seeks independently for seamless navigation through long tracks.
Key Actions: Album Art, Play/Pause, Previous, Next, Shuffle, Repeat, Rating, Track Info, Time Elapsed
Dial Actions: Now Playing Strip with configurable display modes and dial controls
Ampdeck+ works on any Stream Deck model — the button actions (Album Art, Play/Pause, Previous, Next, Shuffle, Repeat, Track Info, Time Elapsed) work on every device with LCD keys. The Now Playing Strip with dials and progress bar is exclusive to the Stream Deck+.
| Feature | Stream Deck / XL / MK.2 / Mini / Neo | Stream Deck+ |
|---|---|---|
| Album Art | ✓ | ✓ |
| Play / Pause | ✓ | ✓ |
| Previous / Next | ✓ | ✓ |
| Shuffle | ✓ | ✓ |
| Repeat | ✓ | ✓ |
| Track Info | ✓ | ✓ |
| Time Elapsed | ✓ | ✓ |
| Rating | ✓ | ✓ |
| Track Title | ✓ | ✓ |
| Next Album | ✓ | ✓ |
| Previous Album | ✓ | ✓ |
| Volume Up | ✓ | ✓ |
| Volume Down | ✓ | ✓ |
| Now Playing Strip | — | ✓ |
| Queue (Up Next) Browser | — | ✓ |
| Dial Controls | — | ✓ |
| Spanning Progress Bar | — | ✓ |
- Any Stream Deck model (Stream Deck+ recommended for the full experience)
- Plexamp running on the same network or remotely
- Access to a Plex Media Server with a music library (you don't need to own the server)
⚠️ Important: If you have Ampdeck installed, please uninstall it first before installing Ampdeck+.
- Close Stream Deck completely (right-click system tray icon → Quit)
- Download
com.dreadheadhippy.ampdeckplus.streamDeckPluginfrom the Releases page - Double-click the file to install
That's it. Stream Deck handles the rest.
Windows:
- Close Stream Deck completely (right-click system tray icon → Quit)
- Download
install.batfrom the latest Releases - Double-click
install.bat
macOS:
- Close Stream Deck completely (menu bar icon → Quit)
- Download
install.shfrom the latest Releases - Run
chmod +x install.sh && ./install.sh
The install scripts will update the plugin while preserving your settings.
-
Find Ampdeck+ in the actions list on the right side of the Stream Deck app
-
Expand to see all available actions:
-
Drag Album Art to any button
-
Drag Now Playing Strip to all 4 dials
-
Optionally drag Play/Pause, Previous, Next, Next Album, Previous Album, Volume Up, Volume Down, Shuffle, Repeat, Track Info, Track Title, Time Elapsed, or Rating to buttons
-
Click any Ampdeck+ action and configure:
Ampdeck+ features automatic Plex authentication and discovery:
- Drag any Ampdeck+ action to a button slot in the Stream Deck app
- Click the button slot to open the Property Inspector (config panel)
- Click Sign in with Plex
- Authorize Ampdeck+ in the browser window that opens
- That's it! Your Plex server and Plexamp player are now configured automatically
The setup process:
- Uses Plex's official PIN-based authentication (no passwords needed)
- Automatically discovers your Plex server from your account
- Auto-detects your local Plexamp player
- Securely stores your auth token
If you prefer manual configuration or need to override auto-discovered settings, expand Advanced Settings in the Property Inspector:
| Setting | Description |
|---|---|
| Player URL | Override auto-discovered Plexamp player address. Default: http://localhost:32500 for headless Plexamp. Desktop users may need a different port — check Plexamp's settings. |
| Server URL | Override auto-discovered Plex server address (e.g. http://192.168.1.100:32400) |
| Plex Token | Override token from Plex sign-in. See Finding Your Plex Token if needed. |
| Client Name | Your computer's name as it appears in the Plex dashboard (used for server fallback) |
Use the Test Player button to verify the Plexamp connection and Test Server to verify the Plex server connection.
Each dial panel can be configured independently:
| Setting | Options |
|---|---|
| Display Mode | Artist, Album, Track Title, Time, or Playlists |
| Font Size | Small (12) through XX-Large (28) |
| Dial Action | None, Next/Previous (rotate), Volume (rotate), or Star Rating (rotate) |
| Rating Mode | Half Star (0.5 increment) or Full Star (1.0 increment) — only appears when Dial Action is set to Star Rating |
| Dial Press | Play/Pause, Toggle Shuffle, or Cycle Repeat |
| Total Panels | How many panels share the progress bar (1–4) |
| Panel Position | This panel's position in the progress bar sequence, or None to disable |
| Text Color | White, Light Gray, Orange, Amber, or Black |
| Dynamic Colors | When enabled, accent colors are extracted from album art. When disabled, they stay orange. |
| Start playlist shuffled | Only visible when Display Mode is set to Playlists. When checked, pressing to play a playlist will shuffle it. |
For example, to have the progress bar span all 4 dials: set each panel to "4 panels" and positions 1, 2, 3, 4 from left to right.
| Setting | Description |
|---|---|
| Time Offset | Compensates for network latency between the player and the display. Defaults to 0ms. Only needed if the time display feels ahead or behind. |
| Debug Logging | When enabled, logs detailed API requests and connection state to the browser console. Plex tokens are automatically sanitized in log output for safe sharing. |
Note: The 1-click setup handles authentication automatically. You only need this if using manual configuration.
- Open Plex Web (app.plex.tv) in your browser
- Play any media
- Press F12 to open developer tools
- Go to the Network tab
- Look for any request and find
X-Plex-Tokenin the URL - Copy the token value
For more details, see the Plex support article.
| Problem | Solution |
|---|---|
| Plugin not showing in actions list | Make sure Stream Deck was fully closed before running install.bat or install.sh |
| Player test fails | Verify Plexamp is running and the Player URL is correct. Headless Plexamp defaults to port 32500. Desktop Plexamp may use a different port. |
| Server test fails | Verify your server URL includes the port (:32400) and your token is correct |
| Buttons not working | This is usually a connection issue. Enable debug logging and check the browser console (http://localhost:23654) for errors. |
| Nothing displays | Confirm Plexamp is actively playing. Check both Player and Server test buttons. |
| Time display is off | Adjust the Time Offset in Advanced settings (try small values like 500–1000) |
| Progress bar not aligned | Check that all strip panels have matching Total Panels values |
If something isn't working, enable Debug Logging in the Advanced section of any Ampdeck+ action's settings. Then open the Stream Deck remote debugger at http://localhost:23654 in your browser to see detailed logs. Plex tokens are automatically masked in log output, so it's safe to share logs when reporting issues.
Copy the com.dreadheadhippy.ampdeckplus.sdPlugin folder to:
Windows:
%APPDATA%\Elgato\StreamDeck\Plugins\
macOS:
~/Library/Application Support/com.elgato.StreamDeck/Plugins/
Then restart Stream Deck.
src/
├── plugin.js # Main entry point & event orchestration
├── core/
│ ├── constants.js # Application constants
│ ├── connectionManager.js # WebSocket with auto-reconnect
│ └── stateManager.js # Centralized state container
├── plex/
│ ├── plexConnection.js # Plex API communication
│ ├── playbackController.js # Playback commands
│ └── metadataCache.js # Metadata & rating cache
├── ui/
│ ├── buttonRenderer.js # Canvas button rendering
│ └── layoutManager.js # Touch strip layouts
└── utils/
├── validator.js # Input validation
├── logger.js # Logging system
└── helpers.js # Utility functions
# Install dependencies
npm install
# Build plugin (compile modules → single file)
npm run build
# Build + watch for changes
npm run dev
# Lint source code
npm run lint
# Build + package for distribution
npm run pack- ES6+ Modules - Modern JavaScript with import/export
- Rollup - Module bundler for production build
- ESLint 10 - Flat config format, zero warnings
- Stream Deck SDK v2 - Latest SDK features
- Web Workers - Non-blocking polling and rendering
| Aspect | v1.0 | v2.0 |
|---|---|---|
| Structure | Single 1934-line file | 12 modular files |
| State Management | 30+ global variables | Centralized StateManager |
| Error Handling | Basic try/catch | Comprehensive with fallbacks |
| Reconnection | None (dead on disconnect) | Automatic with backoff |
| Input Validation | None | Comprehensive validator module |
| Code Quality | Functional | Zero ESLint warnings |
| Maintainability | Difficult | Excellent |
Automatic Reconnection If the WebSocket connection to Stream Deck drops unexpectedly, the plugin automatically attempts to reconnect with exponential backoff (this only happens when disconnected - normal operation is unaffected):
- 1st attempt: 3 seconds
- 2nd attempt: 6 seconds
- 3rd attempt: 12 seconds
- Max delay: 30 seconds
Note: This is separate from the regular polling (1 second for playback data, 200ms for display updates) which runs continuously while connected.
Hold-to-Seek Press and hold the Previous or Next buttons for 400ms to switch from track skipping to seeking. The plugin will seek 10 seconds per step while you hold the button.
Rating Cache The plugin intelligently caches your rating changes to handle Plex server metadata delays. If you rapidly adjust ratings, the UI stays responsive while the server catches up.
Dynamic Color Extraction Album art is analyzed to extract the dominant color, which is then used as an accent color throughout the UI (unless disabled in settings).
Contributions are welcome! Please see the Contributing Guidelines for detailed information on how to contribute to this project.
- @rackemrack - Original Ampdeck creator
- @DreadHeadHippy - v2.0 rewrite, modularization, and ongoing development
If Ampdeck+ is useful to you, consider buying me a coffee. Donations are always appreciated, but never required.
