tgp-2/Plexamp-headless-install.md

## Plexamp-headless-install.md

      
    Raw
  

              Plexamp-headless-install.md
            
          
    Plexamp headless install

install and setup guide for Plexamp headless on the Raspberry Pi


installs Plexamp version 4.10.1 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/65a0c9a3d6c2d375d4a7633cbfe0cbc86ca4c18d/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 ... one exception, after transferring playback from a remote app (Plexamp on your phone, etc.) to headless, pausing the transferred track will hold onto the audio device indefinitely ... to avoid, recommend connecting to headless before starting playback


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