voice

Category: Tools & Productivity | Uploader: rgbkrk | Downloads: 0 | Version: v1.0（Latest）

`voice` speaks text aloud using Kokoro TTS and transcribes speech using Moonshine STT on Apple Silicon. Use it to talk to your user, listen for their response, or run a full voice conversation loop.

Changelog: Source: GitHub https://github.com/rgbkrk/voice

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 1.2 KB
📁 crates/
- 📁 voice-cli/
  - 📁 src/
    
    📄 jsonrpc.rs 22.7 KB
    
    📄 listen.rs 38.4 KB
    
    📄 main.rs 24.5 KB
  - 📁 tests/
    
    📄 jsonrpc_protocol.rs 14.6 KB
  - 📄 build.rs 6.9 KB
  - 📄 Cargo.toml 669 B
  - 📄 README.md 2.7 KB
- 📁 voice-dsp/
  - 📁 src/
    
    📄 lib.rs 17.8 KB
  - 📄 Cargo.toml 267 B
  - 📄 README.md 1.1 KB
- 📁 voice-g2p/
  - 📁 data/
    
    📁 tagger/
    
    📄 classes.txt 149 B
    
    📄 tags.json 25.2 KB
    
    📄 weights.json 132 B
    
    📄 us_gold.json 2.9 MB
    
    📄 us_silver.json 3.0 MB
  - 📁 src/
    
    📄 espeak.rs 8.6 KB
    
    📄 lexicon.rs 45.3 KB
    
    📄 lib.rs 21.7 KB
    
    📄 number.rs 8.4 KB
    
    📄 stress.rs 10.4 KB
    
    📄 tagger.rs 9.7 KB
    
    📄 token.rs 8.4 KB
    
    📄 tokenizer.rs 33.5 KB
  - 📄 build.rs 2.3 KB
  - 📄 Cargo.toml 389 B
  - 📄 README.md 1.7 KB
- 📁 voice-nn/
  - 📁 src/
    
    📁 vocoder/
    
    📄 decoder.rs 11.4 KB
    
    📄 generator.rs 10.0 KB
    
    📄 mod.rs 52 B
    
    📄 source.rs 12.8 KB
    
    📄 ada_norm.rs 5.9 KB
    
    📄 albert.rs 16.9 KB
    
    📄 conv_weighted.rs 6.1 KB
    
    📄 lib.rs 127 B
    
    📄 lstm.rs 4.7 KB
    
    📄 prosody.rs 13.6 KB
    
    📄 text_encoder.rs 4.9 KB
  - 📄 Cargo.toml 399 B
  - 📄 README.md 1.1 KB
- 📁 voice-stt/
  - 📁 data/
    
    📄 moonshine_tiny_config.json 897 B
    
    📄 moonshine_tiny_tokenizer.json 132 B
  - 📁 examples/
    
    📄 transcribe.rs 3.4 KB
  - 📁 src/
    
    📁 moonshine/
    
    📄 config.rs 8.0 KB
    
    📄 mod.rs 1.2 KB
    
    📄 model.rs 34.2 KB
    
    📄 builtin.rs 3.8 KB
    
    📄 error.rs 635 B
    
    📄 lib.rs 19.0 KB
  - 📄 build.rs 2.3 KB
  - 📄 Cargo.toml 500 B
  - 📄 README.md 3.1 KB
- 📁 voice-tts/
  - 📁 data/
    
    📁 voices/
    
    📄 af_bella.safetensors 131 B
    
    📄 af_heart.safetensors 131 B
    
    📄 af_sarah.safetensors 131 B
    
    📄 af_sky.safetensors 131 B
    
    📄 am_adam.safetensors 131 B
    
    📄 am_michael.safetensors 131 B
    
    📄 bf_emma.safetensors 131 B
    
    📄 config.json 2.3 KB
  - 📁 src/
    
    📄 builtin.rs 3.1 KB
    
    📄 config.rs 988 B
    
    📄 error.rs 503 B
    
    📄 lib.rs 2.0 KB
    
    📄 model.rs 8.1 KB
    
    📄 voice.rs 1.4 KB
    
    📄 weights.rs 13.9 KB
  - 📁 tests/
    
    📄 istft_roundtrip.rs 3.1 KB
  - 📄 build.rs 2.7 KB
  - 📄 Cargo.toml 539 B
  - 📄 README.md 1.6 KB
📁 examples/
- 📄 conversation.py 5.9 KB
📁 notebooks/
- 📄 g2p_test_harness.ipynb 11.2 KB
- 📄 stt_comparison.ipynb 8.9 KB
- 📄 vocoder_comparison.ipynb 40.3 KB
📁 tests/
- 📄 spacy_compare.py 7.7 KB
📄 .gitattributes 245 B
📄 .gitignore 29 B
📄 AGENTS.md 5.2 KB
📄 Cargo.lock 107.1 KB
📄 Cargo.toml 50 B
📄 CLAUDE.md 9 B
📄 LICENSE 1.0 KB
📄 README.md 13.2 KB
📄 SKILL.md 4.3 KB
📄 transcript.txt 187 B

SKILL.md

# voice — TTS & STT tool for AI agents

`voice` speaks text aloud using Kokoro TTS and transcribes speech using Moonshine STT on Apple Silicon. Use it to talk to your user, listen for their response, or run a full voice conversation loop.

## Quick reference

### Speak (TTS)

```bash
# Speak text (backward compatible — no subcommand needed)
voice Hello, I finished the task.

# Explicit say subcommand with options
voice say -v am_michael "Switching to a male voice."

# Speak from a pipe
echo "Build complete." | voice say

# Read a file aloud (strip markdown first)
voice say --markdown -f README.md

# Save to WAV instead of playing
voice say -o result.wav "Here is your audio."

# Precise pronunciation via IPA phonemes
voice say --phonemes "həlˈO wˈɜɹld"
```

### Listen (STT)

```bash
# Record from mic, transcribe on Enter/Ctrl+C
voice listen

# Continuous mode — transcribe segments as you speak, split on silence
voice listen --continuous

# Transcribe a WAV file
voice transcribe recording.wav
```

### JSON-RPC server

```bash
# Start the server (for programmatic control)
voice serve -v am_michael
```

```jsonl
# Speak
→ {"jsonrpc":"2.0","method":"speak","params":{"text":"Hello"},"id":1}
← {"jsonrpc":"2.0","result":{"duration_ms":1800,"chunks":1},"id":1}

# Listen (ding plays, records, auto-stops on silence)
→ {"jsonrpc":"2.0","method":"listen","id":2}
← {"jsonrpc":"2.0","result":{"text":"I heard you","tokens":4,"duration_ms":3200},"id":2}

# Cancel current playback or recording
→ {"jsonrpc":"2.0","method":"cancel","id":3}

# Other methods: set_voice, set_speed, list_voices, ping
```

## When to use

- **Get attention**: Speak when a long task finishes, a build fails, or you need input
- **Read content**: Pipe text through `voice say` to read back docs, errors, or summaries
- **Confirm actions**: "Deploying to production" before doing something irreversible
- **Listen for input**: Use `voice listen` to capture a spoken response from the user
- **Voice conversation**: Use `voice serve` with JSON-RPC to alternate between speaking and listening
- **Transcribe recordings**: Use `voice transcribe` to convert audio files to text

## Tips

### TTS tips

- Use `-q` for quiet mode — suppresses phonemes and progress, only errors print
- For long text, `voice` automatically chunks at ~510 phonemes and streams playback
- Stderr shows phoneme output — useful for debugging pronunciation
- Use `--sub word=replacement` to fix names: `voice say --sub kubectl=cube-cuddle "Restarting kubectl"`
- A `.voice-subs` file in the project root is auto-discovered for persistent fixes
- Wrap substitution values in `/slashes/` for raw phoneme overrides: `Kokoro=/kˈOkəɹO/`

### STT tips

- A ding sound plays when the mic is ready — wait for it before speaking
- Bluetooth mics (AirPods) have ~0.5s latency; the ding helps you time it
- Noise floor is calibrated automatically — works with MacBook mic or AirPods
- Use `STT_MODEL=UsefulSensors/moonshine-tiny` for faster (but less accurate) transcription
- Default model is `moonshine-base` (61M params, ~50× real-time on Apple Silicon)

### JSON-RPC tips

- `voice serve` loads the TTS model at startup; STT model loads lazily on first `listen`
- `cancel` interrupts the current speak or listen mid-operation
- `speak` supports per-request `voice` and `speed` overrides without changing defaults
- `listen` params are tunable: `noise_multiplier`, `calibration_ms`, `silence_timeout_ms`
- Notifications (requests without `id`) are fire-and-forget — no response returned

## Subcommands

| Command | What it does |
|---------|-------------|
| `voice <text>` | Speak text (implicit `say`, backward compatible) |
| `voice say` | Speak text with full TTS options |
| `voice listen` | Record from mic, transcribe once |
| `voice listen --continuous` | Record and transcribe segments continuously |
| `voice transcribe <file>` | Transcribe a WAV file |
| `voice serve` | Start JSON-RPC server on stdin/stdout |

## Builtin voices (no network)

`af_heart` (default), `af_bella`, `af_sarah`, `af_sky`, `am_michael`, `am_adam`, `bf_emma`

## Install

```bash
git clone https://github.com/rgbkrk/voice.git
cd voice
cargo install --path crates/voice-cli
```

Requires macOS with Apple Silicon, Git LFS, and Rust 1.85+. TTS model weights download on first `voice say` (~312MB, cached). STT model weights download on first `voice listen` (~246MB, cached).

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

voice

Directory Structure

SKILL.md

Report

Notice