deepgram-voice

## Overview

Deepgram provides text-to-speech voices (the **Aura** model family) for both **in-app TTS** and **phone calls**. Change the voice with the **`voice_config_update`** tool — it writes the voice to **whichever TTS provider is currently active** and pushes to the macOS app via SSE in one call:

```
voice_config_update setting="tts_voice_id" value="<aura-model-id>"
```

> **The voice lives under the _active_ provider, not always Deepgram.** The config key depends on `services.tts.provider`: `deepgram` → `services.tts.providers.deepgram.model`, `vellum` (managed) → `services.tts.providers.vellum.model`, `elevenlabs` → `services.tts.providers.elevenlabs.voiceId`. The `voice_config_update` tool (and the `assistant tts voice <id>` CLI command) handle this routing for you. **Do NOT `assistant config set services.tts.providers.deepgram.model ...` blindly** — on a managed (`vellum`) assistant that field is ignored, so the write "succeeds" but the voice never changes. See [Setting the voice](#setting-the-voice) for the CLI fallback.
>
> **The tables below apply when the active provider is `deepgram` (BYO key) or managed `vellum`.** Managed assistants synthesize Deepgram voices through the platform — the platform bills per rate-carded model and rejects voices it does not offer (the write succeeds but the voice fails on the next turn), so stick to current Aura-2 voices there. With a BYO key ([setup below](#deepgram-api-key-setup)), any Aura model id from the catalog works. Other BYO TTS providers (`elevenlabs`, `xai`, `fish-audio`, …) use their own voice identifiers — never write a Deepgram Aura model id to them; see [Getting to a Deepgram voice from another provider](#getting-to-a-deepgram-voice-from-another-provider).

## Getting to a Deepgram voice from another provider

Check the active provider first: `assistant config get services.tts.provider`.

- **Already on managed `vellum`?** No provider change needed. The managed platform supports **both Deepgram and ElevenLabs voices** — `services.tts.providers.vellum.model` accepts either an Aura model id or an ElevenLabs voice id, so switching between a Deepgram and an ElevenLabs voice is just another `voice_config_update` call.
- **On a BYO provider (e.g. `elevenlabs`) and the user wants a Deepgram voice?** Two options — ask which they prefer. Switch with the `voice_config_update` tool, not raw `assistant config set` — the tool validates the switch (e.g. rejects `vellum` when no platform connection exists, which a raw config write would leave silently broken):
  1. **Switch to managed `vellum`** (`voice_config_update setting="tts_provider" value="vellum"`) — no Deepgram key needed; requires a platform connection and bills managed credits. Bonus: they keep access to both the Deepgram and ElevenLabs catalogs.
  2. **Switch to BYO `deepgram`** (`voice_config_update setting="tts_provider" value="deepgram"`) — requires a Deepgram API key ([setup below](#deepgram-api-key-setup)); usage bills their Deepgram account directly.

After either switch, set the voice with `voice_config_update` as usual.

## Choose a Voice

Pick a voice that matches your identity and the user's preferences. Offer to show the full list if they want to choose themselves. All voice ids follow the pattern `aura-2-<name>-en`.

### Female voices

| Voice  | Style                                  | Model ID           |
| ------ | -------------------------------------- | ------------------ |
| Thalia | Clear, confident, energetic (American) | `aura-2-thalia-en` |
| Luna   | Friendly, natural, engaging (American) | `aura-2-luna-en`   |
| Athena | Calm, smooth, professional (American)  | `aura-2-athena-en` |
| Hera   | Warm, smooth, professional (American)  | `aura-2-hera-en`   |

### Male voices

| Voice    | Style                                     | Model ID             |
| -------- | ----------------------------------------- | -------------------- |
| Zeus     | Deep, trustworthy, smooth (American)      | `aura-2-zeus-en`     |
| Orion    | Approachable, calm, polite (American)     | `aura-2-orion-en`    |
| Arcas    | Natural, smooth, comfortable (American)   | `aura-2-arcas-en`    |
| Apollo   | Confident, casual, comfortable (American) | `aura-2-apollo-en`   |
| Draco    | Warm, trustworthy, baritone (British)     | `aura-2-draco-en`    |
| Hyperion | Caring, warm, empathetic (Australian)     | `aura-2-hyperion-en` |

> These are **Aura-2** voices — Deepgram's current generation. First-generation ids (`aura-asteria-en`, `aura-orion-en`, … without the `-2-`) still work with a BYO key but sound noticeably flatter; prefer Aura-2 unless the user asks otherwise. `aura-2-thalia-en` is the managed platform's default voice.

### Setting the voice

**Preferred — the tool.** It writes to the active provider's voice field **and** pushes to the macOS app via SSE (`ttsVoiceId`) in one call:

```
voice_config_update setting="tts_voice_id" value="<selected-model-id>"
```

**CLI fallback (only if the `voice_config_update` tool is unavailable).** Use `assistant tts voice`, which routes to the active provider's config key for you — do **not** hand-write `assistant config set services.tts.providers.deepgram.model ...`:

```bash
assistant tts voice "<selected-model-id>"
```

Setting `services.tts.providers.deepgram.model` directly while the active provider is `vellum` (or any non-deepgram provider) is the #1 cause of "I changed the voice but it didn't change" — that field is ignored by the active provider, so the write reports success but nothing changes. If you must use `config set`, first check `assistant config get services.tts.provider` and write the matching key (`vellum` → `services.tts.providers.vellum.model`, `deepgram` → `services.tts.providers.deepgram.model`).

Verify it worked by reading back the key for the **active** provider, e.g. for a managed assistant:

```bash
assistant config get services.tts.providers.vellum.model
```

The change hot-applies to the next voice turn (live v