aboutsummaryrefslogtreecommitdiff
path: root/docs/specs/2026-07-09-audio-doctor-spec.org
Commit message (Collapse)AuthorAgeFilesLines
* docs: spec the audio doctor's input side, one doctor per directionCraig Jennings2026-07-101-0/+1
| | | | | | | | | | | | The doctor never examines the microphone. diag collects default_source and default_source_present, the classifier reads neither, so a muted mic, a stale default source, and a mic the sound server can't see all classify as healthy. Chrome losing the mic this morning surfaced it: the stack was genuinely fine and the doctor had nothing useful to say. The design grew past the gap in one conversation. An empty source list is normal on a mic-less desktop and a failure on a machine that should have one, and no probe can tell those apart. The missing fact comes from the user's finger: a doctor key on each of the OUTPUTS and INPUTS section headers, where pressing the input one asserts a mic should exist. That retires the DOCTOR header key I shipped hours earlier, and it dissolves the precedence question a single classifier would have faced. A new probe tier sits below PipeWire. /proc/asound lists capture-capable cards, needs no package, spawns no process, and can't hang, so it separates "the software lost a microphone the kernel sees" from "nothing is plugged in". Push-to-talk stays as it is. It mutes the source, the one state where the server guarantees nothing is captured. A link-based push-to-talk fails open, and a crash mid-hold is a hot mic reading as muted. The doctor reads ptt.read_state() instead of guessing. Four decisions are open. Three are closed.
* docs: close the audio-doctor spec and its taskCraig Jennings2026-07-101-9/+15
| | | | | | | | The doctor shipped end to end, so the spec goes to IMPLEMENTED and the task closes with a dated record of what landed. Three things the Decisions did not anticipate are written into the history rather than left for a reader to infer. A tenth verdict for missing tooling, because an absent pactl is an unobserved stack and not a broken one. A re-probed marker between a fix run's two row blocks. And DIAGNOSE as the read-only key's name, which Craig settled after asking why this panel carries two keys where the net panel carries one. I filed the wall-controls convergence as its own task. Craig wants the net panel's copy and close pair on every output wall, and today no two of the four agree.
* docs: close the audio-doctor decisions, spec is READYCraig Jennings2026-07-091-18/+39
| | | | | | | | | | | | | | | | | All eight decisions resolved. DOCTOR is a section-header key; CLI-first with the GUI as a face; hung and dead are two verdicts sharing one remedy; the remedy tiers stand as drafted; a stream-active guard refuses the audible remedies and is overridable by pressing again; xruns stay out of v1. Two consequences the questions did not make obvious. Taking the guard is what lets the pipewire-pulse restart stay at Confirm — the danger lives in the state of the machine, not the identity of the remedy. And the guard must read stream state from pw-dump rather than pactl: the remedies it protects are the ones you reach for when the Pulse layer is dead, so a pactl-fed guard would go blind exactly when it is needed. Tier 4 drops its xrun probe to match the decision, rather than leaving the probe list contradicting the answer.
* docs: correct the audio-doctor spec's timeout claim, close Phase 0Craig Jennings2026-07-091-8/+13
| | | | | | | | | | | | | | The draft said build_status had no pactl timeout and froze the panel. Driving it disproved that: pactl.run defaults to timeout=8 and raises PactlTimeout, so the panel degrades. The real defect was narrower and is now fixed. Two of build_status's four reads sat outside its degrade guard, so a server that answered the device lists and then stopped answering raised out of a function contracted to return ok:False, and waybar's audio module died rather than dimming. Corrected in place with the reasoning, rather than dropped, since a spec that quietly loses a wrong claim teaches nothing about why it was wrong.
* docs: spec the audio panel doctorCraig Jennings2026-07-091-0/+258
Answers the four questions the request asked, from a live survey rather than from memory. There is no PulseAudio: the stack is pipewire, wireplumber, and pipewire-pulse, all user-scope, so no remedy in this feature needs sudo — which is why it mirrors the net panel's doctor rather than the maintenance console's privileged verb table. Two findings shape the design. pactl hangs against a server that accepts and never answers, which is exactly the fault a doctor exists to diagnose, so every probe is bounded. And the panel cannot diagnose itself, because pactl is the layer most likely to be down — the probes read systemctl and pw-dump before they touch it. Filed the panel's own missing timeout as a separate bug. It freezes the audio panel today, independently of any doctor. Seven decisions left open; the spec is DRAFT and nothing gets built until they close.