vibeaudio 0.11.1 → 0.12.0

package/README.md

@@ -8,7 +8,7 @@
 
 **[Install](#-install)** · **[Agent hooks](#-agent-hooks-no-wrapper-needed)** · **[Genres](#-music-genres)** · **[Flags](#-options--flags)** · **[Troubleshooting](#-troubleshooting)** · **[Uninstall](#-uninstall)**
 
-> **🔊 [Listen to every genre →](https://kiril6.github.io/vibeaudio/)** — hear all 8 genres, the tier escalation, and the three chimes, rendered from the real synth.
+> **🔊 [Listen to every genre →](https://kiril6.github.io/vibeaudio/)** — hear all 10 genres, the tier escalation, and the three chimes, rendered from the real synth.
 
 > **In a hurry?** `npm i -g vibeaudio`, then `vibe --install-hooks`. Your next prompt has music.
 
@@ -25,6 +25,7 @@ AI coding agents take 15–45 seconds to reason, read files and write code. Star
 * 📈 **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.
+* 🌅 **It fades, it doesn't cut.** On macOS the music eases in and out instead of starting and stopping mid-note, and `vibe --volume` reaches music that is already playing within a second.
 * 🔔 **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.
 * 🔌 **Universal drop-in.** Hooks for **Claude Code, Codex, Cursor, Grok, Gemini CLI, Copilot CLI, Qwen Code and Windsurf**; MCP for **Claude Desktop and Antigravity**; the wrapper (`vibe <command>`) for anything else.
@@ -276,7 +277,7 @@ Where an agent reports more than start and stop, VibeAudio listens for that too
 | | |
 | :--- | :--- |
 | **Five agents tell you when they're waiting on you** | When a permission dialog opens the music stops rather than sounding busy while the agent is stuck on you, and it resumes once the thing you answered has run. Claude Code covers the terminal, desktop app and IDEs alike, plus MCP servers asking for input. Copilot CLI's own `PermissionRequest` fires before *every* permission check — dialog or not — so VibeAudio listens for its permission-prompt notification instead. Cursor and Grok have no such event that's been verified, so they keep playing through a prompt. |
-| **Claude Code turns that never reach `Stop` still end the music** | An API error or rate limit ends the turn with `StopFailure` instead, which plays the failure chime. Interrupting (Esc, or the stop button in the desktop app) fires no hook at all, so the background player watches the session transcript for Claude Code's interrupt entry and stops silently within half a second — whether the agent was writing or running a tool. Closing the session mid-turn stops it too — but only if that session started the music, so closing an idle terminal never silences another one. |
+| **Claude Code turns that never reach `Stop` still end the music** | An API error or rate limit ends the turn with `StopFailure` instead, which plays the failure chime. Interrupting (Esc, or the stop button in the desktop app) fires no hook at all, so the background player watches the session transcript for Claude Code's interrupt entry and stops silently within half a second — whether the agent was writing or running a tool. A prompt that another hook blocks (a token-saving proxy, say) never reaches `Stop` either, so the same watcher ends the music on Claude Code's "prompt blocked" entry — or never starts it, when the blocker was quicker than we were. Closing the session mid-turn stops it too — but only if that session started the music, so closing an idle terminal never silences another one. |
 | **Codex asks you to trust the hook once** | Codex keeps a per-hook trust hash in `~/.codex/config.toml` and won't run a hook it hasn't been told to trust, so the install isn't live until you approve each one the first time it fires. |
 | **Only Cursor can play the failure chime** | Its stop event reports whether the turn completed, aborted or errored. The others send no verdict, so a turn there always ends on the success chime — VibeAudio won't invent a failure the agent never claimed. |
 | **Grok and Copilot CLI get a file of their own** | Each reads every `*.json` in its `hooks/` directory, so VibeAudio writes `vibeaudio.json` rather than merging into anyone else's — which makes uninstalling it a delete, and leaves no backup file behind. Copilot's honours `COPILOT_HOME`. |
@@ -350,7 +351,7 @@ vibe --reactive --install-hooks     # on
 vibe --install-hooks                # off again
 ```
 
-Music already playing keeps the old genre until the next prompt swaps the daemon — `vibe --stop` cuts it short.
+Music already playing keeps the old genre until the next prompt swaps the daemon — `vibe --stop` cuts it short. A new **volume** is the exception: the music playing now eases to it within a second.
 
 Removing them is one command:
 
@@ -681,7 +682,7 @@ This needs a PulseAudio-compatible sound server on **your local machine**: a Lin
 If the second connection fails with the socket "already in use", an earlier session left it behind: `rm /tmp/vibe-pulse.sock` on the server, or set `StreamLocalBindUnlink yes` in the server's `sshd_config`. If `paplay` says access denied, your local PulseAudio requires its cookie — copy `~/.config/pulse/cookie` to the same path on the server.
 
 **Volume flag does nothing**
-Shouldn't happen any more — where the player can't attenuate (`aplay`, PowerShell), the gain is baked into the audio instead. A `--volume` change lands at the next loop boundary, and on hooks at your next prompt; `vibe --status` shows the volume in effect and what set it.
+Shouldn't happen any more — where the player can't attenuate (`aplay`, PowerShell), the gain is baked into the audio instead. A `--volume` change reaches music already playing within a second on macOS hooks (it eases there), at the next loop boundary elsewhere, and in the wrapper or MCP on their next run; `vibe --status` shows the volume in effect and what set it.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "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",

package/src/cli.js

@@ -183,6 +183,7 @@ function parseArgs(argv) {
   let hookAction = null;
   let mcp = false;
   let reactive = false;
+  let followVolume = false;
   let here_flag = false;
   let dryRun = false;
   let tools = null;
@@ -352,6 +353,14 @@ function parseArgs(argv) {
       continue;
     }
 
+    // Internal, set by the hooks: a daemon with no volume of its own follows
+    // the saved one while it plays.
+    if (arg === "--follow-volume") {
+      followVolume = true;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--dry-run") {
       dryRun = true;
       i += 1;
@@ -461,6 +470,7 @@ function parseArgs(argv) {
     hookAction,
     mcp,
     reactive,
+    followVolume,
     dryRun,
     tools,
     typed,
@@ -751,8 +761,9 @@ function printStatus() {
     // What it was started with, which is not necessarily what is saved: a
     // daemon keeps its settings until the next prompt replaces it, and
     // "I changed the genre and nothing happened" is that gap.
+    const level = playing.follows ? Math.round(volumeNow() * 100) : playing.volume; // A following daemon plays what is saved.
     const now = playing.genre
-      ? ` ${on(playing.genre)}${playing.volume === null ? "" : on(` @ ${playing.volume}%`)}${playing.reactive ? off(", reactive") : ""}`
+      ? ` ${on(playing.genre)}${level === null ? "" : on(` @ ${level}%`)}${playing.reactive ? off(", reactive") : ""}`
       : "";
     console.log(`  ${on("playing")}${now}${off(`   pid ${pid}`)}`);
     if (playing.genre && playing.genre !== genreNow()) {
@@ -1128,6 +1139,9 @@ function saveDefaults(typed, hereOnly = false) {
   if (playing && patch.genre && playing.genre && playing.genre !== patch.genre) {
     console.log(`  \x1b[90m${playing.genre} is still playing — vibe --stop cuts it short.\x1b[0m`);
   }
+  if (playing && playing.follows && patch.volume !== undefined) {
+    console.log(`  \x1b[90mThe music playing now follows the new volume within a second.\x1b[0m`);
+  }
 
   // An install from before the settings moved out of the hook command line
   // still carries its own genre, and a flag beats this file. Saying nothing
@@ -1259,18 +1273,18 @@ function renderToFile(target, genre) {
   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 = {} }) {
+function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive, followVolume, tools, dryRun, typed = {} }) {
   const hooks = require("./hooks");
 
   switch (action) {
     case "daemon":
-      return hooks.runDaemon(genre, volume, { reactive });
+      return hooks.runDaemon(genre, volume, { reactive, volumeSource: followVolume ? volumeNow : null });
 
     case "hook-start":
       // The payload names the session (so SessionEnd can tell this session's
       // music from another's) and the transcript (so an interrupt, which
       // fires no hook, can still stop it).
-      hooks.readPayload((raw) => hooks.hookStart(genre, volume, { reactive, turn: hooks.newTurn(raw) }));
+      hooks.readPayload((raw) => hooks.hookStart(genre, volume, { reactive, follow: typed.volume === undefined, turn: hooks.newTurn(raw) }));
       return;
 
     case "hook-stop":
@@ -1297,7 +1311,7 @@ function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive,
       return;
 
     case "hook-resume":
-      hooks.readPayload((raw) => hooks.hookResume(raw, genre, volume, { reactive }));
+      hooks.readPayload((raw) => hooks.hookResume(raw, genre, volume, { reactive, follow: typed.volume === undefined }));
       return;
 
     case "hook-end":
@@ -1483,6 +1497,7 @@ async function run() {
     hookAction,
     mcp,
     reactive,
+    followVolume,
     dryRun,
     tools,
     typed,
@@ -1500,7 +1515,7 @@ async function run() {
 
   if (hookAction) {
     try {
-      return runHookAction(hookAction, { genre, volume, chimeVolume, noChime, reactive, tools, dryRun, typed });
+      return runHookAction(hookAction, { genre, volume, chimeVolume, noChime, reactive, followVolume, tools, dryRun, typed });
     } catch (e) {
       // Settings problems are the user's to fix — report them, don't stack-trace.
       console.error(`\x1b[31m[vibeaudio] ${e.message}\x1b[0m`);

package/src/hooks.js

@@ -410,7 +410,8 @@ function daemonPlaying() {
     pid,
     genre: genre ? genre[1] : null,
     volume: volume ? Number(volume[1]) : null,
-    reactive: /--reactive/.test(argv)
+    reactive: /--reactive/.test(argv),
+    follows: /--follow-volume/.test(argv)
   };
 }
 
@@ -610,7 +611,7 @@ const INTERRUPT_POLL_MS = 500;
  * Internal mode: plays while any session is working. The player's own loop
  * timer keeps the event loop alive.
  */
-function runDaemon(genre, volume, { reactive = false } = {}) {
+function runDaemon(genre, volume, { reactive = false, volumeSource = null } = {}) {
   const watchers = new Map(); // session id -> its transcript poll
 
   // Drops sessions whose transcript shows an interrupt (Esc fires no hook, so
@@ -661,6 +662,8 @@ function runDaemon(genre, volume, { reactive = false } = {}) {
   setTimeout(shutdown, MAX_DAEMON_MS);
 
   setInterval(() => {
+    // A volume saved while this plays reaches it now, not at the next prompt.
+    if (volumeSource) player.setVolume(volumeSource());
     if (sweep()) return;
     player.stop({ playChime: false });
     endIdle();
@@ -672,9 +675,10 @@ function daemonRunning() {
   return pid !== null && isOurDaemon(pid);
 }
 
-function spawnDaemon(genre, volume, reactive) {
+function spawnDaemon(genre, volume, reactive, follow = false) {
   const args = [CLI_ENTRY, "--daemon", "--genre", genre, "--volume", String(Math.round(volume * 100))];
   if (reactive) args.push("--reactive");
+  if (follow) args.push("--follow-volume");
 
   const child = spawn(process.execPath, args, { detached: true, stdio: "ignore" });
   child.unref();
@@ -689,7 +693,7 @@ function spawnDaemon(genre, volume, reactive) {
  * always did, so a genre change lands on the next prompt. With one working the
  * music carries on: restarting it would cut every other session's stream.
  */
-function hookStart(genre, volume, { reactive = false, turn = null } = {}) {
+function hookStart(genre, volume, { reactive = false, turn = null, follow = false } = {}) {
   if (turn && turn.blocked) return null; // Rejected before it began: nothing to play for.
   const id = sessionId(turn && turn.session);
   // Before the spawn: the daemon reads it on startup.
@@ -698,7 +702,7 @@ function hookStart(genre, volume, { reactive = false, turn = null } = {}) {
 
   stopDaemon({ keepSessions: true });
   fs.rmSync(INTENSITY_FILE, { force: true }); // Don't inherit the last prompt's activity
-  return spawnDaemon(genre, volume, reactive);
+  return spawnDaemon(genre, volume, reactive, follow);
 }
 
 /**
@@ -889,7 +893,7 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
  * one needing approval, can resume early - after the chime already did its
  * job. Match on tool_input as well if that ever shows up in practice.
  */
-function hookResume(raw, genre, volume, { reactive = false } = {}) {
+function hookResume(raw, genre, volume, { reactive = false, follow = false } = {}) {
   const id = sessionId(payloadSession(parsePayload(raw)));
   const session = readSession(id);
   if (!session || session.waiting == null) return false; // Not waiting - the common case, on every tool call.
@@ -899,7 +903,7 @@ function hookResume(raw, genre, volume, { reactive = false } = {}) {
 
   const blockedMs = (session.blockedMs || 0) + (session.waitStart ? Date.now() - session.waitStart : 0);
   writeSession(id, { ...session, waiting: null, waitStart: null, blockedMs });
-  if (!daemonRunning()) spawnDaemon(genre, volume, reactive);
+  if (!daemonRunning()) spawnDaemon(genre, volume, reactive, follow);
   return true;
 }
 

package/src/mac-player.jxa

@@ -1,6 +1,7 @@
 // VibeAudio macOS player: one long-lived process driving AVAudioPlayer, run by
 // `osascript -l JavaScript`. Lines on stdin:
 //   play <volume 0-1> <fade-in seconds> <path to wav>
+//   volume <volume 0-1> <ramp seconds>      (everything sounding now)
 // End of input - a closed pipe, or the daemon dying - fades out and exits, so
 // the audio can never outlive whoever started it.
 ObjC.import("Foundation");
@@ -26,6 +27,11 @@ function play(volume, fadeIn, path) {
 }
 
 function handle(line) {
+  const v = /^volume (\S+) (\S+)$/.exec(line);
+  if (v) {
+    for (const p of players) if (p.playing) p.setVolumeFadeDuration(parseFloat(v[1]), parseFloat(v[2]));
+    return;
+  }
   const m = /^play (\S+) (\S+) (.+)$/.exec(line);
   if (m) play(parseFloat(m[1]), parseFloat(m[2]), m[3]);
 }

package/src/player.js

@@ -116,6 +116,7 @@ let warnedNoPlayer = false;
 // run, and it is used for the rest of the process once one has failed.
 const MAC_HELPER = path.join(__dirname, "mac-player.jxa");
 const FADE_IN_S = 0.5;
+const VOLUME_RAMP_S = 0.3;
 let helperFailed = false;
 
 function helperUsable(backend) {
@@ -808,6 +809,22 @@ class AudioPlayer {
     this.nextTimer = setTimeout(() => this.playLoop(), Math.max(250, durationMs - LOOP_OVERLAP_MS));
   }
 
+  /**
+   * Changes the volume of music already playing. The helper eases the loops
+   * that are sounding to it; any other backend takes it at the next loop, which
+   * is as live as a player that reads its volume once at spawn can be.
+   */
+  setVolume(volume) {
+    const target = Math.max(0.05, Math.min(1.0, Number(volume))); // Already a fraction, unlike normalizeVolume's percent.
+    if (!this.isPlaying || !Number.isFinite(target) || target === this.volume) return;
+    this.volume = target;
+    try {
+      if (this.helper) this.helper.stdin.write(`volume ${this.volume} ${VOLUME_RAMP_S}\n`);
+    } catch (e) {
+      // The helper's own exit handler deals with a dead pipe.
+    }
+  }
+
   spawnLoop(audioFile, backend) {
     const proc = spawn(backend.cmd, backend.args(audioFile, this.volume), { stdio: "ignore" });