vibeaudio 0.9.0 → 0.10.0

package/README.md

@@ -357,6 +357,23 @@ Removing them is one command:
 vibe --uninstall-hooks
 ```
 
+### Know where your time goes: `vibe --report`
+
+Hooks log each finished turn — which project, how long, how it ended, and how much of it the agent spent blocked on a dialog of yours — to `~/.vibeaudio/history.jsonl`. `vibe --report` (or `--report 30`) totals it:
+
+```
+  Turns             30  3 failed
+  You waited        3h 55m  on agents, 7m 51s per turn
+  Agents waited     5m 35s  on you — permission dialogs and questions
+  Typical turn      2m 57s  median
+```
+
+plus where the time went by project and, for windows up to two weeks, by day. "You waited" is the agent's own working time; the time it spent blocked on you is shown separately, because they are different problems. The log stays on your machine, never leaves it, is capped at about 1 MB, and `VIBE_NO_HISTORY=1` turns it off. Only hook-driven turns are logged — a command wrapped as `vibe <command>` is not, since its lifetime isn't the same thing as an agent's working time.
+
+### The chime is in the music's key
+
+The success chime is the tonic chord of whatever key your genre sits in — C major for lofi, 8bit, jazz and piano, D minor for synthwave and electronic, D major for zen, A minor for drone — so it lands as the resolution of the piece rather than a bell over it. `rain`, `ocean` and `random` have no single key to match and keep the original C major chime.
+
 ### Reactive mode (opt-in)
 
 ```bash
@@ -567,6 +584,7 @@ The full order, highest first: **a flag** → **an environment variable** → **
 | `--status` | Show what's installed, running and detected, then 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 |
+| `--report [days]` | How long you waited on agents, and on which projects, from the local turn log | `7` days |
 | `--stop` | Stop the background player, then exit | — |
 | `--mute [minutes]` | Silence everything for a call, then exit | `60` min (`0` = until unmuted) |
 | `--unmute` | Resume normal playback, then exit | — |
@@ -592,6 +610,7 @@ 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_NOTIFY=1            # Desktop banner naming the project, for this shell
+export VIBE_NO_HISTORY=1        # Do not log finished turns (what --report reads)
 export VIBE_NO_UPDATE_CHECK=1   # Never ask npm whether a newer version is out
 ```
 
@@ -624,6 +643,9 @@ The expiry is deliberate too. A call is a bounded thing; a mute you forget about
 **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`).
 
+**Silent after connecting a monitor or headphones (macOS)**
+`afplay` plays on macOS's *default output device*, which moves when a display or headphones connect. A monitor often has no system volume control at all and speakers much quieter than the laptop's, so a quiet setting — a sparse genre like `piano` at 25% — can fall below what you can hear. `vibe --doctor` shows where sound is going and warns if that output is muted or has no volume control. Then try `vibe --genre lofi --volume 60` for one prompt, and check the monitor's own speaker volume.
+
 **Music starts immediately instead of after the grace window**
 It usually is waiting — your AI tool's own startup (auth, session load) just takes longer than 1.5s, so music and the tool's first output appear together. Raise the window: `vibe --grace 3000 claude`.
 

package/package.json

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

@@ -77,6 +77,7 @@ Procedural focus music while your AI coding tools think.
       --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
       --notify | --no-notify   Also show a desktop banner naming the project when a turn finishes or needs you (off by default)
+      --report [days]          How long you waited on agents, and where (default: 7 days)
       --doctor                 Check the setup; each problem comes with its fix (exit 1 if any)
       --stop                   Stop the background player, then exit
       --mute [minutes]         Silence everything for a call (default: 60 min, 0 = until unmuted)
@@ -175,6 +176,7 @@ function parseArgs(argv) {
   let statusFlag = false;
   let doctorFlag = false;
   let notifyFlag = null;
+  let reportDays = null;
   let stopFlag = false;
   let muteFlag = null;
   let muteMinutes = null;
@@ -285,6 +287,17 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--report") {
+      // Optional window in days, like --mute's minutes: `vibe --report 30`.
+      i += 1;
+      reportDays = 7;
+      if (args[i] !== undefined && /^\d+$/.test(args[i])) {
+        reportDays = Math.min(Math.max(parseInt(args[i], 10), 1), 365);
+        i += 1;
+      }
+      continue;
+    }
+
     if (arg === "--notify" || arg === "--no-notify") {
       notifyFlag = arg === "--notify";
       i += 1;
@@ -441,6 +454,7 @@ function parseArgs(argv) {
     status: statusFlag,
     doctor: doctorFlag,
     notify: notifyFlag,
+    report: reportDays,
     stop: stopFlag,
     mute: muteFlag,
     muteMinutes,
@@ -800,6 +814,24 @@ function doctorChecks() {
     add("ok", "Saved settings", "config.json parses (or none saved)");
   }
 
+  // afplay plays on the default output device, which moves when a monitor or
+  // headphones connect - and an external display often has no system volume at
+  // all, or speakers far quieter than the laptop's. Say where sound is going.
+  const out = require("./output").macOutput();
+  if (out) {
+    const where = out.device ? `${out.device.name}${out.device.transport ? ` (${out.device.transport})` : ""}` : "the default output";
+    if (out.muted) {
+      add("warn", "Sound output", `${where} is muted in macOS — nothing will be heard`, "unmute it in the menu bar, or: osascript -e 'set volume output muted false'");
+    } else if (out.volume === null) {
+      add("warn", "Sound output", `${where} has no system volume control, so VibeAudio's own volume is the only one — and its speakers may be quiet`,
+        "raise it with: vibe --volume 60 (and check the monitor's own speaker volume)");
+    } else if (out.volume < 10) {
+      add("warn", "Sound output", `${where}, system volume ${out.volume}%`, "raise the macOS volume");
+    } else {
+      add("ok", "Sound output", `${where}, system volume ${out.volume}%`);
+    }
+  }
+
   const detected = hooks.detectTargets();
   for (const id of Object.keys(hooks.TARGETS)) {
     const t = hooks.TARGETS[id];
@@ -870,6 +902,93 @@ function doctorChecks() {
   return checks;
 }
 
+/** 95 -> "1m 35s", 4_000_000 -> "1h 06m". */
+function formatDuration(ms) {
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${String(s % 60).padStart(2, "0")}s`;
+  return `${Math.floor(m / 60)}h ${String(m % 60).padStart(2, "0")}m`;
+}
+
+/**
+ * The summary of ~/.vibeaudio/history.jsonl. "You waited" is the agent's own
+ * working time - a turn's length minus the stretches it spent blocked on a
+ * dialog of yours - because the two are different complaints: one is the
+ * agent being slow, the other is you being away.
+ */
+function printReport(days, now = Date.now()) {
+  const { readTurns } = require("./history");
+  const turns = readTurns(days, now);
+  const dim = (s) => `\x1b[90m${s}\x1b[0m`;
+  const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+  console.log(`\n\x1b[1m\x1b[36mVibeAudio\x1b[0m report — last ${days === 1 ? "day" : `${days} days`}\n`);
+
+  if (!turns.length) {
+    console.log(`  No turns recorded yet.`);
+    console.log(dim(`  Turns are logged when your agent's hooks fire (vibe --install-hooks). A command wrapped as \`vibe <command>\` is not.`));
+    console.log(dim(`  The log stays on this machine; VIBE_NO_HISTORY=1 turns it off.`));
+    console.log();
+    return;
+  }
+
+  const working = (t) => t.ms - (t.blockedMs || 0);
+  const sum = (xs) => xs.reduce((a, b) => a + b, 0);
+  const sorted = turns.map((t) => t.ms).sort((a, b) => a - b);
+  const median = sorted[Math.floor(sorted.length / 2)];
+  const longest = turns.reduce((a, b) => (b.ms > a.ms ? b : a));
+  const failed = turns.filter((t) => t.outcome === "failure").length;
+  const waitedOnAgents = sum(turns.map(working));
+  const blocked = sum(turns.map((t) => t.blockedMs || 0));
+
+  // Two projects called `api` under different parents stay apart.
+  const names = new Map();
+  for (const t of turns) {
+    const parts = String(t.project || "?").split(/[\\/]/).filter(Boolean);
+    const clash = [...names.entries()].some(([p, n]) => p !== t.project && n === parts.slice(-1)[0]);
+    names.set(t.project, clash ? parts.slice(-2).join("/") : parts.slice(-1)[0] || "?");
+  }
+  const label = (t) => names.get(t.project);
+
+  const row = (k, v, extra = "") => console.log(`  ${k.padEnd(18)}${bold(v)}${extra ? dim(`  ${extra}`) : ""}`);
+  row("Turns", String(turns.length), failed ? `${failed} failed` : "");
+  row("You waited", formatDuration(waitedOnAgents), `on agents, ${formatDuration(waitedOnAgents / turns.length)} per turn`);
+  if (blocked >= 1000) row("Agents waited", formatDuration(blocked), "on you — permission dialogs and questions");
+  row("Typical turn", formatDuration(median), "median");
+  row("Longest turn", formatDuration(longest.ms), label(longest));
+
+  const byProject = new Map();
+  for (const t of turns) {
+    const p = byProject.get(label(t)) || { ms: 0, n: 0 };
+    p.ms += working(t);
+    p.n += 1;
+    byProject.set(label(t), p);
+  }
+  const top = [...byProject.entries()].sort((a, b) => b[1].ms - a[1].ms).slice(0, 5);
+  const widest = top[0][1].ms || 1;
+  console.log(`\n${bold("Where the time went")}`);
+  for (const [name, p] of top) {
+    console.log(`  ${name.slice(0, 18).padEnd(19)}${formatDuration(p.ms).padStart(8)}  ${"█".repeat(Math.max(1, Math.round((p.ms / widest) * 14))).padEnd(14)} ${dim(`${p.n} ${p.n === 1 ? "turn" : "turns"}`)}`);
+  }
+
+  if (days <= 14) {
+    console.log(`\n${bold("By day")}`);
+    const byDay = new Map();
+    for (const t of turns) {
+      const key = new Date(t.at).toLocaleDateString("en-CA");
+      byDay.set(key, (byDay.get(key) || 0) + working(t));
+    }
+    const maxDay = Math.max(...byDay.values()) || 1;
+    for (let d = days - 1; d >= 0; d--) {
+      const date = new Date(now - d * 86400000);
+      const ms = byDay.get(date.toLocaleDateString("en-CA")) || 0;
+      const name = `${date.toLocaleDateString("en-US", { weekday: "short" })} ${date.getDate()}`;
+      console.log(`  ${name.padEnd(8)}${(ms ? formatDuration(ms) : "—").padStart(8)}  ${"█".repeat(ms ? Math.max(1, Math.round((ms / maxDay) * 14)) : 0)}`);
+    }
+  }
+  console.log();
+}
+
 function printDoctor() {
   const mark = { ok: "\x1b[32m✔\x1b[0m", warn: "\x1b[33m!\x1b[0m", fail: "\x1b[31m✘\x1b[0m" };
   const checks = doctorChecks();
@@ -1163,6 +1282,7 @@ function runHookAction(action, { genre, volume, chimeVolume, noChime, reactive,
           volume,
           chimeVolume,
           noChime,
+          genre,
           raw
         });
       });
@@ -1355,6 +1475,7 @@ async function run() {
     status: showStatus,
     doctor: showDoctor,
     notify: notifyChange,
+    report: reportDays,
     stop: shouldStop,
     mute: muteChange,
     muteMinutes,
@@ -1442,6 +1563,10 @@ async function run() {
     return printDoctor();
   }
 
+  if (reportDays !== null) {
+    return printReport(reportDays);
+  }
+
   if (shouldClear) {
     console.log(`\x1b[32m[vibeaudio] Cleared cache at ${clearCache()}\x1b[0m`);
     return;

package/src/history.js

@@ -0,0 +1,57 @@
+/**
+ * A local log of finished turns - what `vibe --report` reads. One JSON object
+ * per line in ~/.vibeaudio/history.jsonl: when the turn ended, which project,
+ * how long it took, how much of that the agent spent blocked on you, and how
+ * it ended. It never leaves the machine; VIBE_NO_HISTORY=1 turns it off.
+ */
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const HISTORY_FILE = path.join(os.homedir(), ".vibeaudio", "history.jsonl");
+const MAX_BYTES = 1024 * 1024;
+const KEEP_LINES = 4000;
+
+/** Appends one turn. Never throws: a log is not worth failing a hook over. */
+function recordTurn({ project, ms, blockedMs = 0, outcome = "success", at = Date.now() }, file = HISTORY_FILE) {
+  if (process.env.VIBE_NO_HISTORY) return false;
+  if (!Number.isFinite(ms) || ms < 0) return false;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify({ at, project, ms, blockedMs: Math.min(Math.max(blockedMs, 0), ms), outcome })}\n`);
+    // Bounded, so a year of use is still a small file. Rewritten rarely, from
+    // the tail, so the newest turns are always the ones kept.
+    if (fs.statSync(file).size > MAX_BYTES) {
+      const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+      const tmp = `${file}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, `${lines.slice(-KEEP_LINES).join("\n")}\n`);
+      fs.renameSync(tmp, file);
+    }
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/** Turns that ended within the last `days` days. A line that does not parse is skipped, not fatal. */
+function readTurns(days, now = Date.now(), file = HISTORY_FILE) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch (e) {
+    return [];
+  }
+  const since = now - days * 86400000;
+  const turns = [];
+  for (const line of raw.split("\n")) {
+    if (!line) continue;
+    try {
+      const t = JSON.parse(line);
+      if (t && Number.isFinite(t.at) && Number.isFinite(t.ms) && t.at >= since) turns.push(t);
+    } catch (e) { /* a torn or hand-edited line */ }
+  }
+  return turns;
+}
+
+module.exports = { HISTORY_FILE, recordTurn, readTurns };

package/src/hooks.js

@@ -16,6 +16,7 @@ const os = require("os");
 const path = require("path");
 const { spawn, execFileSync } = require("child_process");
 const { AudioPlayer, loadConfig, playbackDisabled } = require("./player");
+const { recordTurn } = require("./history");
 
 const STATE_DIR = path.join(os.homedir(), ".vibeaudio");
 const PID_FILE = path.join(STATE_DIR, "daemon.pid");
@@ -624,7 +625,7 @@ function spawnDaemon(genre, volume, reactive) {
 function hookStart(genre, volume, { reactive = false, turn = null } = {}) {
   const id = sessionId(turn && turn.session);
   // Before the spawn: the daemon reads it on startup.
-  writeSession(id, { transcript: (turn && turn.transcript) || "", offset: (turn && turn.offset) || 0, waiting: null });
+  writeSession(id, { transcript: (turn && turn.transcript) || "", offset: (turn && turn.offset) || 0, waiting: null, started: Date.now(), blockedMs: 0 });
   if (working(listSessions()).some((s) => s.id !== id) && daemonRunning()) return readPid();
 
   stopDaemon({ keepSessions: true });
@@ -729,12 +730,19 @@ function notify(raw, message) {
   }
 }
 
-function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, raw = "" } = {}) {
+function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChime = false, genre, raw = "" } = {}) {
   const id = sessionId(parsePayload(raw).session_id);
   // A turn that ends while paused for the user - a denied tool that nothing
   // resumed after - still finished, so its session counts either way.
-  const tracked = readSession(id) !== null;
+  const session = readSession(id);
+  const tracked = session !== null;
   fs.rmSync(sessionFile(id), { force: true });
+  if (session && Number.isFinite(session.started)) {
+    const now = Date.now();
+    // A turn that ends while still paused for you has been blocked since then.
+    const blockedMs = (session.blockedMs || 0) + (session.waiting != null && session.waitStart ? now - session.waitStart : 0);
+    recordTurn({ project: parsePayload(raw).cwd || process.cwd(), ms: now - session.started, blockedMs, outcome, at: now });
+  }
 
   // The music is every working session's, so it ends with the last of them.
   // Everyone else's carries on, and this session still gets its own chime.
@@ -746,7 +754,7 @@ function hookStop({ outcome = "success", volume = 0.4, chimeVolume = null, noChi
   if (noChime) return false;
 
   // Chime plays in this short-lived hook process.
-  new AudioPlayer().stop({ playChime: true, outcome, volume, chimeVolume });
+  new AudioPlayer().stop({ playChime: true, outcome, volume, chimeVolume, genre });
   return true;
 }
 
@@ -792,7 +800,7 @@ function hookWait(raw, { volume = 0.4, chimeVolume = null, noChime = false } = {
   const session = readSession(id);
   if (!session || session.waiting != null) return false;
 
-  writeSession(id, { ...session, waiting: waitKey(raw) });
+  writeSession(id, { ...session, waiting: waitKey(raw), waitStart: Date.now() });
   if (working(listSessions()).length === 0) stopDaemon({ keepSessions: true });
   const tool = payloadToolName(raw);
   notify(raw, tool ? `needs you (${tool})` : "needs you");
@@ -821,7 +829,8 @@ function hookResume(raw, genre, volume, { reactive = false } = {}) {
   // to finish is the first sign of work carrying on.
   if (session.waiting !== "" && session.waiting !== waitKey(raw)) return false;
 
-  writeSession(id, { ...session, waiting: null });
+  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);
   return true;
 }

package/src/output.js

@@ -0,0 +1,57 @@
+/**
+ * What macOS is actually sending sound to. `afplay` plays on the default
+ * output device, which is not always the one you are listening on: connect a
+ * monitor and the default can move to it, where the system volume may be
+ * missing or the speakers quiet. Read only by `--doctor`; nothing else asks.
+ */
+
+const { spawnSync } = require("child_process");
+
+/** "output volume:39, input volume:88, alert volume:63, output muted:false" */
+function parseVolumeSettings(text) {
+  const volume = /output volume:\s*(\d+)/.exec(text);
+  const muted = /output muted:\s*(true|false)/.exec(text);
+  return {
+    // "missing value" is what macOS reports for a device with no software
+    // volume control - common for monitors - so absent means no knob, not zero.
+    volume: volume ? Number(volume[1]) : null,
+    muted: muted ? muted[1] === "true" : null
+  };
+}
+
+const TRANSPORTS = {
+  coreaudio_device_type_usb: "USB",
+  coreaudio_device_type_hdmi: "HDMI",
+  coreaudio_device_type_displayport: "DisplayPort",
+  coreaudio_device_type_builtin: "built-in",
+  coreaudio_device_type_bluetooth: "Bluetooth",
+  coreaudio_device_type_airplay: "AirPlay",
+  coreaudio_device_type_virtual: "virtual"
+};
+
+/** The device `afplay` will use, from `system_profiler SPAudioDataType -json`. */
+function parseDefaultOutput(json) {
+  try {
+    const items = (JSON.parse(json).SPAudioDataType || []).flatMap((group) => group._items || []);
+    const item = items.find((i) => i.coreaudio_default_audio_output_device === "spaudio_yes");
+    if (!item) return null;
+    return { name: item._name, transport: TRANSPORTS[item.coreaudio_device_transport] || null };
+  } catch (e) {
+    return null;
+  }
+}
+
+/** null off macOS, or when either lookup fails: absence of an answer is not a finding. */
+function macOutput() {
+  if (process.platform !== "darwin") return null;
+  const run = (cmd, args) => {
+    const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 5000 });
+    return r.status === 0 ? r.stdout : null;
+  };
+  const settings = run("osascript", ["-e", "get volume settings"]);
+  if (settings === null) return null;
+  const profile = run("system_profiler", ["SPAudioDataType", "-json"]);
+  return { ...parseVolumeSettings(settings), device: profile ? parseDefaultOutput(profile) : null };
+}
+
+module.exports = { parseVolumeSettings, parseDefaultOutput, macOutput };

package/src/player.js

@@ -18,7 +18,7 @@ const { generateRainLoop } = require("./synth/rain");
 const { generateOceanLoop } = require("./synth/ocean");
 const { generatePianoLoop } = require("./synth/piano");
 const { generateJazzLoop } = require("./synth/jazz");
-const { generateSuccessChime, generateFailureChime, generateAttentionChime } = require("./synth/chime");
+const { generateSuccessChime, generateFailureChime, generateAttentionChime, DEFAULT_CHIME_KEY, SUCCESS_CHIME_NOTES } = require("./synth/chime");
 const { hashString } = require("./synth/generator");
 const pkg = require("../package.json");
 
@@ -633,13 +633,45 @@ const CHIMES = {
   attention: generateAttentionChime
 };
 
-function getChimePath(outcome = "success", gain = 1) {
+/**
+ * The key each genre sits in, so the success chime can resolve onto it. Read
+ * off the generators: lofi, 8bit, jazz and piano are C major (or its relative
+ * A minor, which shares the chord); synthwave and electronic are D minor; zen
+ * is D major; drone's roots (D, A, E) all take an A minor chord. Rain and
+ * ocean are noise with no pitch, and `random` is resolved by whoever started
+ * the music, so those keep the original chime.
+ */
+const GENRE_KEYS = {
+  lofi: "C major",
+  "8bit": "C major",
+  jazz: "C major",
+  piano: "C major",
+  synthwave: "D minor",
+  electronic: "D minor",
+  zen: "D major",
+  drone: "A minor"
+};
+
+function chimeKeyFor(genre) {
+  // resolveGenre would roll the dice here, and a chime in a key picked at
+  // random is no more matched than the default.
+  if (String(genre || "").trim().toLowerCase() === "random") return DEFAULT_CHIME_KEY;
+  const key = GENRE_KEYS[resolveGenre(genre || "")];
+  return key && SUCCESS_CHIME_NOTES[key] ? key : DEFAULT_CHIME_KEY;
+}
+
+function getChimePath(outcome = "success", gain = 1, key = DEFAULT_CHIME_KEY) {
   ensureCacheDir();
   const kind = outcome === "error" ? "failure" : CHIMES[outcome] ? outcome : "success";
-  const filePath = path.join(CACHE_DIR, `chime_${kind}${gainSuffix(gain)}.wav`);
+  // Only the success chime has keys, and the default keeps its original file
+  // name so an upgrade does not leave a cached copy behind.
+  const keyed = kind === "success" && key !== DEFAULT_CHIME_KEY && SUCCESS_CHIME_NOTES[key];
+  const suffix = keyed ? `_${key.replace(" ", "")}` : "";
+  const filePath = path.join(CACHE_DIR, `chime_${kind}${suffix}${gainSuffix(gain)}.wav`);
 
   if (!fs.existsSync(filePath)) {
-    writeCacheFileAtomic(filePath, applyGain(CHIMES[kind](), gain));
+    const wav = keyed ? generateSuccessChime(1.6, key) : CHIMES[kind]();
+    writeCacheFileAtomic(filePath, applyGain(wav, gain));
   }
   return filePath;
 }
@@ -787,7 +819,7 @@ class AudioPlayer {
    * that must hand control back at once - an agent waits on its hooks, and a
    * blocking chime held the permission dialog back for its whole length.
    */
-  stop({ playChime = true, outcome = "success", volume = 0.35, chimeVolume = null, detach = false } = {}) {
+  stop({ playChime = true, outcome = "success", volume = 0.35, chimeVolume = null, detach = false, genre = this.genre } = {}) {
     const wasPlaying = this.isPlaying;
     this.isPlaying = false;
 
@@ -809,7 +841,7 @@ class AudioPlayer {
 
       const targetVol = chimeVolume !== null ? chimeVolume : Math.min(0.65, Math.max(0.35, volume * 1.1));
       const clamped = Math.max(0.05, Math.min(1.0, targetVol));
-      const chimeFile = getChimePath(outcome, bakedGain(backend, clamped));
+      const chimeFile = getChimePath(outcome, bakedGain(backend, clamped), chimeKeyFor(genre));
 
       try {
         if (detach) {
@@ -834,6 +866,8 @@ module.exports = {
   pruneSeedDirs,
   writeCacheFileAtomic,
   getChimePath,
+  chimeKeyFor,
+  GENRE_KEYS,
   clearCache,
   detectPlayer,
   bakedGain,

package/src/synth/chime.js

@@ -10,16 +10,30 @@ const {
   createWavBuffer
 } = require("./generator");
 
-function generateSuccessChime(durationSec = 1.6) {
+// The success chime is the tonic chord of whatever key the music is in - root,
+// fifth, octave, third - so it lands as the resolution of the piece instead of
+// a stranger's bell over it. The default is the original C major chime.
+const DEFAULT_CHIME_KEY = "C major";
+const SUCCESS_CHIME_NOTES = {
+  "C major": ["C5", "G5", "C6", "E6"],
+  "D major": ["D5", "A5", "D6", "F#6"],
+  "D minor": ["D5", "A5", "D6", "F6"],
+  // Sits low on purpose: A, E and C are consonant over each of the drone's
+  // three roots (D, A, E), so one chime serves all of them.
+  "A minor": ["A4", "E5", "A5", "C6"]
+};
+
+function generateSuccessChime(durationSec = 1.6, key = DEFAULT_CHIME_KEY) {
+  const names = SUCCESS_CHIME_NOTES[key] || SUCCESS_CHIME_NOTES[DEFAULT_CHIME_KEY];
   const totalSamples = Math.floor(SAMPLE_RATE * durationSec);
   const left = new Float64Array(totalSamples);
   const right = new Float64Array(totalSamples);
 
   const chimeNotes = [
-    { note: "C5", delay: 0.00, pan: 0.4 },
-    { note: "G5", delay: 0.09, pan: 0.6 },
-    { note: "C6", delay: 0.18, pan: 0.45 },
-    { note: "E6", delay: 0.27, pan: 0.55 }
+    { note: names[0], delay: 0.00, pan: 0.4 },
+    { note: names[1], delay: 0.09, pan: 0.6 },
+    { note: names[2], delay: 0.18, pan: 0.45 },
+    { note: names[3], delay: 0.27, pan: 0.55 }
   ];
 
   for (const c of chimeNotes) {
@@ -130,6 +144,8 @@ function generateAttentionChime(durationSec = 1.3) {
 }
 
 module.exports = {
+  DEFAULT_CHIME_KEY,
+  SUCCESS_CHIME_NOTES,
   generateChime: generateSuccessChime,
   generateSuccessChime,
   generateFailureChime,