vibeaudio 0.6.3 → 0.8.1

package/README.md

@@ -1,6 +1,6 @@
 # 🎧 VibeAudio
 
-[![test](https://github.com/kiril6/vibeaudio/actions/workflows/test.yml/badge.svg)](https://github.com/kiril6/vibeaudio/actions/workflows/test.yml)
+[![test](https://github.com/kiril6/vibeaudio/actions/workflows/test.yml/badge.svg)](https://github.com/kiril6/vibeaudio/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/vibeaudio)](https://www.npmjs.com/package/vibeaudio) [![downloads](https://img.shields.io/npm/d18m/vibeaudio?label=downloads)](https://npm-stat.com/charts.html?package=vibeaudio) [![downloads/month](https://img.shields.io/npm/dm/vibeaudio)](https://npm-stat.com/charts.html?package=vibeaudio)
 
 > **Procedural focus music while your AI coding tools think.**
 > Every project gets its own arrangement. Zero dependencies, zero audio files.
@@ -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,23 @@ 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>
+<summary><b>What the update check sends, and how to turn it off</b></summary>
+
+Once a day at most, a background process asks the public npm registry for the latest version number — the same request `npm outdated` makes. It sends nothing about you: no ID, no settings, no usage. It's the only network request VibeAudio ever makes, and `vibe` never waits for it; the answer is shown the next time. It's skipped in CI, under `npx`, and whenever `VIBE_NO_UPDATE_CHECK=1` or `NO_UPDATE_NOTIFIER=1` is set.
+
+</details>
+
 ### Then pick how it runs
 
 **Using Claude Code, Codex, Cursor or Grok interactively?** Install the hooks — this is the mode that actually tracks thinking:
@@ -455,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.
 >
@@ -517,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) |
@@ -542,6 +583,7 @@ export VIBE_CHIME_VOLUME=70     # Crisp completion chime at 70%
 export VIBE_GRACE_MS=3000       # Wait 3s of thinking before any music
 export VIBE_SEED=7              # Same arrangement everywhere, ignoring the directory
 export VIBE_DISABLE=1           # Mute, without uninstalling anything
+export VIBE_NO_UPDATE_CHECK=1   # Never ask npm whether a newer version is out
 ```
 
 **`VIBE_DISABLE=1` is for a shell you always want quiet** — a CI job, a shared machine, a terminal profile you keep silent. It's read at playback time and covers hooks, wrapper and MCP alike.
@@ -682,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.6.3",
-  "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.1",
+  "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)
@@ -103,7 +107,17 @@ Procedural focus music while your AI coding tools think.
   VIBE_GRACE_MS=<ms>           Override the saved grace window, in ms
   VIBE_SEED=<n>                Pin the arrangement instead of deriving it from the directory
   VIBE_DISABLE=1               Mute automatic playback without uninstalling anything
+  VIBE_NO_UPDATE_CHECK=1       Never check npm for a newer version
 `);
+  printUpdateNotice();
+}
+
+// Only where a person is reading: help, status and the menu. See update.js.
+function printUpdateNotice() {
+  if (!process.stdout.isTTY) return;
+  const { ephemeralInstallReason } = require("./hooks");
+  const line = require("./update").updateNotice({ ephemeral: Boolean(ephemeralInstallReason()) });
+  if (line) console.log(`${line}\n`);
 }
 
 /**
@@ -154,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;
@@ -240,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;
@@ -391,6 +420,7 @@ function parseArgs(argv) {
     noChime,
     noHud,
     preview,
+    render,
     clearCache: clearCacheFlag,
     status: statusFlag,
     stop: stopFlag,
@@ -709,6 +739,7 @@ function printStatus() {
     }
   }
   console.log();
+  printUpdateNotice();
 }
 
 /**
@@ -904,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`);
@@ -917,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");
 
@@ -1014,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);
@@ -1055,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.
@@ -1121,6 +1207,7 @@ async function run() {
     noChime,
     noHud,
     preview,
+    render,
     clearCache: shouldClear,
     status: showStatus,
     stop: shouldStop,
@@ -1207,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);
@@ -1226,6 +1317,8 @@ async function run() {
     // leave. Wrapping the launch too turned every real failure below into a
     // silent exit 0, which is the worst possible thing for a wrapper to do:
     // `vibe && deploy` would chain on a run that never happened.
+    printUpdateNotice();
+
     let selection;
     try {
       selection = await promptInteractive({
@@ -1257,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);
   }
 }
 
@@ -519,17 +562,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 +641,7 @@ class AudioPlayer {
     this.intensity = null;
     this.minTier = null;
     this.currentTier = 1;
+    this.bar = 0;
     this.nextTimer = null;
     this.watchdog = null;
   }
@@ -621,6 +671,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 +712,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);
@@ -748,6 +801,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);

package/src/update.js

@@ -0,0 +1,106 @@
+/**
+ * "A newer version is out", said where a person is looking.
+ *
+ * A global CLI has no other way to reach its users: nothing tells them to
+ * re-run `npm i -g`, so fixes never arrive. This asks the registry at most once
+ * a day, in a detached process, and shows the answer the *next* time - a run
+ * never waits on the network, and an offline machine is simply never told.
+ *
+ * The request is the one `npm outdated` makes, to the public registry, and
+ * carries nothing about the user: no id, no settings, no usage. It is the only
+ * network call VibeAudio makes, which is why it can be switched off.
+ *
+ * Shown only by `--status`, `--help` and the menu. Never by hooks - their
+ * output goes to the agent, not the person - and never by the wrapper, whose
+ * terminal belongs to the command it runs.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawn } = require("child_process");
+const pkg = require("../package.json");
+
+const CHECK_FILE = path.join(os.homedir(), ".vibeaudio", "update.json");
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_URL = `https://registry.npmjs.org/${pkg.name}/latest`;
+
+// CI and the de-facto standard opt-out (update-notifier's) as well as our own.
+function checkDisabled(env = process.env) {
+  return Boolean(env.VIBE_NO_UPDATE_CHECK || env.NO_UPDATE_NOTIFIER || env.CI);
+}
+
+/** Numeric x.y.z comparison; a prerelease or malformed version is never "newer". */
+function isNewer(latest, current) {
+  const parse = (v) => (/^\d+\.\d+\.\d+$/.test(v || "") ? v.split(".").map(Number) : null);
+  const a = parse(latest);
+  const b = parse(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return false;
+}
+
+function readCheck(file) {
+  try {
+    const data = JSON.parse(fs.readFileSync(file, "utf8"));
+    return data && typeof data === "object" ? data : {};
+  } catch (e) {
+    return {};
+  }
+}
+
+function writeCheck(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Per-process temp name: two runs refreshing at once must not share one.
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(data)}\n`);
+  fs.renameSync(tmp, file);
+}
+
+function refreshInBackground(file) {
+  try {
+    // Stamp the attempt first, so a burst of runs starts one check, not many.
+    writeCheck(file, { ...readCheck(file), checked: Date.now() });
+    const child = spawn(process.execPath, [__filename, file], { detached: true, stdio: "ignore" });
+    child.unref();
+  } catch (e) {
+    // An update notice is never worth an error.
+  }
+}
+
+/**
+ * The line to print, or null. Synchronous and offline: it reads what the last
+ * check found, and starts the next check if that one is a day old.
+ * `ephemeral`: running from an npx cache, where "npm i -g" is the wrong advice
+ * and npx fetches the latest on its own anyway.
+ */
+function updateNotice({ file = CHECK_FILE, env = process.env, now = Date.now(), current = pkg.version, ephemeral = false, refresh = refreshInBackground } = {}) {
+  if (checkDisabled(env) || ephemeral) return null;
+
+  const state = readCheck(file);
+  if (!(now - (state.checked || 0) < CHECK_INTERVAL_MS)) refresh(file);
+
+  if (!isNewer(state.latest, current)) return null;
+  return `\x1b[33mUpdate available ${current} → ${state.latest}\x1b[0m  \x1b[1mnpm i -g ${pkg.name}\x1b[0m` +
+    `  \x1b[90m(what's new: https://github.com/kiril6/vibeaudio/releases)\x1b[0m`;
+}
+
+// The detached child: one request, bounded, and silent whatever happens.
+async function runCheck(file) {
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(5000)
+    });
+    if (!res.ok) return;
+    const { version } = await res.json();
+    if (typeof version === "string") writeCheck(file, { ...readCheck(file), latest: version });
+  } catch (e) {
+    // Offline, blocked, or a registry hiccup: try again tomorrow.
+  }
+}
+
+if (require.main === module) runCheck(process.argv[2] || CHECK_FILE);
+
+module.exports = { updateNotice, isNewer, checkDisabled, CHECK_FILE };