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
Complete example
The 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:Python
Request parameters
client.audio.realtime.connect
The following parameters are set with client.audio.realtime.connect.
Click to view sample code
Click to view sample code
| Parameter | Type | Required | Description |
|---|---|---|---|
model | str | Yes | Model to use. |
ws_url | str | No | Full WebSocket endpoint. Pass wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime (Singapore). For another region, replace ap-southeast-1 in the URL. See Regions and endpoints. |
Session configuration
After connecting, call update_session to configure session parameters.
Click to view sample code
Click to view sample code
| 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
Click to view sample code
| 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. |
Key interfaces
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).
| 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). |