Skip to content

opencode.md

Latest commit

 

History

History
110 lines (85 loc) · 4.75 KB

opencode.md

File metadata and controls

110 lines (85 loc) · 4.75 KB
Raw

OpenCode integration

Back to README

Speech Stream supplies the TTS command. The separate opencode-talk plugin chooses which assistant text to narrate and invokes that command on the machine running the OpenCode server.

Status

Live incremental narration is proposed in hdlopesrocha/opencode-talk#3. As of November 5, 2026, it is not merged. The settings below require a plugin revision containing that proposal; the upstream default branch or an older installation may only narrate completed text.

Speech Stream does not install, patch, or enable the plugin. Follow the plugin's own installation instructions for a compatible revision. OpenCode V2's plugin guide describes loading local or packaged plugins; plugin compatibility is separate from this backend's installation.

Enable live stdin narration

First check that tts-stream works in the same user session as the OpenCode server. Then merge the following fields into the plugin's ~/.config/opencode/voice.json, preserving any other voice or recording settings:

{
  "tts": true,
  "ttsEngine": "command",
  "ttsCommand": "\"$HOME/.local/bin/tts-stream\"",
  "ttsStreaming": true,
  "ttsAuto": false,
  "ttsReasoning": false,
  "ttsMaxChars": 10000
}

This is the plugin's configuration file, not OpenCode's opencode.json or Speech Stream's tts.json. The command is executed by the plugin's shell; quoting $HOME keeps the executable path intact even if it contains spaces. The backend selects the provider and voice using its own configuration.

For a native pacman, Debian, or RPM installation, use "ttsCommand": "/usr/bin/tts-stream" instead.

The plugin also exposes OPENCODE_VOICE_TTS_STREAMING=1, but explicit voice.json settings take precedence. A backend credential file is usually simpler than relying on a long-running server inheriting a shell's environment.

The plugin's default character limit is smaller than the backend's limit. Setting ttsMaxChars to 10,000 avoids that default truncating ordinary long responses early; disabling the plugin cap does not disable the backend cap.

Streaming contract

In the proposed integration:

  • Assistant text deltas from the main/root session feed one queued child per text part. Child/subagent session text is filtered out.
  • The plugin holds incomplete words and Markdown constructs, removes markup, and flushes the remaining prose when the part ends.
  • The final event closes stdin rather than replaying the full response.
  • Tool output is not narrated. Reasoning is off by default and, if enabled, follows the plugin's completed-part path.
  • Queue cancellation and the OPENCODE_TTS_QUEUED_AT_MS timestamp cooperate with the backend's global stop marker.

Child sessions are silent by default. When creating a reviewer or other helper through the OpenCode API, pass its actual parentID in POST /api/session. Omitting it creates an independent root conversation, which is eligible for narration regardless of the session's title or purpose.

Use a command that reads stdin, not a {text} placeholder. Do not put speak-text on the live path: it waits for EOF. A buffering command remains buffered even with ttsStreaming enabled.

Speech Stream does not interpret the plugin's edge-tts voice names. Set provider voice IDs in backend configuration. There is no automatic cloud-provider fallback in this backend.

Check and control

The plugin provides /sound status, /sound on, /sound pause, and /sound off. Pause silences the current queue while leaving narration enabled; off also disables future narration. The standalone stop-speech command can be bound to a desktop key.

To check the integration, request a short, harmless multi-sentence answer and observe whether speech starts while the text is still arriving. Check that the ending is spoken once and that stopping does not release older queued speech afterward. This uses provider quota.

If a direct pipe works but OpenCode does not, check the loaded plugin revision, the selected engine and command, the plugin's narration switch, and the server's user/environment. A remote OpenCode server plays audio on its own host, not automatically through the web or desktop client.

Disable or revert

Set ttsStreaming to false to return to completed-part narration. To keep Speech Stream for that mode, leave ttsCommand pointing at tts-stream. Use /sound off or set tts to false to disable narration altogether.

Before uninstalling Speech Stream, restore your previous plugin command or disable its TTS. Remove only the settings you added; do not replace the whole voice configuration file.