https://github.com/muddyblack/kde-audio-visualizer
Plasma 6 Desktop Widget to visualize played audio
https://github.com/muddyblack/kde-audio-visualizer
audio cava flake flakes honors kde-plasma-6 mpris2
Last synced: 4 days ago
JSON representation
Plasma 6 Desktop Widget to visualize played audio
- Host: GitHub
- URL: https://github.com/muddyblack/kde-audio-visualizer
- Owner: Muddyblack
- License: mit
- Created: 2026-05-14T21:11:14.000Z (20 days ago)
- Default Branch: main
- Last Pushed: 2026-05-22T13:15:34.000Z (12 days ago)
- Last Synced: 2026-05-22T15:45:43.721Z (12 days ago)
- Topics: audio, cava, flake, flakes, honors, kde-plasma-6, mpris2
- Language: QML
- Homepage:
- Size: 2.97 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Plasma Audio Wave Visualizer
A glassy audio visualizer plasmoid for KDE Plasma 6. Renders mirrored waveform that reacts to whatever is playing system-wide (via [cava]), alongside MPRIS track metadata, album art, transport controls, and a seekable progress bar.
## Features
- **5 visualizer styles** — Smooth Wave, Rounded Bars, Mirror Bars, Tech Line, Floating Dots
- **4 progress bar styles** — Glassy Sleek, Ultra Minimal, Glowing Pulse, Bold Pill
- System-wide reactive waveform (PipeWire via cava — not tied to any single player)
- MPRIS2 track info: title, artist, album art
- Transport controls (prev / play-pause / next) with customizable color
- Seekable progress bar with elapsed/total time
- Honors the active Plasma accent color (or set a custom color)
- Optional waveform fill + neon glow effect
- Optional background card with configurable color, opacity (via alpha), and corner radius
- Custom text and controls colors
- Customizable dock background color (supports alpha via color picker)
- No panel background — sits cleanly on any panel
## Requirements
- KDE Plasma **6.0+**
- [`cava`][cava] (audio bar generator)
- `flock` (from `util-linux`) and `pkill` (from `procps`) — both standard on virtually every Linux distro
[cava]: https://github.com/karlstav/cava
## Install
### Manual install (any distro)
```bash
git clone https://github.com/muddyblack/plasma-audio-visualizer.git
cd plasma-audio-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)
```nix
# flake.nix
{
inputs.audio-wave.url = "github:muddyblack/plasma-audio-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 KDE Store)
```bash
./pack.sh
# produces plasma-audio-visualizer-.plasmoid
```
## How it works
For a detailed explanation of the architecture and data flow, see the [Architecture Documentation](docs/workflow.md).
In short: the widget uses a small shell helper (`feeder.sh`) to run `cava` in the background and atomically writes the latest bars to `$XDG_RUNTIME_DIR/audio-wave-widget/bars`. The QML side polls that file at ~30 fps.
## Configuration
All settings are available via the widget's right-click → Configure menu:
| Setting | Description |
|---|---|
| **Visualizer Style** | Smooth Wave / Rounded Bars / Mirror Bars / Tech Line / Floating Dots |
| **Progress Bar Style** | Glassy Sleek / Ultra Minimal / Glowing Pulse / Bold Pill |
| **Number of Bars** | How many frequency bars cava outputs (8–128) |
| **Framerate** | Target refresh rate in Hz |
| **Sensitivity** | Cava amplitude multiplier |
| **Smoothing** | Noise reduction factor (0–1) |
| **Wave Color** | System accent or custom color |
| **Wave Glow** | Neon glow shadow on the waveform |
| **Fill Wave** | Transparent gradient fill under the waveform |
| **Line Width** | Stroke width for line-based visualizers |
| **Text / Controls / Dock Colors** | Each independently customizable |
| **Background Card** | Optional frosted card with custom color+alpha and corner radius |
| **Show MPRIS info** | Toggle album art, track title, artist, and controls |