@@ -7,6 +7,8 @@ typed server events (including audio) for responsive, interruptible conversation
77
88> ** Status:** Preview. APIs are subject to change.
99
10+ > ** Important:** As of version 1.0.0b5, this SDK is ** async-only** . The synchronous API has been removed to focus exclusively on async patterns. All examples and samples use ` async ` /` await ` syntax.
11+
1012---
1113
1214Getting started
@@ -25,21 +27,14 @@ Getting started
2527# Base install (core client only)
2628python -m pip install azure-ai-voicelive
2729
28- # For synchronous streaming (uses websockets)
29- python -m pip install " azure-ai-voicelive[websockets]"
30-
3130# For asynchronous streaming (uses aiohttp)
3231python -m pip install " azure-ai-voicelive[aiohttp]"
3332
34- # For both sync + async scenarios (recommended if unsure )
35- python -m pip install " azure-ai-voicelive[all-websockets] "
33+ # For voice samples (includes audio processing )
34+ python -m pip install azure-ai-voicelive[aiohttp] pyaudio python-dotenv
3635```
3736
38- WebSocket streaming features require additional dependencies.
39- Install them with:
40- pip install "azure-ai-voicelive[ websockets] " # for sync
41- pip install "azure-ai-voicelive[ aiohttp] " # for async
42- pip install "azure-ai-voicelive[ all-websockets] " # for both
37+ The SDK now exclusively provides async-only WebSocket connections using ` aiohttp ` .
4338
4439### Authenticate
4540
@@ -58,50 +53,65 @@ AZURE_VOICELIVE_ENDPOINT="your-endpoint"
5853Then, use the key in your code:
5954
6055``` python
56+ import asyncio
6157from azure.core.credentials import AzureKeyCredential
6258from azure.ai.voicelive import connect
6359
64- connection = connect(
65- endpoint = " your-endpoint"
66- credential = AzureKeyCredential(" your-api-key"
67- model = " gpt-4o-realtime-preview"
68- )
60+ async def main ():
61+ async with connect(
62+ endpoint = " your-endpoint"
63+ credential = AzureKeyCredential(" your-api-key"
64+ model = " gpt-4o-realtime-preview"
65+ ) as connection:
66+ # Your async code here
67+ pass
68+
69+ asyncio.run(main())
6970```
7071
7172#### AAD Token Authentication
7273
7374For production applications, AAD authentication is recommended:
7475
7576``` python
76- from azure.identity import DefaultAzureCredential
77+ import asyncio
78+ from azure.identity.aio import DefaultAzureCredential
7779from azure.ai.voicelive import connect
7880
79- credential = DefaultAzureCredential()
81+ async def main ():
82+ credential = DefaultAzureCredential()
83+
84+ async with connect(
85+ endpoint = " your-endpoint"
86+ credential = credential,
87+ model = " gpt-4o-realtime-preview"
88+ ) as connection:
89+ # Your async code here
90+ pass
8091
81- connection = connect(
82- endpoint = " your-endpoint"
83- credential = credential,
84- model = " gpt-4o-realtime-preview"
85- )
92+ asyncio.run(main())
8693```
8794
8895---
8996
9097Key concepts
9198------------
9299
93- - ** VoiceLiveConnection** – Manages an active WebSocket connection to the service
100+ - ** VoiceLiveConnection** – Manages an active async WebSocket connection to the service
94101- ** Session Management** – Configure conversation parameters:
95- - ** SessionResource** – Update session parameters (voice, formats, VAD)
102+ - ** SessionResource** – Update session parameters (voice, formats, VAD) with async methods
96103 - ** RequestSession** – Strongly-typed session configuration
97104 - ** ServerVad** – Configure voice activity detection
98105 - ** AzureStandardVoice** – Configure voice settings
99106- ** Audio Handling** :
100- - ** InputAudioBufferResource** – Manage audio input to the service
101- - ** OutputAudioBufferResource** – Control audio output from the service
107+ - ** InputAudioBufferResource** – Manage audio input to the service with async methods
108+ - ** OutputAudioBufferResource** – Control audio output from the service with async methods
102109- ** Conversation Management** :
103- - ** ResponseResource** – Create or cancel model responses
104- - ** ConversationResource** – Manage conversation items
110+ - ** ResponseResource** – Create or cancel model responses with async methods
111+ - ** ConversationResource** – Manage conversation items with async methods
112+ - ** Error Handling** :
113+ - ** ConnectionError** – Base exception for WebSocket connection errors
114+ - ** ConnectionClosed** – Raised when WebSocket connection is closed
105115- ** Strongly-Typed Events** – Process service events with type safety:
106116 - ` SESSION_UPDATED ` , ` RESPONSE_AUDIO_DELTA ` , ` RESPONSE_DONE `
107117 - ` INPUT_AUDIO_BUFFER_SPEECH_STARTED ` , ` INPUT_AUDIO_BUFFER_SPEECH_STOPPED `
@@ -112,25 +122,25 @@ Key concepts
112122Examples
113123--------
114124
115- ### Basic async Voice Assistant (Featured Sample)
125+ ### Basic Voice Assistant (Featured Sample)
116126
117- The Basic async Voice Assistant sample demonstrates full-featured voice interaction with:
127+ The Basic Voice Assistant sample demonstrates full-featured voice interaction with:
118128
119129- Real-time speech streaming
120- - Server-side voice activity detection
130+ - Server-side voice activity detection
121131- Interruption handling
122132- High-quality audio processing
123133
124134``` bash
125135# Run the basic voice assistant sample
126- # Requires [aiohttp] for async (easiest: [all-websockets])
136+ # Requires [aiohttp] for async
127137python samples/basic_voice_assistant_async.py
128138
129139# With custom parameters
130140python samples/basic_voice_assistant_async.py --model gpt-4o-realtime-preview --voice alloy --instructions " You're a helpful assistant"
131141```
132142
133- ### Minimal async example
143+ ### Minimal example
134144
135145``` python
136146import asyncio
@@ -172,44 +182,6 @@ async def main():
172182asyncio.run(main())
173183```
174184
175- ### Minimal sync example
176-
177- ``` python
178- from azure.core.credentials import AzureKeyCredential
179- from azure.ai.voicelive import connect
180- from azure.ai.voicelive.models import (
181- RequestSession, Modality, InputAudioFormat, OutputAudioFormat, ServerVad, ServerEventType
182- )
183-
184- API_KEY = " your-api-key"
185- ENDPOINT = " your-endpoint"
186- MODEL = " gpt-4o-realtime-preview"
187-
188- with connect(
189- endpoint = ENDPOINT ,
190- credential = AzureKeyCredential(API_KEY ),
191- model = MODEL
192- ) as conn:
193- session = RequestSession(
194- modalities = [Modality.TEXT , Modality.AUDIO ],
195- instructions = " You are a helpful assistant."
196- input_audio_format = InputAudioFormat.PCM16 ,
197- output_audio_format = OutputAudioFormat.PCM16 ,
198- turn_detection = ServerVad(
199- threshold = 0.5 ,
200- prefix_padding_ms = 300 ,
201- silence_duration_ms = 500
202- ),
203- )
204- conn.session.update(session = session)
205-
206- # Process events
207- for evt in conn:
208- print (f " Event: { evt.type} " )
209- if evt.type == ServerEventType.RESPONSE_DONE :
210- break
211- ```
212-
213185Available Voice Options
214186-----------------------
215187
@@ -279,12 +251,8 @@ Troubleshooting
279251 Verify ` AZURE_VOICELIVE_ENDPOINT ` , network rules, and that your credential has access.
280252
281253- ** Missing WebSocket dependencies:**
282- If you see:
283- WebSocket streaming features require additional dependencies.
284- Install them with:
285- pip install "azure-ai-voicelive[ websockets] " # for sync
286- pip install "azure-ai-voicelive[ aiohttp] " # for async
287- pip install "azure-ai-voicelive[ all-websockets] " # for both
254+ If you see import errors, make sure you have installed the package:
255+ pip install azure-ai-voicelive[ aiohttp]
288256
289257- ** Auth failures:**
290258 For API key, double-check ` AZURE_VOICELIVE_API_KEY ` . For AAD, ensure the identity is authorized.
0 commit comments