Skip to content

Instantly share code, notes, and snippets.

@tgp-2
Last active October 1, 2024 20:45
Show Gist options
  • Save tgp-2/fc34c5389bc3e4ef332e28d9430b0ebf to your computer and use it in GitHub Desktop.
Save tgp-2/fc34c5389bc3e4ef332e28d9430b0ebf to your computer and use it in GitHub Desktop.
install and set up Plexamp headless on Raspberry Pi

Plexamp headless install

install and setup guide for Plexamp headless on the Raspberry Pi

  • installs Plexamp version 4.11.2 and prepares systemd service (to auto-start Plexamp at power up)
  • installs node 20 using nvm for version management

QUICK START

  • install Raspberry Pi OS Lite (64 bit recommended, 32 bit also supported) on a Micro SD card for your Raspberry Pi 2, 3, 4, or 5 ... use Raspberry Pi Imager and pre-configure SSH, Pi device name (hostname), username/password, locale, and WiFi connection before writing to the Micro SD card

  • insert the card, power up your Pi, and give it a couple minutes to boot and become visible on your network

  • ssh user@hostname to remote login from another computer into your Pi (user is your username, for example pi)

  • get the installer ...

wget https://gist.githubusercontent.com/tgp-2/65e6f2f637bc81df2c9fd9ba33f73bc6/raw/11c8a04ae47ef6cbba241dd6f518ecf690e6fe3b/plexamp-install.sh
  • run the installer ...
bash ./plexamp-install.sh
  • enter the plex.tv claim code ... copy from a web browser, paste it ctrl-V into your Pi SSH session and enter
  • enter a name for your player
  • after install completes, sudo reboot to restart the Pi ... Plexamp auto-starts after reboot
  • in a web browser, go to hostname:32500, login to Plex, and configure playback settings for your Pi
  • from the browser or from the Plexamp app on another device (your phone, laptop, etc.), tap the Cast icon and select your Pi from the list of players
  • now play some music!

DETAILS

intro ...

  • Plexamp for the Raspberry Pi (and similar single board computers) runs on many 64 and 32 bit Linux operating systems
  • typical usage model is Plexamp running on a "headless" Pi (no attached monitor, etc.), output connected to your audio system, and playback controlled remotely from another computer/phone/device that's also running Plexamp
  • this guide expands on initial install instructions from Plex (https://forums.plex.tv/t/plexamp-on-the-raspberry-pi/791500)
  • use of this installer is straightforward, but building a DIY headless Pi-based streamer from scratch is not for everyone ... for those who want an easier install process and an appliance-like user experience, RoPieee is highly recommended

requirements and prep ...

  • Plex Media Server installed and running on another computer on your home network, for storing/managing your music files and linking your (optional) Tidal account

  • an active Plex Pass subscription, required to use the headless Plexamp app

  • a Windows, MacOS, or Linux computer to use during the install process ... MacOS/Linux terminal apps already have built-in SSH clients ... if using Windows, try the Windows Terminal app as it enables a built-in SSH client ... or, to use SSH thru a web browser, try the Secure Shell extension

  • an ARM v7 or later Raspberry Pi (models 3, 4, 5, and Zero 2 W for sure, maybe others?) ... a device with >= 512MB RAM is recommended for caching and smooth playback, and >= 1GB RAM is preferred for frequent playback of long duration and/or hi-res files (note, Plexamp headless and this installer will also work on other small board computers, from vendors such as Odroid and NanoPi)

  • a general-purpose or audio-specific Linux OS based on Debian ... for Raspberry Pi devices, use current (non-legacy) version of Raspberry Pi OS Lite (64 bit recommended, 32 bit also supported) ... install using Raspberry Pi Imager and pre-configure advanced options before writing to your Micro SD card (read next line for details)

  • to pre-configure advanced options in Raspberry Pi Imager, select the cogwheel icon and set the following ... SSH server enabled with password authentication, Pi device name (hostname), username/password, select your locale, and configure wireless LAN if your Pi will need a Wi-Fi connection

  • for small board computers other than the Raspberry Pi, use a different Debian-based OS (for example, Armbian CLI or DietPi), installed using a flash utility such as balenaEtcher

  • if using an OS older than the current version of Raspberry Pi OS (based on Debian Bookworm, at time of writing), some/all versions of Plexamp might not run due to differences in core dependencies such as glibc

  • your audio device (on-board headphone output, external USB DAC, i2s DAC or SPDIF HAT, etc.) should be attached and available for use ... enter cat /proc/asound/cards and see if your audio device is listed

  • if using a HAT with Raspberry Pi OS, you'll need to make it visible to the OS ... look in /boot/overlays for a file with your HAT device name (for example, devicename.dtbo), then open the boot config file for editing sudo nano /boot/config.txt and add dtoverlay=devicename (without the .dtbo file extension) at the end of the file, ctrl-X save/exit the file, and sudo reboot (for a different OS, or for audio devices that require additional enabling steps, follow HAT manufacturer and OS instructions as needed) ... after rebooting, again enter cat /proc/asound/cards to confirm that your HAT now shows on the list of available audio devices

  • by default, HDMI audio lacks a usable ALSA driver for some boards such as the Pi 3, 4, and 5 ... a usable ALSA driver for HDMI audio can be enabled on the Pi 3 and 4 (not the 5) by following the instructions here

  • if all else fails and a usable ALSA interface is not available (Bluetooth audio, for example), or if you prefer to use your Pi with a monitor, desktop environment, and the default Pulseaudio (or PipeWire?) sound server, you will need to switch to a systemd --user service after Plexamp install completes (the default system service cannot be used to access Pulseaudio) ... this requires some manual file edits described here

playback settings ...

  • to change Plexamp headless playback settings, use a web browser to visit hostname:32500

  • navigate to settings --> playback ... select your audio output device and set other options as needed (for example, if you have audiophile tendencies and think you want less processing than what the defaults will give ... select strict sample rate matching and disable loudness leveling, sweet fades, EQ, and the limiter ... otherwise, start with the defaults and adjust individual playback settings based on your preferences)

  • navigate to settings --> playback --> caching ... set Wi-Fi Caching to "Only Next Track" and set Cache Size to one of the smaller available options (recommend "256MB" or "512MB") ... larger values aren't intended for headless, as a WiFi/Ethernet connection is always present

  • open the Cast menu (icon at top right corner), select your Pi device player name for playback

  • Plexamp headless should now be ready for music playback ... connect and control from a web browser or from the Plexamp app on another device (iOS, Win/MacOS, Android, x86-64 Linux) that's also on your network

  • when connected to a headless player, moving the Plexamp in-app volume slider does NOT touch the hardware (ALSA) volume/gain settings for your audio device ... to avoid audio that is too loud, too quiet, or distorted, check the Plexamp volume slider position (at the bottom of the player screen or Cast menu) and your device gain settings using the OS alsamixer utility ... recommend unity gain (0dB) for systems with a downstream amp or receiver with volume control, or -20dB gain as a starting point for systems feeding directly into a powered speaker

  • headless Plexamp will release the audio device (so other apps can use it) about 10 seconds after playback is paused or stopped

upgrades ...

  • to upgrade Plexamp headless to the latest official release version, use the upgrade.sh script provided by Plex and located in your user's ~/plexamp directory ... from that directory, execute by entering ./upgrade.sh
  • this installer sets up nvm to manage node version ... for future app upgrades requiring a major new version of node (for example, a change from 20 to 24), first upgrade headless as described above, then run nvm install 24 followed by echo "v24" > .nvmrc, then reboot
  • alternately, you can fetch and run the latest version of this installer ... this will update your installation to the latest Plexamp version (keeping your existing settings for playback, etc.), while also updating nvm, node, and the systemd service as needed
@Pe8er
Copy link

Pe8er commented Feb 27, 2024

Amazing resource! I just set up a Plex Server AND Plexamp on a single Raspberry Pi 3 and it seems to be working very well. Thank you very much!

@BrodyStone21
Copy link

Worked great, thank you so much! I set this up myself with node 16, but then couldn’t get it to properly upgrade to node 20, even after editing the plexamp.service config.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment