From the repository root with Python 3.11+:
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m unittest discover -s tests -vDependency installation needs package access. The test suite itself uses local WebSocket servers, test credentials, temporary homes, and mocked or substituted playback/process boundaries. It does not require a paid provider account.
When mpv is installed, the suite also exercises its real demuxer/player using null or file output. Those checks include resumed PCM after an underrun while stdin remains open. They are skipped without mpv and do not test physical audio hardware. Installing mpv locally gives broader coverage than mock playback alone.
The Offline tests workflow runs this suite on Linux. Its configured Python matrix is the source of truth for CI coverage. An offline pass does not validate live provider schemas or audible output.
requirements.txt is the single source of exact Python dependency pins for both
CI and install.py, including validation of an external --venv. Dependabot
opens weekly updates for Python dependencies and GitHub Actions; updates still
need review and passing tests. See automatic releases for the
main-branch versioning, native-package checks, and recovery procedure.
| Path | Responsibility |
|---|---|
src/streaming.py |
ElevenLabs protocol and shared stdin/playback/lifecycle helpers. |
src/cartesia_streaming.py |
Cartesia context and audio protocol. |
src/tts_config.py |
Non-secret provider selection. |
src/speech_text.py |
Completed-text Markdown parsing, speech rendering, bounds, and Dispatcher submission. |
bin/tts-*-stream |
Installed Python environment entry points. |
bin/tts-cartesia, bin/tts-elevenlabs |
Speech Dispatcher job adapters. |
bin/speak-*, bin/speech-*, bin/stop-speech |
Desktop and control commands. |
config/speech-dispatcher/ |
User-installed generic module templates. |
install.py |
User-local installation, update, backup, and removal. |
packaging/ |
Native Linux packages and disposable install/remove validation. |
scripts/release.py, release.json |
Deterministic versions, archives, checksums, and GitHub publication. |
tests/ |
Protocol, process, configuration, and installation checks. |
The public command layout retains the name opencode-tts for compatibility.
The implementation is usable without OpenCode.
- Audio can be delivered to the player before the producer reaches EOF.
- UTF-8 characters and words survive arbitrary pipe/delta boundaries.
- Concatenated provider input preserves the intended text without duplication.
- Completion, provider errors, cancellation, and context expiry cannot silently discard an unread input tail or replay an already-submitted prefix.
- Stop interrupts connection attempts and lock waits as well as active playback; older queued work stays cancelled.
- Helper exit cleans up its player, tasks, PID registration, and IPC socket.
- Credentials, private text, and raw provider payloads stay out of diagnostics.
- Clipboard cleanup preserves prose/code content, paragraph boundaries and table order at the actual Dispatcher boundary; hidden destinations are removed before the spoken-character cap. The parser comparison documents the dependency choice and targeted edge cases.
- Installation and removal operate inside isolated homes and preserve unrelated configuration and preexisting files.
Prefer assertions at observable boundaries—frames sent, PCM received, child lifetime, exit status, and preserved files—over tests that mirror implementation details. See release requirements for the intended contract.
Only perform live synthesis with an account you are authorized to use, a known small text sample, and an explicit quota budget. A useful manual check records:
- Commit, provider/model/voice, platform, and whether output was actually heard.
- A short completed-text request and an incremental request with an open stdin.
- Full audible ending after EOF, without final-message replay.
- Stop during generation/playback, queued-stop behavior, and a later new job.
- Live faster/slower/reset controls and the optional Dispatcher/clipboard path.
- For OpenCode, the plugin revision and absence of child-session narration.
Report observed results, not a generic “works” claim. Do not commit transcripts, account identifiers, credentials, recordings, or private workstation logs. Simulate quota and authentication failures locally rather than consuming quota or deliberately breaking a live account.
Before a release, also check README examples against the installed commands, verify install/update/uninstall in a temporary home, and inspect the staged diff for accidental personal paths or private files. CI status and live validation are different evidence and should be reported separately.