feat(python): voice-agents v1 — custom-tts

Author: recipes-bot

recipes/python/voice-agents/v1/custom-tts/README.md

@@ -0,0 +1,43 @@
+# Configure TTS Voice (Voice Agents v1)
+
+Choose a specific aura-2 voice model for your voice agent's spoken responses.
+
+## What it does
+
+Configures the speak (TTS) component of the voice agent pipeline to use a specific voice model. Different aura-2 voices have distinct vocal characteristics — pitch, tone, and pacing. By changing the `speak.provider.model`, you can match the agent's voice to your brand or use case.
+
+## Key parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `speak.provider.type` | `"deepgram"` | TTS provider |
+| `speak.provider.model` | `"aura-2-arcas-en"` | Voice model for agent speech |
+
+Available aura-2 English voices:
+- `aura-2-thalia-en` (default), `aura-2-arcas-en`, `aura-2-luna-en`
+- `aura-2-asteria-en`, `aura-2-orion-en`, and more
+
+## Example output
+
+```
+Custom TTS settings sent (aura-2-arcas-en)
+Event: SettingsApplied
+```
+
+## Prerequisites
+
+- Python 3.10+
+- Set `DEEPGRAM_API_KEY` environment variable
+- Install: `pip install -r recipes/python/requirements.txt`
+
+## Run
+
+```bash
+python example.py
+```
+
+## Test
+
+```bash
+pytest example_test.py -v
+```

recipes/python/voice-agents/v1/custom-tts/example.py

@@ -0,0 +1,64 @@
+"""
+Recipe: Configure TTS Voice (Voice Agents v1)
+===============================================
+Demonstrates selecting a specific aura-2 voice model for the agent's
+speech output in the speak stage of the pipeline.
+
+The `speak` component controls which TTS model synthesises the agent's
+responses. This recipe uses aura-2-arcas-en — a different voice from
+the default — to demonstrate voice customisation.
+"""
+
+from deepgram import DeepgramClient
+from deepgram.agent.v1.types import (
+    AgentV1Settings, AgentV1SettingsAgent,
+    AgentV1SettingsAgentListen, AgentV1SettingsAgentListenProvider_V1,
+    AgentV1SettingsAudio, AgentV1SettingsAudioInput,
+)
+from deepgram.core.events import EventType
+from deepgram.types.speak_settings_v1 import SpeakSettingsV1
+from deepgram.types.speak_settings_v1provider import SpeakSettingsV1Provider_Deepgram
+from deepgram.types.think_settings_v1 import ThinkSettingsV1
+from deepgram.types.think_settings_v1provider import ThinkSettingsV1Provider_OpenAi
+
+
+def main():
+    client = DeepgramClient()  # reads DEEPGRAM_API_KEY from environment
+
+    with client.agent.v1.connect() as agent:
+        settings = AgentV1Settings(
+            audio=AgentV1SettingsAudio(
+                input=AgentV1SettingsAudioInput(encoding="linear16", sample_rate=24000)
+            ),
+            agent=AgentV1SettingsAgent(
+                listen=AgentV1SettingsAgentListen(
+                    provider=AgentV1SettingsAgentListenProvider_V1(type="deepgram", model="nova-3")
+                ),
+                think=ThinkSettingsV1(
+                    provider=ThinkSettingsV1Provider_OpenAi(type="open_ai", model="gpt-4o-mini"),
+                    prompt="You are a helpful AI assistant.",
+                ),
+                speak=SpeakSettingsV1(
+                    provider=SpeakSettingsV1Provider_Deepgram(
+                        type="deepgram",
+                        model="aura-2-arcas-en",  # <-- THIS is the feature: selecting the TTS voice
+                    )
+                ),
+            ),
+        )
+
+        agent.send_settings(settings)
+        print("Custom TTS settings sent (aura-2-arcas-en)")
+
+        def on_message(message):
+            if not isinstance(message, bytes):
+                msg_type = getattr(message, "type", type(message).__name__)
+                print(f"Event: {msg_type}")
+
+        agent.on(EventType.MESSAGE, on_message)
+        agent.on(EventType.ERROR, lambda e: print(f"Error: {e}"))
+        agent.start_listening()
+
+
+if __name__ == "__main__":
+    main()

recipes/python/voice-agents/v1/custom-tts/example_test.py

@@ -0,0 +1,16 @@
+import subprocess
+from pathlib import Path
+
+def test_example_runs():
+    """Runs the custom-tts voice agent example and verifies it produces output."""
+    example = Path(__file__).parent / "example.py"
+    result = subprocess.run(
+        ["python", str(example)],
+        capture_output=True,
+        text=True,
+        timeout=90,
+    )
+    assert result.returncode == 0, (
+        f"Example failed\nSTDOUT: {result.stdout}\nSTDERR: {result.stderr}"
+    )
+    assert result.stdout.strip(), "Example produced no output"