Sync from GitHub af6d0631

README.md

@@ -15,6 +15,8 @@ short_description: You start playing, it joins in — an AI music companion.
 > tempo, in the instrument you pick. Built for the Stability AI Challenge at
 > Music Hackspace Montreal (August 22–23, 2026).
 
+TRY IT NOW AT [Our HuggingFace Space](https://huggingface.co/spaces/salgadev/jam-buddy)
+
 ## What this is
 
 **Jam Buddy** is a call-and-response music practice partner. You start playing,

apps/web/__tests__/visualizer.test.tsx

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup, act } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { createRef } from "react";
+import { Visualizer, type VisualizerHandle } from "@/lib/jambuddy/visualizer";
+
+/**
+ * Regression test for the "one playback at a time" rule.
+ *
+ * Each playable waveform owns its own <Audio>. The parent wires onStartPlayback
+ * to stop any other playback before a new one starts. This pins:
+ *  - clicking a playable waveform's toggle fires onStartPlayback FIRST
+ *  - the exposed stop() handle actually stops the audio and resets the toggle
+ * So PLAY TOGETHER / another waveform can always silence a playing one.
+ */
+
+// Fake Audio so `new Audio(url)` works under happy-dom.
+class FakeAudio {
+  onended: (() => void) | null = null;
+  paused = true;
+  played = false;
+  play() {
+    this.played = true;
+    this.paused = false;
+    return Promise.resolve();
+  }
+  pause() {
+    this.paused = true;
+  }
+}
+let fakeAudio: FakeAudio | null = null;
+
+// Fake AudioContext + fetch so the waveform-draw effect completes cleanly.
+class FakeAudioContext {
+  sampleRate = 44100;
+  close() {
+    return Promise.resolve();
+  }
+  decodeAudioData() {
+    return Promise.resolve({
+      numberOfChannels: 1,
+      sampleRate: 44100,
+      getChannelData: () => new Float32Array(100),
+    });
+  }
+}
+
+beforeEach(() => {
+  fakeAudio = new FakeAudio();
+  vi.stubGlobal("Audio", class { constructor() { return fakeAudio; } });
+  vi.stubGlobal("AudioContext", FakeAudioContext);
+  vi.stubGlobal("fetch", vi.fn(() =>
+    Promise.resolve({ arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)) }),
+  ));
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+describe("Visualizer playable waveform", () => {
+  it("fires onStartPlayback BEFORE starting play (exclusivity guard)", async () => {
+    const user = userEvent.setup();
+    const onStart = vi.fn();
+    const ref = createRef<VisualizerHandle>();
+    await act(async () => {
+      render(
+        <Visualizer
+          ref={ref}
+          audioUrl="blob:take"
+          playable
+          onStartPlayback={onStart}
+        />,
+      );
+    });
+
+    await user.click(screen.getByRole("button", { name: "Play" }));
+
+    // The owner must be told to stop anything else before this one starts.
+    expect(onStart).toHaveBeenCalledTimes(1);
+    expect(fakeAudio?.played).toBe(true);
+  });
+
+  it("exposes a stop() handle that stops audio and flips the toggle back", async () => {
+    const user = userEvent.setup();
+    const ref = createRef<VisualizerHandle>();
+    await act(async () => {
+      render(<Visualizer ref={ref} audioUrl="blob:take" playable />);
+    });
+
+    await user.click(screen.getByRole("button", { name: "Play" }));
+    // Now playing -> the toggle reads Stop.
+    expect(screen.getByRole("button", { name: "Stop playback" })).toBeInTheDocument();
+
+    act(() => {
+      ref.current?.stop();
+    });
+    expect(fakeAudio?.paused).toBe(true);
+    // stop() resets internal state, so the toggle reads Play again.
+    expect(screen.getByRole("button", { name: "Play" })).toBeInTheDocument();
+  });
+});

apps/web/app/api/jambuddy/route.ts

@@ -17,6 +17,9 @@ interface JambuddyBody {
   midi?: string;
   /** Base64-encoded audio take (mic/interface/render) for audio-to-audio. */
   audio?: string;
+  /** Real extension of the audio take (aif/wav/mp3/...) — keeps the temp file
+   * name matching its content so soundfile can read it. */
+  audioExt?: string;
   /** Response length in seconds. Default 30 (ignored when a take is provided). */
   duration?: number;
   /** Generation backend: "local" (CPU SA3) or "api" (Stable Audio 3.0 Large, 26 credits/gen). */
@@ -166,7 +169,10 @@ export async function POST(req: NextRequest) {
     } else if (body.audio) {
       // Audio: pass to SA3 via init_audio so it responds to the groove. Tempo
       // is still the knob; the take sets duration + drives audio-to-audio.
-      const audioPath = join(tmpdir(), `jambuddy-take-${Date.now()}.wav`);
+      // Use the real audio extension (AIFF/WAV/MP3/...) so soundfile can read
+      // the temp file — a .wav-named AIFF/WEBM fails "Format not recognised".
+      const ext = body.audioExt?.match(/^[a-z0-9]{1,4}$/) ? body.audioExt : "wav";
+      const audioPath = join(tmpdir(), `jambuddy-take-${Date.now()}.${ext}`);
       await writeFile(audioPath, Buffer.from(body.audio, "base64"));
       args.push("--wav", audioPath);
       args.push("--genre", body.knobs.genre);

apps/web/app/page.tsx

@@ -29,7 +29,7 @@ import {
   type AudioInput,
   type MidiInput,
 } from "@/lib/jambuddy/recorder";
-import { Visualizer } from "@/lib/jambuddy/visualizer";
+import { Visualizer, type VisualizerHandle } from "@/lib/jambuddy/visualizer";
 
 /**
  * Jam Buddy — "you start playing, it joins in."
@@ -158,6 +158,15 @@ function Pad({
   );
 }
 
+/** Bundled demo takes (Gradio-style clickable examples).
+ * Each is an MP3 (loads as an audio take so the buddy responds to it) with a
+ * matching BPM (from the source MIDI) that pre-sets the tempo knob. */
+const DEMO_MIDIS = [
+  { name: "tupatutupatututata", label: "Tupatutupatututata (drums)", bpm: 158 },
+  { name: "dangerous-bass-line", label: "Dangerous bass line", bpm: 120 },
+  { name: "this-riff-does-not-exist", label: "This riff does not exist", bpm: 160 },
+];
+
 export default function HomePage() {
   const [instrument, setInstrument] = useState<BuddyInstrument>("bass");
   const [inputInstrument, setInputInstrument] = useState<InputInstrument>("other");
@@ -175,6 +184,10 @@ export default function HomePage() {
   const [usedBpm, setUsedBpm] = useState<number | null>(null);
   const [usedSeconds, setUsedSeconds] = useState<number | null>(null);
   const [busy, setBusy] = useState(false);
+  // Name of the demo chip currently loaded as the take (for active highlight).
+  const [loadedDemo, setLoadedDemo] = useState<string | null>(null);
+  // Monotonic token so a slow demo fetch can't clobber a newer selection.
+  const demoLoadToken = useRef(0);
   // Generation backend. API (Stable Audio 3.0 Large) is default when the key is
   // present — fast + better isolation, 26 credits/gen. Local = CPU small model,
   // free, supports the negative prompt, slower.
@@ -230,8 +243,38 @@ export default function HomePage() {
     );
   }
 
-  /** Handle a single uploaded take (MIDI or audio), auto-detecting the type. */
-  async function handleTakeFile(f: File | null) {
+  /** Load a bundled demo as an audio take + set the tempo knob to its BPM.
+   * The MP3 is what the buddy responds to (audio-to-audio); the exact tempo
+   * comes from the source MIDI, so we set the knob to it rather than trusting
+   * librosa's estimate of the MP3. */
+  async function loadDemo(name: string, demoBpm: number) {
+    // Select immediately (single-select) + pin the knob, so the UI responds
+    // instantly instead of waiting on the slow fetch/detect below.
+    const token = ++demoLoadToken.current;
+    setLoadedDemo(name);
+    setBpm(demoBpm);
+    setStatus(`Loading demo "${name}"…`);
+    try {
+      const res = await fetch(`/demos/${name}.mp3`);
+      if (!res.ok) throw new Error(`fetch ${name}.mp3 -> ${res.status}`);
+      const blob = await res.blob();
+      const file = new File([blob], `${name}.mp3`, { type: "audio/mpeg" });
+      // Ignore a stale load if the user has since picked a different demo.
+      if (token !== demoLoadToken.current) return;
+      // Load it as an audio take; knownBpm skips the slow server detect.
+      await handleTakeFile(file, demoBpm);
+      setStatus(`Loaded demo "${name}" @ ${demoBpm} BPM.`);
+    } catch (e) {
+      if (token === demoLoadToken.current) {
+        setStatus(`Couldn't load demo: ${String(e)}`);
+      }
+    }
+  }
+
+  /** Handle a single uploaded take (MIDI or audio), auto-detecting the type.
+   * `knownBpm` (optional) skips the slow server detect and pins the knob to a
+   * caller-supplied tempo — used by demo chips, which already know their BPM. */
+  async function handleTakeFile(f: File | null, knownBpm?: number) {
     // One upload slot for either kind; picking a new file clears the old take.
     setMidiFile(null);
     setMidiBytes(null);
@@ -256,7 +299,11 @@ export default function HomePage() {
       }
       // Pre-fill the tempo knob from the take's tempo map (Option A: detect
       // first, knob stays authoritative + editable).
-      await prefillTempo(f, "midi");
+      if (knownBpm !== undefined) {
+        setBpm(knownBpm);
+      } else {
+        await prefillTempo(f, "midi");
+      }
       setStatus(
         `Loaded ${f.name}. Tempo auto-detected (${bpm} BPM); adjust the knob if needed.`,
       );
@@ -266,7 +313,11 @@ export default function HomePage() {
       // Audio is heard by the buddy (audio-to-audio). Clear the MIDI-driven
       // input-instrument default so the user's declaration reflects the audio.
       setInputInstrument("other");
-      await prefillTempo(f, "audio");
+      if (knownBpm !== undefined) {
+        setBpm(knownBpm);
+      } else {
+        await prefillTempo(f, "audio");
+      }
       setStatus(
         `Loaded ${f.name}. Tempo auto-detected (${bpm} BPM); adjust the knob if needed.`,
       );
@@ -435,7 +486,17 @@ export default function HomePage() {
    * click can read a stale `false` and start a SECOND simultaneous layer. Keep
    * a synchronous ref so the toggle is atomic. */
   const playbackRef = useRef<{ stop: () => void } | null>(null);
-  const audioRef = useRef<HTMLAudioElement | null>(null);
+  // Refs to the take + response visualizers so PLAY TOGETHER / other toggles
+  // can stop their audio (enforces one playback at a time).
+  const takeVisualizerRef = useRef<VisualizerHandle>(null);
+  const responseVisualizerRef = useRef<VisualizerHandle>(null);
+
+  // Central authority: stop every waveform toggle before any new playback
+  // starts, so the same audio never plays in two places at once.
+  const stopAllWaveformPlayback = () => {
+    takeVisualizerRef.current?.stop();
+    responseVisualizerRef.current?.stop();
+  };
   async function playBoth() {
     if (playbackRef.current) {
       // Stop: kill current playback (synchronous — immune to stale state).
@@ -449,8 +510,9 @@ export default function HomePage() {
       setStatus("Generate a response first.");
       return;
     }
-    // Pause the standalone audio element so the response isn't heard twice.
-    audioRef.current?.pause();
+    // Stop any single-waveform playback so the same audio isn't heard twice
+    // while PLAY TOGETHER runs.
+    stopAllWaveformPlayback();
     playbackRef.current = { stop: () => {} }; // claim the toggle synchronously
     setIsPlayingTogether(true);
     setStatus("Playing your take + the buddy together…");
@@ -504,6 +566,9 @@ export default function HomePage() {
         bpm?: number;
         midi?: string;
         audio?: string;
+        /** Real extension of the audio take (e.g. aif, wav, mp3) so the server
+         * names the temp file correctly. */
+        audioExt?: string;
         duration?: number;
         mode: "api" | "local";
       } = { knobs: { instrument, inputInstrument, genre, mood, bpm }, mode };
@@ -520,6 +585,11 @@ export default function HomePage() {
         setStatus("Reading your audio take…");
         const base64 = await fileToBase64(audioFile);
         payload.audio = base64;
+        // Pass the real audio extension so the server names the temp file
+        // correctly (soundfile won't read a .wav-named AIFF/WEBM).
+        const extMatch = audioFile.name.match(/\.(aiff?|wav|mp3|flac|ogg|m4a|webm)$/i);
+        const ext = extMatch?.[1] ?? "wav";
+        payload.audioExt = ext.toLowerCase();
         // Audio-to-audio: the buddy responds to the groove.
         delete payload.bpm;
       }
@@ -676,6 +746,29 @@ export default function HomePage() {
               {audioFile.name} — audio: buddy responds to its groove (audio-to-audio).
             </p>
           )}
+          {/* Gradio-style demo examples: click to load as a take. Playback is
+              on the take waveform (audio) below. */}
+          <div className="mt-3 flex flex-wrap items-center gap-2">
+            <span className="font-mono text-[10px] uppercase tracking-widest text-[#7f829c]">
+              Demos
+            </span>
+            {DEMO_MIDIS.map((d) => (
+              <button
+                key={d.name}
+                type="button"
+                onClick={() => loadDemo(d.name, d.bpm)}
+                disabled={busy}
+                aria-pressed={loadedDemo === d.name}
+                className={`rounded-full border px-3 py-1 text-xs ${
+                  loadedDemo === d.name
+                    ? "border-[#5fd38a] bg-[#5fd38a]/15 text-[#5fd38a]"
+                    : "border-[#2a2d3d] bg-[#1a1c28] text-[#e8e8f0] hover:border-[#5fd38a] hover:text-[#5fd38a]"
+                }`}
+              >
+                {d.label}
+              </button>
+            ))}
+          </div>
         </section>
 
         {/* Transport */}
@@ -863,16 +956,6 @@ export default function HomePage() {
               Generated in {usedSeconds.toFixed(1)}s
             </p>
           )}
-          {audioUrl && (
-            <audio
-              ref={audioRef}
-              controls
-              src={audioUrl}
-              className="mt-3 w-full"
-            >
-              Your browser does not support audio playback.
-            </audio>
-          )}
         </section>
 
         {/* Take + response visualizers — stacked vertically, DAW-style.
@@ -911,8 +994,11 @@ export default function HomePage() {
               <div className="flex items-end gap-3">
                 <div className="flex-1">
                   <Visualizer
+                    ref={takeVisualizerRef}
                     audioUrl={takeAudioUrl}
                     label="Your take (audio waveform)"
+                    playable
+                    onStartPlayback={stopAllWaveformPlayback}
                   />
                 </div>
               </div>
@@ -921,8 +1007,11 @@ export default function HomePage() {
               <div className="flex items-end gap-3">
                 <div className="flex-1">
                   <Visualizer
+                    ref={responseVisualizerRef}
                     audioUrl={audioUrl}
                     label="Buddy response (waveform)"
+                    playable
+                    onStartPlayback={stopAllWaveformPlayback}
                   />
                 </div>
                 <button

apps/web/lib/jambuddy/player.ts

@@ -188,6 +188,54 @@ export function midiTempo(buf: ArrayBuffer): number {
   }
 }
 
+/**
+ * Play a MIDI take SOLO through the synth (no buddy). Used by the demo
+ * examples so a MIDI can be previewed on its own.
+ *
+ * @param midiBytes the MIDI bytes to play
+ * @returns a stop() handle
+ */
+export async function playMidi(
+  midiBytes: ArrayBuffer,
+): Promise<{ stop: () => void; done: Promise<void> }> {
+  const ctx = new AudioContext();
+  await ctx.resume();
+
+  const master = ctx.createGain();
+  master.gain.value = 0.8;
+  master.connect(ctx.destination);
+
+  const notes = parseMidi(midiBytes);
+  const startAt = ctx.currentTime + 0.1;
+  for (const note of notes) {
+    scheduleNote(ctx, note, master, startAt + note.time);
+  }
+  const lastMidiTime = notes.length ? (notes[notes.length - 1]?.time ?? 0) : 0;
+  const end = startAt + lastMidiTime + 1;
+
+  const done = new Promise<void>((resolve) => {
+    setTimeout(() => {
+      try {
+        ctx.close();
+      } catch {
+        /* already closed */
+      }
+      resolve();
+    }, Math.max(0, (end - ctx.currentTime) * 1000) + 200);
+  });
+
+  return {
+    stop: () => {
+      try {
+        ctx.close();
+      } catch {
+        /* ignore */
+      }
+    },
+    done,
+  };
+}
+
 /**
  * Get the total duration (seconds) of a MIDI file — the time of the last note
  * end. This is what the generated response must match so the take and the

apps/web/lib/jambuddy/visualizer.tsx

@@ -12,9 +12,14 @@
  * you can compare the take and the response side by side.
  */
 
-import { useEffect, useRef } from "react";
+import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from "react";
 import { parseMidi, type ParsedNote } from "./player";
 
+export interface VisualizerHandle {
+  /** Stop any audio this visualizer is playing (used to enforce exclusivity). */
+  stop: () => void;
+}
+
 interface VisualizerProps {
   /** MIDI bytes -> piano-roll. Mutually exclusive with audioUrl. */
   midiBytes?: ArrayBuffer | null;
@@ -24,6 +29,11 @@ interface VisualizerProps {
   label?: string;
   /** Height of the canvas in px. */
   height?: number;
+  /** Show a play/stop toggle on the waveform (audio only). */
+  playable?: boolean;
+  /** Called right before this visualizer starts playing, so the owner can stop
+   * any other audio source (enforces "one waveform, one playback"). */
+  onStartPlayback?: () => void;
 }
 
 const NOTE_MIN = 21; // A0
@@ -119,77 +129,143 @@ function drawWaveform(
   }
 }
 
-export function Visualizer({
-  midiBytes,
-  audioUrl,
-  label,
-  height = 120,
-}: VisualizerProps) {
-  const canvasRef = useRef<HTMLCanvasElement>(null);
-
-  useEffect(() => {
-    const canvas = canvasRef.current;
-    if (!canvas) return;
-
-    if (midiBytes) {
-      let notes: ParsedNote[] = [];
-      let duration = 0;
-      try {
-        notes = parseMidi(midiBytes);
-        duration = notes.reduce(
-          (m, n) => Math.max(m, n.time + n.duration),
-          0,
-        );
-      } catch {
-        /* corrupt bytes -> empty roll */
+export const Visualizer = forwardRef<VisualizerHandle, VisualizerProps>(
+  function Visualizer(
+    {
+      midiBytes,
+      audioUrl,
+      label,
+      height = 120,
+      playable = false,
+      onStartPlayback,
+    },
+    ref,
+  ) {
+    const canvasRef = useRef<HTMLCanvasElement>(null);
+    // Play/stop state for the waveform toggle (audio only).
+    const [playing, setPlaying] = useState(false);
+    const audioRef = useRef<HTMLAudioElement | null>(null);
+
+    // Expose a stop() so the parent can enforce one-waveform-at-a-time.
+    useImperativeHandle(ref, () => ({
+      stop: () => {
+        audioRef.current?.pause();
+        audioRef.current = null;
+        setPlaying(false);
+      },
+    }));
+
+    useEffect(() => {
+      const canvas = canvasRef.current;
+      if (!canvas) return;
+      // reset play state whenever the audio changes
+      setPlaying(false);
+      if (audioRef.current) {
+        audioRef.current.pause();
+        audioRef.current = null;
+      }
+      if (midiBytes) {
+        let notes: ParsedNote[] = [];
+        let duration = 0;
+        try {
+          notes = parseMidi(midiBytes);
+          duration = notes.reduce(
+            (m, n) => Math.max(m, n.time + n.duration),
+            0,
+          );
+        } catch {
+          /* corrupt bytes -> empty roll */
+        }
+        drawPianoRoll(canvas, notes, duration);
+        return;
+      }
+
+      if (audioUrl) {
+        const ctx = new AudioContext();
+        fetch(audioUrl)
+          .then((r) => r.arrayBuffer())
+          .then((buf) => ctx.decodeAudioData(buf))
+          .then((audio) => {
+            drawWaveform(canvas, audio);
+            ctx.close();
+          })
+          .catch(() => {
+            const c = canvas.getContext("2d");
+            if (c) {
+              c.fillStyle = "#12131b";
+              c.fillRect(0, 0, canvas.clientWidth, canvas.clientHeight);
+              c.fillStyle = "#7f829c";
+              c.font = "12px ui-monospace, monospace";
+              c.textAlign = "center";
+              c.fillText("no audio", canvas.clientWidth / 2, canvas.clientHeight / 2);
+            }
+          });
+        return;
       }
-      drawPianoRoll(canvas, notes, duration);
-      return;
-    }
 
-    if (audioUrl) {
-      const ctx = new AudioContext();
-      fetch(audioUrl)
-        .then((r) => r.arrayBuffer())
-        .then((buf) => ctx.decodeAudioData(buf))
-        .then((audio) => {
-          drawWaveform(canvas, audio);
-          ctx.close();
-        })
+      // Nothing to draw.
+      const c = canvas.getContext("2d");
+      if (c) {
+        c.fillStyle = "#12131b";
+        c.fillRect(0, 0, canvas.clientWidth, canvas.clientHeight);
+      }
+    }, [midiBytes, audioUrl]);
+
+    // Toggle play/stop of the waveform's audio (audio only).
+    const togglePlay = () => {
+      if (!audioUrl) return;
+      if (playing) {
+        audioRef.current?.pause();
+        audioRef.current = null;
+        setPlaying(false);
+        return;
+      }
+      // Tell the owner to stop anything else first (one playback at a time).
+      onStartPlayback?.();
+      const a = new Audio(audioUrl);
+      a.onended = () => {
+        audioRef.current = null;
+        setPlaying(false);
+      };
+      audioRef.current = a;
+      a.play()
+        .then(() => setPlaying(true))
         .catch(() => {
-          const c = canvas.getContext("2d");
-          if (c) {
-            c.fillStyle = "#12131b";
-            c.fillRect(0, 0, canvas.clientWidth, canvas.clientHeight);
-            c.fillStyle = "#7f829c";
-            c.font = "12px ui-monospace, monospace";
-            c.textAlign = "center";
-            c.fillText("no audio", canvas.clientWidth / 2, canvas.clientHeight / 2);
-          }
+          audioRef.current = null;
+          setPlaying(false);
         });
-      return;
-    }
+    };
 
-    // Nothing to draw.
-    const c = canvas.getContext("2d");
-    if (c) {
-      c.fillStyle = "#12131b";
-      c.fillRect(0, 0, canvas.clientWidth, canvas.clientHeight);
-    }
-  }, [midiBytes, audioUrl]);
-
-  return (
-    <div className="w-full">
-      {label && (
-        <div className="mb-1 font-mono text-[10px] uppercase tracking-widest text-[#7f829c]">
-          {label}
+    return (
+      <div className="w-full">
+        {label && (
+          <div className="mb-1 font-mono text-[10px] uppercase tracking-widest text-[#7f829c]">
+            {label}
+          </div>
+        )}
+        <div className="flex items-center gap-2">
+          {playable && audioUrl && (
+            <button
+              type="button"
+              onClick={togglePlay}
+              aria-label={playing ? "Stop playback" : "Play"}
+              title={playing ? "Stop" : "Play"}
+              className={`grid h-9 w-9 shrink-0 place-items-center rounded-full border text-sm ${
+                playing
+                  ? "border-[#e05252] bg-[#e05252] text-[#12131b]"
+                  : "border-[#2a2d3d] bg-[#1a1c28] text-[#5fd38a] hover:bg-[#5fd38a] hover:text-[#12131b]"
+              }`}
+            >
+              {playing ? "■" : "▶"}
+            </button>
+          )}
+          <canvas
+            ref={canvasRef}
+            className="w-full rounded border border-[#2a2d3d] bg-[#12131b]"
+            style={{ height }}
+          />
         </div>
-      )}
-      <canvas
-        ref={canvasRef}
-        className="w-full rounded border border-[#2a2d3d] bg-[#12131b]"
-        style={{ height }}
-      />
-    </div>
-  );
-}
+      </div>
+    );
+  },
+);

docs/09-risks.md

@@ -312,3 +312,54 @@ Risks ranked by impact × likelihood. Each has an owner, a mitigation, and a con
 - Mobile apps
 - Cloud accounts / user authentication
 - Anything that requires a third-party API key beyond SA3
+
+---
+
+## Current Jam Buddy bugs & findings (verified against Stability API docs)
+
+> These are open/confirmed items tracked for the current work. Docs consulted:
+> `platform.stability.ai/docs/api-reference` → `post /v2beta/audio/stable-audio/audio-to-audio`.
+
+### 1. SA3 `strength` (noise/denoising) is NOT being sent — open bug (high priority)
+
+The SA3 **audio-to-audio** request schema exposes a `strength` parameter (a.k.a.
+*denoising*): **0 = output identical to input, 1 = as if no input was given.**
+We do **not** send it, so it defaults to **1** = full diffusion. This explains:
+- "generations render nothing new" (input take fully morphed / barely anchors output)
+- "output contains more than one instrument" (the take's instrument doesn't anchor,
+  model freely adds others)
+
+Stability's guidance for audio-to-audio is `strength` ≈ **0.5–0.8** (diffuse the
+take but keep it as the anchor). This is the pending **"Noise knob"** task —
+wire `strength` into `tools/jam_buddy_api.py` and expose it in the UI. **UNSENT today.**
+
+### 2. The audio API has NO `negative_prompt` — confirmed
+SA3 audio-to-audio only accepts: `prompt`, `audio`, `model`, `duration`, `seed`,
+`steps`, `cfg_scale`, `output_format`, `strength`. There is **no `negative_prompt`**.
+(Negative prompts exist on Stable *Image*, not Stable Audio.) So we **cannot** steer
+away from extra instruments via a negative prompt — the positive prompt + `cfg_scale`
++ `strength` are the only levers. The local CPU fallback (`small-music`) DOES accept
+a negative prompt.
+
+### 3. Demo examples can't be played — RESOLVED
+The clickable demo chips (Gradio-style) load MIDI as a take, but preview playback
+doesn't work — the MIDI examples need to render to audio to actually be audible
+as a "playable example." Consider pre-rendering the demo MIDIs to audio (or
+ensuring the Web-MIDI synth preview actually plays).
+
+**Resolved:** demos now load their pre-rendered MP3 as an audio take (with the
+BPM knob pinned to the source MIDI's tempo), and playback is a play/stop toggle
+on the waveform. Single-select + instant highlight/knob update.
+
+### 4. Stale `.next` cache corrupts the dev server (recurring) — OPEN
+`next dev`'s incremental cache corrupts after heavy edits. Symptoms: API routes
+500 (`MODULE_NOT_FOUND` in `webpack-runtime.js`) OR the page renders blank
+(every `/_next/static/chunk` 404s while `GET /` still returns 200). Often a
+leftover process squats on port 3000. Fix today: kill the port-3000 PID
+(`netstat -ano | grep :3000`, `taskkill /F /PID`), `rm -rf apps/web/.next`,
+restart `pnpm dev`, verify chunks load (not just `GET /`). **Address later** —
+candidate: a `dev:clean` npm script that clears `.next` before starting, or a
+more robust dev workflow.
+
+
+

tools/midi_to_audio.py

@@ -12,7 +12,7 @@ guitar reference.
 
 Usage:
   .venv/Scripts/python.exe tools/midi_to_audio.py \
-      --midi tools/hextermination_blast.mid \
+      --midi demos/tupatutupatututata.mid \
       --oneshots tools/oneshots \
       --bpm 184 --out drums.wav
   # add --guitar ref.wav to mix drums under the guitar