Plasma Audio Wave Visualizer

Features · Gallery · Settings Studio · Requirements · Install · How it works · Support

The widget follows system audio with cava and shows album artwork, track information, and playback controls from MPRIS players. Choose a ready-made look or tune one in the built-in settings studio.

The panel pill defaults to a music-reactive mini visualizer. Enable Layout → Track text → Scroll long titles to scroll overflowing pill text; Reduced motion keeps it still.

Track info groups selected fields into Song, Credits, Release and Playback sections. Tooltip gives a compact preview; Drawer opens a wider panel below the widget. Flip opens after hovering over the cover or song title for 350 ms, leaving playback controls and seeking unaffected. The info button remains available as a click backup; disable “Show flip info button” for hover-only. Leave the widget, press Escape or click × to return. Long details scroll, and volume stays with the playback controls. Choose Essentials, Credits or All details in one click, or Customize to select fields by group. Surprise me and daily looks preserve the track-info setup.

Online track information is off by default. Enable it in the settings studio’s Track info tab to send song title, artist, album and length to MusicBrainz and the artist name to English Wikipedia. Recording matches can add songwriters, composers, producers, performers, arrangers, version notes and ISRCs. Label, country and edition date appear only when a specific release is identified. Apple catalog fallback has a separate default-off switch: when enabled alongside online information, unmatched titles and artists can be sent to Apple’s public music catalog for album, genre, date and track details. Choose which fields to display. Player metadata takes priority; ambiguous matches are not guessed. Source links identify the catalog used. Results are cached locally for 24 hours, separately by song and provider setting. Shared appearance presets cannot enable either online setting.

Features

• Dozens of ready-made presets: Choose from cards, artwork backgrounds, posters, compact strips, panel icons, and more.
• Many audio visualizers: Waves, bars, particles, rings, and other styles react to system audio captured by cava.
• Visualizer only: Choose the Visualizer only preset for transparent Neon Terrain, or select Arrangement → Visualizer only with any effect. Resize and position the widget on your desktop to complement your wallpaper.
• Live settings studio: Preview changes as you customize layouts, colors, visualizers, progress bars, artwork, and motion.
• Make and share presets: Save your own looks and exchange them as JSON with the Plasma, Quickshell, and browser studios.
• Custom QML styles: Import your own visualizers and progress bars from trusted local QML files.
• Album art and track details: Show cover art, title, artist, playback time, and an optional artwork backdrop.
• Playback controls: Play, pause, skip tracks, and seek through MPRIS players when supported.
• Lyrics and karaoke: Show a synced line on the card or switch to a lyrics-only view, with local files and optional online lookup.
• Plasma and Hyprland: Use the widget on KDE Plasma 6 or with Quickshell on Hyprland.

Gallery

Real captures of the actual QML widget with sample playback. The gallery has all 28 presets.

Cards

Surfaces & Players

Stacked Glass

Posters & Heroes

Orbits & Lyrics

Slim & Minimal

Panel Layouts

Make it yours

Pick from many visualizers, change the layout and colours, add lyrics, and preview changes as you go. You can save your own presets and share them as JSON between the widget and the browser studio.

In a Plasma panel, Behaviour → Panel placement → Display → Automatic shows the selected card directly when the widget has enough width and height, including in large side panels. Small panels fall back to the pill or icon; Pill / icon keeps that compact presentation at any size. Automatic orientation turns the pill along a side panel and rotates a full card when that lets it fit. Choose Upright, Rotate left, or Rotate right under Behaviour → Panel placement to override it. Popups stay upright. Panel pill and Card / popup have separate designs and live previews. Choose Hover, Click or Both under Layout to open the compact widget's popup, and add playback controls under Buttons. Apply saves both designs. Desktop widgets keep their usual editor.

Use popup look / Use pill look copies the other design’s colours, artwork and effect styles into the selected design. The pill enables the copied visualizer and progress styles. Each view keeps its layout and playback controls. Apply saves the copy; Discard restores the previous designs. Export still shares the selected look as JSON v1, including after syncing. Legacy preset imports remain supported.

Use the pin button in the popup card’s bottom-right corner to keep it open above other windows, even after clicking elsewhere. Click the pin again or press Escape to close it.

Glass and liquid popups support Blur behind card under Card / popup → Appearance → Card. Plasma supplies KWin with a rounded mask while its theme frame and shadow are hidden. KWin’s Blur effect controls the actual strength; the wallpaper slider adjusts the preview. New popup designs enable this by default; saved choices are preserved. This uses Plasma’s internal SVG background item, with a borderless fallback if that item is unavailable. A shell helper keeps one small mask file per widget in the session runtime directory, updated only when its geometry changes. No C++ plugin, compilation or extra packages are needed.

The studio is built into both the Plasma and Quickshell settings. The browser version lets you explore the same looks before installing. See how preset sharing works.

Requirements

• KDE Plasma 6.0+ (or Quickshell for Hyprland)
• cava — the audio bar generator
• A running PipeWire or PulseAudio server (the widget auto-detects which one cava can capture from)
• flock (from util-linux) and pkill (from procps) — standard on virtually every Linux distro

Install

Full setup options and configuration details are in the installation guide.

KDE Plasma

Manual (any distro)

git clone https://github.com/Muddyblack/audio-wave-visualizer.git
cd audio-wave-visualizer
kpackagetool6 -t Plasma/Applet -i package
# or, to update an existing install:
kpackagetool6 -t Plasma/Applet -u package

Then add the widget from Plasma's Add Widgets panel.

To remove:

kpackagetool6 -t Plasma/Applet -r org.muddyblack.plasmaAudioVisualizer

NixOS (flake)

# flake.nix
{
  inputs.audio-wave.url = "github:Muddyblack/audio-wave-visualizer";

  outputs = { self, nixpkgs, audio-wave, ... }: {
    nixosConfigurations.mybox = nixpkgs.lib.nixosSystem {
      modules = [
        ({ pkgs, ... }: {
          environment.systemPackages = [
            audio-wave.packages.${pkgs.system}.default
            pkgs.cava
          ];
        })
      ];
    };
  }
}

Package as .plasmoid (for the KDE Store)

make pack
# produces plasma-audio-visualizer-<version>.plasmoid

Hyprland / Quickshell

From this checkout, run:

make view-hyprland

The widget appears on your desktop. Right-click it for Settings and press Ctrl+C in the terminal to stop it. The launcher also works alongside Caelestia. See the installation guide for login startup, monitor placement, NixOS, and settings access when the widget is hidden.

Windows (working, not yet tested on real Windows)

A PySide6-based overlay app that renders the same visualizer, with WASAPI loopback capture in place of cava — see docs/windows.md for how it is hosted, how to run it (make run-windows) and exactly what has and has not been verified. There is no settings UI on Windows yet, and the always-on-bottom window behaviour has only been reasoned about, not run on a Windows machine. Microsoft Store distribution is still planned, not built.

How it works

For a detailed explanation of the architecture and data flow, see the Architecture Documentation.

In short: a small shell helper (feeder.sh) runs cava in the background and writes each changed frame to $XDG_RUNTIME_DIR/audio-wave-widget/. The QML side reads it in-process at the configured frame rate, drops to 2 FPS after a few seconds of silence, and stops polling while the widget is hidden.

Waveforms and Orbit rings use bounded fragment-shader families on supported scene graphs, with Canvas fallbacks for software sessions. Particle state advances on the audio clock. Software covers use a static crop/mask fallback. After editing a shader, run make shaders.

Regression tests (synthetic audio, no desktop or sound server needed): nix develop --command python3 tests/run.py.

Check Python lint and formatting with make lint-python; apply formatting with make format-python. Ruff is also available in nix develop, or directly through nix run .#ruff -- check . and nix run .#ruff -- format .. The Ruff workflow runs both checks on pull requests and pushes, using the version pinned by flake.lock.

Help and project docs

• Installation, configuration, and troubleshooting
• Full preset gallery
• Lyrics and karaoke
• Custom visualizers
• Architecture and development workflow

Support

If you enjoyed it feel free to show appreciation with a github star or some coin :)

Credits

• cava provides audio capture for the visualizers.
• LRCLIB provides optional synced lyrics.
• lumaribbon inspired visual ideas and studio concepts.

Thanks to the creators and contributors of these projects. This project is licensed under GPL-3.0.