agent-tts

Why agent-tts

Your AI agents already write, build, deploy, and review. They should also talk — without stealing focus, without a Python venv, without paying ElevenLabs per token, without a shell-out from every tool.

# CLI
agent-tts "Build green in 12 seconds."
agent-tts --voice gabriel "Deploy concluído."   # cloned voice
agent-tts history --limit 10                    # persistent timeline
agent-tts pause; agent-tts resume; agent-tts replay 42

# MCP (Claude Code, Cursor, Cline) — 13 tools
claude mcp add agent-tts /opt/homebrew/bin/agent-tts mcp
# say · queue · skip · clear · voices · say_stream · pause · resume · replay · history
# synth_voice_test · voice_knob_search · tech_profile_search

	agent-tts	macOS say	Piper (Python)	ElevenLabs
Warm synth latency	~91 ms	n/a	200–300 ms	200–800 ms + network
Long-input first audio	~50 ms (v1.2 streaming)	n/a	full-input wait	full-input wait
MCP tool-call (Claude Code)	~1–3 ms warm	shell-out + permission	shell-out	network
Persistent queue + history	✅ SQLite WAL	❌	❌	❌
Pause / resume / replay	✅ (v1.10.2+)	❌	❌	❌
Voice cloning	✅ XTTS-v2 sidecar (v1.4+)	❌	bring-your-own	✅ (paid)
SSML prosody	✅ subset (v1.8+) incl. <phoneme> / <sub> (v1.10.12)	✅ [[ ]] only	❌	✅
Per-call Piper knobs	✅ length_scale / noise_scale / noise_w (v1.10.7)	❌	env-only	partial
Tech-report mode	✅ acronym + unit + brand glossary + CamelCase + URL/hash/version normalizer (v1.10.8 / v1.10.9)	❌	❌	❌
Audio post-fx pipeline	✅ ffmpeg RNNoise + EQ + de-esser + comp (v1.10.10)	❌	❌	partial
Cadence pipeline	✅ list-end drop + bullet lift + breathing splice (v1.10.12)	❌	❌	partial
Structured logging	✅ ISO 8601 file sink, rotating, scope/level filters (v1.10.13)	❌	❌	n/a
Streaming text input	✅ (v1.7+)	❌	manual	✅
Menubar app	✅ SwiftUI status item + floating player (v1.10 / v1.10.2)	❌	❌	❌
MCP server bundled	✅ stdio JSON-RPC, 13 tools	❌	❌	❌
Single binary	✅ ~1 MB	n/a	❌ Python venv	❌
Offline	✅	✅	✅	❌
Cost per message	$0	$0	$0	$$$

One KPI: time-to-first-audio

Everything is benchmarked against the gap between calling agent-tts "text" and the first audible sample.

Scenario	Target	Measured
Warm CLI ack round-trip	< 5 ms	0.2–0.4 ms
Warm daemon piper synth (short)	< 300 ms	~91 ms
Long-input first audio (streaming, v1.2)	< 200 ms	~50 ms
MCP warm tool-call (persistent process)	< 10 ms	~1–3 ms
First call after boot (cold)	< 800 ms	pre-warm 280 ms + zaudio 79 ms + piper 373 ms = ~720 ms

Built for AI agents

MCP server bundled

agent-tts mcp — stdio JSON-RPC. 13 tools: say, queue, skip, clear, voices, say_stream, pause, resume, replay, history, synth_voice_test, voice_knob_search, tech_profile_search. Drop-in for Claude Code / Cursor / Cline. Read →

Streaming input

agent-tts stream reads stdin and emits sentences as terminators arrive. MCP say_stream(stream_id, chunk, final?) matches the LLM delta shape. Hear the agent before it finishes thinking.

Voice cloning

Record 30–90 seconds via the menubar window with a guided Pt-BR script. XTTS-v2 sidecar produces an embedding.npz. Use it from any client via --voice <slug>.

History + pause/resume/replay

SQLite WAL keeps every utterance. Pause mid-playback, resume from the same cursor, replay any past item by id. CLI + MCP + menubar all hit the same ops.

Menubar floating player

macOS NSStatusItem + floating NSPanel. Skip / Replay / voice picker — without opening a terminal. Read →

SSML & prosody

W3C SSML 1.1 subset: <emphasis>, <break>, <prosody>, <say-as>, plus <phoneme alphabet="ipa"> and <sub alias="…"> (v1.10.12) for brand-name IPA and code-identifier substitution. Parse < 0.2 µs / 280 chars. Read →

Tech-report mode

--profile tech ships research-anchored Faber knobs (length=1.05 / noise=0.35 / noise_w=0.45) plus an ~80-entry acronym + unit + brand glossary, a CamelCase splitter and a version/commit-hash/URL/path/hex normalizer. tech_profile_search MCP tool A/Bs four bundles in one round-trip (v1.10.8 / v1.10.9).

Audio post-fx pipeline

--postfx clean|tech|broadcast spawns ffmpeg with RNNoise + 4-band EQ + de-esser + 2:1 compressor between piper and zaudio. Per-chunk; falls back to dry PCM if ffmpeg or the RNNoise model is missing. postfx_ms logged per chunk (v1.10.10).

Per-call Piper knobs

--length-scale / --noise-scale / --noise-w flags + matching MCP say params. No daemon restart for A/B. synth_voice_test and voice_knob_search MCP tools batch up to 16 variants in one call (v1.10.7 / v1.10.8).

Structured logging

~/.cache/agent-tts/daemon.log with ISO 8601 lines, rotating at 10 MiB × 3 backups. AGENT_TTS_LOG_LEVEL / _SCOPES / _PATH / _MAX_BYTES filter without rebuild. Worker watchdog kills hung ffmpeg, defer finishPlaying keeps the queue advancing (v1.10.13).

Locked constraints

• Platform: macOS Apple Silicon + Intel universal binary. Linux code paths compile on ubuntu-latest CI (espeak-ng + systemd); v1.3 ships structurally, runtime testing in flight.
• Footprint: single ~1 MB binary (zig build). Piper voice ONNX (~63 MB) and XTTS-v2 (~1.8 GB) are opt-in downloads to ~/.cache/agent-tts/.
• Architecture: CLI + daemon + MCP + menubar all share the binary or the same UNIX socket protocol.
• Pt-BR human cadence: cardinals, abbreviations, and punctuation pauses preprocessed in 2–5 µs.
• Offline by default: no cloud, no telemetry, no quota. Voice models cached locally.

License

Dual MIT OR Apache-2.0 for the agent-tts source. GPL-3.0-or-later inherits when you build with -Dwith-piper=true (libpiper is GPL). The XTTS sidecar runs out-of-process so MPL-2.0 (Coqui TTS) stays at the process line.

Stay in sync

Living project. Eighteen base + thirteen patch milestones already shipped (current head v1.10.13) — see the Roadmap and Changelog for the full timeline. The current state of every feature lives in Architecture, TTS engine, MCP server, Menubar UI, and Playground.

PRs welcome at biliboss/agent-tts. Vote with stars + issues tagged roadmap to push priority.