A Different Audio Spectrum Analyzer for KDE Plasma

Contents

• Requirements
• Install the required dependencies
  • Arch Linux
  • Ubuntu
• Installation
  • Via KDE Store
  • Via Command Line
  • Via AUR
  • Drag panon widget to your panel
• Visual Effects
  • Debugging Shaders
• Troubleshooting
• Credits

Requirements

	Minimal version required
OpenGL / GLSL	3.0 / 1.30
QtQuick	2.0

Install the required dependencies

Arch Linux

sudo pacman -S qt5-websockets \
    python-docopt python-numpy python-pillow python-pyaudio python-cffi python-websockets 

Ubuntu

sudo apt-get install qml-module-qt-websockets \
    python3-docopt python3-numpy python3-pyaudio python3-cffi python3-websockets python3-pil 

Installation

Via KDE Store

1. Open the “Add Widgets” dialog of your desktop
2. Go to “Get New Widgets” in the bottom
3. Click “Download New Plasma Widgets”
4. Search for “panon”
5. Click “Install”

Via Command Line

git clone https://github.com/rbn42/panon.git
cd panon/kde
# Download SoundCard and hsluv-glsl
git submodule update --init
# To install
kpackagetool5 -t Plasma/Applet --install plasmoid
# To upgrade. Backup your modified shaders before upgrading.
kpackagetool5 -t Plasma/Applet --upgrade plasmoid

Via AUR

plasma5-applets-panon and plasma5-applets-panon-git are available for ArchLinux.

Drag panon widget to your panel (eg. latte-dock).

Visual Effects

Visual effects are stored in kde/plasmoid/contents/shaders/. You can create your own visual effects in ~/.config/panon/.

A visual effect consists of a single main shader file with its name ended with .frag, like solid.frag, or a folder, like spectrogram/, with the following struture.

• effect folder
  • image.frag, is the main shader file, must exist.
  • buffer.frag, draws to the buffer, is optional.
  • hint.html, shows hints to the user, is optional.
  • meta.json, declares the arguments for the user, is optional.

Shader API and Shadertoy.com

What is a shader? And a turtorial for beginners.

Shadertoy.com is a cross-browser online community and tool for creating and sharing shaders through WebGL, from where you can find many wonderful works shared by kind people. By default, these works are licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. And here is an interactive tutorial for shadertoy.com.

Panon’s shader API is designed to be similar to shadertoy.com. Many of the works can be copied directly to panon, providing you add #version 130 to the shader file’s first line. example-shadertoy.frag is such an example. But all these works were designed to show in browsers, so they won’t look good in tiny space like a panel.

These shadertoy-like uniforms are provided.

Uniform Name	Description
iResolution	Width and heigh of the applet
iTime
iTimeDelta
iFrame
iMouse	Mouse position
iChannel0	Wave data: Red channel corresponds to left audio channel, green channel corresponds to right audio channel.
iChannel1	Spectrum data: Red channel corresponds to left audio channel, green channel corresponds to right audio channel.
iChannel2	Buffer data: Output of buffer.frag, has the same width and height of the applet.
iChannelResolution	Input channels’ width and height

Both image.frag (or the single main shader) and buffer.frag can access these uniforms.

Arguments

meta.json contains a JSON list like this.

{
  "arguments":[{
    "name":"arg_name",
    "default":1,
    "type":"int"
  }]
}

“type” can be “int”, “double” or “bool”. A decalred argument can be used in a shader file’s macros, like

#define NAME $arg_name

Which will be translated into

#define NAME 1

Debugging Shaders

Neither KDE Panel nor Latte-Dock shows the errors caused by the shaders. To catch the error messages, you have install plasma-sdk, and start plasmoidviewer in a console.

cd ./kde/
#Providing plasma-sdk is installed
plasmoidviewer --applet ./plasmoid/

In plasmoidviewer, go to the configuration window and choose your own visual effect. Then plasmoidviewer will run your visual effect and show the errors, if exist, in the console.

Background transparency

To achieve background transparency, after installing panon, go to ~/.local/share/plasma/plasmoids/panon/contents/ui/main.qml in your home directory, alter the following part and add the line marked below:

   Plasmoid.preferredRepresentation: Plasmoid.compactRepresentation
++ Plasmoid.backgroundHints: PlasmaCore.Types.NoBackground

Troubleshooting

Credits

Files	Source	Licensed under
source.py and spectrum.py	adapted from PyVisualizer
hsv2rgb in utils.fsh	copied from GLSL-color.md
example-shadertoy.frag	copied from shadertoy	CC BY-NC-SA 3.0
firefly/image.frag	adapted from shadertoy	CC BY-NC-SA 3.0
example-shadertoy-fractal-tiling.frag	copied from shadertoy	CC BY-NC-SA 3.0