vini 1c1a854875 docs: CLAUDE.md — céu realista e tools/build_catalog.py

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015HtPHsTnDcLVSCiF5FGHZj

2026-07-19 10:52:06 -03:00

3 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)
    starcatalog.js            # Generated star data (Yale BSC) — see tools/build_catalog.py
tools/
  build_catalog.py            # Regenerates starcatalog.js from the Yale Bright Star Catalog

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
Realistic sky (stars + Milky Way)	`<canvas>`; real-time alt-az projection of `starcatalog.js` (2,887 Yale BSC stars) + seeded procedural Milky Way for the configured lat/long (default Toledo-PR). Static layer pre-rendered offscreen, bright stars twinkle per frame; reprojects every 30 s. Debug: `window.__skyTimeOffset` (ms) fast-forwards the sky
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.

3 KiB Raw Blame History