speak_skill

Overview

This skill gives your agent real-time local text-to-speech on Apple Silicon. It converts agent text to streamed or saved audio, supports voice cloning, emotion tags, batch processing, and runs entirely on-device via MLX with no API keys. Use it from the CLI to play, save, or concatenate generated audio files.

How this skill works

The skill runs a local TTS server that generates WAV audio using Chatterbox models optimized for Apple Silicon. You can stream output as it is generated, play after generation, or save files to a configurable output directory. Voice cloning uses a short WAV sample (24000 Hz, mono, 10–30s) to approximate a custom voice; auto-chunking splits long texts and reassembles final outputs.

When to use it

• Read articles, docs, or clipboard text aloud with streaming playback.
• Produce narrated audiobooks or multi-voice podcasts using batch and concat features.
• Create voice responses for an assistant without sending data to external APIs.
• Quickly preview TTS results or estimate generation time and storage before long runs.
• Resume interrupted long-generation jobs or skip already-processed files.

Best practices

• Run on Apple Silicon macOS 12+—Intel is not supported.
• Prepare voice samples as WAV, 24000 Hz, mono, 15–25 seconds for best cloning quality.
• Create required directories (e.g., ~/.chatter/voices/ and ~/Audio/custom/) before using custom paths.
• Use --auto-chunk for large documents and --skip-existing for safe retries.
• Zero-pad filenames (01, 02, 03) before concatenation to preserve order.

Example use cases

• Stream an article from the web to listen while working: lynx -dump URL | speak --stream
• Generate an audiobook: pdftotext chapters -> speak ch01.txt ch02.txt --output-dir audiobook/ --auto-chunk
• Clone your voice for personalized narration: record, convert to required WAV, then speak notes.txt --voice ~/.chatter/voices/my_voice.wav --output file.wav
• Produce a two-voice podcast: render host and guest separately with different voice samples and then speak concat them into a final mix.
• Estimate runtime and storage for a long project using speak --estimate ch*.txt