94 lines
3.4 KiB
Markdown
94 lines
3.4 KiB
Markdown
# AGENTS.md
|
|
|
|
Operational guide for AI agents working on this repository.
|
|
|
|
## Remote machine
|
|
|
|
The plugin runs on **jozz** (`vini@jozz`). SSH access is pre-configured; no password needed.
|
|
|
|
```bash
|
|
ssh vini@jozz "some command"
|
|
```
|
|
|
|
## Deploy cycle
|
|
|
|
After editing any file under `plugin/`, commit, push, then run on jozz:
|
|
|
|
```bash
|
|
git push && ssh vini@jozz "bash -s" <<'EOF'
|
|
git -C "$HOME/skeledance" pull
|
|
cp -r "$HOME/skeledance/plugin/." "$HOME/.local/share/plasma/wallpapers/com.vini.dancingcharacter/"
|
|
export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
|
|
qdbus6 org.kde.plasmashell /PlasmaShell org.kde.PlasmaShell.refreshCurrentShell 2>&1
|
|
echo "done"
|
|
EOF
|
|
```
|
|
|
|
The `qdbus6` call hot-reloads QML. For HTML/CSS/JS changes the page reloads automatically. If visuals look wrong after deploy, wait a few seconds — WebEngine takes a moment to reinitialize.
|
|
|
|
## Services on jozz
|
|
|
|
### music-light
|
|
|
|
Reads the current track via `playerctl`, extracts the dominant album color, and exposes it over HTTP.
|
|
|
|
```bash
|
|
# Status
|
|
ssh vini@jozz "systemctl --user status music-light.service"
|
|
|
|
# Restart (needed after updating luz-musica.py)
|
|
ssh vini@jozz "systemctl --user restart music-light.service"
|
|
|
|
# Logs
|
|
ssh vini@jozz "journalctl --user -u music-light.service -n 30 --no-pager"
|
|
```
|
|
|
|
Endpoints (all on `127.0.0.1:8765`):
|
|
|
|
| Path | Description |
|
|
|------|-------------|
|
|
| `GET /current` | Returns `{"art_url": "...", "rgb": [r, g, b]}` for the playing track |
|
|
| `GET /art?t=` | Proxies the album art image bytes (use query string for cache-busting) |
|
|
|
|
**CORS**: `Access-Control-Allow-Origin: *` is set on all responses. Required because `dancer.html` is loaded from `file://`.
|
|
|
|
**Deploying changes to luz-musica.py**: `scp` the file, then restart the service. The repo at `~/music-light` on jozz may be behind; always `scp` directly.
|
|
|
|
```bash
|
|
scp /home/ltadeu6/Projetos/Codigo/music-light/luz-musica.py vini@jozz:~/music-light/luz-musica.py
|
|
ssh vini@jozz "systemctl --user restart music-light.service"
|
|
```
|
|
|
|
### cava-server
|
|
|
|
Started automatically by the wallpaper via `cava-start.sh` on load. Reads CAVA audio bars from stdin and streams them as SSE on `127.0.0.1:5555`.
|
|
|
|
```bash
|
|
# Check if running
|
|
ssh vini@jozz "pgrep -a python | grep cava"
|
|
|
|
# Restart manually if bars stop animating
|
|
ssh vini@jozz "bash ~/.local/share/plasma/wallpapers/com.vini.dancingcharacter/contents/ui/cava-start.sh &"
|
|
```
|
|
|
|
## Debugging JS errors
|
|
|
|
Add a `onJavaScriptConsoleMessage` handler to `main.qml` to capture JS errors to a file:
|
|
|
|
```qml
|
|
onJavaScriptConsoleMessage: function(level, message, lineNumber, sourceID) {
|
|
var logDs = Qt.createQmlObject('import org.kde.plasma.plasma5support as P5S; P5S.DataSource { engine: "executable" }', webView)
|
|
logDs.connectSource("echo '[skeledance] " + message.replace(/'/g, '') + " :" + lineNumber + "' >> /tmp/skeledance_console.log")
|
|
}
|
|
```
|
|
|
|
Then read on jozz: `ssh vini@jozz "cat /tmp/skeledance_console.log"`.
|
|
|
|
**Remove the handler after debugging** — it creates a new QmlObject per message and causes performance issues.
|
|
|
|
## Known WebEngine constraints
|
|
|
|
- `fetch()` to `http://` works from `file://` pages when `localContentCanAccessRemoteUrls: true` is set in QML.
|
|
- `<img src="http://...">` also works with `localContentCanAccessRemoteUrls: true`, but the server must include `Access-Control-Allow-Origin: *`.
|
|
- `CSS background-image: url('http://...')` is blocked — use `<img>` or `fetch()+blob URL` instead.
|
|
- `img.src` with `file:///` paths works when `localContentCanAccessFileUrls: true` is set.
|