1 +#
Audio Popup Redesign — Design Spec 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`.
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).
17 +##
2. Decisions (locked) 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. |
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.
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.
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.
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.