Project with PeppyMeter/PeppySpectrum Screensaver Plugin for VOLUMIO

Omg that looks awesome… Due to this o like volumio… This is on my short list, nr1. Until now for my next streamer.
Thanks for sharing and help us with this great ideeas


Ok, let’ start with
step 1: core installation

  • install a fresh VOLUMIO image
  • enable SSH: http://volumio.local/dev
  • username: volumio password: volumio
  • for some configurations it’s better to enable root account, use putty with the volumio account for this and edit sshd_config:
sudo nano /etc/ssh/sshd_config
  • set: PermitRootLogin yes and reboot
  • for a connected HDMI-display you need the touchscreen-plugin
  • if installation succsesfully, set ‘supress Screenssaver while playing’ to ‘ON’
  • for the AMOLED the follow entries in /root/userconfig.txt important
hdmi_timings=1080 1 26 4 50 1920 1 8 2 6 0 0 0 60 0 135580000 3

hdmi_blanking is for the AMOLED, it has no backlight, the blank screensaver is only work with hdmi_blanking=1

The install script do all this steps (dependency is an installed touchscreen plugin)

To use the script, copy the Install_amoled folder to /home/volumio and make the executable.

chmod +x /home/volumio/Install_amoled_EDID/

and start it with:


the updated scripts you finde here:
Waveshare AMOLED on Pi5 and Pi4 with GPU acceleration

For some other HDMI displays disable the overscan to use the native display resolution without scale factor.
Set in /boot/userconfig.txt:


Just awesome! Very very nice!


Step 2: UI optimizations

The customiziations thread for a better view on a landscape display you find here:

Contemporary optimizations for small or large landscape displays
Download plugin
contemporary_advanced plugin

Some little changes are included for the rotated AMOLED display to increase the performance with a fullHD resolution. Important is this option:

It disabled the blur filter on the header of an album selection. This filter needs many time on 1920 resolution.

With this changes you have a usable 5,5" AMOLED display. If this enough for you you can brake out here.


Step3: install peppyalsa

What peppy alsa is exactly doing you find here:

The Volumio version 2.882, 2.906 had a little bug. The installation of build essentials run into an error. The build essentials are needed to compile the source.
A workaround for this problem with a little script to install the dependencies find here:
Cannot install build-essential package
But you don’t need anymore this separate script. The peppyalsa installer have included it now.

You don’t run manually all the steps, An install script is attached, that’s all follow steps do for you.
what’s the script doing:

cd /home/volumio

git clone
pushd peppyalsa
sudo apt-get -y install build-essential autoconf automake libtool libasound2-dev libfftw3-dev
aclocal && libtoolize
autoconf && automake --add-missing
./configure && make
sudo make install

This create a directory peppyalsa in /home/volumio and compile the source and install it.

Buster works with a separat asound.conf file thats included in an existing /etc/asound.conf ( modular alsa) no changes in asound.conf and mpd.conf are needed.

The MPD must be configure to use peppyalsa with an additional output device (mpd_peppyalsa). Thats the best way that the original output stream is not changed and reformated to PCM, when DSD is used. Therefore a second entrypoint in asound.conf for the sound output is available (mpd_alsa) VOLUMIO used a template file, thats copied if the sound card or mixer type is changed.


this section is added:

audio_output {
        enabled     "yes"
        type        "alsa"
        name      "mpd_peppyalsa"
        device     "mpd_peppyalsa"
        dop         "yes"
        mixer_type  "none"
        format      "44100:16:2"

After reboot please check if the mpd.conf in /etc have an additional section with the mpd_peppyalsa as output device.

As output card for PeppyMeter is a dummy device needed.
The install script add this entry to /etc/modules-load.d/modules.conf and set the index of last card in file: /etc/modprobe.d/alsa-base.conf

The MPD user needs rights to write the name pipe /tmp/myfifo, therefore it’s better to create the name pipe at startup with the correct rights.

mkfifo -m 646 /tmp/myfifo

Check if peppyalsa now working with the little tool: peppyalsa-client
start it in a console


and play a song. If it running with meters all is ok.


if not, check in /tmp/ if both name pipes created. myfifo (created on startup) and myfifosa with a running peppyalsa (don’t forget to press refresh directory on winscp)


Step 4: install PeppyMeter

the complete documentation of PeppyMeter you can find here:

The next script install PeppyMeter and the modifications to use the meters as screensaver.

The first thing to do is to copy PeppyMeter as git clone and the modifications with startscript to /home/volumio/PeppyMeter

cd /home/volumio
git clone
pushd Install_peppy
cp -R -f PeppyMeterChanges/* /home/volumio/PeppyMeter/
sudo chmod +x /home/volumio/PeppyMeter/

at next, python3 with pygame will be installed and some dependencies for the new VOLUMIO interaction:

sudo apt-get install python3-pip
sudo apt-get install python3-pygame
sudo python3 -m pip install socketIO-client
sudo apt install libjpeg-dev zlib1g-dev
sudo python3 -m pip install cairosvg

To check all dependencies are install successfully start python3 with:


and run the command inside the python interpreter:

import pygame
from socketIO_client import SocketIO
import cairosvg
from PIL import Image

If no error showing up all is ok. Exit from python with


Download as Plugin:

(it’s all inclusive, nothing other is needed)
Version 2.2.1 (2024.06.10)

Be sure you have installed the TouchScreen PlugIn before!
To install the peppy_screensaver plugin create a new folder in /home/volumio and copy the content of zip file and switch into this folder and run:

volumio plugin install

!! Important !! Do you want update from a previous version < 1.5.0, please start with a new fresh Volumio original image or a factory reset. Otherwise an installed pygame will not be replaced. Install the original TouchScreen-Plugin at first.
Please restart after the plugin peppy screensaver is installed

What’s new in version 2.2.1:

  • fix stop screensaver on title end
  • add volume fadeIn also for spectrum
  • add animation on startup and on close of screensaver
  • add the possibility to change the position of screensaver window if it smaller then screen
  • disable cache mode per default for systems with installed memory smaller then 4Gb


  • compatible with updated socketIO of Volumio > 3.661
  • fix some little issues with buildin templates


  • complete spectrum templates for all resolutions
  • add an option for USB-DAC’s to prevent abbort playing with spotify
  • add the possibility to disable screensaver explicit for Spotify
  • add transitions between different albumarts and different styles in random mode for a better look
  • add check for list mode, are all sections available which you want use
  • upper and lower character now allowed in meter sections and list mode
  • add UI option for cache size configuration (default is now 20 different meters) to use also bigger meter folders
  • exit peppy meter screen now also when music ends
  • fix some graphical artefacts on random mode with title change


  • fix title info change issue
  • convert to pygame 2.6 with arm neon fpu support (hardware acceleration) based on SDL2 for Raspberry pi3/4/5
  • all dependecies (peppyalsa, pygame2, cairosvg, socketIO) now precompiled for Raspberry pi3/4/5
  • therefore no more compilation at installation time, no developer libraries needed → very easy installation


  • add Airplay integration
  • fix some graphical issues for random mode on title change
  • performance optimizations


  • fix Spotify stops playing in combination of PeppyMeter and some USB-DAC’s
  • external stop of PeppyMeter now possible with deletion of /tmp/peppyrunning
  • disable of screensaver function available, with timeout = 0


  • better compatibility with FusionDSP
  • PeppyMeter is running now after an installed DSP, so the meters are synchron with audio if a DSP enabled
  • Spotify now working in combination with DSP
  • for RaspberryPi peppyalsa is precompiled included (no more buildessentials and compiling needed)
  • Custum Meters you can put now outside the installation folder here:



Step 5: install autostart and UI integration

not more needed with plugin installation

Many hours I have search a solution to start a program as screensaver without install an external additional screensaver program. The only one idea that I had, was create a crontab with timeout value from VOLUMIO. But the crontab time resolution is only per minute (the task is always triggered on full minute), not per second. Have you set 120 sec in VOLUMIO the task starts between 1…2 minute. I think thats ok, not optimal but ok.
The crontab entry is created, when you press play and removed when you press pause. I start a little bash script, that only start python if it not already running, to avoid multiple python tasks. To be on the safe side, i erase the crontab at volumio start.
The crontab is already installed with the Install_peppymeter script

sudo apt-get install cron

Also the autostart entry to clear the crontab list is already created in /etc/rc.local:

crontab -u volumio -r

The last install script expand the touchscreen plugin with some GUI entries to select a meter, and add the lines for creation/delete of crontab entries, when you start play or pause.
You can select your active meter folder for your resolution after the right custom folder is copied. The set of screen resolution is only needed for the use of custom folder. If you use the standard folder (small, medium, large, wide) the screen resolution is ignored.
The needle cache is a new feature from peppy.player to prevent a memory leak from python. This use more memory so that the switch in random mode is faster and no calculation on every switch is needed. Please deactivate this feature on a Raspberry with 1GB RAM and a connected display with 1920x 1080 or 1280x800, otherwise the memory is overflow.
The new VU-Meter type list gives you the possibility to use not all available meters in one folder. Have you select the right folder and the settings are saved, press the info icon to see the list of available meters to copy and paste.

Download: (updated 2021.08.22) not more needed with the plugin version (8.1 KB)

To use the install script copy the Change_touchscreen folder to /home/volumio and make the executable with:

chmod +x /home/volumio/Change_touchscreen/

and start with:


I think you need a restart now.

  • set the VOLUMIO Screensaver (touchscreen plugin settings) to 60 or 120 seconds and
    !!! Important !!!
    set option for ‘No screensaver while playing’

  • check now if cron entry correct created when you press play and removed when you press pause with

crontab -l

Now it’s time for a first test, start manually with:

cd /home/volumio/PeppyMeter
export DISPLAY=:0

If all is ok, press play. :wink:
If this working wait for a automatic start after your sceensaver timeout.


Step 6: VOLUMIO interaction

For the VOLUMIO interaction is now used the socketIO API with event triggered view of albumart, playinfo, time and framerate (statemachine.js is not more modified)

It is working now with the follow services:

  • local source on USB or internal share
  • medienserver on nas
  • Tidal, Qobuz, Spotify
  • Webradio
  • Airplay

For Spotify
The installed Spotify plugin needs a little change to work with peppymeter. This Plugin don’t use the alsa configuration from asound.conf. It have a config file that’s hardcoded to the output device.
open the file:
and change the output_name to spotify

output_type = alsa
#output_name = ${outdev}
output_name = Spotify

With this change a separate pipe for Spotify is used. This pipe is defined in asound.conf and very tricky.

Congratulations, it’s done :yum:

All the install scripts make a backup of all expanded original files into the install folders. :wink:

Thanks a lot to peppy.player for the excellent cooperation and his many adjustments to give me the possibility to create a VOLUMIO integration without changes of original code, an important requirement to create a plugin for an easy installation.

What’s now included per standard:

  • add an option in config.txt to set the framebuffer dimension, it’s needed to draw an fullscreen background (for me is set to 1920x1080)
  • support for custom folders to place additional meters and backgrounds
  • new layer for backgrounds to use custom screen resolutions
  • to use a smaller VU-meter as the screen resolution its now possible to set the position of meters
  • to interrupt the screensaver the touch event from display is used
  • many call back functions to implement additional code for the VOLUMIO interaction

At last I have compare both installations, Jessie and Buster, and find out, the performance on a rotate fullHD display with Buster Beta is much better as on a Jessie environment. The scrolling with Chromium is smoother and PeppyMeter runs excellent. I don’t know exactly why, but I think the graphic driver is much better now.

have fun :yum:


You have done a great job! And a very detailed how-to.
But you have to warn other users that:
It won’t work with all sources (not with Spotify and Spotify connect).
It will prevent Volumio to update.
I suggest you to work with Volumio buster and use the new alsa pipeline.
I have a working plugin that install peppyalsa and peppymeter to work with it.
It also provides a selector for meters in the plugin settings.

It will be great to integrate this with peppymeter plugin from balbuze. To be compatible with new volumio version 3. For sure a lot of users will use this. At least me for sure I will :slight_smile:


Hi balbuze,
I didn’t want to bring the installation to the fore so much. An add-in is always better. But it is certainly no longer worthwhile for the current Volumio version.
Rather, I wanted to show the changes to PeppyMeter to have a flexible ScreenSaver when using high display resolutions. And I wanted to show the possibility of interacting with Volumio. Since all new functions are optional parameters, normal use is also possible with this change. The ideas could also be used for your add-in.
I didn’t want to create a new, similar add-in.

1 Like

Good job 2aCD,

it shows just what can be achieved. I can see that people would want to install this plugin regardless of it preventing Volumio updates … btw, this Volumio policy is to ensure that people can enjoy the core Volumio experience seamlessly. Going forward, it seems obvious to me that you should embrace the ALSA changes in the current Volumio change from 2 to 3, as I would expect that the vast majority of Volumio users to make the upgrade.

Again, well done, and I’ll follow your plugin with interest. :grinning:

1 Like

Here’s the one that I created (with 2aCD help). Switched to Pi4 for now.


Hello, may i ask if is possible to make little bit quicker response of needle as you have ? For me it looks little bit lazy, maybe some modification is needed, or parameter set. I am on Raspi 4 Many thanks

Yes it’s possible.
at first set in asound.conf

decay_ms 400

and then in config.txt in data_source section

smooth.buffer.size = 8

or lower, then the meters are quicker


2aCD many thanks, works perfectly !

ready for housing

I’m glad to hear that’s work.
Now I’m ready with an update package with some improvements. First of all, I would like to thank Andy_Yong for the persistence in testing the non standard configuration.
What’s new with this update:

  • new config parameter in sdl.env section to use standard displays without touch and without mouse
mouse.nomouse = 1
  • interrupt the peppy meter screen also with press the pause button on your smartphone app
  • playinfo and albumart now also working with special characters in title or album
  • new config parameter to use other fonts for Chinese or Thai
font.path = /usr/share/fonts/truetype
font.light = /Lato/Lato-Light.ttf
font.regular = /Lato/Lato-Regular.ttf
font.bold = /Lato/Lato-Bold.ttf
# for Thai ---
#font.light = /tlwg/Laksaman.ttf
#font.regular = /tlwg/Laksaman.ttf
#font.bold = /tlwg/Laksaman-Bold.ttf
# for Chinese ---
#font.light = /arphic/ukai.ttc
#font.regular = /arphic/ukai.ttc
#font.bold = /arphic/ukai.ttc
  • remove the remarks witch font are active
    this are installed with volumio, no additional fonts needed
  • optimized timing to change the albumart while the meters running

This update is already included in all downloads.


Thanks again to 2aCD for helping us to create this. Here are some of his work on my system.


Here’s the 2aCD’s screen saver in action.


May i please very polite ask if soomeone would be able to create this awesome VU design, i think just background would be OK

I am not so good in graphics

1 Like