LibVisual Desktop Background

Audio-reactive wallpaper plugin for KDE Plasma 6. Renders real-time visualizations on the desktop background, driven by live microphone or audio input via PulseAudio/PipeWire.

Demo Video

▶️ Watch here: https://vhsky.cz/w/vnuNcJBrdng6z1J6Em1NED

Version 1.1.5

Features

• 20 built-in visualization types, all audio-reactive
• GPU-accelerated Mandelbrot zoom via GLSL shader (NVIDIA/AMD/Intel)
• Real-time FFT spectrum analysis using FFTW3
• PulseAudio/PipeWire integration — reads from any capture source
• Configuration dialog with live audio level meter and per-type animated preview
• Input-only device selector — monitors and loopback sources are excluded
• Color scheme selection (Rainbow, Blue Gradient, Fire, Plasma, Monochrome)
• Status indicator overlay (optional)

Visualization Types

#	Name	Description
0	Spectrum Analyzer	64-bar FFT spectrum, height and color driven by frequency magnitude
1	Waveform	Full-screen dual sine wave, amplitude tracks audio peak
2	Lissajous	XY oscilloscope Lissajous figures, reactive to bass/treble
3	Circular Burst	50 concentric circles pulsing with frequency bands
4	Circular Spectrum	64 radial bars arranged in a circle
5	Plasma	8 animated colored blobs with sine-driven motion
6	Starfield	120 stars flying outward from center, speed scales with peak
7	Fireworks	Particle bursts spawned on bass beats
8	Matrix Rain	Falling green characters, speed driven by treble
9	DNA Helix	Two intertwined sine strands with connecting rungs
10	Particle Storm	150 particles orbiting in audio-reactive paths
11	Ripple Effect	Expanding concentric rings, radius and opacity driven by bass
12	Tunnel Vision	Rotating nested rectangles converging to center
13	Spiral Galaxy	200 dots in three rotating spiral arms
14	Lightning	Recursive jagged bolts spawned on peaks
15	Mandelbrot Zoom	GPU-rendered Mandelbrot set, zoom and iterations driven by audio
16	Geometric Dance	Five rotating polygons (triangle→octagon), scale with audio
17	Audio Bars 3D	FFT bars rendered in perspective projection
18	Kaleidoscope	8-segment radially mirrored animated pattern
19	ProjectM Visualizer	Milkdrop-compatible GPU presets via libprojectM (4 000+ presets)

ProjectM Visualization

Type 19 renders Milkdrop-compatible GPU presets via libprojectM. It requires an OpenGL/EGL backend — which is the default under KDE Plasma on Wayland.

Install presets (Debian/Ubuntu):

sudo apt install projectm-data libprojectm-dev

Default preset path: /usr/share/projectM/presets. Additional preset packs (4 000+) can be placed in any directory and selected in the config dialog. The config dialog lets you pick a preset, enable shuffle, and set the display duration.

On rare Vulkan-only setups, set QSG_RHI_BACKEND=opengl before starting plasmashell. Under standard KDE Plasma + Wayland (EGL) no extra configuration is needed.

Dependencies

Debian/Ubuntu

sudo apt install cmake qt6-base-dev qt6-declarative-dev \
                 libkf6coreaddons-dev libkf6i18n-dev \
                 libkf6package-dev plasma-workspace-dev \
                 libpulse-dev libfftw3-dev \
                 pipewire-pulse pulseaudio-utils
# Optional: ProjectM visualization (type 19)
sudo apt install libprojectm-dev projectm-data

Fedora

sudo dnf install cmake qt6-qtbase-devel qt6-qtdeclarative-devel \
                 kf6-kcoreaddons-devel kf6-ki18n-devel \
                 kf6-kpackage-devel plasma-workspace-devel \
                 pulseaudio-libs-devel fftw-devel pipewire-pulseaudio
# Optional: ProjectM visualization (type 19)
sudo dnf install projectM-devel

Arch Linux

sudo pacman -S cmake qt6-base qt6-declarative \
               kcoreaddons ki18n kpackage plasma-workspace \
               libpulse fftw pipewire-pulse

Build and Install

git clone https://github.com/VitexSoftware/kde-desktop-background-libvisual
cd kde-desktop-background-libvisual/plasma-wallpapers/org.kde.libvisual
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX="$HOME/.local"
make -j"$(nproc)"
sudo make install

Restart Plasma to load the plugin:

killall plasmashell && plasmashell &

Build Debian package

sudo apt install debhelper devscripts
./build_deb.sh
sudo dpkg -i ../kde-desktop-background-libvisual_*.deb

Activating the Wallpaper

1. Right-click the desktop → Configure Desktop and Wallpaper…
2. In the Wallpaper Type dropdown select LibVisual Background
3. Click Apply

The configuration panel appears below the selector. From there you can:

• Input Device — choose from detected microphone/capture sources (output monitors are excluded)
• Sensitivity / Smoothing — tune the audio reactivity
• Visualization Type — pick from 20 types; the preview updates live
• Color Scheme — global color palette used by most visualizations
• Show Status Indicator — small overlay showing dB level and backend state

Audio Level Meter

The level meter in the config dialog reads from the real PulseAudio/PipeWire backend. When a device with no microphone connected is selected (e.g. onboard audio without a mic plugged in), the meter shows −60 dB (silence). It updates in real time as you switch devices or plug in a microphone.

Testing

# Full build, install, and diagnostic check
./test.sh

# Config UI and schema validation
bash test_config.sh

# AudioVisualizer QML module install check
bash test_qml_module.sh

# System diagnostics (plugin files, symbols, PulseAudio sources)
./diagnostics.sh
# or quick mode (skip ldd / journal):
./diagnostics.sh --quick

Troubleshooting

No audio detected / meter stays at −60 dB

1. Verify the audio services are running:

   systemctl --user status pipewire pipewire-pulse
   

   If pipewire-pulse is inactive, start it:

   systemctl --user start pipewire-pulse
   

2. Check available capture sources (monitors are expected to be absent from this list):

   pactl list short sources | grep -v monitor
   

3. If the list is empty, no capture device is connected or the driver is not loaded:

   # PipeWire view — look for nodes with media.class = Audio/Source
   pw-cli list-objects Node | grep -A5 'Audio/Source'
   # ALSA view
   arecord -l
   

4. Select the correct device in the wallpaper configuration dialog and check the level meter.

Wallpaper shows a black or blank screen

1. Verify the plugin was installed correctly:

   ./diagnostics.sh --quick
   

2. Check the Plasma journal for QML errors:

   journalctl --user -n 100 | grep -i libvisual
   

3. Restart Plasma:

   killall plasmashell && plasmashell &
   

Mandelbrot Zoom shows blank

The Mandelbrot visualization requires a compiled GLSL shader (mandelbrot.frag.qsb). This is built automatically when Qt6 ShaderTools is available. Check:

ls ~/.local/share/plasma/wallpapers/org.kde.libvisual/contents/shaders/

If mandelbrot.frag.qsb is missing, install qt6-shader-baker and rebuild.

Audio Backend

The plugin uses the native libpulse async API and works transparently with both PulseAudio and PipeWire. No detection or switching logic is needed: when PipeWire is running, its pipewire-pulse service implements the full PulseAudio protocol and exposes PipeWire nodes as PA sources.

How capture works

PipeWire / PulseAudio
        │
   pa_threaded_mainloop  ←── owns its own OS thread
        │
   pa_context → pa_stream (PA_STREAM_START_CORKED)
        │
   streamReadCb() callback — PA thread
        ├─ normalize int16 → float
        ├─ compute RMS → dB level
        ├─ run FFTW r2c FFT → 256-bin spectrum
        └─ QMetaObject::invokeMethod(Qt::QueuedConnection)
                │
        onAudioProcessed() — Qt main thread
                └─ emit spectrumChanged / levelChanged / …
                        │
                    QML binding updates

All shared data (spectrum, waveform, decibels, level) is protected by a QMutex. Property getters lock the mutex before reading; the PA callback locks it only for the final move-assignment.

Device enumeration

getInputSources() opens a separate non-threaded pa_mainloop, connects a pa_context, and calls pa_context_get_source_info_list(). Sources with monitor_of_sink != PA_INVALID_INDEX are filtered out so only real capture devices appear in the device selector. This replaces the former pactl subprocess.

PipeWire requirements

# Verify PipeWire services are running
systemctl --user status pipewire pipewire-pulse

# List nodes as seen by PipeWire (all audio objects)
pw-cli list-objects Node | grep -A3 'media.class.*Source'

# Same view via PulseAudio compat layer
pactl list sources short | grep -v monitor

If pipewire-pulse is not active, libpulse connections fail and the meter stays at −60 dB. Start it with:

systemctl --user start pipewire-pulse

Project Structure

plasma-wallpapers/org.kde.libvisual/
├── audiovisualizer.cpp/h   # Async libpulse capture + FFTW backend (QML element)
├── plugin.cpp/h            # Plasma wallpaper plugin entry point (KPluginFactory)
├── CMakeLists.txt          # Build system
├── metadata.json           # KPackage metadata
└── contents/
    ├── config/main.xml     # KConfig schema (all settings with defaults)
    └── ui/
        ├── main.qml        # Wallpaper rendering – all 20 visualization types
        └── config.qml      # Configuration dialog – device picker, level meter, preview

License

GPL-3.0-or-later — see LICENSE

Contributing

1. Fork the repository
2. Create a feature branch
3. Run ./test.sh to verify the build
4. Open a Pull Request