aboutsummaryrefslogtreecommitdiff
path: root/docs/specs/2026-07-09-audio-doctor-spec.org
Commit message (Collapse)AuthorAgeFilesLines
* docs: close the audio-doctor decisions, spec is READYHEADmainCraig Jennings12 hours1-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 Jennings14 hours1-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 Jennings14 hours1-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.