> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice CLI overview

> On-device speech: STT, TTS, and kiosk RAG on Linux edge hardware.

## Overview

The **`moorcheh-edge voice`** commands run **speech-to-text (Whisper)**, **text-to-speech (Piper)**, and a **voice RAG loop** on the same machine as Moorcheh Edge - for example an **Arduino UNO Q** with a USB mic and speaker.

<Note>
  Voice commands require **Linux** with ALSA audio. They are not supported on Windows or macOS. On a PC demo, use browser-based voice in your app instead.
</Note>

## Prerequisites

1. Moorcheh Edge running with RAG: `moorcheh-edge up --with-llm --warm-llm -y`
2. One-time voice setup: [`moorcheh-edge voice setup`](/cli/voice/setup)
3. Bluetooth speaker: [manual pairing guide](/cli/voice/bluetooth) (wired USB is configured by [`voice setup`](/cli/voice/setup))

For the **retail kiosk demo** (holding welcome audio + ambient thinking loop), see [Retail Kiosk](/examples/retail-kiosk#kiosk-audio-cache).

## Commands

| Command                               | Purpose                                                       |
| ------------------------------------- | ------------------------------------------------------------- |
| [`setup`](/cli/voice/setup)           | Install Whisper, Piper, whisper.cpp, and audio deps           |
| [`bluetooth`](/cli/voice/bluetooth)   | Manual Bluetooth speaker pairing + `audio.json`               |
| [`check`](/cli/voice/check)           | List ALSA devices and probe mic/speaker                       |
| [`listen`](/cli/voice/listen)         | Record from mic and print transcribed text                    |
| [`speak`](/cli/voice/speak)           | Synthesize and play text on the speaker                       |
| [`transcribe`](/cli/voice/transcribe) | Transcribe an existing WAV file                               |
| [`ask`](/cli/voice/ask)               | Record → RAG answer → speak (local kiosk loop)                |
| [`serve`](/cli/voice/serve)           | HTTP server on `:8766` for remote UIs (mic/speaker on device) |

## Typical workflow (UNO Q)

```bash theme={null}
source ~/moorcheh-venv/bin/activate
moorcheh-edge up --with-llm --warm-llm -y
moorcheh-edge voice setup
moorcheh-edge voice check
```

Terminal 1 - Moorcheh Edge (already running from `up`).

Terminal 2 - voice HTTP server for a remote display PC:

```bash theme={null}
moorcheh-edge voice serve --port 8766
```

Or test locally without HTTP:

```bash theme={null}
moorcheh-edge voice ask --kiosk-mode --query "What are your hours?"
```

When `speak: true` on [`/ask/stream`](/api-references/voice-serve#post-askstream), the server **streams answer tokens to the client immediately** and starts **TTS after the full answer** is ready (one Piper pass on the device speaker).

## HTTP API

When you run [`voice serve`](/cli/voice/serve), the CLI starts a small HTTP server (default **`http://0.0.0.0:8766`**) documented in [Voice server API](/api-references/voice-serve).

## Related

* [Arduino UNO Q](/guides/arduino-uno-q)
* [Retail Kiosk example](/examples/retail-kiosk)
* [CLI overview](/cli/introduction)