Project with PeppyMeter Screensaver Plugin for VOLUMIO v2.9xx and 3.0xx buster

Hi together.

I would like to share here my experiences with the FullHD AMOLED display from waveshare with VOLUMIO.
The point is, it’s a 1080x1920 display and not a 1920x1080. I have learned, that’s not the same. Per default this display runs in portrait mode an not in landscape. You can rotate it 90 degree, but it’s not a hardware rotation, it’s a hard work for the GPU to rotate all content. A smooth scrolling is not more possible with chromium.
I have found some performance optimizations for chromium to work better with the rotated screen. Also implemented is the css modification of UI to show better in landscape from here:
Contemporary optimizations for small or large landscape displays

The next issue on a PI4 with this display is a interference between hdmi with 1920x1080 and WiFi. I had lost connections and a flicker display.
I didn’t know the context until I found the following:

Pi4 WiFi not working when resolution is set too high

With disabled WiFi - no more flicker on the screen. What’s that??
Ok I can live with that, I have now connect a cable, that’s stable without interferences.

At last I have search a screensaver to prevent the burnin of AMOLED. The standard screensaver give us unfortunately a black screen. I found PeppyMeter a wonderful animation of VU meter, a python program that’s write directly to the framebuffer.
Together with peppy.player, the developer of PeppyMeter we have modified the core engine to include it better to VOLUMIO and it’s usable now with many resolutions. With this modifications it’s configurable with some options to use also your own background pictures and styles.

Everything what I explain in this step by step guide for the PeppyMeter installation is now available as plugin for Volumio. You don’t need install it manually.

Supported screen resolutions at time:
320x240, 480x320, 1280x400
800x480, 1024x600, 1280x800, 1280x720
1920x1080, 1920x480

Plugin Download v1.2.0

on Post 7

But at first some pictures of implemented PeppyMeter in fullHD:

Thanks to @dvo for this new nice design:


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, you find it in plugins

  • for Buster you find a version here:

  • copy the folder into /home/volumio and install the plugin with:

cd /home/volumio/touch_display_1_2_1Busterbeta
volumio plugin install
  • if installation succsesfully, set GPU mem to 48MB and for the waveshare AMOLED rotation to 90°
  • 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)
Download: (952 Bytes)

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

chmod +x /home/volumio/Install_amoled/

and start it with:


After reboot you see the standard VolumioUI on the hdmi display. :yum:

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!

1 Like

Step 2: UI optimizations

The do also the follow modification:
5,5" with a 1920 resolution… the content it very small and unusable with volumio per default. You need a scale factor and a changed css file for better readable UI with a better smooth scrolling in chromium. The add some chromium options to the file /opt/

    --disable-smooth-scrolling \
    --disable-gpu-compositing \
    --enable-experimental-canvas-features \
    --enable-scroll-prediction \
    --disable-quic \
    --max-tiles-for-interest-area=512 \
    --num-raster-threads=4 \
    --enable-low-res-tiling \
    --enable-native-gpu-memory-buffers \
    --enable-gpu-rasterization \
    --enable-zero-copy \
    --use-gl=egl \
    --force-device-scale-factor=2.0 \
    --disk-cache-dir='/tmp/chromium' \
  • in addition the chromium cache folder is changed to ramdisk (better for SD-Card)
  • for AMOLED the scale-factor is here set to 2.0.
    Edit: With latest Volumio version 2.882 a new TouchScreen plugin is available with the possibility to set this value with an UI option, but unfortunetally 200% is maximum. It is the minimum for the AMOLED display but it works.

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 have 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. The peppylsa integration on a Volumio is a little bit different to the new alsa pipline of Volumio buster
The installer detect your version and install the right way.

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. The same procedure also in Volumio buster.

For VOLUMIO 2.x:

This Volumio integration works now (since latest update from 15.07.2021) with an asound.conf.tmpl. The installer copied it to /volumio/app/plugins/audio_interface/alsa_controller This template is used to create an active asound.conf in /etc/ depend on your output device settings in Playback Options. If you change your sound card or change the mixer a new asound.conf is created.
No more manually edit of asound.conf is needed.

this is a sample for created /etc/asound.conf:

pcm.!default {
	type plug
	slave.pcm "peppyalsa"
ctl.!default {
   	type hw
   	card 2
   	device 0

# input from Spotify / airplay
pcm.peppyalsa {	
	type plug
	slave.channels 4
	slave.pcm {
		type multi
		slaves.a.pcm "mpd_alsa"
		slaves.a.channels 2
		slaves.b.pcm "mpd_peppyalsa"
		slaves.b.channels 2
		bindings.0 { slave a; channel 0; }
		bindings.1 { slave a; channel 1; }
		bindings.2 { slave b; channel 0; }
		bindings.3 { slave b; channel 1; }
	ttable.0.0 1
	ttable.1.1 1
	ttable.0.2 1
	ttable.1.3 1

# input from MPD for sound card (direct DSD only working with type hw)
pcm.mpd_alsa {
   	type hw
   	card 2
   	device 0

# input from MPD for peppyalsa	
	type meter
	slave.pcm "dummy"
	scopes.0 peppyalsa
pcm_scope.peppyalsa {
	type peppyalsa
	decay_ms 400
	meter "/tmp/myfifo"
	meter_max 100
	meter_show 1
	spectrum "/tmp/myfifosa"
	spectrum_max 100
   	spectrum_size 30
pcm_scope_type.peppyalsa {
   	lib /usr/local/lib/

pcm.dsp0 peppyalsa

pcm.mpd_alsa_deakt {
   	type softvol
   	slave.pcm "snd_card"
   	control {
        name "SoftMaster"
        card 2
        device 0
   	max_dB 0.0
   	min_dB -50.0
   	resolution 100

# sound card output
pcm.snd_card {
   	type hw
   	card 2
   	device 0

# null output
pcm.dummy {
   	type hw
	card Dummy
	device 0

# Control device for program compatibility.
ctl.snd_card {
   	type hw
   	card 2
   	device 0

Buster works with a separat file thats included in an existing 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 {
		type		"alsa"
		name		"mpd_alsa"
		device		"mpd_alsa"
		dop			"no"

audio_output {
        type        "alsa"
        name        "mpd_peppyalsa"
        device      "mpd_peppyalsa"
        dop         "yes"

Now change the sound card in VOLUMIO UI settings to HDMI and switch back to your sound card. With this operation the template file is copy to /etc
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.

The install script add this line to /opt/ before the line starts with openbox-session

mkfifo -m 646 /tmp/myfifo

Download for VOLUMIO and Buster v3.xx:
The installscript ‘’ is included in the complete download in next post
To use the install scripts copy the Install_peppy folder to /home/volumio and make the executable

chmod +x /home/volumio/Install_peppy/

and start it with


Please reboot after the installation.
If you play music after reboot with the follow error:
please change the mixer type in playback options and wait until the music service (mpd) is restarted. Then try again. If the music play, can you switch back the mixer type.
The switch of mixter type generate a new /etc/asound.conf.

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

for VOLUMIO 2.x:

    sudo python3 -m pip install pip==19.1.1
    sudo mv /usr/lib/python3/dist-packages/pip-1.5.6.egg-info/ /usr/lib/python3/dist-packages/pip-1.5.6.egg-info_/
    sudo mv /usr/lib/python3/dist-packages/pip/ /usr/lib/python3/dist-packages/pip_/
    sudo python3 -m pip install socketIO-client
    yes | sudo python3 -m pip uninstall websocket websocket-client
    sudo python3 -m pip install websocket-client==0.53   
    sudo apt-get -y install libffi-dev
    sudo python3 -m pip install --upgrade Pillow==5.4.1 --global-option="build_ext" --global-option="--disable-jpeg"
    sudo python3 -m pip install cffi
    sudo python3 -m pip install cairocffi==0.9.0
    sudo python3 -m pip install cairosvg==2.2.0

for VOLUMIO 3.x

sudo python3 -m pip install socketIO-client
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 1.3.0 (2021.10.30)

To install the 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 of plugin, please deinstall the old plugin at first and install the new downloaded plugin again. Do you use the manually installation before, please start from new Image and install the original TouchScreen-Plugin at first

Download for manually Installation:
(updated 2021.08.22) (953.9 KB)

To use the install scripts copy the Install_peppy folder to /home/volumio and make the executeble with:

chmod +x /home/volumio/Install_peppy/

and start it with:


If the installation successfully running, copy the right custom folder with meters for your resolution to:

Download meters for manually installation
(updated 2021.10.30)
custom meter folder for 800x480, 1024x600, 1280x800, 1280x720, 1920x1080, 1920x480

This is the resulting folder structure:

(not all custom folder are needed)


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 in both files the output_name to peppyalsa

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

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:

1 Like

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:

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

1 Like

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.