repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

audio: design spec for popup redesign (pure audio.js + solid-dark mixer)

ba7f3ceac4ef676f776a68a94c60b511e2b05037

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Changed files (1)

quickshell/nuguland/docs/superpowers/specs/2026-06-29-audio-popup-redesign-design.md

Added
new file mode 100644
1 +# Audio Popup Redesign — Design Spec
3 +**Date:** 2026-06-29
4 +**Status:** Approved (owner-delegated, autonomous)
5 +**Goal:** Turn the narration-heavy audio popup into a clean graphical sink/source mixer — solid dark cards, real volume sliders, mute/default affordances — with the pure shaping/role/format logic extracted to a node-tested `audio.js`. Native PipeWire I/O stays in `Audio.qml`. Same architecture as `launch.js`/`clip.js`/`sysinfo.js`.
7 +---
9 +## 1. Problems with the current audio popup
11 +- **Logic tangled in QML, untested.** `nodeName`, `channelNames`, `nodeVolume` (clamp 0..1.5), `nodeMuted`, `nodeRow`, `roleForSink`, `privacyLabel`, volume-percent formatting — all pure, all stuck in `Audio.qml`, none node-tested.
12 +- **Narration bloat.** `audioPanelContract()` returns `panel.*` gate booleans that are all `true` (dead gates the view reads back). `stateObject()` carries self-describing metadata: `backend`, `usesNativePipewire`, `helperProcesses`, `sampler`, plus two shader descriptors (`privacy-veil`, `audio-waveform`) with `"source": "shaders/*.qsb"` strings. **No `ShaderEffect` renders these** — only `aurora.frag.qsb` is ever loaded (AuroraBackdrop/Lock). Dead weight — delete.
13 +- **Washout-prone view.** `AudioPanel` paints rows with translucent `withAlpha(ui.minor, 0.12)` fills; the popup frame is light, so low-alpha tints wash to near-white. Known recurring bug (system/clipboard/launcher).
15 +---
17 +## 2. Decisions (locked)
19 +| Topic | Decision |
20 +|-------|----------|
21 +| Architecture | Pure `audio.js` (node-tested, dual-mode export, **no I/O, plain-data only**) + thin `Audio.qml` (native PipeWire I/O + cadence, delegates shaping to `audio.js`) + pure `AudioPanel` view. |
22 +| **Native boundary** | PipeWire natives (`Quickshell.Services.Pipewire`, `Pipewire.nodes/links/defaultAudioSink/Source`, `PwNodeType`, `PwLinkState`, `PwAudioChannel`, `PwObjectTracker`, `node.audio.volume/.muted`) **stay in `Audio.qml`**. `audio.js` receives plain field dicts only. Do NOT move native access into JS. |
23 +| Extracted pure logic | `nodeName`, `channelNames`, `clampVolume` (0..1.5), `volumePercent`, `nodeMuted`, `shapeRow(plainNode, kind)`, `roleForSink(plainSink)` (returns `"warning"`/`"ui.minor"`/`"ui.accent"` by volume/mute), `privacyLabel(flags)` (Mic/Cam/Mic Cam/Audio), `rowsById(rows)`. |
24 +| **Preserve (external consumers — DO NOT remove or rename)** | `privacyLabel()` & `privacyActive()` (Bar.qml:47,76); `stateJson()`, `privacyWidgetJson()`, `setVolume(id,v)`, `toggleMute(id)`, `setDefaultSink(id)`, `setDefaultSource(id)`, `moveStream(...)`, `increase`, `decrease`, `muteOutput`, `muteInput`, `route(action)` (shell.qml IPC). Service keeps each method name; pure ones delegate to `audio.js`. |
25 +| Removed narration | `audioPanelContract()` and all `panel.*` gates; `stateObject` metadata `backend`/`usesNativePipewire`/`helperProcesses`/`sampler`; the two shader descriptors + `privacyShaderValues()`. The view stops reading panel gates and renders unconditionally. |
26 +| Layout | Two sections in a `Column`: **Outputs (sinks)** then **Inputs (sources)**. Each row = solid dark card: leading speaker/mic glyph · device name · inline volume slider track + fill · trailing percent. Default device carries an `ui.accent` left accent bar; muted rows desaturate + show a muted glyph. |
27 +| Card style (washout fix) | Solid dark base `theme.withAlpha(theme.ui.backdrop, 0.55)`; default/selected device `~0.82`; identity via thin left accent bar (default = `ui.accent`) + border; **never** a translucent tint fill. Per the frame-light-washout memory. |
28 +| Slider | Click/drag on the track sets volume (`setVolume(id, ratio*1.5?` — keep current 0..1.5 scale and the existing click-maps-to-ratio math); fill width = `volumePercent/150`. Middle-click toggles mute; click device name selects default. Keep the current MouseArea verb mapping. |
29 +| IPC contract | Keep every listed method + `stateJson()` shape's **functional** keys (sinks, sources, default ids, privacy). Drop only the narration keys. Add `selfTest()`. |
30 +| Glyphs | Output `` (speaker), muted `` (speaker-off / volume-mute), input `` (mic), mic-muted ``. Plain `Text { font.family: "Symbols Nerd Font Mono" }` (NuguText hardcodes Plex → tofu for PUA). Verify codepoints with `od -An -tx1` before locking. |
32 +---
34 +## 3. Components
36 +### 3.1 `audio.js` (new — pure, node-tested)
37 +- `clampVolume(v)` → clamp Number to `0..1.5`, null-safe → 0.
38 +- `volumePercent(v)` → `Math.round(clampVolume(v) * 100)` (integer, so 1.0→100, 1.5→150).
39 +- `nodeName(plainNode)` → description || nickname || name || "Audio", null-safe.
40 +- `channelNames(channels)` → maps channel enums/strings to labels (preserve current mapping).
41 +- `nodeMuted(plainNode)` → `!!plainNode.muted`.
42 +- `roleForSink(plainSink)` → `"warning"` if muted, `"ui.minor"` if volume 0, else `"ui.accent"` (preserve current thresholds).
43 +- `privacyLabel(flags)` → `{mic,cam}` → "Mic" / "Cam" / "Mic Cam" / "Audio" / "" (preserve current text).
44 +- `shapeRow(plainNode, kind)` → `{id, name, kind, volume, percent, muted, role, isDefault, glyph}` plain dict for the view.
45 +- `rowsById(rows)` → `{id: row}` map.
46 +- Dual-mode export tail (guarded `module.exports`), identical pattern to `clip.js`.
48 +### 3.2 `audio.test.js` (new — node)
49 +Assert: `clampVolume` clamps `-1→0`, `2→1.5`, `0.5→0.5`, `null→0`; `volumePercent(1)→100`, `(1.5)→150`, `(0)→0`; `nodeName` precedence (description > nickname > name > "Audio") and null-safety; `roleForSink` → muted⇒warning, vol0⇒ui.minor, vol0.5⇒ui.accent; `privacyLabel` for each `{mic,cam}` combo; `shapeRow` produces the full dict with correct `percent`/`muted`/`glyph`; `rowsById` keys by id. Prints `ALL PASS`.
51 +### 3.3 `Audio.qml` (reworked — thin, native I/O stays)
52 +- Imports `audio.js`; delegates name/clamp/percent/role/privacy/row-shaping.
53 +- Keeps ALL native PipeWire wiring, `PwObjectTracker`, default sink/source binding, and every preserved method (Section 2). Pure methods delegate (e.g. `function privacyLabel() { return Audio.privacyLabel(privacyFlags()); }`).
54 +- `stateJson()` serializes the live sink/source rows (via `shapeRow`), default ids, and privacy — **drops** narration keys.
55 +- Adds `selfTest()` (fixtures through `audio.js`: clampVolume, volumePercent, roleForSink, privacyLabel, shapeRow) returning `{pass, fail, cases}`.
56 +- Deletes `audioPanelContract`, `privacyShaderValues`, shader descriptors, and `backend`/`usesNativePipewire`/`helperProcesses`/`sampler`.
58 +### 3.4 `PopoutHost.qml` `AudioPanel` (rewrite, line 3509)
59 +- Drop `audioPanelContract`/`panel.*` gate reads — render unconditionally.
60 +- Two labelled sections (Outputs / Inputs), each a `Repeater` over `stateJson()` rows.
61 +- `SinkRow`/`SourceRow`: solid dark card (`withAlpha(ui.backdrop, isDefault ? 0.82 : 0.55)`), leading Nerd Font glyph (speaker/mic, muted variant when muted), device name (`NuguText`), inline slider track (`ui.minor` bg) + fill (`role` color, width `percent/150`), trailing `percent + "%"`. Default device: `ui.accent` left accent bar + border.
62 +- MouseArea verbs unchanged: click-name ⇒ `setDefaultSink`/`setDefaultSource`, middle-click ⇒ `toggleMute(id)`, click/drag-on-track ⇒ `setVolume(id, ratio)`.
64 +### 3.5 `SurfaceManager.qml`
65 +- Keep the `"audio"` popup size (`heightBudget(520)`). Drop any audio narration catalog strings if present.
67 +---
69 +## 4. Error handling
70 +- Missing/empty node name → `"Audio"`.
71 +- Volume out of range → clamped to `0..1.5` by `clampVolume`.
72 +- Empty sink/source list → section renders header + empty (no crash).
73 +- `privacyLabel` with no flags → `""` (privacy widget hides — preserve current `privacyActive()` behavior).
74 +- Native default sink/source null → no default accent bar; rows still list.
76 +## 5. Testing
77 +- `node audio.test.js` → `ALL PASS`.
78 +- `qs -c nuguland ipc call nuguland audioSelfTest` (or dedicated selfTest IPC) → pass counts (after `rm -rf ~/.cache/quickshell/qmlcache` + restart).
79 +- Live-verify **external consumers**, not just the popup: confirm the **Bar privacy widget** still renders (privacyLabel/privacyActive) and a volume `increase`/`decrease` IPC still moves the slider. Then open audio popup, screenshot — verify solid dark cards, real sliders, default accent bar, mute desaturation.
81 +## 6. Out of scope
82 +- Per-app stream routing UI redesign (keep `moveStream` IPC working; no new UI).
83 +- Waveform/privacy-veil shaders (deleting dead descriptors only; no shader work).
84 +- New audio backends — native PipeWire stays; iwd/NM not involved here.