oc-sounds 0.1.0 → 0.1.2

package/README.md

@@ -15,9 +15,10 @@ Once the first release is published to npm, install globally with:
 opencode2 plugin add oc-sounds
 ```
 
-All sounds are enabled at **100% volume** by default. No individual sound setup
-is required. The package includes all 17 sound files and needs no browser or
-sound renderer at runtime.
+All sounds are enabled at **85% volume** by default. No individual sound setup
+is required. You can [change the sound for any action](#customize) in your OpenCode
+config. The package includes all 17 sound files and needs no browser or sound
+renderer at runtime.
 
 For project-only installation, add `oc-sounds` to `plugins` in your project's
 `opencode.jsonc` instead:
@@ -28,7 +29,7 @@ For project-only installation, add `oc-sounds` to `plugins` in your project's
   "plugins": [
     {
       "package": "oc-sounds",
-      "options": { "volume": 1 }
+      "options": { "volume": 0.85 }
     }
   ]
 }
@@ -67,10 +68,22 @@ Sound plays on the **machine running the OpenCode server**. For a local TUI,
 desktop app, or browser connected to a local server, that is your computer. A
 remote/headless server needs its own accessible audio output.
 
-Playback runs asynchronously. Concurrent actions can overlap, and no action is
-throttled. If a player fails, automatic mode tries the next player; if none work,
-the plugin logs one warning and lets the agent continue. Unloading the plugin
-stops its audio processes and event subscription.
+Playback runs asynchronously with burst smoothing enabled by default:
+
+- Sound starts are spaced at least **180ms** apart per plugin instance.
+- Repeated copies of the same sound within **300ms** are coalesced, including
+  duplicate cues waiting to play. Five simultaneous commands produce one start
+  cue and one return cue instead of ten overlapping sounds.
+- At most **three cues** wait to play. Older routine cues are dropped when the
+  queue fills, and routine cues older than a second expire.
+- Completion, errors, permission requests, questions, and interruptions take
+  priority over queued routine activity. Custom sound mappings retain this
+  priority.
+
+The quiet tails of longer sounds can still overlap. If a player fails, automatic
+mode tries the next player; if none work, the plugin logs one warning and lets
+the agent continue. Unloading stops its queued cues, audio processes, and event
+subscription.
 
 ## What makes a sound?
 
@@ -81,25 +94,28 @@ hooks. The built-in tool palette is:
 | Tool action | Sound |
 | --- | --- |
 | Read files | `page` |
-| Glob, grep, web search | `scan` |
-| Fetch a URL | `droplet` |
-| Write, edit, patch | `toggle` |
-| Shell / code execution | `pulse` |
+| Glob and grep | `release` |
+| Web search | `arrival` |
+| Web fetch | `loading` |
+| Write and edit | `toggle` |
+| Patch a file | `arrival` |
+| Shell / code execution | `tick` |
 | Delegate to a subagent | `arrival` |
 | Load a skill | `sparkle` |
 | Ask the user a question | `chime` |
 | Other tools | `tick` |
 | Tool succeeds / fails | `release` / `error` |
+| Web fetch succeeds | `ready` |
 
 Session actions also have cues. The option keys are listed below:
 
 | Option key | Action | Default |
 | --- | --- | --- |
-| `prompt` | Input enters the session inbox | `press` |
+| `prompt` | Input enters the session inbox | muted |
 | `start` | Agent execution starts | `loading` |
-| `step` | Model step starts | `pulse` |
+| `step` | Model step starts | muted |
 | `thinking` | Reasoning block starts | `whisper` |
-| `reply` | Reply block starts | `chime` |
+| `reply` | Model text / progress message starts | `scan` |
 | `tool` | Fallback tool-start cue | `tick` |
 | `toolComplete` | Tool completes | `release` |
 | `toolError` | Tool fails | `error` |
@@ -119,10 +135,27 @@ Reasoning and replies sound once per block, rather than on every streamed token.
 Tool progress updates do not repeat the start cue. Public events are scoped to
 the plugin's location and repeated event IDs are deduplicated.
 
+`reply` covers model text, including mid-task updates such as "I'll check the
+files now." OpenCode's text-start event does not distinguish intermediate text
+from the final reply, so both use `scan`. The separate `complete` cue plays
+`success` when the agent finishes its execution.
+
+OpenCode emits `prompt`, `start`, and `step` almost simultaneously for ordinary
+prompts, including before any text is visible. Only `start` is audible by
+default, producing one `loading` cue rather than a three-sound burst. Set
+`prompt` to `"press"` or `step` to `"pulse"` in `cues` if you want those extra
+lifecycle cues.
+
 ## Customize
 
+**Every action's sound is configurable.** Use `cues` for session actions such as
+thinking, replying, and completion, `tools` for individual tool-start sounds,
+and `returns` for successful per-tool return sounds. Set a value to any Cuelume
+sound name, or `false` to mute it. Omitted settings keep their defaults.
+
 Edit the existing plugin entry in `~/.config/opencode/opencode.jsonc` (global)
-or your project's `opencode.jsonc`. Merge it with your other settings:
+or your project's `opencode.jsonc`. Merge it with your other settings. If you use
+a local checkout, keep its directory path in `package`:
 
 ```jsonc
 {
@@ -132,17 +165,29 @@ or your project's `opencode.jsonc`. Merge it with your other settings:
       "package": "oc-sounds",
       "options": {
         "enabled": true,
-        "volume": 0.35,
+        "volume": 0.85,
         "player": "auto",
+        "playback": {
+          "minIntervalMs": 180,
+          "dedupeWindowMs": 300
+        },
         "cues": {
+          "prompt": "press",
           "thinking": "whisper",
+          "reply": "scan",
           "complete": "ready",
           "step": false
         },
         "tools": {
           "read": "tick",
+          "edit": "toggle",
           "shell": "pulse",
+          "webfetch": "loading",
+          "websearch": "arrival",
           "my_mcp_tool": "sparkle"
+        },
+        "returns": {
+          "webfetch": "ready"
         }
       }
     }
@@ -150,10 +195,24 @@ or your project's `opencode.jsonc`. Merge it with your other settings:
 }
 ```
 
+This example changes reads to `tick`, completion to `ready`, and mutes model-step
+cues. Change any name to choose a different sound. For all available action and
+tool mappings in one file, see [`examples/opencode.json`](examples/opencode.json),
+which is also included in the npm package.
+
+Save your OpenCode config to apply the changes. If the running plugin does not
+reload automatically, run `opencode2 service restart`. Changing these options
+does not require rebuilding or reinstalling the plugin.
+
 - `enabled`: defaults to `true`. Set to `false` to disable all sounds.
-- `volume`: from `0` to `1`, defaults to `1` (100%). Zero disables playback.
+- `volume`: from `0` to `1`, defaults to `0.85` (85%). Zero disables playback.
 - `player`: `auto`, `paplay`, `pw-play`, `afplay`, or `ffplay`. An explicit player
   disables automatic fallback to other players.
+- `playback.minIntervalMs`: minimum time between sound starts, defaults to `180`.
+- `playback.dedupeWindowMs`: cooldown for repeating the same sound, defaults to
+  `300`. Both timing values accept integers from `0` to `5000` milliseconds. Set
+  both to `0` for immediate, unthrottled playback. For a calmer pace, try `250`
+  and `500` respectively.
 - `cues`: override any action in the table, or set it to `false` to mute it.
   Setting `cues.tool` replaces the built-in starting palette for all ordinary
   tools. `question` is configured separately.
@@ -161,6 +220,10 @@ or your project's `opencode.jsonc`. Merge it with your other settings:
   name (`read` also matches `functions.read` / `functions_read`). Exact names
   take precedence. `false` mutes that tool's starting cue; completion and error
   cues are controlled separately. Tool overrides take precedence over `cues.tool`.
+- `returns`: override successful return cues by exact effective tool name or
+  built-in short name. The default `webfetch` return is `ready`; other successful
+  tools fall back to `cues.toolComplete`. Set a value to `false` to mute that
+  tool's successful return without muting its starting cue.
 
 All 17 Cuelume sounds are available:
 `chime`, `sparkle`, `droplet`, `bloom`, `whisper`, `tick`, `press`, `release`,
@@ -192,7 +255,7 @@ project OpenCode configuration:
   "plugins": [
     {
       "package": "/absolute/path/to/oc-sounds",
-      "options": { "volume": 1 }
+      "options": { "volume": 0.85 }
     }
   ]
 }
@@ -217,8 +280,9 @@ device. Cuelume and the native offline renderer are development dependencies;
 neither is needed by the installed plugin.
 
 Tests cover the V2 plugin lifecycle, event isolation/deduplication, concurrent
-tools, muting, cleanup, player fallback, and bundled WAV integrity. Linux player
-tests use fake executables and do not play audio.
+tools, burst coalescing, playback spacing and priority, bounded queues, muting,
+cleanup, player fallback, and bundled WAV integrity. Scheduler tests use a fake
+clock; Linux player tests use fake executables and do not play audio.
 
 ### Publish to npm
 
@@ -230,8 +294,8 @@ npm pack --dry-run
 ```
 
 The `prepack` hook builds the plugin automatically. The package contains `dist/`,
-`sounds/`, the README, and the license notices; development dependencies and
-rendering scripts are excluded.
+`sounds/`, `examples/`, the README, and the license notices; development
+dependencies and rendering scripts are excluded.
 
 Sign in to an npm account with publishing access, then publish:
 

package/dist/config.d.ts

@@ -1,11 +1,11 @@
 export declare const sounds: readonly ["chime", "sparkle", "droplet", "bloom", "whisper", "tick", "press", "release", "toggle", "success", "error", "page", "loading", "ready", "pulse", "scan", "arrival"];
 export type SoundName = (typeof sounds)[number];
 export declare const defaultCues: {
-    readonly prompt: "press";
+    readonly prompt: false;
     readonly start: "loading";
-    readonly step: "pulse";
+    readonly step: false;
     readonly thinking: "whisper";
-    readonly reply: "chime";
+    readonly reply: "scan";
     readonly tool: "tick";
     readonly toolComplete: "release";
     readonly toolError: "error";
@@ -23,12 +23,23 @@ export declare const defaultCues: {
 };
 export type Action = keyof typeof defaultCues;
 export declare const defaultToolCues: Record<string, SoundName>;
+export declare const defaultToolReturnCues: Record<string, SoundName>;
 export type PlayerName = "auto" | "paplay" | "pw-play" | "afplay" | "ffplay";
+export declare const defaultPlayback: {
+    minIntervalMs: number;
+    dedupeWindowMs: number;
+};
+export interface PlaybackOptions {
+    minIntervalMs: number;
+    dedupeWindowMs: number;
+}
 export interface Options {
     enabled: boolean;
     volume: number;
     player: PlayerName;
+    playback: PlaybackOptions;
     cues: Record<Action, SoundName | false>;
     tools: Record<string, SoundName | false>;
+    returns: Record<string, SoundName | false>;
 }
 export declare function parseOptions(input: unknown): Options;

package/dist/config.js

@@ -4,11 +4,11 @@ export const sounds = [
     "pulse", "scan", "arrival",
 ];
 export const defaultCues = {
-    prompt: "press",
+    prompt: false,
     start: "loading",
-    step: "pulse",
+    step: false,
     thinking: "whisper",
-    reply: "chime",
+    reply: "scan",
     tool: "tick",
     toolComplete: "release",
     toolError: "error",
@@ -26,21 +26,25 @@ export const defaultCues = {
 };
 export const defaultToolCues = {
     read: "page",
-    glob: "scan",
-    grep: "scan",
-    websearch: "scan",
-    webfetch: "droplet",
+    glob: "release",
+    grep: "release",
+    websearch: "arrival",
+    webfetch: "loading",
     write: "toggle",
     edit: "toggle",
-    patch: "toggle",
-    apply_patch: "toggle",
-    shell: "pulse",
-    bash: "pulse",
-    execute: "pulse",
+    patch: "arrival",
+    apply_patch: "arrival",
+    shell: "tick",
+    bash: "tick",
+    execute: "tick",
     subagent: "arrival",
     task: "arrival",
     skill: "sparkle",
 };
+export const defaultToolReturnCues = {
+    webfetch: "ready",
+};
+export const defaultPlayback = { minIntervalMs: 180, dedupeWindowMs: 300 };
 function object(value) {
     if (value && typeof value === "object" && !Array.isArray(value)) {
         return value;
@@ -55,14 +59,14 @@ function cue(value) {
 export function parseOptions(input) {
     const raw = object(input);
     for (const key of Object.keys(raw)) {
-        if (!["enabled", "volume", "player", "cues", "tools"].includes(key)) {
+        if (!["enabled", "volume", "player", "playback", "cues", "tools", "returns"].includes(key)) {
             throw new Error(`oc-sounds: unknown option ${key}`);
         }
     }
     const enabled = raw.enabled ?? true;
     if (typeof enabled !== "boolean")
         throw new Error("oc-sounds: enabled must be a boolean");
-    const volume = raw.volume ?? 1;
+    const volume = raw.volume ?? 0.85;
     if (typeof volume !== "number" || !Number.isFinite(volume) || volume < 0 || volume > 1) {
         throw new Error("oc-sounds: volume must be between 0 and 1");
     }
@@ -79,5 +83,17 @@ export function parseOptions(input) {
     const tools = Object.create(null);
     for (const [key, value] of Object.entries(object(raw.tools ?? {})))
         tools[key] = cue(value);
-    return { enabled, volume, player: player, cues, tools };
+    const returns = Object.create(null);
+    for (const [key, value] of Object.entries(object(raw.returns ?? {})))
+        returns[key] = cue(value);
+    const playback = { ...defaultPlayback };
+    for (const [key, value] of Object.entries(object(raw.playback ?? {}))) {
+        if (!Object.hasOwn(playback, key))
+            throw new Error(`oc-sounds: unknown playback option ${key}`);
+        if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 5000) {
+            throw new Error(`oc-sounds: playback.${key} must be an integer between 0 and 5000 milliseconds`);
+        }
+        playback[key] = value;
+    }
+    return { enabled, volume, player: player, playback, cues, tools, returns };
 }

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { Plugin } from "@opencode/plugin";
 import { type Action, type Options } from "./config.js";
 import { type Player } from "./player.js";
-export { defaultCues, defaultToolCues, sounds } from "./config.js";
-export type { Action, Options, SoundName } from "./config.js";
+export { defaultCues, defaultToolCues, defaultToolReturnCues, defaultPlayback, sounds } from "./config.js";
+export type { Action, Options, PlaybackOptions, SoundName } from "./config.js";
 type Event = ReturnType<Plugin.Context["event"]["subscribe"]> extends AsyncIterable<infer E> ? E : never;
 export declare function actionForEvent(event: Event): Action | undefined;
 export declare function setup(ctx: Plugin.Context, makePlayer?: (selection: Options["player"], volume: number) => Player): Promise<Plugin.Cleanup | void>;

package/dist/index.js

@@ -1,9 +1,10 @@
 import { Plugin } from "@opencode/plugin";
 import { resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
-import { defaultToolCues, parseOptions } from "./config.js";
+import { defaultToolCues, defaultToolReturnCues, parseOptions } from "./config.js";
 import { createPlayer } from "./player.js";
-export { defaultCues, defaultToolCues, sounds } from "./config.js";
+import { schedulePlayer } from "./scheduler.js";
+export { defaultCues, defaultToolCues, defaultToolReturnCues, defaultPlayback, sounds } from "./config.js";
 const eventActions = {
     "session.inbox.enqueued": "prompt",
     "session.execution.started": "start",
@@ -25,33 +26,49 @@ const eventActions = {
 export function actionForEvent(event) {
     return eventActions[event.type];
 }
+function shortToolName(tool) {
+    return tool.split(".").at(-1).replace(/^(functions|tools)_/, "");
+}
+const importantActions = new Set([
+    "complete", "error", "toolError", "permission", "question", "interrupt",
+]);
 // Exported separately to exercise the actual plugin lifecycle with a fake player.
 export async function setup(ctx, makePlayer = createPlayer) {
     const options = parseOptions(ctx.options);
     if (!options.enabled || options.volume === 0)
         return;
-    const player = makePlayer(options.player, options.volume);
+    const player = schedulePlayer(makePlayer(options.player, options.volume), options.playback);
     const controller = new AbortController();
     const registrations = [];
+    const calls = new Map();
     const emit = (action, tool) => {
         if (controller.signal.aborted)
             return;
         let sound = options.cues[action];
         if (tool !== undefined) {
-            const name = tool.split(".").at(-1);
-            const short = name.replace(/^(functions|tools)_/, "");
-            if (Object.hasOwn(options.tools, tool))
-                sound = options.tools[tool];
-            else if (Object.hasOwn(options.tools, short))
-                sound = options.tools[short];
-            // An explicit tool cue replaces the built-in palette for all tools.
-            else if (action === "tool" && !Object.hasOwn(ctx.options.cues ?? {}, "tool")) {
-                if (Object.hasOwn(defaultToolCues, short))
-                    sound = defaultToolCues[short];
+            const short = shortToolName(tool);
+            if (action === "tool") {
+                if (Object.hasOwn(options.tools, tool))
+                    sound = options.tools[tool];
+                else if (Object.hasOwn(options.tools, short))
+                    sound = options.tools[short];
+                // An explicit general cue replaces the built-in palette for all tools.
+                else if (!Object.hasOwn(ctx.options.cues ?? {}, "tool")) {
+                    if (Object.hasOwn(defaultToolCues, short))
+                        sound = defaultToolCues[short];
+                }
+            }
+            else if (action === "toolComplete") {
+                if (Object.hasOwn(options.returns, tool))
+                    sound = options.returns[tool];
+                else if (Object.hasOwn(options.returns, short))
+                    sound = options.returns[short];
+                else if (Object.hasOwn(defaultToolReturnCues, short))
+                    sound = defaultToolReturnCues[short];
             }
         }
         if (sound)
-            player.play(sound);
+            player.play(sound, importantActions.has(action));
     };
     const cleanup = async () => {
         controller.abort();
@@ -60,11 +77,14 @@ export async function setup(ctx, makePlayer = createPlayer) {
     };
     try {
         registrations.push(await ctx.tool.hook("execute.before", (event) => {
-            const name = event.tool.split(/[._]/).at(-1);
+            const name = shortToolName(event.tool);
+            calls.set(event.id, event.tool);
             emit(name === "question" ? "question" : "tool", event.tool);
         }));
         registrations.push(await ctx.tool.hook("execute.after", (event) => {
-            emit(event.status === "error" ? "toolError" : "toolComplete");
+            const tool = calls.get(event.id) ?? event.tool;
+            calls.delete(event.id);
+            emit(event.status === "error" ? "toolError" : "toolComplete", typeof tool === "string" ? tool : undefined);
         }));
     }
     catch (error) {

package/dist/player.d.ts

@@ -1,7 +1,7 @@
 import type { PlayerName, SoundName } from "./config.js";
 type Backend = Exclude<PlayerName, "auto">;
 export interface Player {
-    play(sound: SoundName): void;
+    play(sound: SoundName, important?: boolean): void;
     dispose(): void;
 }
 export declare function playerArgs(player: Backend, file: string, volume: number): string[];

package/dist/scheduler.d.ts

@@ -0,0 +1,4 @@
+import type { PlaybackOptions } from "./config.js";
+import type { Player } from "./player.js";
+/** One queue per plugin instance, shared by hooks and the session event stream. */
+export declare function schedulePlayer(player: Player, options: PlaybackOptions, now?: () => number): Player;

package/dist/scheduler.js

@@ -0,0 +1,66 @@
+const MAX_PENDING = 3;
+const MAX_AGE_MS = 1000;
+/** One queue per plugin instance, shared by hooks and the session event stream. */
+export function schedulePlayer(player, options, now = () => performance.now()) {
+    let queue = [];
+    const recent = new Map();
+    let lastStart = -Infinity;
+    let timer;
+    let disposed = false;
+    function pump() {
+        if (disposed || timer)
+            return;
+        const time = now();
+        queue = queue.filter((item) => item.important || time - item.time <= MAX_AGE_MS);
+        if (!queue.length)
+            return;
+        const wait = options.minIntervalMs - (time - lastStart);
+        if (wait > 0) {
+            timer = setTimeout(() => {
+                timer = undefined;
+                pump();
+            }, Math.ceil(wait));
+            timer.unref();
+            return;
+        }
+        const item = queue.shift();
+        lastStart = time;
+        recent.set(item.sound, { time, important: item.important });
+        player.play(item.sound, item.important);
+        pump();
+    }
+    return {
+        play(sound, important = false) {
+            if (disposed)
+                return;
+            const time = now();
+            const previous = recent.get(sound);
+            if (previous && time - previous.time < options.dedupeWindowMs
+                && (!important || previous.important))
+                return;
+            // Attention/finish cues replace stale routine work instead of waiting
+            // behind a flood of tools. Priority follows the action, not its sound.
+            if (important)
+                queue = queue.filter((item) => item.important);
+            else if (queue.some((item) => item.important))
+                return;
+            if (queue.some((item) => item.sound === sound))
+                return;
+            if (queue.length >= MAX_PENDING)
+                queue.shift();
+            queue.push({ sound, important, time });
+            pump();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+            queue = [];
+            recent.clear();
+            player.dispose();
+        },
+    };
+}

package/examples/opencode.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "oc-sounds",
+      "options": {
+        "enabled": true,
+        "volume": 0.85,
+        "player": "auto",
+        "playback": {
+          "minIntervalMs": 180,
+          "dedupeWindowMs": 300
+        },
+        "cues": {
+          "prompt": false,
+          "start": "loading",
+          "step": false,
+          "thinking": "whisper",
+          "reply": "scan",
+          "tool": "tick",
+          "toolComplete": "release",
+          "toolError": "error",
+          "permission": "bloom",
+          "permissionReply": "toggle",
+          "question": "chime",
+          "retry": "scan",
+          "complete": "success",
+          "error": "error",
+          "interrupt": "droplet",
+          "compact": "page",
+          "compactComplete": "ready",
+          "skill": "sparkle",
+          "agent": "arrival"
+        },
+        "tools": {
+          "read": "page",
+          "glob": "release",
+          "grep": "release",
+          "websearch": "arrival",
+          "webfetch": "loading",
+          "write": "toggle",
+          "edit": "toggle",
+          "patch": "arrival",
+          "apply_patch": "arrival",
+          "shell": "tick",
+          "bash": "tick",
+          "execute": "tick",
+          "subagent": "arrival",
+          "task": "arrival",
+          "skill": "sparkle"
+        },
+        "returns": {
+          "webfetch": "ready"
+        }
+      }
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oc-sounds",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Cuelume sound feedback for OpenCode V2 agent actions",
   "type": "module",
   "license": "MIT",
@@ -9,7 +9,7 @@
   "exports": {
     ".": "./dist/index.js"
   },
-  "files": ["dist", "sounds", "THIRD_PARTY_NOTICES.md"],
+  "files": ["dist", "sounds", "examples", "THIRD_PARTY_NOTICES.md"],
   "engines": { "node": ">=22" },
   "scripts": {
     "build": "tsc",