@mcptoolshop/voice-soundboard-mcp 0.0.0 → 1.0.3

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog: @mcptoolshop/voice-soundboard-mcp
+
+The full history of the repository, including the Python package, is in the [repository CHANGELOG](https://github.com/mcp-tool-shop-org/mcp-voice-soundboard/blob/main/CHANGELOG.md).
+
+## [1.0.3] - 2026-10-15
+
+The first npm release of both packages (`1.0.2` was never published to npm).
+
+- `@mcptoolshop/voice-soundboard-core` and `@mcptoolshop/voice-soundboard-mcp` publish from CI through npm Trusted Publishing, with provenance.
+- Each package has its own README. The core package's README described the server; both now match the code: 46 voices (not 48), the eight emotions and their `{emotion}` syntax, the six sound-effect tags, the presets, and how the server picks its speech backend.
+- `voice-soundboard-mcp --help` lists the environment variables the server reads (`VOICE_SOUNDBOARD_TTS_URL`, not `_HTTP_URL`) and its real defaults (backend chosen automatically, 1 concurrent synthesis, a 20,000 ms timeout).
+- `LICENSE` and `CHANGELOG.md` are in each package, as `files` already listed.
+- Includes the 2.5.5 security fixes in `@mcptoolshop/voice-soundboard-core`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+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

@@ -1,5 +1,263 @@
-# @mcptoolshop/voice-soundboard-mcp
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/mcp-voice-soundboard/main/assets/logo-dark.jpg" alt="MCP Voice Soundboard" width="420" />
+</p>
 
-Placeholder release. The real package is published from CI.
+<h3 align="center">Text-to-speech for AI agents, as an MCP server.</h3>
 
-Source: <https://github.com/mcp-tool-shop-org/mcp-voice-soundboard>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@mcptoolshop/voice-soundboard-mcp"><img src="https://img.shields.io/npm/v/@mcptoolshop/voice-soundboard-mcp?style=flat-square&color=cb3837&logo=npm" alt="npm"></a>
+  <a href="https://github.com/mcp-tool-shop-org/mcp-voice-soundboard/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/mcp-tool-shop-org/mcp-voice-soundboard/ci.yml?branch=main&style=flat-square&label=CI" alt="CI"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 20+">
+  <a href="https://github.com/mcp-tool-shop-org/mcp-voice-soundboard/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  46 voices &bull; 9 languages &bull; 5 presets &bull; 8 emotions &bull; SSML-lite &bull; sound effects &bull; multi-speaker dialogue
+</p>
+
+Give an agent a voice. Claude Desktop, Cursor or any MCP client can speak a line, perform a scripted dialogue between several speakers, and drop a chime where it belongs. Speech comes from **Kokoro-82M** (Apache-2.0) through **kokoro-onnx**, so it runs on your own machine with no account and no API key. Every request passes the same guardrails: rate limits, one synthesis at a time, timeouts, a sandboxed output folder and redaction of secrets.
+
+## Quick start
+
+```bash
+npx -y @mcptoolshop/voice-soundboard-mcp
+```
+
+Add it to your MCP client, for example `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "voice-soundboard": {
+      "command": "npx",
+      "args": ["-y", "@mcptoolshop/voice-soundboard-mcp"]
+    }
+  }
+}
+```
+
+The server speaks MCP over stdio. Set `PORT` to serve it over HTTP instead.
+
+## Where the speech comes from
+
+The server picks a backend when it starts and logs which one:
+
+1. **HTTP:** when `VOICE_SOUNDBOARD_TTS_URL` is set, it sends synthesis to that endpoint (with `VOICE_SOUNDBOARD_TTS_TOKEN` as a bearer token if you set one).
+2. **Python bridge (Kokoro):** otherwise, when `python` is on your `PATH` (or `VOICE_SOUNDBOARD_PYTHON` names one), it starts the bundled bridge.
+   - On first use the bridge installs `kokoro-onnx` with `pip install --user` and downloads the model (`kokoro-v1.0.onnx`, about 310 MB, and `voices-v1.0.bin`, about 26 MB) into `~/.cache/voice-soundboard`.
+   - After that it runs offline.
+3. **Mock:** with neither, it answers with silent WAV files, so the tools still work end to end while you wire things up.
+
+Choose one explicitly with `--backend=http|python|mock|none`.
+
+## Tools
+
+### `voice_speak`
+
+Speak text with one voice.
+
+```
+text:          "Hello world!"
+voice?:        "am_fenrir"     # a voice ID or a preset name
+speed?:        1.0             # 0.5 to 2.0
+format?:       "wav"           # wav | mp3 | ogg | raw
+artifactMode?: "path"          # path | base64
+outputDir?:    "clips"         # a subfolder of the output root, in path mode
+sfx?:          true            # turn on [ding], [chime] and the other sound-effect tags
+```
+
+### `voice_dialogue`
+
+Perform a script with several speakers.
+
+```
+script:        "Alice: Hello!\n[pause 300ms]\nBob: Hey there!"
+cast?:         { "Alice": "af_sky", "Bob": "narrator" }   # anyone not cast is assigned a voice
+speed?:        1.0
+concat?:       true            # one audio file for the whole scene
+debug?:        true            # include the cue sheet and parse warnings
+artifactMode?: "path"
+outputDir?:    "scenes"
+```
+
+### `voice_status`
+
+The backend and its health, the voices, the presets and the default voice. No arguments.
+
+### `voice_interrupt`
+
+Stop speech in progress.
+
+```
+streamId?:     "stream-123"
+reason?:       "user_spoke"    # user_spoke | context_change | timeout | manual
+```
+
+### `voice_inner_monologue`
+
+Short, throwaway utterances for ambient narration: up to 500 characters, rate-limited, with secrets redacted. Off unless the server runs with `--ambient` or `VOICE_SOUNDBOARD_AMBIENT_ENABLED=1`.
+
+```
+text:          "Interesting..."
+category?:     "thinking"      # general | thinking | observation | debug
+```
+
+## Markup
+
+| Markup | Syntax | Values |
+|---|---|---|
+| Emotion | `{joy}Great news!{/joy}` | `neutral`, `serious`, `friendly`, `professional`, `calm`, `joy`, `urgent`, `whisper` |
+| Sound effect | `[ding]` (with `sfx: true`) | `ding`, `chime`, `whoosh`, `click`, `pop`, `tada` |
+| SSML-lite | `<break time="300ms"/>` | `<speak>`, `<break>`, `<prosody>`, `<emphasis>` |
+| Dialogue | `Alice: Hello!` | one line per cue, `[pause 350ms]` between cues |
+
+Each emotion maps to a voice and speed. For example, `joy` uses `am_eric` at 1.03 and `urgent` uses `am_fenrir` at 1.08.
+
+## Voices
+
+46 voices in 9 languages. The language follows from the voice ID's prefix, so there's nothing to configure. The default voice is `bm_george`.
+
+### Presets
+
+| Preset | Voice | Speed | Character |
+|---|---|---|---|
+| `assistant` | `af_jessica` | 1.0 | Friendly, helpful, conversational |
+| `narrator` | `bm_george` | 0.95 | Calm, clear, documentary style |
+| `announcer` | `am_eric` | 1.1 | Bold, energetic, broadcast style |
+| `storyteller` | `bf_emma` | 0.9 | Expressive, varied pacing |
+| `whisper` | `af_sky` | 0.85 | Soft, intimate, gentle |
+
+#### English (American) (14)
+
+| Voice | Name | Gender | Style |
+|---|---|---|---|
+| `af_aoede` | Aoede | female | musical |
+| `af_bella` | Bella | female | warm |
+| `af_heart` | Heart | female | caring |
+| `af_jessica` | Jessica | female | professional |
+| `af_kore` | Kore | female | youthful |
+| `af_nicole` | Nicole | female | soft |
+| `af_sarah` | Sarah | female | clear |
+| `af_sky` | Sky | female | airy |
+| `am_eric` | Eric | male | confident |
+| `am_fenrir` | Fenrir | male | powerful |
+| `am_liam` | Liam | male | friendly |
+| `am_michael` | Michael | male | deep |
+| `am_onyx` | Onyx | male | smooth |
+| `am_puck` | Puck | male | playful |
+
+#### English (British) (6)
+
+| Voice | Name | Gender | Style |
+|---|---|---|---|
+| `bf_alice` | Alice | female | proper |
+| `bf_emma` | Emma | female | refined |
+| `bf_isabella` | Isabella | female | warm |
+| `bm_fable` | Fable | male | storytelling |
+| `bm_george` | George | male | authoritative |
+| `bm_lewis` | Lewis | male | friendly |
+
+#### Japanese (5)
+
+| Voice | Name | Gender | Style |
+|---|---|---|---|
+| `jf_alpha` | Alpha | female | clear |
+| `jf_gongitsune` | Gongitsune | female | storytelling |
+| `jf_nezuko` | Nezuko | female | gentle |
+| `jf_tebukuro` | Tebukuro | female | warm |
+| `jm_kumo` | Kumo | male | calm |
+
+#### Mandarin Chinese (8)
+
+| Voice | Name | Gender | Style |
+|---|---|---|---|
+| `zf_xiaobei` | Xiaobei | female | bright |
+| `zf_xiaoni` | Xiaoni | female | gentle |
+| `zf_xiaoxiao` | Xiaoxiao | female | clear |
+| `zf_xiaoyi` | Xiaoyi | female | warm |
+| `zm_yunjian` | Yunjian | male | authoritative |
+| `zm_yunxi` | Yunxi | male | friendly |
+| `zm_yunxia` | Yunxia | male | calm |
+| `zm_yunyang` | Yunyang | male | confident |
+
+#### Spanish (3)
+
+| Voice | Name | Gender | Style |
+|---|---|---|---|
+| `ef_dora` | Dora | female | warm |
+| `em_alex` | Alex | male | confident |
+| `em_santa` | Santa | male | jolly |
+
+#### French (1)
+
+| Voice | Name | Gender | Style |
+|---|---|---|---|
+| `ff_siwis` | Siwis | female | refined |
+
+#### Hindi (4)
+
+| Voice | Name | Gender | Style |
+|---|---|---|---|
+| `hf_alpha` | Alpha | female | clear |
+| `hf_beta` | Beta | female | warm |
+| `hm_omega` | Omega | male | deep |
+| `hm_psi` | Psi | male | calm |
+
+#### Italian (2)
+
+| Voice | Name | Gender | Style |
+|---|---|---|---|
+| `if_sara` | Sara | female | warm |
+| `im_nicola` | Nicola | male | confident |
+
+#### Brazilian Portuguese (3)
+
+| Voice | Name | Gender | Style |
+|---|---|---|---|
+| `pf_dora` | Dora | female | warm |
+| `pm_alex` | Alex | male | confident |
+| `pm_santa` | Santa | male | jolly |
+
+## Options
+
+| Flag | Default | What it does |
+|---|---|---|
+| `--backend=<type>` | chosen automatically (see above) | `http`, `python`, `mock` or `none` |
+| `--artifact=path\|base64` | `path` | Return audio as a file path or as base64 |
+| `--output-dir=<path>` | `<tmpdir>/voice-soundboard` | Where audio files are written |
+| `--max-concurrent=<n>` | `1` | Syntheses at the same time |
+| `--timeout=<ms>` | `20000` | Timeout per request |
+| `--retention-minutes=<n>` | `240` | Delete audio older than this (`0` keeps it) |
+| `--ambient` | off | Enable `voice_inner_monologue` |
+| `--version`, `--help` | | Print the version or the usage |
+
+| Environment variable | What it does |
+|---|---|
+| `PORT` | Serve over HTTP on this port instead of stdio |
+| `VOICE_SOUNDBOARD_TTS_URL` | HTTP backend endpoint (selects the HTTP backend) |
+| `VOICE_SOUNDBOARD_TTS_TOKEN` | Bearer token for the HTTP backend |
+| `VOICE_SOUNDBOARD_HTTP_TIMEOUT` | HTTP backend timeout in milliseconds |
+| `VOICE_SOUNDBOARD_PYTHON` | Python command for the bridge |
+| `VOICE_SOUNDBOARD_PYTHON_MODULE` | Bridge module to run |
+| `VOICE_SOUNDBOARD_OUTPUT_DIR` | Output folder for the Python bridge |
+| `VOICE_SOUNDBOARD_AMBIENT_ENABLED` | `1` enables `voice_inner_monologue` |
+
+## Limits and safety
+
+- **Request size:** 12,000 characters of text, 50 chunks, 100 emotion spans, 400 SSML nodes, 30 sound effects and breaks of 2 seconds or less.
+- **Output:** audio is written only inside the output root. Paths that climb out of it, and symlinks, are refused, and file names are generated by the server.
+- **Errors:** each one comes back with a code, a hint and whether it's safe to retry, never a stack trace.
+- **Privacy:** no telemetry, and nothing leaves your machine except calls to the HTTP backend you configure, and the bridge's one-time install and model download.
+
+See the [threat model](https://github.com/mcp-tool-shop-org/mcp-voice-soundboard/blob/main/THREAT_MODEL.md) and the [security policy](https://github.com/mcp-tool-shop-org/mcp-voice-soundboard/blob/main/SECURITY.md).
+
+## Related
+
+- [`@mcptoolshop/voice-soundboard-core`](https://www.npmjs.com/package/@mcptoolshop/voice-soundboard-core): the engine-agnostic library this server is built on, for your own integrations.
+- [Source](https://github.com/mcp-tool-shop-org/mcp-voice-soundboard), [discussions](https://github.com/mcp-tool-shop-org/mcp-voice-soundboard/discussions) and [issues](https://github.com/mcp-tool-shop-org/mcp-voice-soundboard/issues).
+
+## Credits and license
+
+Speech is generated by [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) (Apache-2.0) through [kokoro-onnx](https://github.com/thewh1teagle/kokoro-onnx) (MIT).
+
+This package is [MIT](https://github.com/mcp-tool-shop-org/mcp-voice-soundboard/blob/main/LICENSE). Part of [MCP Tool Shop](https://mcptoolshop.com/).

package/backend-python/soundboard_bridge/__main__.py

@@ -0,0 +1,200 @@
+"""
+Voice Soundboard Python Bridge — NDJSON stdio protocol.
+
+Auto-downloads Kokoro ONNX model + voices on first run.
+Communicates with the Node.js MCP server via newline-delimited JSON on stdin/stdout.
+
+Protocol:
+  IN:  {"id": "...", "op": "health"}
+  OUT: {"id": "...", "ok": true, "model": "kokoro-v0.19"}
+
+  IN:  {"id": "...", "op": "synthesize", "text": "Hello", "voice": "af_bella", "speed": 1.0,
+        "format": "wav", "artifact_mode": "base64"}
+  OUT: {"id": "...", "ok": true, "audio_bytes_base64": "...", "duration_ms": 1234,
+        "sample_rate": 24000, "format": "wav"}
+
+  IN:  {"id": "...", "op": "interrupt"}
+  OUT: {"id": "...", "ok": true}
+"""
+
+import json
+import sys
+import io
+import base64
+import struct
+import os
+
+
+GITHUB_RELEASE = "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0"
+MODEL_FILE = "kokoro-v1.0.onnx"
+VOICES_FILE = "voices-v1.0.bin"
+
+
+def ensure_deps():
+    """Install kokoro-onnx if missing."""
+    try:
+        import kokoro_onnx  # noqa: F401
+    except ImportError:
+        import subprocess
+        print("[bridge] Installing kokoro-onnx...", file=sys.stderr)
+        subprocess.check_call(
+            [sys.executable, "-m", "pip", "install", "--user", "-q", "kokoro-onnx"],
+            stdout=sys.stderr,
+            stderr=sys.stderr,
+        )
+
+
+def download_file(url: str, dest: str):
+    """Download a file with progress."""
+    import urllib.request
+    filename = os.path.basename(dest)
+    print(f"[bridge] Downloading {filename}...", file=sys.stderr)
+    urllib.request.urlretrieve(url, dest)
+    size_mb = os.path.getsize(dest) / (1024 * 1024)
+    print(f"[bridge] Downloaded {filename} ({size_mb:.0f} MB)", file=sys.stderr)
+
+
+def download_model():
+    """Download Kokoro ONNX model + voices from GitHub releases. Returns (model_path, voices_path)."""
+    cache_dir = os.path.join(os.path.expanduser("~"), ".cache", "voice-soundboard")
+    os.makedirs(cache_dir, exist_ok=True)
+
+    model_path = os.path.join(cache_dir, MODEL_FILE)
+    voices_path = os.path.join(cache_dir, VOICES_FILE)
+
+    if not os.path.exists(model_path):
+        download_file(f"{GITHUB_RELEASE}/{MODEL_FILE}", model_path)
+
+    if not os.path.exists(voices_path):
+        download_file(f"{GITHUB_RELEASE}/{VOICES_FILE}", voices_path)
+
+    print(f"[bridge] Model ready: {model_path}", file=sys.stderr)
+    return model_path, voices_path
+
+
+def pcm_to_wav(samples, sample_rate: int) -> bytes:
+    """Convert float32 numpy array to WAV bytes."""
+    import numpy as np
+
+    # Clamp and convert to 16-bit PCM
+    pcm = np.clip(samples, -1.0, 1.0)
+    pcm = (pcm * 32767).astype(np.int16)
+    raw = pcm.tobytes()
+
+    # Build WAV header
+    buf = io.BytesIO()
+    num_channels = 1
+    bits_per_sample = 16
+    byte_rate = sample_rate * num_channels * bits_per_sample // 8
+    block_align = num_channels * bits_per_sample // 8
+    data_size = len(raw)
+
+    buf.write(b"RIFF")
+    buf.write(struct.pack("<I", 36 + data_size))
+    buf.write(b"WAVE")
+    buf.write(b"fmt ")
+    buf.write(struct.pack("<I", 16))
+    buf.write(struct.pack("<H", 1))  # PCM
+    buf.write(struct.pack("<H", num_channels))
+    buf.write(struct.pack("<I", sample_rate))
+    buf.write(struct.pack("<I", byte_rate))
+    buf.write(struct.pack("<H", block_align))
+    buf.write(struct.pack("<H", bits_per_sample))
+    buf.write(b"data")
+    buf.write(struct.pack("<I", data_size))
+    buf.write(raw)
+
+    return buf.getvalue()
+
+
+def main():
+    ensure_deps()
+
+    from kokoro_onnx import Kokoro
+
+    model_path, voices_path = download_model()
+    kokoro = Kokoro(model_path, voices_path)
+    available_voices = kokoro.get_voices()
+
+    print(f"[bridge] Ready — {len(available_voices)} voices available", file=sys.stderr)
+
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        req_id = msg.get("id")
+        op = msg.get("op")
+
+        if op == "health":
+            resp = {"id": req_id, "ok": True, "model": "kokoro-v1.1-onnx", "voices": len(available_voices)}
+            sys.stdout.write(json.dumps(resp) + "\n")
+            sys.stdout.flush()
+
+        elif op == "synthesize":
+            try:
+                text = msg.get("text", "")
+                voice = msg.get("voice", "af_bella")
+                speed = float(msg.get("speed", 1.0))
+                artifact_mode = msg.get("artifact_mode", "base64")
+
+                # Validate voice
+                if voice not in available_voices:
+                    # Try partial match
+                    matches = [v for v in available_voices if v.startswith(voice)]
+                    voice = matches[0] if matches else available_voices[0]
+
+                samples, sample_rate = kokoro.create(text, voice=voice, speed=speed)
+                wav_bytes = pcm_to_wav(samples, sample_rate)
+                duration_ms = int(len(samples) / sample_rate * 1000)
+
+                if artifact_mode == "base64":
+                    resp = {
+                        "id": req_id,
+                        "ok": True,
+                        "audio_bytes_base64": base64.b64encode(wav_bytes).decode(),
+                        "duration_ms": duration_ms,
+                        "sample_rate": sample_rate,
+                        "format": "wav",
+                    }
+                else:
+                    output_dir = msg.get("output_dir", os.path.join(os.path.expanduser("~"), ".voice-soundboard"))
+                    os.makedirs(output_dir, exist_ok=True)
+                    import uuid
+                    audio_path = os.path.join(output_dir, f"vsmcp_{uuid.uuid4().hex[:8]}.wav")
+                    with open(audio_path, "wb") as f:
+                        f.write(wav_bytes)
+                    resp = {
+                        "id": req_id,
+                        "ok": True,
+                        "audio_path": audio_path,
+                        "duration_ms": duration_ms,
+                        "sample_rate": sample_rate,
+                        "format": "wav",
+                    }
+
+                sys.stdout.write(json.dumps(resp) + "\n")
+                sys.stdout.flush()
+
+            except Exception as e:
+                resp = {
+                    "id": req_id,
+                    "ok": False,
+                    "error": {"code": "SYNTHESIS_FAILED", "message": str(e)},
+                }
+                sys.stdout.write(json.dumps(resp) + "\n")
+                sys.stdout.flush()
+
+        elif op == "interrupt":
+            resp = {"id": req_id, "ok": True}
+            sys.stdout.write(json.dumps(resp) + "\n")
+            sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

package/dist/backend.d.ts

@@ -0,0 +1,67 @@
+/** Backend interface, types, and mock implementation. */
+import type { SynthesisRequest } from "@mcptoolshop/voice-soundboard-core";
+export type BackendType = "mock" | "python" | "http" | "none";
+export interface SynthesisResult {
+    readonly audioPath?: string;
+    readonly audioBytesBase64?: string;
+    readonly durationMs: number;
+    readonly sampleRate: number;
+    readonly format: string;
+}
+export interface BackendHealth {
+    readonly ready: boolean;
+    readonly details?: string;
+}
+export interface Backend {
+    readonly type: BackendType;
+    readonly ready: boolean;
+    readonly model?: string;
+    readonly sampleRate?: number;
+    health(): Promise<BackendHealth>;
+    synthesize(request: SynthesisRequest): Promise<SynthesisResult>;
+    interrupt?(): Promise<void>;
+}
+export interface BackendConfig {
+    /** Explicit backend choice (--backend flag). */
+    backend?: BackendType;
+    /** HTTP backend URL (env: VOICE_SOUNDBOARD_TTS_URL). */
+    ttsUrl?: string;
+    /** HTTP backend auth token (env: VOICE_SOUNDBOARD_TTS_TOKEN). */
+    ttsToken?: string;
+    /** HTTP backend timeout in ms. */
+    httpTimeout?: number;
+    /** Python command (env: VOICE_SOUNDBOARD_PYTHON). */
+    pythonCommand?: string;
+    /** Python bridge module (env: VOICE_SOUNDBOARD_PYTHON_MODULE). */
+    pythonModule?: string;
+}
+/**
+ * Read backend config from CLI args and environment.
+ * CLI flags take precedence over env vars.
+ */
+export declare function readBackendConfig(argv: string[]): BackendConfig;
+/**
+ * Select and instantiate the appropriate backend.
+ *
+ * Priority:
+ * 1. Explicit --backend flag
+ * 2. VOICE_SOUNDBOARD_TTS_URL set → http
+ * 3. Python available → python
+ * 4. Fallback → none (or mock for dev)
+ */
+export declare function selectBackend(config: BackendConfig): Promise<Backend>;
+export declare class NoneBackend implements Backend {
+    readonly type: "none";
+    readonly ready = false;
+    health(): Promise<BackendHealth>;
+    synthesize(): Promise<SynthesisResult>;
+}
+export declare class MockBackend implements Backend {
+    readonly type: "mock";
+    readonly ready = true;
+    readonly model = "mock-silence";
+    readonly sampleRate = 24000;
+    health(): Promise<BackendHealth>;
+    synthesize(request: SynthesisRequest): Promise<SynthesisResult>;
+}
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA,yDAAyD;AAOzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAI3E,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IACjC,UAAU,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAChE,SAAS,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAID,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAqB/D;AAWD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAoD3E;AAID,qBAAa,WAAY,YAAW,OAAO;IACzC,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAChC,QAAQ,CAAC,KAAK,SAAS;IAEjB,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC;IAIhC,UAAU,IAAI,OAAO,CAAC,eAAe,CAAC;CAG7C;AAyCD,qBAAa,WAAY,YAAW,OAAO;IACzC,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAChC,QAAQ,CAAC,KAAK,QAAQ;IACtB,QAAQ,CAAC,KAAK,kBAAkB;IAChC,QAAQ,CAAC,UAAU,SAAS;IAEtB,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC;IAIhC,UAAU,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;CAwBtE"}