perf(audio): async decode + PCM/waveform caching (Slice 1, #151)

[thewrz]

Why

Firing playback had a subtle, length-dependent lag: play_sound_entry decoded
the entire file to PCM synchronously inside Iced's update() loop on every
press, so longer files hitched the UI. The same hot path also recomputed the
waveform envelope, read the playhead length off a full decode, and copied the
whole PCM to apply per-sound volume.

What (Slice 1 of #151)

Move the decode off the UI thread and cache aggressively, in a memory-conscious way:

• audio::store::AudioStore — a byte-capped LRU of decoded Arc<CachedPcm>
  (default 256 MB; a hot re-fired sound stays resident, cold ones evict; a lone
  oversized entry is kept) plus the in-memory waveform-envelope map.
• Async decode — a press returns an iced::Task that decodes on a blocking
  thread and yields Message::Decoded; a warm cache hit fires synchronously
  (instant replay). The decode is keyed by the play_generation token so a
  superseded press is dropped, and a play cancelled mid-decode (StopAll) is
  dropped via the playing check.
• Per-sound volume → engine gain — PlaybackState applies master * gain,
  so the canonical pre-volume Arc is shared with the engine with no per-play copy.
• app.rs → app/mod.rs + app/playback.rs — the new play-coordination
  logic lives in a focused module rather than growing the Application file
  (honors the CLAUDE.md "don't grow app.rs" override).

Result: fast clicks, instant warm replays, waveforms computed once then cached.

Reviews

Two adversarial passes (an in-workflow reviewer + Codex GPT-5.5 xhigh). Fixed a
CRITICAL (StopAll resurrecting a cold decode), a HIGH (per-sound boost >1.0
clamped to unity), and a HIGH regression the first StopAll fix introduced
(stale PlaybackStarted after StopAll) — each pinned by a regression test.
Remaining narrow async-decode edge cases are tracked in #152 (decision recorded:
keep the snappy optimistic highlight; the real guard is the background pipeline
#158).

Testing

• cargo test — 487 lib + 24 integration, incl. new AudioStore LRU,
  engine-gain, async-ordering, and StopAll-resurrection regression tests
• cargo clippy --all-targets -- -D warnings clean (default and
  --features pipewire-test); cargo fmt --all --check clean
• Manual: UI fast, replay fast, waveforms generate on first fire then cache
• CI green

Design + plan: docs/superpowers/specs/2026-06-23-playback-decode-and-waveform-caching-design.md,
docs/superpowers/plans/2026-06-23-async-decode-pcm-cache.md. Slice 2 (persisted
envelope) is a follow-up.

🤖 Co-authored by Claude Opus 4.8 (1M context). Closes #151.

[coderabbitai]

Warning

Review limit reached

@thewrz, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 59 minutes and 39 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c1a06720-1528-4301-93f4-3da4b2d56683

📥 Commits

Reviewing files that changed from the base of the PR and between 2ecacc1 and 99a92f3.

📒 Files selected for processing (9)

• docs/superpowers/plans/2026-06-23-async-decode-pcm-cache.md
• docs/superpowers/specs/2026-06-23-playback-decode-and-waveform-caching-design.md
• src/app/mod.rs
• src/app/playback.rs
• src/audio/engine.rs
• src/audio/mod.rs
• src/audio/playback.rs
• src/audio/store.rs
• tests/pipewire_integration.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch perf/issue-151-decode-caching

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[thewrz]

🔍 Codex (GPT-5.5, xhigh) review — backup gate (CodeRabbit hit its org review rate-limit this window, so its green check is a no-op, not a real review; Codex served as the review gate per the workflow).

Codex surfaced 2 × [P2] findings against src/app/playback.rs. Both verified against the code — and both are already-tracked, deliberately-deferred edge cases of the Slice-1 async-decode model, not new regressions:

• [P2] Preserve current playback until cold decode succeeds (playback.rs:17-22) — optimistic playing highlight commits before the cold decode lands, so a failed/corrupt cold press clears the UI while the prior voice keeps playing. Declining for this PR — this is the documented UX decision: keep the snappy optimistic highlight (fix(ui): playing indicator falls behind audio when sound buttons are spammed (audio event backlog) #111); the real guard is the background-decode pipeline (feat(audio): background library pre-processing pipeline (clean/fix/hash/waveform) with progress UI #158). Already captured as the HIGH — cold decode failure desyncs UI item in perf(audio): async-decode edge cases — cold-fail desync, rescan invalidation, envelope cap, decode coalescing #152.

• [P2] Invalidate cached audio when the file changes (playback.rs:23) — PCM/envelope are keyed by the path-derived sound.id with no size/mtime fingerprint, so editing a file in place at the same path serves stale PCM/waveform until eviction/restart. Declining for this PR — inherent tradeoff of introducing the cache; invalidation belongs with cache-lifecycle work, already captured as the MEDIUM — rescan / source removal does not invalidate in-flight decodes item in perf(audio): async-decode edge cases — cold-fail desync, rescan invalidation, envelope cap, decode coalescing #152 (and naturally handled alongside Slice 2 envelope persistence).

No new in-scope findings; nothing under-emphasized on re-scan. The PR body already references #152/#158, so the deferrals are linked. No code change needed.

[thewrz]

🧹 Backlog grooming (post-#159 pickup) — proposal only; no board moves made.

Ready already holds 4 vetted items (#13, #141, #144, #147 — above the ~3 healthy-queue bar), so the queue does not strictly need topping up. With #151 about to leave In-progress, two strong Backlog candidates are worth surfacing for the next pickup:

PROMOTE (vetted Ready-bar pass)

• refactor(app): extract now-playing playback state out of app.rs into a dedicated owner #142 refactor(app): extract now-playing playback state out of app.rs — ✅ specified (clear AC) · right-sized (~150–200 LOC) · isolated to the app state owner · attacks the documented app.rs 400-line-cap violation. ⏳ Ordering note: land after perf(audio): async decode + PCM/waveform caching (Slice 1, #151) #159 merges — perf(audio): async decode + PCM/waveform caching (Slice 1, #151) #159 reshapes app/mod.rs/adds app/playback.rs, so picking refactor(app): extract now-playing playback state out of app.rs into a dedicated owner #142 first would conflict. Not blocked, just sequence it second.
• chore(ci): clippy.toml cognitive-complexity & too-many-lines thresholds are never enforced #145 chore(ci): enforce clippy.toml cognitive-complexity & too-many-lines — ✅ specified · unblocked · infra-only (no audio/ui overlap) · ~100–200 LOC. Confirmed real: clippy.toml sets the thresholds but CI never promotes/denies them, and app/mod.rs (3075 lines) blows past the per-file budget.

HOLD (needs a human call / prerequisite first)

• feat(ui): sticker tile hover + playing animations (PR2 of #13) #92 sticker hover/playing animations — blocked: it is "PR2 of feat(ui): canvas sticker tiles + hand-drawn glyphs #13" and feat(ui): canvas sticker tiles + hand-drawn glyphs #13’s static-tile PR1 is not merged to main yet.
• feat(ui): audio mixer panel (mic + app sources → virtual mic) #28, feat(audio): per-source volume + mute #29 — mixer UI / per-source volume; child + grandchild of mixer epic feat(audio): audio mixer — mic + app passthrough into virtual mic #17, dependency chain not landed.
• feat: bulk sound import + folder drag-and-drop #16 bulk import — scope still soft (batch-action/review-screen interaction model undefined); tighten AC first.
• feat(audio): audio mixer — mic + app passthrough into virtual mic #17 audio mixer engine — epic (~600+ LOC, multi-module + feedback-safety architecture); slice into child issues.
• feat(audio, ui): Robust Audio Handling: Global Normalization, Compression, Per-Sound Controls, and Auto Mono-Summing #52 robust audio handling (normalize/compress/per-sound/mono-sum) — Phase-4 epic, 8+ subtasks; slice first.
• chore(packaging): AUR, Flathub, and signed deb/rpm repository — how-to and tracking #84 packaging tracking — tracking checklist spanning 4 distro channels; spin per-channel child issues.
• feat(ui,state): per-sound tile graphics — assigned images, album-art preview, profile association (tracking) #148 per-sound tile graphics — explicitly "(tracking)"; epic, must be sliced (and partly gated on feat(ui): canvas sticker tiles + hand-drawn glyphs #13).

On confirmation I can gh-project-move 142 "Ready" / gh-project-move 145 "Ready". No destructive changes proposed.

[thewrz]

Codex (GPT-5.5, xhigh) adversarial review — second-reviewer gate

CodeRabbit hit its org fair-usage review limit on this PR (its green check is a rate-limit ack, not a real review), so per the review-remote-pr workflow Codex ran as the review gate. It surfaced two [P2] findings; both are real but already tracked and deliberately deferred out of Slice 1 — neither is a new regression introduced here, and neither blocks this PR.

[P2] Cold decode failure desyncs UI from a still-playing sound — declined (tracked)

A stop_before=false tile press commits playing = Some(B) optimistically (#111 instant highlight) before the async decode resolves; if B is corrupt/undecodable, handle_decoded clears UI state while A still plays in the engine.

Declining — deliberate design choice, already tracked as the HIGH item in #152. The owner decision (this session) is to keep the snappy optimistic highlight; the real guard is the background pre-processing pipeline in #158, which validates/decodes ahead of the click so a cold press of a broken file is caught before playback. No code change in this slice.

[P2] Cache not invalidated when a file changes at the same path — declined (tracked)

sound.id is a hash of the path only (path_to_id); the PCM and envelope caches key on it with no size/mtime/content fingerprint, so replacing/editing a file at the same path mid-session serves stale audio + waveform until eviction or restart.

Declining — deliberate Slice-1 scope. Content-fingerprint invalidation is exactly what #158 (background clean/fix/hash/waveform pipeline) provides; the in-session staleness is captured in #152 (MEDIUM rescan-invalidation item, now annotated with this sharper same-path-replacement framing). No code change in this slice.

Net: 0 blocking findings. All CI green; CodeRabbit rate-limited (self-resolving throttle), so Codex was the review gate.