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

Author: recipes-bot

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

@@ -0,0 +1,43 @@
+# Custom TTS (Voice Agents v1)
+
+Configure a custom text-to-speech voice for the voice agent's audio output.
+
+## What it does
+
+This recipe demonstrates how to customize the Text-to-Speech (TTS) configuration in a Deepgram voice agent. It shows how to select different voice models to change the character and tone of the agent's spoken responses, creating distinct voice personalities for different use cases.
+
+## Key parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `speak.provider.model` | `"aura-2-arcas-en"` | Custom voice model (male voice character) |
+| `speak.provider.type` | `"deepgram"` | TTS provider (Deepgram Aura voices) |
+
+## Example output
+
+```
+Configuring Voice Agent with Custom TTS Voice...
+Voice agent configured with custom TTS voice!
+Listen Model: nova-3 (Deepgram)
+Think Model: gpt-4o-mini (OpenAI)
+Speak Model: aura-2-arcas-en (Deepgram) - Male Voice
+Agent will respond with a distinct male voice character.
+```
+
+## 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,46 @@
+"""Demonstrates selecting a custom TTS voice for the voice agent."""
+
+from deepgram import DeepgramClient
+from deepgram.agent.v1.types import (
+    AgentV1Settings, AgentV1SettingsAgent, AgentV1SettingsAgentListen,
+    AgentV1SettingsAgentListenProvider_V1, AgentV1SettingsAudio,
+    AgentV1SettingsAudioInput,
+)
+from deepgram.types.think_settings_v1 import ThinkSettingsV1
+from deepgram.types.think_settings_v1provider import ThinkSettingsV1Provider_OpenAi
+from deepgram.types.speak_settings_v1 import SpeakSettingsV1
+from deepgram.types.speak_settings_v1provider import SpeakSettingsV1Provider_Deepgram
+
+
+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",  # <-- choose voice here
+                    ),
+                )],
+            ),
+        )
+
+        agent.send_settings(settings)
+        print("Voice agent configured with custom TTS:")
+        print("  Speak: aura-2-arcas-en (clear, professional male voice)")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,18 @@
+import subprocess
+from pathlib import Path
+
+
+def test_example_runs():
+    """Runs the example and verifies it produces output."""
+    example = Path(__file__).parent / "example.py"
+    result = subprocess.run(
+        ["python", str(example)],
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    assert result.returncode == 0, (
+        f"Example failed\nSTDOUT: {result.stdout}\nSTDERR: {result.stderr}"
+    )
+    assert result.stdout.strip(), "Example produced no output"
+    assert len(result.stdout.strip()) > 10, "Output seems too short"