OpenCode TTS Plugin

Simple TTS for OpenCode using Kokoro TTS.

Status

Experimental. This plugin is still in testing. For now, it is intended for power users only - I need feedback. Confirmed working on TUI, unsure about the other flavours.

Features

• Speaks assistant responses in message or idle mode
• Local CPU or HTTP GPU backend
• Toggle via /tts-on and /tts-off
• Switch profiles via /tts-profile <name>
• Cross-platform playback
• 11 voice options

TTS only runs for main sessions. Child/subagent sessions are ignored. Messages do not overlap; a new message cuts off the previous audio.

Quick Start

Local CPU Mode (Default - zero config)

TTS starts disabled by default. Enable it with /tts-on once the plugin is loaded.

Add the path manually to your opencode.json, pointing at wherever you copied the plugin:

{
  "plugin": ["file:///home/igorw/Work/opencode/.opencode/plugin/tts-reader/src/index.ts"]
}

The built-in slash commands are registered directly by the plugin at startup.

On first use, the plugin downloads the Kokoro TTS model (~87MB). You'll see a toast notification when ready.

GPU Mode (Faster)

1. Start the Kokoro-FastAPI server with GPU:

# NVIDIA GPU (CUDA)
docker run -d --gpus all -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-gpu:latest

# CPU fallback (no GPU)
docker run -d -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest

2. Configure the plugin to use HTTP backend by editing ~/.config/opencode/tts.jsonc or switching profiles:

/tts-profile kokoro-gpu

Requirements

System Compatibility

• Linux - Tested on Omarchy
• macOS - Should work (afplay built-in)
• Windows - Should work (PowerShell built-in, ffmpeg recommended)

Audio Player

The plugin uses cascading fallbacks to find an available audio player. It tries OS-bundled tools first, then common third-party options:

Linux (tried in order):

1. ffplay (from ffmpeg - most compatible with HTTP engine)
2. mpv (if installed)
3. paplay (PulseAudio)
4. aplay (ALSA)

macOS (tried in order):

1. ffplay (from ffmpeg)
2. afplay (built-in)

Windows (tried in order):

1. ffplay (from ffmpeg - recommended for HTTP engine)
2. Media.SoundPlayer (PowerShell built-in - strict WAV format)
3. wmplayer (Windows Media Player - if installed)

Note on HTTP/GPU mode: The HTTP engine returns WAV files that may not play with Windows' built-in Media.SoundPlayer. Installing ffmpeg is strongly recommended for Windows users using the HTTP backend.

Installation:

• macOS: brew install ffmpeg
• Windows: winget install ffmpeg (or winget install ffmpeg.Gyan)
• Linux: sudo apt install ffmpeg

For HTTP/GPU Mode

• Docker with NVIDIA GPU support (nvidia-docker2)
• Or any machine running Kokoro-FastAPI (can be remote)

Configuration

Defaults are stored at ~/.config/opencode/tts.jsonc on first run. Edit that file to customize profiles and settings.

Profile Switching

You can switch between defined profiles at runtime using the /tts-profile command:

/tts-profile openai
/tts-profile kokoro-gpu

The slash command templates are embedded in the plugin. The markdown files in command/ are kept as a human-readable reference.

Security Considerations

• Trusted Backends: The plugin sends text data to the configured httpUrl. Ensure you trust the backend server, especially when using remote APIs.
• Provider Options: The providerOptions field in profiles allows passing raw JSON to the backend. These are passed without validation and can override core fields like model or voice.
• Authentication: Use httpHeaders to securely pass API keys or Bearer tokens to remote providers.

Config Format (JSONC)

// OpenCode TTS Reader configuration (JSONC)
{
  // Active profile name from the "profiles" object below
  "activeProfile": "default",
  // Enable/disable TTS at startup
  "enabled": false,
  // "message" (each response) or "idle" (session idle)
  "speakOn": "message",
  // Fallback to local (CPU) backend if HTTP fails
  "fallbackToLocal": true,
  // Max local worker processes (0 disables pool)
  "maxWorkers": 2,

  "profiles": {
    "default": {
      "backend": "local",
      "voice": "af_heart",
      "speed": 1.0
    },
    "kokoro-gpu": {
      "backend": "kokoro",
      "httpUrl": "http://localhost:8880",
      "voice": "af_heart",
      "speed": 1.0,
      "httpFormat": "wav"
    }
  }
}

Available Commands

• /tts-on: Enable the reader
• /tts-off: Disable the reader
• /tts-profile <name>: Switch to a different backend/voice profile
• /tts toggle: Invert the current state (default)
• /tts profile <name>: Alternative syntax for profiles (if /tts command file is present)