vibeaudio 0.25.1 → 0.25.2

package/README.md

@@ -160,7 +160,7 @@ vibe npm test
 vibe claude -p "explain this repo"
 ```
 
-**Lost?** `vibe --help` lists every flag, and `vibe --status` reads your live setup back to you — what's installed, what's playing, and which agents it found. If something seems broken, `vibe --doctor` checks it and prints the fix for each problem.
+**Lost?** `vibe --help` lists every flag, and `vibe --status` reads your live setup back to you — what's installed, what's playing, and which agents it found. Its first line says why the music is silent or playing right now (`silent: muted for 42 more min (vibe --unmute)`, `playing: lofi @ 40%, 2 sessions working (api, web)`). If something seems broken, `vibe --doctor` checks it and prints the fix for each problem.
 
 > **Which one you want:** the wrapper plays music for as long as the wrapped process lives. That's exactly right for a command that exits when its work is done — and wrong for an interactive REPL like `claude`, where the process stays alive while you read and type, so the music never stops. Hooks know when the agent is actually thinking; the wrapper can only time the process.
 
@@ -429,6 +429,12 @@ The optional [`/vibeaudio` mod](#vibeaudio-instant-controls-and-a-pane-claude-co
 
 `/vibe` is a prompt, so Claude has to read it, run a command and answer: it costs a turn and a few tokens, and it waits for the current turn to end. The optional **VibeAudio mod** runs inside Claude Code instead, so `/vibeaudio mute` takes effect at once, even while Claude is working, and costs no tokens.
 
+<p align="center">
+  <a href="https://kiril6.github.io/vibeaudio/#band-video"><img src="docs/video/band-poster.jpg" alt="The VibeAudio band above the Claude Code prompt" width="49%"></a>
+  <a href="https://kiril6.github.io/vibeaudio/#band-video"><img src="docs/video/pane.jpg" alt="The VibeAudio pane: now playing, sound, alerts and share" width="49%"></a>
+  <br><sub>▶ <a href="https://kiril6.github.io/vibeaudio/#band-video">Watch the 43-second demo</a> of the band and the pane (frames from the demo video, with sound on the site).</sub>
+</p>
+
 ```text
 claude plugin marketplace add kiril6/vibeaudio
 claude plugin install vibeaudio-mod@vibeaudio
@@ -864,7 +870,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--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 (full scale, ignores `--volume`) | `vibeaudio-<genre>.wav` |
-| `--status` | Show what's installed, running and detected, then exit | — |
+| `--status` | Say why the music is silent or playing, then show what's installed, running and detected, and exit | — |
 | `--doctor` | Check the setup; every problem comes with the command that fixes it. Exits 1 on a failure, so it scripts | — |
 | `--notify` / `--no-notify` | Also show a desktop banner naming the project when a turn finishes, fails or needs you. Saved to `config.json` | off |
 | `--speak` / `--speak-always` / `--no-speak` | Say which project finished, failed or needs you, after the chime: only with two or more sessions going (`--speak`), or every time (`--speak-always`). Saved to `config.json` | off |
@@ -935,6 +941,8 @@ The expiry is deliberate too. A call is a bounded thing; a mute you forget about
 
 ## 🔧 Troubleshooting
 
+**Start with `vibe --status`.** Its first line answers "why is it silent?" or "why is it still playing?" in one sentence, with the command that changes it: a mute and how long it has left, `VIBE_DISABLE` in your shell, no audio player, music turned off (globally, for this project, or by `VIBE_MUSIC`), a session waiting on you, or simply no agent working right now.
+
 **No sound at all**
 Check that a player exists for your platform (see [Requirements](#-requirements)). VibeAudio prints a notice to stderr when it can't find one. On Linux: `sudo apt install pulseaudio-utils` (or `ffmpeg` / `alsa-utils`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeaudio",
-  "version": "0.25.1",
+  "version": "0.25.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",

package/src/cli.js

@@ -41,6 +41,9 @@ const HOOK_ACTIONS = [
 ];
 
 function printHelp() {
+  // Both callers process.exit() next. On macOS a piped stdout is async, so Node 18/20
+  // dropped everything past the 8 KB pipe buffer (CI on #77). Blocking writes flush first.
+  process.stdout._handle?.setBlocking?.(true);
   console.log(`
 \x1b[1m\x1b[36mVibeAudio\x1b[0m v${pkg.version}
 Procedural focus music while your AI coding tools think.
@@ -80,7 +83,8 @@ Procedural focus music while your AI coding tools think.
       --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 (full scale, ignores --volume)
-      --status                 Show what is installed, running and detected, then exit
+      --status                 Say why the music is silent or playing, then show what is
+                               installed, running and detected, and exit
       --notify | --no-notify   Also show a desktop banner naming the project when a turn finishes, fails, needs you or looks stuck (macOS and Linux; off by default)
       --speak | --no-speak     Also say which project finished, failed or needs you, after the chime - with two or more sessions going (off by default)
       --speak-always           Like --speak, but every time, even with one session
@@ -869,21 +873,37 @@ function uninstallHookTargets() {
  * do". Every line is read from live state rather than assumed, because the
  * usual cause of confusion is a mismatch between config and what is running.
  */
+// What hooks.explainMusic() needs, read once: the same sources the sections of
+// --status read, so the one-line answer cannot disagree with them.
+function musicFacts() {
+  const hooks = require("./hooks");
+  const { muteState, playbackDisabled, detectPlayer: detect } = require("./player");
+  const mute = muteState();
+  const daemon = hooks.daemonPlaying();
+  return {
+    disabledByEnv: mute === null && playbackDisabled(),
+    mute: mute === null ? null : mute.until ? Math.max(1, Math.round((mute.until - Date.now()) / 60000)) : Infinity,
+    backend: Boolean(detect()),
+    daemon,
+    genre: genreNow(),
+    volume: daemon ? (daemon.follows ? Math.round(volumeNow() * 100) : daemon.volume) : null,
+    music: musicEnabled(),
+    musicSource: process.env.VIBE_MUSIC ? "env" : projectSettings(loadConfig()).music !== undefined ? "project" : "",
+    sessions: hooks.agentState().sessions
+  };
+}
+
 function printStatus() {
   const hooks = require("./hooks");
-  const { playbackDisabled, detectPlayer: detect, CACHE_ROOT } = require("./player");
+  const { detectPlayer: detect, CACHE_ROOT } = require("./player");
   const on = (s) => `\x1b[32m${s}\x1b[0m`;
   const off = (s) => `\x1b[90m${s}\x1b[0m`;
 
   console.log(`\n\x1b[1m\x1b[36mVibeAudio\x1b[0m v${pkg.version}\n`);
 
-  const { muteState, muteRemainingText } = require("./player");
-  const mute = muteState();
-  if (mute !== null) {
-    console.log(`\x1b[33m🔇 Muted ${muteRemainingText(mute)}\x1b[0m \x1b[90m(since ${mute.since})\x1b[0m\n`);
-  } else if (playbackDisabled()) {
-    console.log(`\x1b[33m⏸ Muted by VIBE_DISABLE=${process.env.VIBE_DISABLE}\x1b[0m — automatic playback is off (--preview still works).\n`);
-  }
+  // The answer first (#76): everything below is the detail behind it.
+  const now = hooks.explainMusic(musicFacts());
+  console.log(`\x1b[1mNow\x1b[0m  ${now.playing ? on(now.text) : `\x1b[33m${now.text}\x1b[0m`}\n`);
 
   // What will actually play, and which of the three possible sources decided
   // it - the usual confusion is a saved default quietly beaten by an export.

package/src/hooks.js

@@ -805,6 +805,50 @@ function formatStatusline({ status, sessions }) {
   return `${status}${project}${active.length > 1 ? ` ×${active.length}` : ""}`;
 }
 
+/**
+ * "Why is it silent?" / "why is it still playing?" as one line, the first of
+ * --status (#76). Pure over what --status gathers (`musicFacts()` in cli.js),
+ * so the order is the test: what silences everything (VIBE_DISABLE, a mute)
+ * outranks what silences only the music, and a running player outranks every
+ * reason it might not be running. Each silent line names the command that
+ * changes it. `mute` is the minutes left, Infinity for an open-ended mute,
+ * null when not muted; `musicSource` is "env", "project" or "" (saved or default).
+ */
+function explainMusic({ disabledByEnv, mute, backend, daemon, genre, volume, music, musicSource, sessions }) {
+  const names = (list) => {
+    const all = [...new Set(list.map((s) => (s.project ? projectName(s.project) : null)).filter(Boolean))];
+    return all.length > 3 ? `${all.slice(0, 3).join(", ")} +${all.length - 3}` : all.join(", ");
+  };
+  const counted = (list, word) => {
+    const n = names(list);
+    return `${list.length} session${list.length === 1 ? "" : "s"} ${word}${n ? ` (${n})` : ""}`;
+  };
+  const silent = (text) => ({ playing: false, text: `silent: ${text}` });
+  const working = sessions.filter((s) => s.state !== "waiting");
+  const waiting = sessions.filter((s) => s.state === "waiting");
+
+  if (disabledByEnv) return silent("VIBE_DISABLE is set in this shell (unset it to hear music)");
+  if (mute != null) return silent(`muted ${mute === Infinity ? "until you unmute" : `for ${mute} more min`} (vibe --unmute)`);
+  if (!backend) return silent("no audio player found on this machine (vibe --doctor)");
+  if (daemon) {
+    const stuck = sessions.filter((s) => s.state === "stuck");
+    const level = volume === null ? "" : ` @ ${volume}%`;
+    return {
+      playing: true,
+      text: `playing: ${daemon.genre || genre}${level}, ${working.length ? counted(working, "working") : "finishing a turn"}` +
+        `${stuck.length ? `; heartbeat on, ${names(stuck) || "a session"} keeps failing` : ""}`
+    };
+  }
+  if (waiting.length && !working.length) return silent(`${counted(waiting, "waiting on you")}; music resumes when you answer`);
+  if (!music) {
+    // The fix has to beat whatever turned it off: a saved global does not outrank an export or --here.
+    const [where, fix] = { env: [" by VIBE_MUSIC in this shell", "unset VIBE_MUSIC"], project: [" for this project", "vibe --music on --here"] }[musicSource] || ["", "vibe --music on"];
+    return silent(`music is off${where}; chimes still play (${fix})`);
+  }
+  if (working.length) return silent(`${counted(working, "working")} but the player is not running (vibe --doctor)`);
+  return silent("no agent is working; music starts with your next prompt");
+}
+
 const EVENTS_MAX_BYTES = 256 * 1024;
 
 /**
@@ -1781,6 +1825,7 @@ module.exports = {
   STUCK_WINDOW,
   agentState,
   formatStatusline,
+  explainMusic,
   followEvents,
   EVENTS_FILE,
   hookEnd,