vibeaudio 0.7.0 → 0.8.2

package/README.md

@@ -23,6 +23,7 @@ AI coding agents take 15–45 seconds to reason, read files and write code. Star
 * 🧮 **Pure synthesis, zero MP3s.** Every note, chord and pad is generated in code — no audio assets, no npm dependencies, no `node-gyp`.
 * 🎼 **A different arrangement per project.** Your working directory seeds the progression, bass line and melody, so each repo has its own sound and keeps it.
 * 📈 **Escalating layers.** Tier 1 (0–15s) gentle intro → Tier 2 (15–45s) main groove → Tier 3 (45s+) deep focus. You can hear how deep into the task the agent is.
+* 🔁 **A phrase, not a loop.** Each piece is three bars that rotate through your project's own progressions, so a long turn moves through a ~21-second phrase instead of replaying one 7-second bar for half an hour.
 * 🎛️ **Music that follows the work** ([reactive mode](#reactive-mode-opt-in), opt-in). Calm while the agent reads, fuller while it edits, busiest when it runs commands or hands work to sub-agents — you can hear *what* it's doing, not just for how long.
 * 🔔 **Outcome-aware chimes.** Ascending on success, a soft descending minor chord on failure, and **silence on `Ctrl+C`** — an abort is never reported as done.
 * ✋ **A "your turn" chime.** When Claude Code stops to ask permission (or an MCP server asks for input), the music pauses and a rising two-note chime asks for you; it picks back up once you've answered.
@@ -60,6 +61,15 @@ That's a deliberate choice. Focus music has one job: **be ignorable.** Music tha
 
 ---
 
+### 🎧 Send someone your repo's sound
+
+```bash
+vibe --render            # -> vibeaudio-lofi.wav, ~53s
+vibe --genre jazz --render our-api.wav
+```
+
+A whole session in one file: every bar of the phrase at tier 1, then tier 2, then tier 3, and the success chime at the end — rendered from your project's own seed, at full scale so your player's volume control is the only one in the way. Plain WAV, so nothing has to be installed to play it.
+
 ## 📋 Requirements
 
 * **Node.js ≥ 18**
@@ -87,6 +97,14 @@ npm i -g vibeaudio
 
 That puts `vibe` and `vibeaudio` on your `PATH`. Re-run the same command to update, or see [Uninstall](#-uninstall) to remove it cleanly.
 
+**Want what's on `main`?** Fixes land here before they reach the registry, and installing from GitHub gets them straight away — no clone, no build:
+
+```bash
+npm i -g github:kiril6/vibeaudio
+```
+
+Same command to update it again. Switch back to the released version any time with `npm i -g vibeaudio`.
+
 **Staying up to date.** When a newer version is out, `vibe --status`, `vibe --help` and the menu say so in one line. They're the only places it's shown — never in your agent's hooks, and never over a command you wrapped. What changed is on the [releases page](https://github.com/kiril6/vibeaudio/releases).
 
 <details>
@@ -464,7 +482,20 @@ VibeAudio includes **8 procedural music styles** synthesized entirely in code:
 | `drone` | 🌫️ **Deep Drone** | A held tone and filtered noise — **no melody at all** |
 | `random` | 🎲 **Shuffle Mode** | Picks a surprise genre for the run — **never `drone`** |
 
-Aliases also work: `chiptune` → `8bit`, `downtempo` → `electronic`, `bossa` → `jazz`, `ambient` → `zen`, `sparse`/`satie` → `piano`, `noise`/`focus` → `drone`.
+**Aliases also work**, so you can ask for a genre the way you'd say it — `vibe --preview chill` is `lofi`:
+
+| Canonical | Also accepted |
+| :--- | :--- |
+| `lofi` | `lo-fi`, `lofi-hiphop`, `chill`, `chillhop`, `study` |
+| `synthwave` | `retrowave`, `outrun`, `80s` |
+| `8bit` | `chiptune`, `chip`, `nes`, `gameboy`, `retro` |
+| `electronic` | `downtempo`, `techno`, `edm` |
+| `jazz` | `bossa`, `swing`, `lounge` |
+| `zen` | `ambient`, `calm`, `meditation` |
+| `piano` | `sparse`, `satie`, `keys`, `minimal` |
+| `drone` | `noise`, `focus`, `hum`, `whitenoise`, `white-noise` |
+
+Matching is case-insensitive, so `BOSSA` works too.
 
 > **If any melody distracts you, use `drone`.** Every other genre plays something — notes, a progression, a bass line — and some people can't read while that happens. `drone` holds one low tone under a slow-breathing noise bed and never moves: closer to a fan or rainfall than to music. Tiers add weight rather than movement.
 >
@@ -526,6 +557,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--no-chime` | Disable the resolution completion chime | `false` |
 | `--no-hud` | Disable terminal window/tab title animation | `false` |
 | `--preview <genre>` | Play one loop of a genre and exit | — |
+| `--render [file]` | Write this project's music to a `.wav` and exit | `vibeaudio-<genre>.wav` |
 | `--status` | Show what's installed, running and detected, then exit | — |
 | `--stop` | Stop the background player, then exit | — |
 | `--mute [minutes]` | Silence everything for a call, then exit | `60` min (`0` = until unmuted) |
@@ -692,6 +724,10 @@ Apart from those two, the three commands above remove everything VibeAudio write
 
 ---
 
+If VibeAudio is useful to you, consider giving it a ⭐ on [GitHub](https://github.com/kiril6/vibeaudio) — it helps others find it.
+
+---
+
 ## 🤝 Contributing
 
 Contributions welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the ground rules (zero runtime dependencies, no build step, pure synth modules) and the dev loop. Found a bug? [Open an issue](https://github.com/kiril6/vibeaudio/issues/new) with your **OS**, **Node version**, and which audio player you have installed.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vibeaudio",
-  "version": "0.7.0",
-  "description": "Procedural focus music while your AI coding tools (Claude Code, Codex, Cursor, Grok, Gemini, Copilot) think \u2014 a different arrangement per project.",
+  "version": "0.8.2",
+  "description": "Procedural focus music while your AI coding tools (Claude Code, Codex, Cursor, Grok, Gemini, Copilot) think — a different arrangement per project.",
   "bin": {
     "vibeaudio": "bin/vibeaudio.js",
     "vibe": "bin/vibeaudio.js"
@@ -28,16 +28,25 @@
   ],
   "keywords": [
     "claude-code",
+    "claude",
     "codex",
     "cursor",
+    "gemini-cli",
+    "copilot",
     "grok",
-    "gemini",
-    "cli",
-    "audio",
+    "qwen",
+    "ai",
+    "ai-agent",
+    "hooks",
+    "mcp",
+    "music",
+    "focus-music",
     "lofi",
     "synthwave",
     "chiptune",
-    "focus-music",
+    "productivity",
+    "notification",
+    "cli",
     "developer-tools"
   ],
   "author": "Kiril Delovski <delovski.office@gmail.com>",

package/src/cli.js

@@ -11,6 +11,7 @@ const {
   getAudioPath,
   clearCache,
   detectPlayer,
+  bakedGain,
   resolveGenre,
   isKnownGenre,
   normalizeVolume,
@@ -19,6 +20,7 @@ const {
   projectSettings,
   saveProjectConfig,
   wavDurationMs,
+  projectSeed,
   AVAILABLE_GENRES
 } = require("./player");
 const pkg = require("../package.json");
@@ -56,6 +58,7 @@ Procedural focus music while your AI coding tools think.
   vibe --genre 8bit sleep 5
   vibe --volume 30 npm test
   vibe --preview jazz
+  vibe --render                  \x1b[90m# save this repo's sound as a .wav to share\x1b[0m
   vibe                           \x1b[90m# menu: pick a tool and a sound (p auditions a genre)\x1b[0m
 
 \x1b[1mOPTIONS:\x1b[0m
@@ -71,6 +74,7 @@ Procedural focus music while your AI coding tools think.
       --no-chime               Disable the resolution completion chime
       --no-hud                 Disable terminal window/tab title animation
       --preview <genre>        Play one loop of a genre and exit
+      --render [file]          Write this project's music to a .wav and exit
       --status                 Show what is installed, running and detected, then exit
       --stop                   Stop the background player, then exit
       --mute [minutes]         Silence everything for a call (default: 60 min, 0 = until unmuted)
@@ -164,6 +168,7 @@ function parseArgs(argv) {
   let noChime = false;
   let noHud = false;
   let preview = null;
+  let render = null;
   let clearCacheFlag = false;
   let statusFlag = false;
   let stopFlag = false;
@@ -250,6 +255,20 @@ function parseArgs(argv) {
       continue;
     }
 
+    // Optional filename: `--render` alone names the file after the genre.
+    // Only a non-flag counts, so `vibe --render --genre zen` still parses as
+    // both, the way `--mute claude` does.
+    if (arg === "--render") {
+      i += 1;
+      if (args[i] !== undefined && !args[i].startsWith("-")) {
+        render = args[i];
+        i += 1;
+      } else {
+        render = "";
+      }
+      continue;
+    }
+
     if (arg === "--clear-cache") {
       clearCacheFlag = true;
       i += 1;
@@ -401,6 +420,7 @@ function parseArgs(argv) {
     noChime,
     noHud,
     preview,
+    render,
     clearCache: clearCacheFlag,
     status: statusFlag,
     stop: stopFlag,
@@ -915,6 +935,15 @@ function signalExitCode(signal) {
   return 128 + (os.constants.signals[signal] || 0);
 }
 
+function previewAudioFile(genre, volume, backend) {
+  return getAudioPath(
+    resolveGenre(genre),
+    2,
+    projectSeed(),
+    bakedGain(backend, volume)
+  );
+}
+
 function previewGenre(genre, volume) {
   if (!isKnownGenre(genre)) {
     console.error(`\x1b[31m[vibeaudio] Unknown genre '${genre}'.\x1b[0m Available: ${AVAILABLE_GENRES.join(", ")}, random`);
@@ -928,13 +957,45 @@ function previewGenre(genre, volume) {
   }
 
   const resolved = resolveGenre(genre);
-  const audioFile = getAudioPath(resolved, 2);
+  const audioFile = previewAudioFile(resolved, volume, backend);
   const seconds = ((wavDurationMs(audioFile) || 6500) / 1000).toFixed(1);
 
   console.log(`\x1b[36m♫ Previewing \x1b[1m${resolved}\x1b[0m\x1b[36m (tier 2, ${seconds}s) — Ctrl+C to stop\x1b[0m`);
   spawnSync(backend.cmd, backend.args(audioFile, volume), { stdio: "ignore" });
 }
 
+/**
+ * Writes this project's music to a file, so the thing that is actually
+ * distinctive about VibeAudio - that a repo has its own arrangement - is
+ * something a user can hear outside their own terminal, and send to someone.
+ *
+ * Rendered at full scale rather than at the configured volume: a file is
+ * played by something with its own volume control, and a quiet render is not
+ * recoverable. WAV because it needs no encoder on any platform; it is large,
+ * and the caller can compress it with whatever they already have.
+ */
+function renderToFile(target, genre) {
+  if (!isKnownGenre(genre)) {
+    console.error(`\x1b[31m[vibeaudio] Unknown genre '${genre}'.\x1b[0m Available: ${AVAILABLE_GENRES.join(", ")}, random`);
+    process.exit(1);
+  }
+
+  const { renderPiece } = require("./render");
+  const resolved = resolveGenre(genre);
+  const seed = projectSeed();
+  const file = path.resolve(target || `vibeaudio-${resolved}.wav`);
+
+  process.stdout.write(`\x1b[36m♫ Rendering \x1b[1m${resolved}\x1b[0m\x1b[36m for ${path.basename(process.cwd())}…\x1b[0m`);
+  const piece = renderPiece({ genre: resolved, seed });
+  fs.writeFileSync(file, piece.wav);
+
+  const seconds = (piece.durationMs / 1000).toFixed(0);
+  const mb = (piece.wav.length / 1024 / 1024).toFixed(1);
+  console.log(`\r\x1b[32m✔ Wrote ${file}\x1b[0m\x1b[K`);
+  console.log(`  \x1b[90m${seconds}s, ${mb} MB — all three tiers and the success chime, seed ${seed >>> 0}.\x1b[0m`);
+  console.log(`  \x1b[90mAnother project's sound: run it there, or vibe --seed <n> --render.\x1b[0m\n`);
+}
+
 function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive, tools, dryRun, typed = {} }) {
   const hooks = require("./hooks");
 
@@ -1025,6 +1086,20 @@ function hooksAlreadyCover(cmdArgs, settingsFile = null) {
   }
 }
 
+/**
+ * Windows needs a shell for .cmd/.bat wrappers and for bare commands that may
+ * resolve to one (npm, npx, etc). Real executables and explicit paths should
+ * be spawned directly: cmd.exe otherwise breaks paths containing spaces.
+ */
+function windowsCommandNeedsShell(command) {
+  const ext = path.extname(command).toLowerCase();
+
+  if (ext === ".cmd" || ext === ".bat") return true;
+  if (ext) return false;
+
+  return !/[\\/]/.test(command);
+}
+
 function executeCommand(cmdArgs, genre, volume, chimeVolume, grace = DEFAULT_GRACE_PERIOD_MS, noChime, noHud = false) {
   const player = new AudioPlayer();
   const hookDriven = hooksAlreadyCover(cmdArgs);
@@ -1066,7 +1141,7 @@ function executeCommand(cmdArgs, genre, volume, chimeVolume, grace = DEFAULT_GRA
 
   const child = spawn(command, commandArgs, {
     stdio: "inherit",
-    shell: process.platform === "win32"
+    shell: process.platform === "win32" && windowsCommandNeedsShell(command)
   });
 
   // Runs exactly once: both the signal path and the close path lead here.
@@ -1132,6 +1207,7 @@ async function run() {
     noChime,
     noHud,
     preview,
+    render,
     clearCache: shouldClear,
     status: showStatus,
     stop: shouldStop,
@@ -1218,6 +1294,10 @@ async function run() {
     return previewGenre(preview, volume);
   }
 
+  if (render !== null) {
+    return renderToFile(render, genre);
+  }
+
   // Settings typed with no command to run: save them, don't open the launcher.
   if (cmdArgs.length === 0 && Object.keys(typed).length > 0) {
     return saveDefaults(typed, hereOnly);
@@ -1270,4 +1350,10 @@ async function run() {
   executeCommand(cmdArgs, genre, volume, chimeVolume, grace, noChime, noHud);
 }
 
-module.exports = { run, parseArgs, hooksAlreadyCover };
+module.exports = {
+  run,
+  parseArgs,
+  hooksAlreadyCover,
+  previewAudioFile,
+  windowsCommandNeedsShell
+};

package/src/player.js

@@ -69,6 +69,26 @@ const LOOP_OVERLAP_MS = 120;
 const TIER_2_AFTER_MS = 15000;
 const TIER_3_AFTER_MS = 45000;
 
+/**
+ * How many bars one piece is played as.
+ *
+ * A tier renders one ~7 second loop and the last tier arrives at 45 seconds,
+ * so everything past a turn's first minute used to be a single file on
+ * repeat: ~85 identical plays across a ten-minute turn, ~250 across half an
+ * hour. Music stays in the background only until the ear starts tracking it,
+ * and what it does then is send someone to --mute for good.
+ *
+ * Each bar rotates to the next of the genre's own curated variants (see
+ * `rotate` in synth/generator.js), so the phrase is ~21 seconds instead of
+ * ~7 and every bar is still hand-written harmony. Three is not a taste
+ * setting: every genre carries exactly three variants, and rotation can only
+ * guarantee distinct bars while it has one to move to.
+ *
+ * Bar 0 is the unrotated variant, so a project still opens on the sound it
+ * has always had.
+ */
+const LOOP_BARS = 3;
+
 /**
  * Playback backends, in preference order. `volume` marks whether the backend
  * can attenuate; the others play at system volume.
@@ -171,14 +191,37 @@ function clearCache() {
 }
 
 const GENRE_ALIASES = {
+  "lo-fi": "lofi",
+  "lofi-hiphop": "lofi",
+  chill: "lofi",
+  chillhop: "lofi",
+  study: "lofi",
   chiptune: "8bit",
+  chip: "8bit",
+  nes: "8bit",
+  gameboy: "8bit",
+  retro: "8bit",
+  retrowave: "synthwave",
+  outrun: "synthwave",
+  "80s": "synthwave",
   downtempo: "electronic",
+  techno: "electronic",
+  edm: "electronic",
   bossa: "jazz",
+  swing: "jazz",
+  lounge: "jazz",
   ambient: "zen",
+  calm: "zen",
+  meditation: "zen",
   noise: "drone",
   focus: "drone",
+  hum: "drone",
+  whitenoise: "drone",
+  "white-noise": "drone",
   sparse: "piano",
-  satie: "piano"
+  satie: "piano",
+  keys: "piano",
+  minimal: "piano"
 };
 
 function isKnownGenre(genre) {
@@ -212,25 +255,25 @@ function resolveGenre(genre) {
   return GENRE_ALIASES[normalized] || normalized;
 }
 
-function generateLoop(genre, tier, seed) {
+function generateLoop(genre, tier, seed, bar = 0) {
   switch (genre) {
     case "synthwave":
-      return generateSynthwaveLoop(6.8, tier, seed);
+      return generateSynthwaveLoop(6.8, tier, seed, bar);
     case "8bit":
-      return generateChiptuneLoop(7.5, tier, seed);
+      return generateChiptuneLoop(7.5, tier, seed, bar);
     case "electronic":
-      return generateElectronicLoop(6.4, tier, seed);
+      return generateElectronicLoop(6.4, tier, seed, bar);
     case "jazz":
-      return generateJazzLoop(6.26, tier, seed);
+      return generateJazzLoop(6.26, tier, seed, bar);
     case "zen":
-      return generateZenLoop(7.2, tier, seed);
+      return generateZenLoop(7.2, tier, seed, bar);
     case "drone":
-      return generateDroneLoop(7.0, tier, seed);
+      return generateDroneLoop(7.0, tier, seed, bar);
     case "piano":
-      return generatePianoLoop(7.6, tier, seed);
+      return generatePianoLoop(7.6, tier, seed, bar);
     case "lofi":
     default:
-      return generateLofiLoop(6.4, tier, seed);
+      return generateLofiLoop(6.4, tier, seed, bar);
   }
 }
 
@@ -251,9 +294,21 @@ function seedDir(seed) {
   return path.join(CACHE_DIR, `s${seed >>> 0}`);
 }
 
-/** Keep a small working set of projects cached; regenerating costs ~100ms. */
+/**
+ * Keep a small working set of projects cached; regenerating costs ~100ms.
+ *
+ * A directory touched within PRUNE_MIN_AGE_MS is left alone whoever owns it.
+ * Another process may be part-way through a render there - it creates the
+ * directory, then writes its .tmp into it - and deleting it underneath that
+ * write throws ENOENT on the playback path, which is the one thing audio is
+ * never allowed to do. Time is the only signal we have across processes;
+ * skipping only our own directory would not have helped the other one.
+ */
+const PRUNE_MIN_AGE_MS = 10_000;
+
 function pruneSeedDirs(keep = 3) {
   try {
+    const now = Date.now();
     const dirs = fs
       .readdirSync(CACHE_DIR, { withFileTypes: true })
       .filter((e) => e.isDirectory() && /^s\d+$/.test(e.name))
@@ -264,6 +319,7 @@ function pruneSeedDirs(keep = 3) {
       .sort((a, b) => b.mtime - a.mtime);
 
     for (const stale of dirs.slice(keep)) {
+      if (now - stale.mtime < PRUNE_MIN_AGE_MS) continue;
       fs.rmSync(stale.full, { recursive: true, force: true });
     }
   } catch (e) {
@@ -506,6 +562,23 @@ function writeCacheFileAtomic(filePath, buffer) {
   } catch (e) {
     fs.rmSync(tmp, { force: true });
 
+    // The seed directory can be pruned by another process between our mkdir
+    // and this write. The mtime floor in pruneSeedDirs makes that rare rather
+    // than impossible, so recreate the directory and try once more - a second
+    // ENOENT would mean a prune landed inside a window of microseconds.
+    if (e.code === "ENOENT") {
+      try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(tmp, buffer);
+        fs.renameSync(tmp, filePath);
+        return;
+      } catch (retryErr) {
+        fs.rmSync(tmp, { force: true });
+        if (fs.existsSync(filePath)) return;
+        throw retryErr;
+      }
+    }
+
     // POSIX rename replaces the destination silently. Windows does not: it
     // fails with EPERM/EACCES when another process holds the destination
     // open - which is precisely the concurrent case this function exists to
@@ -519,17 +592,23 @@ function writeCacheFileAtomic(filePath, buffer) {
   }
 }
 
-function getAudioPath(genre, tier = 2, seed = projectSeed(), gain = 1) {
+function getAudioPath(genre, tier = 2, seed = projectSeed(), gain = 1, bar = 0) {
   ensureCacheDir();
   const normalizedGenre = resolveGenre(genre);
   const safeTier = Math.max(1, Math.min(3, tier));
+  const safeBar = ((bar % LOOP_BARS) + LOOP_BARS) % LOOP_BARS;
 
+  // Bars of one piece share the project's seed directory, so a project's
+  // music is still pruned as a unit. Bar 0 keeps the unsuffixed name and
+  // renders byte-identically to the pre-bars loop, so a project upgrading
+  // into this opens on exactly the bar it has always opened on.
+  const barSuffix = safeBar === 0 ? "" : `_b${safeBar}`;
   const dir = seedDir(seed);
-  const filePath = path.join(dir, `loop_${normalizedGenre}_t${safeTier}${gainSuffix(gain)}.wav`);
+  const filePath = path.join(dir, `loop_${normalizedGenre}_t${safeTier}${barSuffix}${gainSuffix(gain)}.wav`);
 
   if (!fs.existsSync(filePath)) {
     fs.mkdirSync(dir, { recursive: true });
-    writeCacheFileAtomic(filePath, applyGain(generateLoop(normalizedGenre, safeTier, seed >>> 0), gain));
+    writeCacheFileAtomic(filePath, applyGain(generateLoop(normalizedGenre, safeTier, seed >>> 0, safeBar), gain));
     pruneSeedDirs();
   }
 
@@ -592,6 +671,7 @@ class AudioPlayer {
     this.intensity = null;
     this.minTier = null;
     this.currentTier = 1;
+    this.bar = 0;
     this.nextTimer = null;
     this.watchdog = null;
   }
@@ -621,6 +701,7 @@ class AudioPlayer {
     this.genre = resolved;
     this.volume = targetVolume;
     this.seed = projectSeed();
+    this.bar = 0; // Every run opens on the project's own bar.
     this.intensity = intensity;
     this.minTier = minTier;
 
@@ -661,7 +742,9 @@ class AudioPlayer {
     // never both, or the volume would be applied twice.
     const backend = detectPlayer();
     const gain = bakedGain(backend, this.volume);
-    const audioFile = getAudioPath(this.genre, this.currentTier, this.seed, gain);
+    const audioFile = getAudioPath(this.genre, this.currentTier, this.seed, gain, this.bar);
+    // Advanced after the choice, so the bar that plays first is bar 0.
+    this.bar = (this.bar + 1) % LOOP_BARS;
     const proc = spawn(backend.cmd, backend.args(audioFile, this.volume), { stdio: "ignore" });
 
     this.procs.add(proc);
@@ -736,6 +819,8 @@ class AudioPlayer {
 module.exports = {
   AudioPlayer,
   getAudioPath,
+  pruneSeedDirs,
+  writeCacheFileAtomic,
   getChimePath,
   clearCache,
   detectPlayer,
@@ -748,6 +833,7 @@ module.exports = {
   projectSeed,
   wavDurationMs,
   generateLoop,
+  LOOP_BARS,
   AVAILABLE_GENRES,
   SHUFFLE_GENRES,
   synthFingerprint,

package/src/render.js

@@ -0,0 +1,123 @@
+/**
+ * Rendering a piece to a file, rather than to the speakers.
+ *
+ * The live player spawns one bar at a time and crossfades the boundary by
+ * re-spawning early (LOOP_OVERLAP_MS in player.js); a file has to do that
+ * stitching itself, or the seams click. Everything here is pure - buffers in,
+ * buffer out - so both callers (`vibe --render` and the landing page's
+ * scripts/render-demo.js) get the same audio the player would have produced.
+ */
+
+const { generateLoop, LOOP_BARS } = require("./player");
+const { generateSuccessChime } = require("./synth/chime");
+const { createWavBuffer } = require("./synth/generator");
+
+// Matches the live player's own crossfade window.
+const LOOP_OVERLAP_MS = 120;
+
+function parseWav(buf) {
+  const numChannels = buf.readUInt16LE(22);
+  const sampleRate = buf.readUInt32LE(24);
+  const dataSize = buf.readUInt32LE(40);
+  const numSamples = Math.floor(dataSize / 2 / numChannels);
+  const left = new Float64Array(numSamples);
+  const right = numChannels === 2 ? new Float64Array(numSamples) : null;
+  let offset = 44;
+  for (let i = 0; i < numSamples; i++) {
+    left[i] = buf.readInt16LE(offset) / 32768;
+    offset += 2;
+    if (right) {
+      right[i] = buf.readInt16LE(offset) / 32768;
+      offset += 2;
+    }
+  }
+  return { sampleRate, left, right };
+}
+
+/** Crossfades consecutive clips over `overlapMs`, mirroring the live player's loop boundary. */
+function crossfadeConcat(clips, overlapMs = LOOP_OVERLAP_MS) {
+  const sampleRate = clips[0].sampleRate;
+  const overlapSamples = Math.floor((sampleRate * overlapMs) / 1000);
+  const stereo = !!clips[0].right;
+  let totalLen = 0;
+  for (const c of clips) totalLen += c.left.length;
+  totalLen -= overlapSamples * (clips.length - 1);
+
+  const outL = new Float64Array(totalLen);
+  const outR = stereo ? new Float64Array(totalLen) : null;
+  const starts = [];
+  let pos = 0;
+
+  for (let ci = 0; ci < clips.length; ci++) {
+    const c = clips[ci];
+    starts.push(pos);
+    for (let i = 0; i < c.left.length; i++) {
+      const idx = pos + i;
+      if (idx >= totalLen) break;
+      let gL = c.left[i];
+      let gR = stereo ? c.right[i] : 0;
+      if (ci > 0 && i < overlapSamples) {
+        const fadeIn = i / overlapSamples;
+        gL *= fadeIn;
+        gR *= fadeIn;
+      }
+      if (ci < clips.length - 1 && i >= c.left.length - overlapSamples) {
+        const fadeOut = (c.left.length - i) / overlapSamples;
+        gL *= fadeOut;
+        gR *= fadeOut;
+      }
+      outL[idx] += gL;
+      if (outR) outR[idx] += gR;
+    }
+    pos += c.left.length - overlapSamples;
+  }
+  return { sampleRate, left: outL, right: outR, starts, totalLen };
+}
+
+/** Plain append, no crossfade - used for the trailing chime. */
+function append(a, b) {
+  const totalLen = a.left.length + b.left.length;
+  const stereo = !!a.right;
+  const outL = new Float64Array(totalLen);
+  const outR = stereo ? new Float64Array(totalLen) : null;
+  outL.set(a.left, 0);
+  outL.set(b.left, a.left.length);
+  if (stereo) {
+    outR.set(a.right, 0);
+    outR.set(b.right, a.left.length);
+  }
+  return { sampleRate: a.sampleRate, left: outL, right: outR, chimeStart: a.left.length };
+}
+
+/**
+ * A whole session as one file: every bar of the phrase at each tier in turn,
+ * then the success chime - what someone would have heard sitting through a
+ * turn long enough to reach tier 3.
+ *
+ * `tiers` repeated per bar rather than per tier, so the escalation is audible
+ * without the phrase being cut short at the point it starts to make sense.
+ */
+function renderPiece({ genre = "lofi", seed = 0, tiers = [1, 2, 3], chime = true } = {}) {
+  const clips = [];
+  const tierStarts = [];
+  for (const tier of tiers) {
+    tierStarts.push(clips.length);
+    for (let bar = 0; bar < LOOP_BARS; bar++) {
+      clips.push(parseWav(generateLoop(genre, tier, seed, bar)));
+    }
+  }
+
+  const stitched = crossfadeConcat(clips);
+  const piece = chime ? append(stitched, parseWav(generateSuccessChime())) : stitched;
+  const wav = createWavBuffer({ left: piece.left, right: piece.right, sampleRate: piece.sampleRate });
+
+  const msAt = (samples) => Math.round((samples / piece.sampleRate) * 1000);
+  return {
+    wav,
+    durationMs: msAt(piece.left.length),
+    tierStartsMs: tierStarts.map((i) => msAt(stitched.starts[i])),
+    chimeStartMs: chime ? msAt(piece.chimeStart) : null
+  };
+}
+
+module.exports = { parseWav, crossfadeConcat, append, renderPiece, LOOP_OVERLAP_MS };

package/src/synth/chiptune.js

@@ -9,7 +9,7 @@ const {
   softPulse,
   triangle,
   makeRng,
-  pick,
+  rotate,
   createWavBuffer
 } = require("./generator");
 
@@ -33,8 +33,8 @@ const VARIANTS = [
   }
 ];
 
-function generateChiptuneLoop(durationSec = 7.5, tier = 2, seed = 0) {
-  const variant = pick(makeRng(seed), VARIANTS);
+function generateChiptuneLoop(durationSec = 7.5, tier = 2, seed = 0, bar = 0) {
+  const variant = rotate(makeRng(seed), VARIANTS, bar);
   const bpm = 128;
   const secPerBeat = 60.0 / bpm;
   const totalBeats = Math.floor(durationSec / secPerBeat);

package/src/synth/drone.js

@@ -12,7 +12,7 @@ const {
   noteToFreq,
   sine,
   makeRng,
-  pick,
+  rotate,
   ornamentRng,
   createWavBuffer
 } = require("./generator");
@@ -26,10 +26,10 @@ const DRONE_VARIANTS = [
   { root: "E1", partial: 1.335, cutoff: 0.070, label: "open fourth" } // E + A
 ];
 
-function generateDroneLoop(durationSec = 7.0, tier = 2, seed = 0) {
+function generateDroneLoop(durationSec = 7.0, tier = 2, seed = 0, bar = 0) {
   // Drawn before any tier gating, so gating a layer can't shift these.
   const orn = ornamentRng(seed);
-  const variant = pick(orn, DRONE_VARIANTS);
+  const variant = rotate(orn, DRONE_VARIANTS, bar);
   const sweepDepth = 0.55 + orn() * 0.35;
   const breathOffset = orn() * Math.PI * 2;
 

package/src/synth/electronic.js

@@ -11,7 +11,7 @@ const {
   triangle,
   sine,
   makeRng,
-  pick,
+  rotate,
   ornamentRng,
   pluckEnv,
   createWavBuffer
@@ -34,8 +34,8 @@ const VARIANTS = [
   }
 ];
 
-function generateElectronicLoop(durationSec = 6.4, tier = 2, seed = 0) {
-  const variant = pick(makeRng(seed), VARIANTS);
+function generateElectronicLoop(durationSec = 6.4, tier = 2, seed = 0, bar = 0) {
+  const variant = rotate(makeRng(seed), VARIANTS, bar);
   const orn = ornamentRng(seed);
   const bpm = 116;
   const secPerBeat = 60.0 / bpm;

package/src/synth/generator.js

@@ -59,6 +59,28 @@ function pick(rng, options) {
   return options[Math.floor(rng() * options.length) % options.length];
 }
 
+/**
+ * The seed picks which curated variant a project gets; `bar` steps to the next
+ * one along, so one piece can be several bars long without any of them being
+ * invented.
+ *
+ * A loop is ~7 seconds and a tier stops changing at 45, so without this every
+ * turn past its first minute was one file on repeat - 85 identical plays
+ * across ten minutes, 250 across half an hour. Rotation is what makes the
+ * bars *guaranteed* different: salting the seed instead leaves it to chance,
+ * and with three variants per genre, three salted draws land on three
+ * different ones only 2 times in 9.
+ *
+ * Draws exactly once, like `pick`, so a stream shared with ornaments below is
+ * left in the same place and `bar = 0` renders what the seed alone always
+ * rendered.
+ */
+function rotate(rng, options, bar = 0) {
+  const index = Math.floor(rng() * options.length) % options.length;
+  const step = ((bar % options.length) + options.length) % options.length;
+  return options[(index + step) % options.length];
+}
+
 /**
  * Ornament placement draws from its own stream so that gating a layer by tier
  * can't shift the choices made by other layers - tier 1 and tier 3 stay the
@@ -196,6 +218,7 @@ module.exports = {
   hashString,
   pick,
   ornamentRng,
+  rotate,
   noteToFreq,
   sine,
   triangle,

package/src/synth/jazz.js

@@ -9,6 +9,7 @@ const {
   sine,
   triangle,
   makeRng,
+  rotate,
   pick,
   ornamentRng,
   createWavBuffer
@@ -36,9 +37,9 @@ const CHANGES = [
 
 const STAB_NOTES = ["D5", "E5", "G5", "A5", "B5"];
 
-function generateJazzLoop(durationSec = 6.26, tier = 2, seed = 0) {
+function generateJazzLoop(durationSec = 6.26, tier = 2, seed = 0, bar = 0) {
   const rng = makeRng(seed);
-  const changes = pick(rng, CHANGES);
+  const changes = rotate(rng, CHANGES, bar);
   const bpm = 92;
   const secPerBeat = 60.0 / bpm;
   const totalBeats = Math.floor(durationSec / secPerBeat);

package/src/synth/lofi.js

@@ -7,6 +7,7 @@ const {
   SAMPLE_RATE,
   noteToFreq,
   makeRng,
+  rotate,
   pick,
   ornamentRng,
   createWavBuffer
@@ -24,9 +25,9 @@ const PROGRESSIONS = [
 const DROP_NOTES = ["C5", "D5", "E5", "G5", "A5", "B5", "C6"];
 const SHIMMER_NOTES = ["E6", "G6", "A6", "B6"];
 
-function generateLofiLoop(durationSec = 6.4, tier = 2, seed = 0) {
+function generateLofiLoop(durationSec = 6.4, tier = 2, seed = 0, bar = 0) {
   const rng = makeRng(seed);
-  const progression = pick(rng, PROGRESSIONS);
+  const progression = rotate(rng, PROGRESSIONS, bar);
   const totalSamples = Math.floor(SAMPLE_RATE * durationSec);
   const left = new Float64Array(totalSamples);
   const right = new Float64Array(totalSamples);

package/src/synth/piano.js

@@ -13,6 +13,7 @@ const {
   noteToFreq,
   sine,
   makeRng,
+  rotate,
   pick,
   ornamentRng,
   createWavBuffer
@@ -52,9 +53,9 @@ const PARTIALS = [
   { mult: 5.05, amp: 0.035, decay: 4.5 }
 ];
 
-function generatePianoLoop(durationSec = 7.6, tier = 2, seed = 0) {
+function generatePianoLoop(durationSec = 7.6, tier = 2, seed = 0, bar = 0) {
   const rng = makeRng(seed);
-  const variant = pick(rng, PIANO_VARIANTS);
+  const variant = rotate(rng, PIANO_VARIANTS, bar);
 
   const totalSamples = Math.floor(SAMPLE_RATE * durationSec);
   const left = new Float64Array(totalSamples);

package/src/synth/synthwave.js

@@ -9,7 +9,7 @@ const {
   analogSaw,
   triangle,
   makeRng,
-  pick,
+  rotate,
   pluckEnv,
   createWavBuffer
 } = require("./generator");
@@ -52,8 +52,8 @@ const PROGRESSIONS = [
   }
 ];
 
-function generateSynthwaveLoop(durationSec = 6.8, tier = 2, seed = 0) {
-  const variant = pick(makeRng(seed), PROGRESSIONS);
+function generateSynthwaveLoop(durationSec = 6.8, tier = 2, seed = 0, bar = 0) {
+  const variant = rotate(makeRng(seed), PROGRESSIONS, bar);
   const progression = variant.steps;
   const arps = variant.arps;
   const totalSamples = Math.floor(SAMPLE_RATE * durationSec);

package/src/synth/zen.js

@@ -8,6 +8,7 @@ const {
   noteToFreq,
   sine,
   makeRng,
+  rotate,
   pick,
   ornamentRng,
   createWavBuffer
@@ -24,9 +25,9 @@ const PAD_PAIRS = [
 // D major pentatonic - the safest set to strike a bowl on over any pad above.
 const BOWL_NOTES = ["D4", "E4", "F#4", "A4", "B4", "D5"];
 
-function generateZenLoop(durationSec = 7.2, tier = 2, seed = 0) {
+function generateZenLoop(durationSec = 7.2, tier = 2, seed = 0, bar = 0) {
   const rng = makeRng(seed);
-  const pads = pick(rng, PAD_PAIRS);
+  const pads = rotate(rng, PAD_PAIRS, bar);
 
   const totalSamples = Math.floor(SAMPLE_RATE * durationSec);
   const left = new Float64Array(totalSamples);