Initial commit — DANCEBOT-9000 KDE Plasma wallpaper plugin

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-06-07 07:11:26 -03:00

2.5 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A KDE Plasma 6 wallpaper plugin — a dancing retrowave robot (DANCEBOT-9000) that reacts to currently playing music via playerctl. No build step, no dependencies to install; the plugin is deployed directly.

Plugin ID: com.vini.dancingcharacter
Install path: ~/.local/share/plasma/wallpapers/com.vini.dancingcharacter

Deploy / test cycle

# Install (or reinstall after edits)
./install.sh

# Remove
./uninstall.sh

After install, activate via: Right-click desktop → Configure Desktop and Wallpaper → Wallpaper Type → Dancing Character.

Plasma hot-reloads QML changes when you reinstall; for HTML/CSS/JS changes you may need to switch away and back to the wallpaper type to force a reload.

Runtime requirement: QtWebEngine QML module must be installed (e.g., qml6-module-qtwebengine on Debian/Ubuntu). playerctl must be running for the music ticker to show track info.

Architecture

plugin/
  metadata.json               # KPackage/KPlugin descriptor for Plasma 6
  contents/ui/
    main.qml                  # Plasma WallpaperItem — hosts everything
    dancer.html               # Self-contained animation (HTML + CSS + JS)

main.qml — the Plasma host

Declares a WallpaperItem with a full-screen WebEngineView pointed at dancer.html.
A Plasma5Support.DataSource with engine: "executable" runs playerctl metadata every 2 s and injects the result into the page with webView.runJavaScript("updateMusic(...)").
JavaScript is enabled; local file access and local storage are on/off respectively.

dancer.html — the visual layer

Pure HTML/CSS/JS, no external dependencies. All visuals are self-contained:

Layer	Technique
Starfield	`<canvas>` + `requestAnimationFrame`
Nebula blobs, grid floor, horizon	CSS animations
DANCEBOT-9000 robot	Pure CSS (divs + `@keyframes`)
Chest EQ bars & VU meter	JS-driven `requestAnimationFrame`
Music ticker	DOM text set by `updateMusic(artist, title)` (called from QML)
Dance style cycling	`data-dance` attribute on `<body>`, toggled by JS every 8 s

Tempo anchor: everything is keyed to 120 BPM (BEAT_MS = 500 ms). CSS animation durations for the robot parts use multiples/fractions of 0.5 s, 1 s, or 2 s.

Dance styles (cycle order): bounce → wave → shuffle → moonwalk → spin. CSS selectors like [data-dance="spin"] .robot { ... } override the default animations via !important.

2.5 KiB Raw Blame History