Calibrate Voice Pyramid volume with checked output gates and DMA fence

[eirabie]

Summary

The AtomS3R / Voice Pyramid slider previously reached only -19 dB at 100%. The calibrated profile now reaches 0 dB, uses software attenuation with extra codec attenuation for very quiet levels, and defaults to 56%. Saved levels migrate without increasing their computed gain; CRC-protected companion settings and a quiet legacy mirror preserve older-firmware and interrupted-save compatibility.

Gain changes now keep output closed until both hardware readbacks and actual DMA completion succeed. Checked AW87559 SYSCTRL PA control replaces the incorrect expander GPIO binding, with codec mute as a second gate. The adapter owns software gain, so restored media-player preferences cannot override it. Raw staged PCM is scaled per DMA descriptor before bit-depth conversion; session/generation tokens complete only after the matching descriptor transmits, or after complete stopped-speaker cleanup. Superseded requests and Stop/restarts cancel obsolete tokens. A two-second deadline faults playback and attempts both mutes; it never authorizes unmute. Zero remains a valid applied volume with both gates closed.

The review correction prevents a stalled speaker task from acknowledging a fence after ESP-IDF loses descriptor ordering. Each fenced descriptor is composed and written as a whole buffer; completion backlog is checked synchronously before event publication, with a defensive driver overflow callback. Playback health is separated from admission readiness so healthy muted changes preserve active Quran streams while new starts and gain readback remain gated.

Hardware impact

• No new required hardware
• Adds optional hardware
• Changes the required reference BOM

Uses the existing A167 ES8311, Si5351 and AW87559. Generic amplifier startup stays enabled; calibrated startup verifies PA disabled. The volume curve and amplifier boost settings retain their contracts. Physical output-gate and maximum-volume acceptance remain pending.

Standalone impact

Playback, volume, settings and scheduling remain local and independent of Home Assistant and the public website. Prayer history, shared audio, both OTA slots and HTTP interfaces retain their contracts. Rebasing onto main 2cea368 preserves Quran streaming capability, playback ownership, state and epochs through the calibrated adapter. Generic hardware retains its ordinary ESPHome DAC route.

Testing

Automated for this correction: all 20 UBSan CTests, 120 pinned Python tests and 13 configuration schemas passed. Vendored provenance reverses the maintained patch to every original upstream hash. The production Quran worker/HTTPS tests and actual Atom-adapter/controller integration pass, including zero/rapid gain changes, unchanged active-stream epoch, pending start rejection, Stop, disconnection, maintenance and hardware faults. Circular-DMA tests model five descriptors and the separate four-entry driver queue; six/seven-completion stalls and deferred faults during acknowledgement fail closed. Restoring the old DMA or Quran behavior makes the new regressions fail. Ordinary unfenced playback is covered.

All ten matched firmware comparisons pass capacity and dependency checks using identical public compile-only settings/audio and the pinned toolchain. Compared with PR head 12231c9, reference OTA is 1,305,920 bytes (+624), with 266,944 application-budget bytes remaining; reported static RAM is +136 bytes. Atom variants grow 560–624 bytes; Waveshare controls grow 64–80 bytes with unchanged static RAM. Both OTA slots and the separate 3.5 MiB audio partition are preserved. No audio task, PCM buffer or queue is added. The latest-main rebase was a no-op and the final diff was reviewed.

Earlier fence validation passed 532 Chromium/WebKit cases; those were not repeated locally for this correction because device-UI assets are unchanged. All 12 exact-head GitHub checks passed on bc74b39 in run 38161988984.

Physical: no device connection, installation, playback or restart performed. Output gating, live adjustments with approved recordings, cold restart and runtime heap/fragmentation/stack/PSRAM acceptance remain separate attended work under the existing runbooks. Compile-only fixtures must NEVER be installed or played. See the complete validation and size report and calibration contract. Merge, release, website changes and installation remain separate actions.

Licensing/media

• No new third-party media or dependency licensing concerns
• Licensing/attribution details are documented in this PR

The calibrated package selects a repository-local pinned copy of ESPHome 2026.9.0 I2S audio with an opt-in fence. Upstream provenance, original file hashes and maintained patch are recorded, and the exact upstream GPLv3 runtime/MIT Python license is retained. The new C++ fence header follows GPLv3; other OpenAthan software remains Apache-2.0. No recordings or private diagnostic material are added.