Stream audio to Qwen-ASR-Realtime over WebSocket and receive real-time transcription results via the DashScope Python SDK.
Prerequisites
Before you begin, make sure that you have:
- DashScope SDK 2.0.1 or later
- An API key
- An understanding of the interaction flow
ImportantAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:
- China (Beijing): from
dashscope.aliyuncs.comto{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: from
dashscope-intl.aliyuncs.comto{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Replace {WorkspaceId} with your actual Workspace ID. The existing domains remain fully functional.
Quick start
NoteThe example code reads your_audio_file.pcm (PCM16, 16 kHz, mono). If you only have an MP3, WAV, or similar format, convert it with ffmpeg:
ffmpeg -i your_audio.mp3 -ar 16000 -ac 1 -f s16le your_audio_file.pcm
import logging
import os
import signal
import sys
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor
# The API Key differs between the Singapore and Beijing regions. Get your API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key="sk-xxx"
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
# The following is the configuration for the Singapore (ap-southeast-1) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ by region.
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
def setup_logging():
"""Configure log output"""
logger = logging.getLogger('dashscope')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(sys.stdout)
handler.setLevel(logging.DEBUG)
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)
logger.propagate = False
return logger
def handle_event(event):
"""Handle a server-side event"""
kind = event.get('type')
if kind == 'session.created':
print(f"Start session: {event['session']['id']}")
elif kind == 'conversation.item.input_audio_transcription.completed':
print(f"Final recognized text: {event['transcript']}")
elif kind == 'conversation.item.input_audio_transcription.text':
print(f"Got transcription result: {event['text'] + event['stash']}")
elif kind == 'input_audio_buffer.speech_started':
print('======Speech Start======')
elif kind == 'input_audio_buffer.speech_stopped':
print('======Speech Stop======')
def receive_events(session):
"""Receive and process server-side events"""
for event in session.events():
handle_event(event)
def read_audio_chunks(file_path, chunk_size=3200):
"""Read the audio file in chunks"""
with open(file_path, 'rb') as f:
while chunk := f.read(chunk_size):
yield chunk
def send_audio(session, file_path, delay=0.1):
"""Send audio data"""
if not os.path.exists(file_path):
raise FileNotFoundError(f"Audio file {file_path} does not exist.")
print("Processing audio file... Press 'Ctrl+C' to stop.")
for chunk in read_audio_chunks(file_path):
session.append_audio(chunk) # bytes are automatically Base64-encoded before being sent
time.sleep(delay)
def main():
setup_logging()
audio_file_path = "./your_audio_file.pcm"
# Entering the with context automatically establishes the connection
with client.audio.realtime.connect(
model='qwen3-asr-flash-realtime',
) as session:
def handle_exit(sig, frame):
print('Ctrl+C pressed, exiting...')
session.close()
sys.exit(0)
signal.signal(signal.SIGINT, handle_exit)
# Update the session configuration: text output only, with input audio transcription enabled
session.update_session(
output_modalities=['text'],
enable_input_audio_transcription=True,
transcription_params={
'language': 'zh',
'sample_rate': 16000,
'input_audio_format': 'pcm',
},
)
# Read until session.updated to confirm that the configuration has taken effect
for event in session.events():
if event.get('type') == 'session.updated':
break
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, session)
try:
send_audio(session, audio_file_path)
# send session.finish and wait for finished and close
session.end_session()
receiver.result()
finally:
# close must run inside the pool context to unblock the receiver
session.close()
print("Audio processing completed.")
if __name__ == '__main__':
main()
Request parameters
client.audio.realtime.connect
The following parameters are set with client.audio.realtime.connect.
Click to view sample code
# The API Key differs between the Singapore and Beijing regions. Get your API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key="sk-xxx"
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
# The following is the configuration for the Singapore (ap-southeast-1) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ by region.
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# Create a real-time recognition session: entering the with context automatically establishes the connection
session = client.audio.realtime.connect(
model='qwen3-asr-flash-realtime',
)
| Parameter | Type | Required | Description |
|---|---|---|---|
model | str | Yes | Model to use. |
ws_url | str | No | Full WebSocket endpoint. If not specified, the endpoint is automatically selected based on the workspace and region of the Client: China (Beijing): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime Singapore: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime. Replace {WorkspaceId} with your actual Workspace ID. |
Session configuration
After connecting, call update_session to configure session parameters.
Click to view sample code
session.update_session(
output_modalities=['text'],
enable_turn_detection=True,
turn_detection_type="server_vad",
turn_detection_threshold=0.0,
turn_detection_silence_duration_ms=400,
enable_input_audio_transcription=True,
transcription_params={
'language': 'zh',
'sample_rate': 16000,
'input_audio_format': 'pcm',
},
)
| Parameter | Type | Required | Description |
|---|---|---|---|
output_modalities | List[str] | Yes | Output modality. Fixed to ["text"]. |
enable_turn_detection | bool | No | Enables server-side Voice Activity Detection (VAD). Default: True. When False, call commit() manually to trigger recognition. |
turn_detection_type | str | No | Server-side VAD type. Fixed to server_vad. |
turn_detection_threshold | float | No | VAD sensitivity threshold. Default: 0.2. Recommended: 0.0. Valid range: [-1, 1]. Lower values = higher sensitivity (may trigger on background noise). Higher values = fewer false triggers in noisy environments. |
turn_detection_silence_duration_ms | int | No | Silence duration (ms) that marks the end of a statement. Default: 800. Recommended: 400. Valid range: [200, 6000]. Lower values (e.g., 300 ms) = faster response but may split natural pauses. Higher values (e.g., 1200 ms) = better handling of long-sentence pauses but higher latency. |
transcription_params | dict | No | Speech recognition configurations. See transcription_params. |
transcription_params
Set speech recognition settings with the transcription_params dictionary of update_session.
Click to view sample code
session.update_session(
output_modalities=['text'],
enable_input_audio_transcription=True,
transcription_params={
'language': 'zh',
'sample_rate': 16000,
'input_audio_format': 'pcm',
},
)
| Parameter | Type | Required | Description |
|---|---|---|---|
language | str | No | Source language of the audio. Supported values: zh (Chinese: Mandarin, Sichuanese, Minnan, Wu), yue (Cantonese), en (English), ja (Japanese), ko (Korean), de (German), fr (French), es (Spanish), pt (Portuguese), it (Italian), ru (Russian), ar (Arabic), hi (Hindi), id (Indonesian), th (Thai), tr (Turkish), uk (Ukrainian), vi (Vietnamese), cs (Czech), da (Danish), fi (Finnish), fil (Filipino), is (Icelandic), ms (Malay), no (Norwegian), pl (Polish), sv (Swedish) |
sample_rate | int | No | Audio sampling rate in Hz. Default: 16000. Supported: 16000, 8000. With 8000, the server upsamples to 16,000 Hz before recognition, which may add minor latency. Use 8000 only for 8 kHz source audio like telephone recordings. |
input_audio_format | str | No | Audio format. Default: pcm. Supported: pcm, opus. |
corpus_text | str | No | Background text, entity vocabularies, or other reference information for contextual biasing. Max: 10,000 tokens. For details, see Contextual biasing. |
API reference
RealtimeSession class
A real-time recognition session is created with client.audio.realtime.connect(model=...): the connection is established when you enter the with context (or call the session's connect() method).
| Method | Server response event (delivered via events()) | Description |
|---|---|---|
connect() | session.created, session.updated | Opens a WebSocket connection to the server. Automatically called when entering the with context; do not call connect() and then enter the with context of the same session. |
update_session(...) | session.updated | Configures the session. Call after connect(). If omitted, defaults apply. See Session configuration for parameters. |
append_audio(audio: Union[str, bytes]) | None | Appends an audio chunk to the server input buffer. A str is treated as already Base64-encoded; bytes are automatically Base64-encoded. With enable_turn_detection=True, the server detects speech boundaries and commits automatically. With enable_turn_detection=False, the client controls commit timing (max 15 MiB per event). Smaller chunks improve VAD responsiveness. |
commit() | input_audio_buffer.committed | Commits buffered audio for recognition. Returns an error if the buffer is empty. Disabled when enable_turn_detection=True. |
end_session() | session.finished | Ends the session after the server completes final recognition. In VAD mode (default), call after sending all audio. In Manual mode, call after commit(). |
close() | None | Terminates the task and closes the connection (idempotent, does not send session.finish). |
events() | Server events (the event type is in event["type"]) | Continuously reads server events. The iteration ends after session.finished is yielded; consume events from a single receiver thread and do not create multiple concurrent readers. |
session.session_id, session.last_response_id | None | The session ID of the current task and the response ID of the most recent response (attributes). |
Event iteration (events())
The server returns response events and data to the client as events. Iterate the session's events() in a receiver thread and dispatch on event["type"] (see the full event list in Server events).
def receive_events(session):
for event in session.events():
kind = event.get('type')
if kind == 'session.created':
print(f"Start session: {event['session']['id']}")
elif kind == 'conversation.item.input_audio_transcription.completed':
print(f"Final recognized text: {event['transcript']}")
elif kind == 'conversation.item.input_audio_transcription.text':
print(f"Got transcription result: {event['text'] + event['stash']}")
| Method | Parameters | Description |
|---|---|---|
events() | event: a server event | Continuously reads and yields server events (dict). The iteration ends when the connection closes or session.finished is received. |
recv_event() | None | Blocks to read a single server event without looping; returns None when there are no events (the connection is closed). |