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

# Voice mode

> Talk to Headmaster with your voice and hear responses spoken aloud — powered by local or cloud STT and a choice of TTS providers.

# Voice mode

Headmaster supports real-time voice interaction — talk to the agent with your voice and hear responses spoken aloud.

***

## How it works

The full voice cycle:

<Steps>
  <Step title="You speak">
    Click the microphone icon in the chat composer to start recording.
  </Step>

  <Step title="STT transcribes">
    Your speech is converted to text by either a local faster-whisper model or OpenAI Whisper.
  </Step>

  <Step title="Agent processes">
    The transcribed text is sent as a message to the agent, which generates a response.
  </Step>

  <Step title="TTS speaks">
    The agent's text response is converted to speech audio and played back through your speakers.
  </Step>
</Steps>

***

## Enabling voice mode

<Steps>
  <Step title="Open Voice settings">
    Go to **Settings → My Headmaster → Look → Voice**.
  </Step>

  <Step title="Turn on voice mode">
    Enable **Enable voice mode**.
  </Step>

  <Step title="Choose a TTS provider">
    Pick a provider and voice from the dropdown.
  </Step>

  <Step title="Choose an STT backend">
    Select local faster-whisper (no API key) or OpenAI Whisper (requires key).
  </Step>

  <Step title="Save">
    Click Save. Voice mode is ready in your next message.
  </Step>
</Steps>

***

## Providers

<Tabs>
  <Tab title="TTS providers">
    | Provider       | Voices                                  | Notes                                       |
    | -------------- | --------------------------------------- | ------------------------------------------- |
    | **OpenAI**     | Alloy, Echo, Fable, Onyx, Nova, Shimmer | Natural, high quality. Requires OpenAI key. |
    | **xAI**        | Various                                 | Requires xAI key.                           |
    | **MiniMax**    | Various                                 | Requires MiniMax key.                       |
    | **ElevenLabs** | 5k–40k voice options                    | Premium quality. Requires ElevenLabs key.   |
    | **Edge**       | Built-in system voices                  | Free, no API key. Lower quality.            |
  </Tab>

  <Tab title="STT backends">
    | Backend                  | Quality | Notes                                                       |
    | ------------------------ | ------- | ----------------------------------------------------------- |
    | **Local faster-whisper** | Good    | Free, runs locally, no API key. Default.                    |
    | **OpenAI Whisper**       | High    | Requires OpenAI key. Better accuracy for accents and noise. |
  </Tab>
</Tabs>

***

## Using voice mode

<Tabs>
  <Tab title="Click to talk">
    Click the **microphone icon** in the chat composer. The icon turns red to indicate recording. Speak your message, then click the icon again (or press `Esc`) to stop. The agent transcribes, processes, and speaks the response.
  </Tab>

  <Tab title="Push to talk">
    Enable **Push to talk** in voice settings. Hold the microphone button (or a configured keyboard shortcut) to talk, release to send. The agent responds with speech automatically.
  </Tab>

  <Tab title="Continuous mode">
    The agent listens for your speech, responds, then automatically listens again — no need to click each time. Enable in **Settings → Voice → Continuous mode**.

    To interrupt while the agent is speaking, click **Stop** or press `Esc`.
  </Tab>
</Tabs>

***

## Voice on messaging platforms

On Telegram and Discord, voice messages you send are transcribed and processed as text. If TTS is enabled for that platform, the response comes back as a voice message.

***

## Microphone button states

| State         | Meaning                                         |
| ------------- | ----------------------------------------------- |
| **Gray mic**  | Voice mode is off. Click to start recording.    |
| **Red mic**   | Recording in progress. Click to stop and send.  |
| **Blue mic**  | Processing — transcribing or generating speech. |
| **Green mic** | Speaking — the agent is playing the response.   |

***

## Voice settings reference

| Setting         | What it controls                                       |
| --------------- | ------------------------------------------------------ |
| TTS provider    | Which service generates speech                         |
| TTS voice       | Which voice to use                                     |
| TTS speed       | How fast the agent speaks (0.5× to 2×)                 |
| STT backend     | Which service transcribes your speech                  |
| Auto-listen     | Start listening automatically after the agent responds |
| Push to talk    | Hold to talk, release to send                          |
| Continuous mode | Agent listens → responds → listens again               |
| Voice volume    | Output volume for TTS audio                            |

***

## Tips

<Tip>
  Use push to talk if you're in a noisy environment — it prevents the agent from picking up background conversation as input.
</Tip>

* 🎙️ **Speak clearly** — the STT model works best with moderate-paced, clear speech.
* 🤫 **Use a quiet environment** — background noise reduces transcription accuracy.
* 🔊 **Try different voices** — some TTS voices sound more natural for your use case.
* ⚡ **Adjust speed** — if the agent speaks too fast or slow, tweak the TTS speed setting.

***

<CardGroup cols={2}>
  <Card title="Channels" icon="message" href="/channels">
    Voice messages on Telegram and other messaging platforms.
  </Card>

  <Card title="Modes" icon="sliders" href="/modes">
    Continuous voice works best in Hands-Off or Autopilot mode.
  </Card>
</CardGroup>