opencode-speaker 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 herquiloide
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,281 @@
+# opencode-speaker
+
+[![npm version](https://img.shields.io/npm/v/opencode-speaker.svg)](https://www.npmjs.com/package/opencode-speaker)
+[![CI](https://github.com/herquiloidehele/opencode-speaker/actions/workflows/ci.yml/badge.svg)](https://github.com/herquiloidehele/opencode-speaker/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+A speaker plugin for [opencode](https://opencode.ai) that **speaks agent activity out loud** through pluggable text-to-speech backends.
+
+Hear what your agent is doing while you work on something else — session summaries, errors, permission requests, and todo completions, narrated by an LLM and spoken by a TTS model.
+
+Supports **OpenAI** (default) and **ElevenLabs** for TTS, with **OpenAI** or **Anthropic** for the LLM narrator. Powered by the [Vercel AI SDK](https://sdk.vercel.ai).
+
+---
+
+## Requirements
+
+- **Node.js ≥ 20**
+- An API key for your chosen provider (OpenAI by default; ElevenLabs and/or Anthropic optional)
+- On Linux, a TTS/audio backend — see [Troubleshooting](#troubleshooting)
+
+---
+
+## Install
+
+### 1. Add the plugin to `opencode.json`
+
+Your global opencode config file is usually located at `~/.config/opencode/opencode.json`.
+If you use a project-local opencode config, add the same plugin entry there instead.
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-speaker"]
+}
+```
+
+### 2. Set your OpenAI API key
+
+For the current terminal session:
+
+```bash
+export OPENAI_API_KEY=sk-...
+```
+
+To make it available every time you open a terminal, add it to your shell startup file:
+
+```bash
+# zsh, macOS default
+echo 'export OPENAI_API_KEY=sk-...' >> ~/.zshrc
+
+# bash
+echo 'export OPENAI_API_KEY=sk-...' >> ~/.bashrc
+```
+
+If you use fish:
+
+```fish
+set -Ux OPENAI_API_KEY sk-...
+```
+
+Restart your terminal after adding the variable, or run `source ~/.zshrc` / `source ~/.bashrc` for the current session.
+
+That's it. Start opencode and you'll hear a short greeting confirming the plugin is ready.
+
+By default, the plugin uses:
+- TTS model: `openai/gpt-4o-mini-tts`
+- Narrator model: `openai/gpt-4.1-mini`
+
+And out of the box, you'll hear:
+- Session starts, idle summaries, errors, and compactions
+- Permission requests and replies
+- Tool starts and finishes
+- File edits and executed commands
+- Reasoning deltas while the assistant is thinking
+- Todo item completions and “all todos complete” summaries
+
+---
+
+## Using ElevenLabs instead
+
+Configure the plugin using the **tuple form** in the `plugin` array (per-plugin config goes as the second tuple element — not as a top-level key):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    ["opencode-speaker", {
+      "tts": {
+        "model": "elevenlabs/eleven_turbo_v2_5",
+        "voice": "EXAVITQu4vr4xnSDxMaL"
+      }
+    }]
+  ]
+}
+```
+
+Then set your API key:
+
+```bash
+export ELEVENLABS_API_KEY=...
+```
+
+The `voice` field takes an ElevenLabs voice ID.
+
+> **Note:** The narrator (LLM summarizer) is separate from TTS. You can mix and match — e.g., narrate with Anthropic, speak with ElevenLabs.
+
+---
+
+## Configuration
+
+All options go inside the tuple's second element: `["opencode-speaker", { ... }]`.
+
+### Full example
+
+```json
+{
+  "plugin": [
+    ["opencode-speaker", {
+      "greeting": "opencode speaker ready",
+      "tts": {
+        "model": "openai/gpt-4o-mini-tts",
+        "voice": "nova",
+        "rate": 1.0
+      },
+      "narrator": {
+        "model": "openai/gpt-4.1-mini",
+        "timeoutMs": 5000,
+        "minIntervalMs": 3000
+      },
+      "events": {
+        "tool.execute.before": { "enabled": true }
+      }
+    }]
+  ]
+}
+```
+
+### TTS providers
+
+| Provider | Model slug example | Voices | Env var |
+|---|---|---|---|
+| OpenAI (default) | `openai/gpt-4o-mini-tts`, `openai/tts-1`, `openai/tts-1-hd` | `alloy`, `ash`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage`, `shimmer` | `OPENAI_API_KEY` |
+| ElevenLabs | `elevenlabs/eleven_turbo_v2_5` | ElevenLabs voice ID | `ELEVENLABS_API_KEY` |
+
+### Narrator (LLM) providers
+
+| Provider | Model slug example | Env var |
+|---|---|---|
+| OpenAI (default) | `openai/gpt-4.1-mini` | `OPENAI_API_KEY` |
+| Anthropic | `anthropic/claude-haiku-4` | `ANTHROPIC_API_KEY` |
+
+The plugin resolves `provider/model` slugs internally — no imports needed.
+
+### Events
+
+Each event is independently configurable.
+
+### Verbosity
+
+Use `verbosity` to choose a default event profile, then override individual events as needed.
+
+| Value | Behavior |
+|---|---|
+| `minimal` | Speaks only session idle summaries, session errors, permission requests, and all-todos-complete summaries. |
+| `normal` | Current default event profile. |
+| `verbose` | Same as `normal` today; reserved for future high-detail defaults while preserving a stable option name. |
+
+```json
+{
+  "plugin": [
+    ["opencode-speaker", {
+      "verbosity": "minimal",
+      "events": {
+        "tool.execute.before": { "enabled": true }
+      }
+    }]
+  ]
+}
+```
+
+| Event | Default | Mode |
+|---|---|---|
+| `session.idle` | on | narrate (LLM summary) |
+| `session.error` | on | template, urgent |
+| `session.compacted` | on | template |
+| `session.created` | on | template |
+| `permission.asked` | on | template, urgent |
+| `permission.replied` | on | template |
+| `tool.execute.before` | on | template, chatty |
+| `tool.execute.after` | on | template, chatty |
+| `file.edited` | on | template, chatty |
+| `command.executed` | on | template |
+| `message.reasoning.delta` | on | verbatim, chatty |
+| `message.text.delta` | off | verbatim, chatty |
+| `message.updated` | off | verbatim |
+| `todo.completed.item` | on | template, chatty |
+| `todo.completed.all` | on | narrate |
+
+Override per event:
+
+```json
+{
+  "events": {
+    "tool.execute.before": { "enabled": true, "mode": "template" }
+  }
+}
+```
+
+Modes:
+- `template` — fixed phrasing (fast, no LLM)
+- `narrate` — LLM-generated summary (concise but covers what happened, blockers, next steps)
+- `verbatim` — speak the raw text as-is
+
+The narrator is rate-limited by `minIntervalMs` and falls back to a template if the call fails or is throttled.
+
+### Greeting
+
+A short startup line, spoken once when the plugin is ready. Default: `"Welcome to OpenCode Speaker!"`.
+
+```json
+{ "greeting": "welcome back" }
+```
+
+Set to `""` to disable. Skipped automatically when `startMuted: true` or `OPENCODE_VOICE_MUTE=1`.
+
+## Custom providers
+
+Runtime provider selection is currently built in. TTS slugs route `openai/*` and
+`elevenlabs/*`; narrator slugs route `openai/*` and `anthropic/*`.
+
+The `opencode-speaker/api` entrypoint exports provider-related TypeScript types
+for integrations, but it does not register custom providers at runtime. To add a
+provider today, fork the model resolver in `src/ai-sdk/models.ts` or open an
+issue.
+
+---
+
+## Troubleshooting
+
+**No audio on Linux:** install `speech-dispatcher` (`sudo apt install speech-dispatcher`) or `espeak`. For cloud-provider audio playback, install `pulseaudio-utils` (`paplay`), `alsa-utils` (`aplay`), or `ffmpeg` (`ffplay`).
+
+**Windows blocked by execution policy:** run PowerShell once with `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.
+
+**Plugin disabled with a toast on startup:** the toast carries a short summary (invalid config, missing API key, TTS init failure). The full structured detail is in opencode's log file — `opencode-speaker` errors are logged at `error` / `warn` level.
+
+**`Unrecognized key: voice` schema error:** you put options at the top level. Use the tuple form: `"plugin": [["opencode-speaker", { ... }]]`, not `"voice": { ... }`.
+
+---
+
+## Development
+
+Six runnable demo scripts exercise each feature without booting opencode (all use `tsx`):
+
+| Script | Validates |
+|---|---|
+| `npm run demo:say -- "text"` | Synthesis + playback. Override TTS with `--model=elevenlabs/eleven_turbo_v2_5 --voice=<id>`. |
+| `npm run demo:queue` | Speech queue priority + dedup behavior. |
+| `npm run demo:event -- <event.type>` | Full event-to-audio pipeline. E.g. `session.idle`, `permission.asked --tool=write`. |
+| `npm run demo:narrator -- --assistant-text="..." --tool=bash` | LLM narrator handler. |
+| `npm run demo:config -- '{...}'` or `--file=path.json` | Validate a config block against the Zod schema. |
+| `npm run demo:greet` | Startup greeting via the full plugin. |
+
+Standard commands:
+
+```bash
+npm test          # full unit + integration suite
+npm run typecheck # TypeScript validation
+npm run build     # produce dist/
+```
+
+To restart opencode against a local build:
+
+```bash
+rm -rf ~/.cache/opencode/node_modules/opencode-speaker && npm run build
+```
+
+---
+
+## License
+
+MIT.

package/dist/api.d.ts

@@ -0,0 +1,14 @@
+interface SynthesisOptions {
+    voice?: string;
+    rate?: number;
+}
+interface SynthesisResult {
+    audio: Buffer;
+    contentType: string;
+}
+interface TTSProvider {
+    readonly name: string;
+    synthesize(text: string, opts: SynthesisOptions, signal: AbortSignal): Promise<SynthesisResult>;
+}
+
+export type { SynthesisOptions, SynthesisResult, TTSProvider };

package/dist/api.js

@@ -0,0 +1 @@
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFtdLAogICJzb3VyY2VzQ29udGVudCI6IFtdLAogICJtYXBwaW5ncyI6ICIiLAogICJuYW1lcyI6IFtdCn0K

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+type PluginCtx = {
+    client: {
+        app: {
+            log: (...args: any[]) => Promise<unknown>;
+        };
+    };
+    directory: string;
+    worktree?: string;
+    project?: unknown;
+    $: unknown;
+};
+type PluginOptions = Record<string, unknown> | undefined;
+declare const OpencodeSpeaker: (ctx: PluginCtx, options?: PluginOptions) => Promise<{
+    event?: undefined;
+} | {
+    event: ({ event, }: {
+        event: {
+            type: string;
+            [k: string]: unknown;
+        };
+    }) => Promise<void>;
+}>;
+
+export { OpencodeSpeaker, OpencodeSpeaker as default };