pi-mimo-voice

🇨🇳 中文文档

Voice input (STT) and output (TTS) for pi powered by Xiaomi MiMo V2.5 API.

🔊 Please turn on sound for the demo below

https://github.com/user-attachments/assets/9a9f9984-9476-4c4e-bbeb-ae088a7d875c

Features

• 🎤 Speech-to-Text (STT) — Record audio from microphone and transcribe
• 🔊 Text-to-Speech (TTS) — Speak text aloud through speakers
• 🗣️ Auto-speak — Automatically read all assistant replies
• 🎙️ Live mode — Continuous voice conversation loop
• 🎛️ Interactive config — Voice, model, engine, and region settings

Installation

# Install from npm
pi install npm:@wenjinnn/pi-mimo-voice

# Or install from GitHub
pi install git:github.com/wenjinnn/pi-mimo-voice

# Or clone manually
cd ~/.pi/agent/extensions
git clone https://github.com/wenjinnn/pi-mimo-voice.git

Quick Start

# 1. Set API key (via environment variable or pi /login)
export XIAOMI_TOKEN_PLAN_CN_API_KEY="your-key"  # China region
# Or: export XIAOMI_API_KEY="your-key"          # Global

# 2. Restart pi or /reload

# 3. Try it
/speak Hello from MiMo!
/listen
/listen stop

Commands

Text-to-Speech

| Command | Description | |---------|-------------| | /speak <text> | Speak text aloud using MiMo TTS |

Speech-to-Text

| Command | Description | |---------|-------------| | /listen | Start recording (manual stop with /listen stop) | | /listen stop | Stop recording and transcribe | | /listen auto-stop N | Record for N seconds then transcribe | | /listen N | Record for N seconds (max 60) then transcribe |

Auto-speak & Live Mode

| Command | Description | |---------|-------------| | /auto-speak | Toggle auto-speak (read all assistant replies). Use /auto-speak on\|off for explicit control | | /live | Start/stop live voice mode (auto-speak ON, begins recording) | | /live reply | Stop recording, transcribe, and send to LLM |

Live mode flow:

1. /live → recording starts
2. Speak when ready
3. /live reply → transcribes and sends
4. AI responds → auto-speak reads it → next recording starts
5. Repeat from step 2
6. /live to stop

Configuration

| Command | Description | |---------|-------------| | /voice-config | Interactive settings: voice, TTS model, STT engine, API region |

LLM Tools

When installed, the LLM can call these tools directly:

mimo_tts

Convert text to speech. Parameters:

• text (required) — Text to speak
• style (optional) — Style instruction (e.g., "excited", "calm", "东北话")

mimo_stt

Record and transcribe speech. Parameters:

• duration (optional) — Recording duration in seconds (default: 10, max: 60)
• auto_stop (optional) — Auto-stop when silence detected (default: false)

Voices

Preset Voices

| Voice | ID | Language | Gender | |-------|-----|----------|--------| | Default | mimo_default | auto | auto | | 冰糖 | 冰糖 | zh | female | | 茉莉 | 茉莉 | zh | female | | 苏打 | 苏打 | zh | male | | 白桦 | 白桦 | zh | male | | Mia | Mia | en | female | | Chloe | Chloe | en | female | | Milo | Milo | en | male | | Dean | Dean | en | male |

TTS Models

| Model | Description | |-------|-------------| | mimo-v2.5-tts | Preset voices (default) | | mimo-v2.5-tts-voicedesign | Custom voice via text description | | mimo-v2.5-tts-voiceclone | Clone voice from audio sample |

API Configuration

The extension auto-detects the API region from your pi auth.json provider:

| Provider | auth.json Key | Environment Variable | Region | |----------|---------------|---------------------|--------| | Xiaomi MiMo | xiaomi | XIAOMI_API_KEY | Global | | Token Plan CN | xiaomi-token-plan-cn | XIAOMI_TOKEN_PLAN_CN_API_KEY | China | | Token Plan AMS | xiaomi-token-plan-ams | XIAOMI_TOKEN_PLAN_AMS_API_KEY | Amsterdam | | Token Plan SGP | xiaomi-token-plan-sgp | XIAOMI_TOKEN_PLAN_SGP_API_KEY | Singapore |

Setup Options

Option 1: Environment Variable

export XIAOMI_TOKEN_PLAN_CN_API_KEY="your-key"

Option 2: pi /login

/login  → Select provider → Enter API key

Option 3: auth.json

{
  "xiaomi-token-plan-cn": { "type": "api_key", "key": "your-key" }
}

See pi providers docs for more details.

Requirements

• Node.js ≥ 18
• MiMo API key — configured via pi /login or environment variable (see API Configuration)
• ffmpeg — for audio recording and playback (cross-platform)

Platform-Specific Audio Tools

| Platform | Recording | Playback (priority order) | |----------|-----------|--------------------------| | Linux | parecord (PulseAudio) → ffmpeg | paplay → aplay → ffplay → mpv | | macOS | ffmpeg + avfoundation | afplay (built-in) → ffplay → mpv | | Windows | ffmpeg + dshow | ffplay → mpv |

Linux: PulseAudio is recommended (parecord/paplay). ALSA (aplay) also works for playback.

macOS: No extra tools needed — afplay is built-in, ffmpeg handles recording via avfoundation.

Windows: Install ffmpeg and ensure it's in PATH. Default recording device is audio=麦克风, override with MIC_DEVICE env var.

⚠️ Cross-platform note: macOS and Windows support is based on ffmpeg's platform-specific audio backends (avfoundation/dshow) but has not been fully tested on real hardware. Linux is the primary tested platform. If you encounter issues on macOS or Windows, please open an issue — feedback and contributions are very welcome!

Environment Variables

| Variable | Description | |----------|-------------| | MIC_DEVICE | Override audio recording device (all platforms) | | WHISPER_MODEL | Path to whisper.cpp model file |

npm Dependencies

The following dependencies are provided by pi automatically:

• @earendil-works/pi-coding-agent — pi extension API
• @earendil-works/pi-tui — pi TUI components
• typebox — type validation

Optional

• whisper.cpp — for local STT (faster, no API calls)
  • Set path: /voice-config → Whisper.cpp Path
  • Download model: whisper-cpp-download-ggml-model base

How It Works

TTS Flow

Text → MiMo TTS API → WAV audio → paplay/aplay/ffplay/mpv

STT Flow

Microphone → parecord/ffmpeg → WAV file → whisper.cpp or MiMo API → Text

Live Mode Flow

/live → Start recording
User speaks
/live reply → Stop recording → Transcribe → Send to LLM
LLM responds → Auto-speak reads response
Auto-start next recording

Feedback & Contributing

This project is actively maintained. If you have questions, bug reports, or feature requests:

• 🐛 Open an issue
• 🔀 Submit a pull request
• 💬 Share your experience and suggestions

Contributions of any kind are welcome!

License

MIT