feat: add realtime peak envelope visualizer (#87)

[thedavidweng]

Summary

Peak envelope visualizer (#87)

• Add lock-free atomic ring buffer (PeakRing) in the CPAL output callback that publishes sanitized, clamped stereo peak pairs — one per 512 rendered frames, 256-pair capacity (~3.0 s @ 44.1 kHz) — after EQ, limiter, and fade
• Add PeakAccumulator owned by the output closure (beside EqProcessor); device restart starts a fresh partial window while retaining the process-wide ring and write counter
• Add read-only get_audio_peaks IPC command that copies the ring snapshot without holding the playback mutex
• Add DPR-aware PeakMeter canvas component that polls at 30 Hz and renders a scrolling stereo waveform in the fullscreen player controls
• Update IPC contract docs and contract test registry

Fullscreen player lyrics fixes

• Fix lyrics frozen at entry position: readLyricsPlaybackClockMs and readLyricsAdjustedPlaybackMs used AirPlay displayedPositionMs (a stale remote clock) instead of the local playback clock when AirPlay was active. The fullscreen window receives AirPlay state via BroadcastChannel but does not run the AirPlay listener, so the displayed position never updated on local seeks — freezing lyrics at the position when the fullscreen window was opened. Lyrics now always use the local playback clock; the AirPlay clock is only used for CDG sync. Also added a transport_generation staleness check in applyPlayerSyncSnapshot to prevent delayed BroadcastChannel messages from regressing the clock.
• Fix lyrics not scrolling: getLineScrollMetrics used offsetTop relative to offsetParent — a nested justify-center inner div in audience mode. Lines above the vertical center had negative offsetTop, and getCenteredScrollTop clamped to 0, freezing scroll at the top. Now uses getBoundingClientRect when offsetParent is not the container. Also changed the audience lyrics inner container from justify-center to justify-start so all lines are reachable via scrollTop.

Fullscreen player keyboard shortcuts

• Add spacebar (play/pause), left/right arrow (seek ±5s), and Escape (close fullscreen) keyboard shortcuts in the fullscreen player, with tests.

Audience mode seek-unlock

• Audience mode line-click seek now unlocks auto-follow with an idle re-lock timer (4s) instead of immediately resuming tracking. The operator can click a line to jump and browse freely; after inactivity the view snaps back to the active (playing) line — appropriate for an audience-facing second monitor. Standard mode behavior is unchanged.

Architecture

• src-tauri/src/audio/peaks.rs — PeakRing (single-writer lock-free ring using AtomicU32 bit-packed f32 slots + AtomicU64 write index with Release/Acquire ordering), PeakAccumulator (512-frame max window), AudioPeakSnapshot (IPC DTO)
• src-tauri/src/audio/output.rs — render_output_buffer and build_output_stream wired to feed the accumulator after the fade stage
• src-tauri/src/state/playback.rs — PlaybackState gains peak_ring: Arc<PeakRing>
• src/components/Player/PeakMeter.tsx — 30 Hz polling canvas with writeIndex-skip optimization
• src/components/Player/FullscreenControls.tsx — keyboard shortcuts for play/pause, seek, and close
• src/lib/lyrics-engine.ts — local-clock-only lyrics position, audience seek-unlock with idle re-lock
• src/components/Lyrics/lyrics-scroll.ts — getBoundingClientRect fallback for nested offsetParent
• src/stores/player-store.ts — transport_generation staleness guard in applyPlayerSyncSnapshot

Test plan

• Rust unit tests: ring capacity, empty ring, push/snapshot, non-finite sanitization, chronological order, wraparound at 3× capacity, concurrent reader stress, accumulator window boundary, mono duplication, stereo channel selection, reset window, rendered-samples-only clamping, zero-render no-op, device restart counter retention
• Frontend tests: canvas rendering, default dimensions, 30 Hz polling, error handling, drawing with peaks, flat baseline, writeIndex skip/redraw, multi-bar rendering
• IPC contract test updated with get_audio_peaks command
• Fullscreen keyboard shortcut tests (spacebar, arrows, Escape)
• Lyrics engine tests: audience seek-unlock, local clock, scroll metrics
• Player store tests: transport_generation staleness guard
• cargo test — 447 passed
• cargo clippy --all-targets -- -D warnings — clean
• cargo deny check — clean
• pnpm test — 1376 passed
• pnpm lint — clean
• pnpm check:i18n — clean
• npx knip — clean
• Patch coverage — 98.5% (target 80%)

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	78.27% (🎯 65%)	3715 / 4746
🔵	Statements	77.85% (🎯 65%)	3947 / 5070
🔵	Functions	68.74% (🎯 60%)	983 / 1430
🔵	Branches	71.2% (🎯 60%)	2161 / 3035

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/components/Lyrics/LyricsPanel.tsx	92.94%	83.16%	86.66%	91.54%	139, 161-176, 181-196, 240-270
src/components/Lyrics/lyrics-scroll.ts	75%	87.5%	100%	75%	61-68
src/components/Player/FullscreenControls.tsx	74.54%	64.7%	62.5%	75.92%	34, 88-107
src/components/Player/PeakMeter.tsx	97.27%	88.46%	100%	100%	55, 58, 112
src/hooks/use-lyrics-engine.ts	100%	100%	100%	100%
src/lib/lyrics-engine.ts	92.43%	84.68%	93.93%	92.26%	198, 224, 270, 287, 292, 432, 491, 548-551, 554-555, 568
src/stores/player-store.ts	88.88%	83.87%	92.1%	91.66%	234, 242, 300, 308, 316, 340, 348, 356, 411-412

Generated in workflow #902 for commit 215e1a0 by the Vitest Coverage Report Action

[codecov]

Codecov Report

❌ Patch coverage is 95.05495% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.3%. Comparing base (3fb8c62) to head (215e1a0).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/lib/lyrics-engine.ts	73.3%	4 Missing ⚠️
src/components/Lyrics/lyrics-scroll.ts	40.0%	3 Missing ⚠️
src/components/Player/FullscreenControls.tsx	97.3%	1 Missing ⚠️
src/stores/player-store.ts	92.3%	1 Missing ⚠️

Additional details and impacted files

@@                  Coverage Diff                   @@
##           feat/eq-equalizer-86    #102     +/-   ##
======================================================
+ Coverage                  77.7%   78.3%   +0.6%     
======================================================
  Files                       127     128      +1     
  Lines                      6399    6562    +163     
  Branches                   2041    2048      +7     
======================================================
+ Hits                       4976    5143    +167     
+ Misses                     1379    1375      -4     
  Partials                     44      44             

Flag	Coverage Δ
frontend	78.3% <95.0%> (+0.6%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Components	Coverage Δ
frontend	78.3% <95.0%> (+0.6%)	⬆️
rust	∅ <ø> (∅)

Files with missing lines	Coverage Δ
src/components/Lyrics/LyricsPanel.tsx	86.3% <100.0%> (+0.4%)	⬆️
src/components/Player/PeakMeter.tsx	100.0% <100.0%> (ø)
src/hooks/use-lyrics-engine.ts	100.0% <ø> (ø)
src/components/Player/FullscreenControls.tsx	79.1% <97.3%> (+51.5%)	⬆️
src/stores/player-store.ts	93.1% <92.3%> (+1.1%)	⬆️
src/components/Lyrics/lyrics-scroll.ts	78.9% <40.0%> (-21.1%)	⬇️
src/lib/lyrics-engine.ts	92.7% <73.3%> (-0.3%)	⬇️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[greptile-apps]

Greptile Summary

This PR adds a realtime peak envelope visualizer for fullscreen playback. The main changes are:

• A lock-free Rust PeakRing and PeakAccumulator publish stereo peak pairs from the output callback.
• The audio pipeline records peaks after EQ, limiter, and fade processing.
• A read-only get_audio_peaks IPC command returns copied peak snapshots without taking the playback mutex.
• A DPR-aware React PeakMeter polls at 30 Hz and draws the scrolling stereo waveform.
• IPC contracts, E2E fixtures, and frontend/Rust tests were updated for the new command and rendering behavior.

Confidence Score: 5/5

Safe to merge with minimal risk.

The peak publishing path avoids playback mutex reads from IPC, output wiring uses rendered sample counts correctly, and frontend polling handles stale, reordered, slow, and unmounted responses.

No files require special attention.

T-Rex Logs

What T-Rex did

• Ran the focused Vitest command for the PeakMeter tests; the log shows the command, working directory, and exit code 0.
• Captured the live UI by recording a video and a poster image that display the fullscreen player controls on the real app route.
• Recorded the observed canvas geometry and DPR-aware backing dimensions from the live page into a JSON artifact for validation.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
src-tauri/src/audio/peaks.rs	Implements lock-free peak ring snapshots and 512-frame accumulation with coverage for sanitization, wraparound, and retry cursor races.
src-tauri/src/audio/output.rs	Wires post-EQ/limiter/fade peak accumulation into the render callback using rendered sample counts correctly.
src-tauri/src/commands/playback.rs	Adds a read-only get_audio_peaks command that snapshots the ring without taking the playback mutex.
src/components/Player/PeakMeter.tsx	Implements DPR-aware canvas rendering with 30 Hz single-flight polling and stale snapshot fallback.
src/components/Player/PeakMeter.test.tsx	Covers polling, drawing, stale-write fallback, single-flight coalescing, and unmount behavior for PeakMeter.
src/types/ipc.ts	Adds the TypeScript AudioPeakSnapshot interface matching the Rust camelCase DTO.
tests/e2e/fixtures/tauri-mock.ts	Adds an empty get_audio_peaks fixture response for browser-based E2E mocks.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant CPAL as CPAL output callback
participant Render as render_output_buffer
participant Acc as PeakAccumulator
participant Ring as PeakRing
participant IPC as get_audio_peaks
participant UI as PeakMeter

CPAL->>Render: render mixed samples
Render->>Render: apply EQ, limiter, fade
Render->>Acc: process(output, rendered, channels)
Acc->>Ring: push(stereo peak) every 512 frames
UI->>IPC: poll at 30 Hz
IPC->>Ring: snapshot()
Ring-->>IPC: writeIndex + peaks
IPC-->>UI: AudioPeakSnapshot
UI->>UI: draw waveform or flat baseline

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant CPAL as CPAL output callback
participant Render as render_output_buffer
participant Acc as PeakAccumulator
participant Ring as PeakRing
participant IPC as get_audio_peaks
participant UI as PeakMeter

CPAL->>Render: render mixed samples
Render->>Render: apply EQ, limiter, fade
Render->>Acc: process(output, rendered, channels)
Acc->>Ring: push(stereo peak) every 512 frames
UI->>IPC: poll at 30 Hz
IPC->>Ring: snapshot()
Ring-->>IPC: writeIndex + peaks
IPC-->>UI: AudioPeakSnapshot
UI->>UI: draw waveform or flat baseline

Loading

_{Reviews (3): Last reviewed commit: "fix(peaks): unify snapshot() and test in..." | Re-trigger Greptile}

[thedavidweng]

Maintainer acceptance — merge slot 7, strictly after repaired #114

BLOCKED — changes required.

Blocking frontend polling race

PeakMeter starts a new async getAudioPeaks() on every 30 Hz interval without an in-flight guard. A slow IPC call therefore overlaps later calls. Responses are also accepted whenever writeIndex !== lastWriteIndex, so an older delayed response can move the stored index backward and redraw stale peaks after a newer response.

#87 explicitly requires one request in flight under slow IPC and stale-response suppression. Add a shared in-flight/sequence guard, accept only monotonic newer snapshots, and test delayed out-of-order responses plus visibility lifecycle.

GitHub currently reports this PR as mergeable=false and there is no CI run for the current head. Rebase it onto the final repaired #114 before rerunning the full validation.

[thedavidweng]

Re-review: blocking async polling race fix required

This PR depends on #114 and must remain unmerged until #114's DSP correction is accepted. Independently, the current PeakMeter polling logic is race-prone: it starts async getAudioPeaks() calls on every timer tick and accepts any response whose writeIndex !== lastWriteIndex. A slow older response can resolve after a newer one and rewind the rendered peak history.

Implement exactly the following:

1. Create one shared polling coordinator inside PeakMeter. There must be at most one IPC request in flight for the mounted component. Timer ticks while a request is active must coalesce/skip instead of creating another request.
2. Also use a monotonically increasing request/generation identifier. Apply a resolved snapshot only when the component is still mounted, the response belongs to the current generation, and it is newer than the last applied snapshot. Do not use !== as the freshness predicate; the process-wide write index is monotonic, so an older index must never replace a newer one.
3. Make cleanup invalidate outstanding work so an unmount, song/session replacement, or React Strict Mode remount cannot draw or set state after disposal. Keep the 30 Hz target cadence and existing failure handling.
4. Do not change the lock-free Rust ring design merely to work around this frontend ordering bug.

Add deterministic frontend tests with deferred IPC promises:

• start two would-be poll cycles, resolve the newer snapshot first and the older snapshot second, and prove the canvas/history never reverts;
• prove rapid timer ticks issue no more than one concurrent request;
• prove cleanup prevents a late resolution from drawing or updating state;
• retain the existing new-write redraw behavior.

After #114 merges, rebase this branch onto the resulting main so the PR diff contains only the peak feature. Run pnpm test, pnpm test:ui-smoke, the Rust suite, and CI. Reply with the commit SHA and test output summary.

[thedavidweng]

Re-review — still blocked: PeakMeter still creates overlapping IPC polls

Reviewed at 8ab85c4. requestGeneration suppresses older results, but setInterval(poll, 1000 / 30) still calls getAudioPeaks() every tick while an earlier call is unresolved. There is no in-flight guard.

This has a user-visible failure mode: when IPC takes longer than ~33 ms, every response is invalidated by a newer timer tick, so the meter can stop rendering entirely while continuously issuing concurrent requests.

Implement the required single-flight coordinator inside PeakMeter:

1. Add explicit inFlight and rerunRequested state local to the effect. A timer tick while a request is active must set rerunRequested (or simply coalesce) and return without starting another IPC call.
2. In finally, clear inFlight; if still mounted and rerunRequested is set, clear it and run exactly one follow-up poll.
3. Keep a cleanup-invalidated generation and accept a snapshot only when it belongs to the active generation and snapshot.writeIndex > lastWriteIndex (never !==). Preserve the stale flat-line behavior.
4. Add fake-timer/deferred-promise tests proving: rapid ticks create at most one concurrent call; a delayed response still draws once rather than being perpetually discarded; stale/unmounted resolutions do not draw; and an older write index cannot replace a newer canvas state.

Do not alter the Rust ring buffer to compensate for this frontend scheduling defect.

[thedavidweng]

Re-review — blocked: the peak snapshot cursor can be newer than the copied data

Reviewed at 7d232fc. In PeakRing::snapshot, the retry path copies entries for second_index, then loads and returns third_index:

• retry = copy_entries(second_index)
• third_index = write_index.load(...)
• returns (third_index, retry)

If the writer advances between those two operations, the frontend accepts third_index while the returned peaks only reach second_index. Its monotonic guard then suppresses the next correct snapshot at the same third_index, so the visualizer can remain permanently one update behind when playback stops.

Please make the reported cursor describe exactly the copied snapshot: return (second_index, retry), or retry again until the copied data and returned index are paired. Do not report an index later than the data represented by peaks.

Add a deterministic regression that forces a write after the retry copy and proves the returned cursor is not ahead of the copied entries; retain the Acquire/Release publication contract and the lossy, lock-free design. Re-run the Rust suite after the fix.

[thedavidweng]

Re-review — core cursor fix is correct, but the required deterministic regression is still missing

Reviewed at 4cc606d. Returning second_index after the retry copy fixes the original cursor/data mismatch: the public cursor no longer advertises entries that were not copied.

However, peaks.rs still has no regression that can fail the old implementation. test_concurrent_reader_stress only checks monotonicity and bounded values; it does not force a writer update after the retry copy and before the old third-index load, so the pre-fix code would pass it.

Please add deterministic coverage for that interleaving (a narrowly scoped test-only synchronization hook around the retry copy is acceptable, or an equivalent barrier-based helper). Arrange:

1. the first read observes a changed write index and takes the retry path;
2. a writer publishes one more pair after the retry copy; and
3. the snapshot returns the retry index and values ending at that index, never the later write index.

Keep the public API and lock-free/realtime contract unchanged. No LGTM until the race that caused this bug is protected by a regression test.

[thedavidweng]

Re-review of head b4345c53a27db687e3da10fb0f1fd9447eecd10f:

The cursor regression blocker is resolved. Production snapshot() and the deterministic race test now execute the same private snapshot_impl; the retry returns the exact second_index used to copy the returned entries. Latest CI on this head is green.

Do not merge/approve the stacked feature yet: this head predates the latest #114 commit 6c616cb9ab713fdebcc81a44ee0020c40d4f694a (the current comparison is 1 commit behind), so its green run did not validate the final combined graph. After #114 is accepted, update/retarget this branch onto that exact head and obtain fresh CI. The peak visualizer still requires its declared manual visual/performance acceptance before final LGTM.

[thedavidweng]

Re-review — no LGTM yet: older version already entered main via #103

Reviewed head 215e1a0b2b6dc03ad756908d2a116c77fcea2857.

The current branch contains the corrected peak cursor implementation, shared production/test snapshot algorithm, single-flight polling, stale/idle handling, and smooth decay work; CI is green. However, #103 already carried an older #102 tree into main, while this PR is stacked on the latest #114 head.

After the #114 recovery/hotfix lands:

1. rebase onto current main;
2. reduce the diff to only peak changes still missing from main;
3. preserve the current main gapless path and the corrected EQ bounding invariant;
4. verify changelog/contract entries are single, current-state entries;
5. rerun full CI, the deterministic cursor race regression, slow-IPC single-flight tests, idle redraw/decay tests, and visual acceptance.

The existing green run is not merge evidence for the post-#103 mainline.