From 337e77350c2f37789579cb1577eac3297a4ea276 Mon Sep 17 00:00:00 2001
From: "prompt.ac/@jeffrey" <mail@aesthetic.computer>
Date: Sun, 7 Jun 2026 19:53:58 -0700
Subject: [PATCH] menuband: fix audio on rate-switch + rewind to notepat
 semantics + scrolling waveform strip
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- rewind voice: connect with engine-derived (nil) formats and build the
  reversed clip in the player's actual output format, so a 96 kHz interface
  or hot device-swap no longer breaks the graph / kills all audio (was the
  hardcoded 44.1k connection asserting in scheduleBuffer)
- rewind behavior now matches native notepat: each Space press reverses the
  audio SINCE THE LAST PRESS (floored 0.5s, capped 12s); hold-to-reverse with
  capture resuming on Space RELEASE (not a fixed clip timer) — fixes the
  laggy / "adding again" second run where new notes weren't being captured
- popover: live waveform strip above the instrument name — a scrolling
  min/max envelope (one column per frame, newest on the right, ~8s history)
  with forward ▶ / reverse ◀+orange directionality, so spacebar-rewind is
  debuggable; lightweight Core Graphics, polled ~30fps only while on screen

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../Sources/MenuBand/MenuBandController.swift |  22 +++-
 .../MenuBand/MenuBandRewindVoice.swift        | 104 ++++++++-------
 .../Sources/MenuBand/MenuBandSynth.swift      |   6 +
 .../CollapsedPianoWaveformView.swift          |  19 ++-
 .../Sources/MenuBand/WaveformStripView.swift  | 120 ++++++++++++++++++
 5 files changed, 223 insertions(+), 48 deletions(-)
 create mode 100644 slab/menuband/Sources/MenuBand/WaveformStripView.swift

diff --git a/slab/menuband/Sources/MenuBand/MenuBandController.swift b/slab/menuband/Sources/MenuBand/MenuBandController.swift
index 0ce3f65974..46d0c66bdc 100644
--- a/slab/menuband/Sources/MenuBand/MenuBandController.swift
+++ b/slab/menuband/Sources/MenuBand/MenuBandController.swift
@@ -885,12 +885,25 @@ final class MenuBandController {
     /// Bounced to the main thread because `playKeyEvent` runs on the
     /// KeyEventTap background thread and reverse playback mutates the engine
     /// graph + schedules a player buffer (both main-thread-only).
+    /// True while the spacebar reverse-replay is sounding — drives the
+    /// popover waveform strip's direction indicator (◀ reverse vs ▶ live).
+    private(set) var isRewinding = false
+
     func rewind() {
+        isRewinding = true
         DispatchQueue.main.async { [weak self] in
             self?.synth.playReverse()
         }
     }
 
+    /// Spacebar released — stop reverse playback and resume capture.
+    func rewindRelease() {
+        isRewinding = false
+        DispatchQueue.main.async { [weak self] in
+            self?.synth.releaseReverse()
+        }
+    }
+
     func setBend(amount: Float, allChannels: Bool = false) {
         // No clamp here — the trackpad accumulator can swing past
         // ±1 and the sample voice can vari-speed an arbitrary
@@ -2266,7 +2279,14 @@ final class MenuBandController {
         // note or a literal space character. Trigger on the first key-down
         // (ignore auto-repeat); consume key-up too so it stays swallowed.
         if keyCode == 49 /* kVK_Space */ {
-            if isDown && !isRepeat { rewind() }
+            // Hold-to-reverse (notepat model): press starts reverse playback
+            // of the audio since the last press; release stops it and resumes
+            // live capture so the next press reverses whatever you play next.
+            if isDown {
+                if !isRepeat { rewind() }
+            } else {
+                rewindRelease()
+            }
             return true
         }
 
diff --git a/slab/menuband/Sources/MenuBand/MenuBandRewindVoice.swift b/slab/menuband/Sources/MenuBand/MenuBandRewindVoice.swift
index 7a29bebfa3..752d189aff 100644
--- a/slab/menuband/Sources/MenuBand/MenuBandRewindVoice.swift
+++ b/slab/menuband/Sources/MenuBand/MenuBandRewindVoice.swift
@@ -31,14 +31,18 @@ final class MenuBandRewindVoice {
     /// single reverse window at REVERSE_MAX_AGE_MS = 12 s; we keep that as
     /// the ring ceiling so the buffer is generously sized.
     private let bufferSeconds: Double = 12.0
-    /// Window actually reversed per spacebar press. Notepat grabs "audio
-    /// since the previous press" (floored to a 500 ms minimum); Menu Band's
-    /// spacebar is a simple one-shot (no press-pair state), so we reverse a
-    /// fixed recent window. ~4 s is long enough to hear a phrase rewind but
-    /// short enough to feel like an instant replay.
-    private let captureSeconds: Double = 4.0
     /// Floor so a brief history still yields an audible clip.
     private let minCaptureSeconds: Double = 0.5
+    /// `CACurrentMediaTime()` of the previous Space press. The reverse window
+    /// is "audio SINCE the last press" (notepat semantics) — so rapid taps
+    /// reverse successive short chunks (a stutter), and a press after a long
+    /// phrase reverses the whole phrase. Floored to `minCaptureSeconds`,
+    /// capped at `bufferSeconds`. Set on attach so the first press measures
+    /// from launch.
+    private var lastPressTime: Double = 0
+    /// Bumped each press so a stale backstop timer from an earlier press
+    /// can't resume capture during a newer press's playback.
+    private var pressGeneration = 0
 
     private let player = AVAudioPlayerNode()
     private let mixer = AVAudioMixerNode()
@@ -68,12 +72,6 @@ final class MenuBandRewindVoice {
     /// Bool is fine (single-word, set-then-read, no torn state that matters).
     private var recording = true
 
-    /// Fixed render format for the player. The captured ring is mono; we
-    /// connect the player as mono and let the engine up-mix to the device.
-    private let renderFormat = AVAudioFormat(
-        commonFormat: .pcmFormatFloat32, sampleRate: 44_100,
-        channels: 1, interleaved: false)!
-
     // MARK: Attach
 
     /// Wire the rewind player into the engine. Called from
@@ -84,9 +82,15 @@ final class MenuBandRewindVoice {
         self.engine = engine
         engine.attach(player)
         engine.attach(mixer)
-        engine.connect(player, to: mixer, format: renderFormat)
-        engine.connect(mixer, to: engine.mainMixerNode, format: renderFormat)
+        // Connect with engine-derived (nil) formats so the rewind graph
+        // tracks the device's sample rate — a hardcoded 44.1k connection
+        // breaks (and `scheduleBuffer` asserts) when the user is on a 96 kHz
+        // interface or hot-swaps devices. The reversed clip is built in the
+        // player's *actual* output format at play time (see `playReverse`).
+        engine.connect(player, to: mixer, format: nil)
+        engine.connect(mixer, to: engine.mainMixerNode, format: nil)
         mixer.outputVolume = 1.0
+        lastPressTime = CACurrentMediaTime()
         attached = true
     }
 
@@ -159,10 +163,14 @@ final class MenuBandRewindVoice {
         // How many valid frames exist: the whole ring once it has wrapped,
         // otherwise only what's been written so far.
         let valid = Swift.min(framesWritten, cap)
-        // Capture window: the most-recent `captureSeconds`, floored to the
-        // minimum so a quiet/short history still yields an audible clip.
-        let want = Swift.max(Int(minCaptureSeconds * rate),
-                             Int(captureSeconds * rate))
+        // Capture window = audio SINCE the last press (notepat), floored to
+        // `minCaptureSeconds` and capped at the ring length. Rapid taps grab
+        // short successive chunks; a press after a phrase grabs the phrase.
+        let now = CACurrentMediaTime()
+        let sinceLast = lastPressTime > 0 ? (now - lastPressTime) : bufferSeconds
+        lastPressTime = now
+        let windowSec = Swift.min(bufferSeconds, Swift.max(minCaptureSeconds, sinceLast))
+        let want = Int(windowSec * rate)
         let count = Swift.min(valid, Swift.min(want, cap))
         guard count >= 256 else { ringLock.unlock(); return false }
         // Walk backward from the write head, emitting samples in REVERSE
@@ -177,48 +185,54 @@ final class MenuBandRewindVoice {
         }
         ringLock.unlock()
 
-        // --- Build a mono PCM buffer at the captured rate ---
-        guard let clipFormat = AVAudioFormat(commonFormat: .pcmFormatFloat32,
-                                             sampleRate: rate,
-                                             channels: 1, interleaved: false),
-              let clip = AVAudioPCMBuffer(pcmFormat: clipFormat,
+        // --- Build the clip in the player's ACTUAL output format ---
+        // (nil-connected, so it tracks the device). Building to match the
+        // player's format means `scheduleBuffer` never asserts on a sample-
+        // rate/channel mismatch — the bug that broke audio on a 96 kHz
+        // device. The ring is captured at the same device rate, so the
+        // reversed mono samples are copied into every output channel at the
+        // right speed.
+        let outFormat = player.outputFormat(forBus: 0)
+        guard outFormat.channelCount >= 1, outFormat.sampleRate > 0,
+              let clip = AVAudioPCMBuffer(pcmFormat: outFormat,
                                           frameCapacity: AVAudioFrameCount(count)),
-              let dst = clip.floatChannelData?[0]
+              let chData = clip.floatChannelData
         else { return false }
+        let chCount = Int(outFormat.channelCount)
         reversed.withUnsafeBufferPointer { src in
-            dst.update(from: src.baseAddress!, count: count)
+            guard let base = src.baseAddress else { return }
+            for c in 0..<chCount { chData[c].update(from: base, count: count) }
         }
         clip.frameLength = AVAudioFrameCount(count)
 
         // --- Pause capture, then play DRY into mainMixerNode ---
-        // Gate recording off for the playback duration so the reversed audio
-        // (which flows through the tapped mainMixerNode) is not recaptured.
+        // Gate recording off WHILE reverse-playing so the reversed audio
+        // (which flows through the tapped mainMixerNode) isn't recaptured.
+        // Capture resumes the instant Space is RELEASED (see `release()`),
+        // NOT when the clip ends — so notes you play right after letting go
+        // are captured immediately and the next press reverses THEM (this is
+        // the fix for the laggy/"adding-again" second run).
         recording = false
+        pressGeneration += 1
+        let gen = pressGeneration
         if !engine.isRunning { try? engine.start() }
         player.stop()
-        // The player was connected with `renderFormat` (44.1k mono). If the
-        // device is running at a different rate the engine resamples between
-        // our mixer and mainMixerNode; scheduling a clip at the captured rate
-        // is fine because AVAudioPlayerNode honours the buffer's own format.
-        let frameDuration = Double(count) / rate
-        player.scheduleBuffer(clip, at: nil, options: []) { [weak self] in
-            // Completion fires on a render thread — bounce to main to resume
-            // recording and re-arm the ring.
-            DispatchQueue.main.async { self?.finishReverse() }
-        }
+        player.scheduleBuffer(clip, at: nil, options: [], completionHandler: nil)
         if !player.isPlaying { player.play() }
-        // Safety net: if the completion handler is ever swallowed (engine
-        // reconfig mid-clip), resume recording shortly after the clip's
-        // natural end so we don't get stuck never recording again.
-        DispatchQueue.main.asyncAfter(deadline: .now() + frameDuration + 0.1) {
-            [weak self] in self?.finishReverse()
+        // Backstop only — if a Space key-up is ever dropped, don't get stuck
+        // muted: resume capture a bit after the clip would have ended, but
+        // only if no newer press has happened since.
+        let frameDuration = Double(count) / outFormat.sampleRate
+        DispatchQueue.main.asyncAfter(deadline: .now() + frameDuration + 2.0) {
+            [weak self] in
+            guard let self = self, self.pressGeneration == gen else { return }
+            self.finishReverse()
         }
         return true
     }
 
-    /// Stop any in-flight reverse clip and resume recording. Idempotent —
-    /// both the completion handler and the safety-net timer call it.
-    func stop() {
+    /// Space released — stop the reverse voice and resume live capture.
+    func release() {
         finishReverse()
     }
 
diff --git a/slab/menuband/Sources/MenuBand/MenuBandSynth.swift b/slab/menuband/Sources/MenuBand/MenuBandSynth.swift
index 1b49187aea..6b29a0c177 100644
--- a/slab/menuband/Sources/MenuBand/MenuBandSynth.swift
+++ b/slab/menuband/Sources/MenuBand/MenuBandSynth.swift
@@ -694,6 +694,12 @@ final class MenuBandSynth {
         return rewindVoice.playReverse()
     }
 
+    /// Spacebar released — stop the reverse voice and resume live capture so
+    /// notes played next are recorded for the following rewind.
+    func releaseReverse() {
+        rewindVoice.release()
+    }
+
     /// Play one random drum hit — the About-window card-flip easter egg
     /// pairs this with the sparkle chord so repeated flips build a little
     /// beat. Uses the live percussion kit (already attached to the bus).
diff --git a/slab/menuband/Sources/MenuBand/PianoWaveformWindow/CollapsedPianoWaveformView.swift b/slab/menuband/Sources/MenuBand/PianoWaveformWindow/CollapsedPianoWaveformView.swift
index 91361c2c99..a0fd5f2d04 100644
--- a/slab/menuband/Sources/MenuBand/PianoWaveformWindow/CollapsedPianoWaveformView.swift
+++ b/slab/menuband/Sources/MenuBand/PianoWaveformWindow/CollapsedPianoWaveformView.swift
@@ -42,6 +42,9 @@ final class CollapsedPianoWaveformView: NSView {
     /// instrument," and the popover stays a music-theory surface.
     private let modeStack = NSStackView()
     private var modeButtons: [NSButton] = []
+    /// Live audio strip above the instrument name — shows the output
+    /// waveform + reverse/forward direction so spacebar-rewind is debuggable.
+    private let waveformStrip = WaveformStripView()
     /// Single accent-colored "Keymap" button under the instrument picker.
     /// Opens the full-screen liquid-glass keymap view (large piano + large
     /// QWERTY + the Notepat/Conventional mode toggle). The collapsed panel
@@ -253,9 +256,13 @@ final class CollapsedPianoWaveformView: NSView {
             ])
         keymapButton.toolTip = "Open the full-screen keymap (piano + QWERTY)"
 
+        waveformStrip.menuBand = menuBand
+        waveformStrip.translatesAutoresizingMaskIntoConstraints = false
+
         addSubview(contentContainer)
         contentContainer.addSubview(instrumentGridContainer)
         instrumentGridContainer.addSubview(instrumentList)
+        contentContainer.addSubview(waveformStrip)
         contentContainer.addSubview(instrumentReadoutLabel)
         // [v1] Skip our own glass backdrop when embedded in the popover's
         // glass surface — otherwise the two stack into a doubled sheet.
@@ -272,7 +279,15 @@ final class CollapsedPianoWaveformView: NSView {
             contentContainer.topAnchor.constraint(equalTo: topAnchor),
             contentContainer.bottomAnchor.constraint(equalTo: bottomAnchor),
 
-            // Active-instrument readout at the top of the picker.
+            // Live waveform strip pinned at the very top of the picker.
+            waveformStrip.topAnchor.constraint(
+                equalTo: contentContainer.topAnchor, constant: Self.topInset),
+            waveformStrip.centerXAnchor.constraint(equalTo: contentContainer.centerXAnchor),
+            waveformStrip.widthAnchor.constraint(
+                equalToConstant: InstrumentListView.preferredWidth),
+            waveformStrip.heightAnchor.constraint(equalToConstant: 22),
+
+            // Active-instrument readout below the strip.
             instrumentReadoutLabel.leadingAnchor.constraint(
                 greaterThanOrEqualTo: contentContainer.leadingAnchor,
                 constant: Self.edgePadding),
@@ -282,7 +297,7 @@ final class CollapsedPianoWaveformView: NSView {
             instrumentReadoutLabel.centerXAnchor.constraint(
                 equalTo: contentContainer.centerXAnchor),
             instrumentReadoutLabel.topAnchor.constraint(
-                equalTo: contentContainer.topAnchor, constant: Self.topInset),
+                equalTo: waveformStrip.bottomAnchor, constant: Self.rowGap),
 
             // Instrument chooser grid below the readout.
             instrumentGridContainer.centerXAnchor.constraint(equalTo: contentContainer.centerXAnchor),
diff --git a/slab/menuband/Sources/MenuBand/WaveformStripView.swift b/slab/menuband/Sources/MenuBand/WaveformStripView.swift
new file mode 100644
index 0000000000..92240b79f2
--- /dev/null
+++ b/slab/menuband/Sources/MenuBand/WaveformStripView.swift
@@ -0,0 +1,120 @@
+import AppKit
+
+/// Compact live audio strip for the popover, shown above the instrument
+/// name. Instead of redrawing one instantaneous snapshot (which just
+/// flickers in place), it accumulates a SCROLLING min/max envelope — one
+/// column per frame, newest on the right, older columns drifting left — so
+/// you watch the recent buffer scroll by, the way native notepat's top
+/// strip does. ▶ while playing live (forward); while the spacebar reverse-
+/// replay is sounding the strip flips ◀ + orange and the trace mirrors so
+/// you can see it scrub backward through the buffer. Makes spacebar-rewind
+/// debuggable at a glance.
+///
+/// Lightweight (Core Graphics, polled at ~30 fps only while on screen).
+final class WaveformStripView: NSView {
+    weak var menuBand: MenuBandController?
+
+    /// One frame's worth of the tap ring (~46 ms at 44.1k); we reduce it to
+    /// a single min/max column per tick.
+    private var samples = [Float](repeating: 0, count: 2048)
+    /// Rolling per-column envelope. ~256 columns × ~33 ms/frame ≈ 8 s of
+    /// scrolling history (close to the 12 s rewind ring). Index 0 is oldest.
+    private static let columnCount = 256
+    private var colMin = [Float](repeating: 0, count: columnCount)
+    private var colMax = [Float](repeating: 0, count: columnCount)
+    private var timer: Timer?
+
+    override init(frame frameRect: NSRect) {
+        super.init(frame: frameRect)
+        wantsLayer = true
+    }
+    required init?(coder: NSCoder) { fatalError() }
+
+    override func viewDidMoveToWindow() {
+        super.viewDidMoveToWindow()
+        if window != nil { start() } else { stop() }
+    }
+
+    private func start() {
+        guard timer == nil else { return }
+        menuBand?.setWaveformCaptureEnabled(true)
+        let t = Timer(timeInterval: 1.0 / 30.0, repeats: true) { [weak self] _ in
+            self?.tick()
+        }
+        t.tolerance = 1.0 / 90.0
+        RunLoop.main.add(t, forMode: .common)
+        timer = t
+    }
+
+    private func stop() {
+        timer?.invalidate(); timer = nil
+        menuBand?.setWaveformCaptureEnabled(false)
+    }
+
+    deinit { timer?.invalidate() }
+
+    private func tick() {
+        menuBand?.synthSnapshotWaveform(into: &samples)
+        var mn: Float = 0, mx: Float = 0
+        for s in samples {
+            if s < mn { mn = s }
+            if s > mx { mx = s }
+        }
+        // Push one new column on the right, drop the oldest on the left.
+        colMin.removeFirst(); colMin.append(mn)
+        colMax.removeFirst(); colMax.append(mx)
+        needsDisplay = true
+    }
+
+    override func draw(_ dirtyRect: NSRect) {
+        let r = bounds
+        guard r.width > 4, r.height > 4 else { return }
+        let reversing = menuBand?.isRewinding ?? false
+        let accent = NSColor.controlAccentColor
+        let color = reversing ? NSColor.systemOrange : accent
+
+        // Recessed screen — opaque enough to read over the glass + when silent.
+        let plate = NSBezierPath(roundedRect: r.insetBy(dx: 0.5, dy: 0.5),
+                                 xRadius: 4, yRadius: 4)
+        NSColor.black.withAlphaComponent(0.55).setFill(); plate.fill()
+        color.withAlphaComponent(0.6).setStroke(); plate.lineWidth = 1.0; plate.stroke()
+
+        let mid = r.midY
+        let zero = NSBezierPath()
+        zero.move(to: NSPoint(x: 3, y: mid)); zero.line(to: NSPoint(x: r.width - 3, y: mid))
+        color.withAlphaComponent(0.25).setStroke(); zero.lineWidth = 0.5; zero.stroke()
+
+        let n = Self.columnCount
+        let inset: CGFloat = 4
+        let usableW = r.width - inset * 2
+        let amp = r.height * 0.44
+        // Scrolling min/max bars. Newest column on the RIGHT in live mode; in
+        // reverse the column order is mirrored so the trace runs the other
+        // way (you see the buffer scrub backward).
+        color.withAlphaComponent(0.95).setStroke()
+        let bars = NSBezierPath()
+        bars.lineWidth = 1.0
+        for i in 0..<n {
+            let col = reversing ? (n - 1 - i) : i
+            let x = inset + usableW * CGFloat(i) / CGFloat(n - 1)
+            let top = mid - CGFloat(max(-1, min(1, colMax[col]))) * amp
+            let bot = mid - CGFloat(max(-1, min(1, colMin[col]))) * amp
+            // Ensure at least a 0.5px tick even on near-silence so the
+            // scroll is visible as a moving baseline texture.
+            bars.move(to: NSPoint(x: x, y: min(top, bot)))
+            bars.line(to: NSPoint(x: x, y: max(top, bot) + 0.5))
+        }
+        bars.stroke()
+
+        // Direction glyph in the corner the trace flows toward.
+        let glyph = NSAttributedString(
+            string: reversing ? "◀" : "▶",
+            attributes: [
+                .font: NSFont.systemFont(ofSize: 9, weight: .bold),
+                .foregroundColor: color,
+            ])
+        let gs = glyph.size()
+        let gx = reversing ? 4 : r.width - gs.width - 4
+        glyph.draw(at: NSPoint(x: gx, y: mid - gs.height / 2))
+    }
+}
-- 
2.54.0