This topic describes the parameters and interface details of the Paraformer Real-time Speech Recognition Python SDK.
ImportantThis document applies only to the China (Beijing) region. To use the models, you must use the API Key of the China (Beijing) region.
ImportantAlibaba Cloud Model Studio has launched workspace-specific domains for the China (Beijing) region, which deliver superior performance and higher stability for inference requests. We recommend migrating from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com.
{WorkspaceId} must be replaced with your actual Workspace ID. The existing domain still works.
User guide: For model introduction and selection recommendations, see Real-time speech recognition-Fun-ASR/Paraformer.
Prerequisites
You have activated the service and obtained and configured an API Key. We recommend that you configure the API Key in environment variables instead of hardcoding it in your code, to prevent security risks caused by code leakage.
NoteWhen you need to grant temporary access to third-party applications or users, or want to strictly control high-risk operations such as accessing or deleting sensitive data, we recommend using a temporary authentication token.
Compared with a long-term API Key, a temporary authentication token is short-lived (60 s) and highly secure, making it suitable for temporary call scenarios and effectively reducing the risk of API Key leakage.
Usage: In your code, simply replace the API Key originally used for authentication with the obtained temporary authentication token.
Models
| paraformer-realtime-v2 | paraformer-realtime-8k-v2 | |
|---|---|---|
| Applicable Scenario | Scenarios such as live streaming and meetings | Scenarios for recognizing 8 kHz audio, such as call centers and voicemail |
| Sampling rate | Any | 8kHz |
| Languages | Chinese (including Mandarin Chinese and various dialects), English, Japanese, Korean, German, French, Russian Supported Chinese dialects: Shanghai dialect, Wu Chinese, Minnan dialect, Northeastern Mandarin, Gansu dialect, Guizhou dialect, Henan dialect, Hubei dialect, Hunan dialect, Jiangxi dialect, Ningxia dialect, Shanxi dialect, Shaanxi dialect, Shandong dialect, Sichuan dialect, Tianjin dialect, Yunnan dialect, Cantonese | Chinese |
| Punctuation prediction | Enabled by default, no configuration required | Enabled by default, no configuration required |
| Inverse text normalization (ITN) | Enabled by default, no configuration required | Enabled by default, no configuration required |
| Custom hotwords | ||
| Specify the language to recognize | Specified via the | Not supported |
| Emotion recognition | Not supported | Click to view usage Emotion recognition is subject to the following constraints:
How to obtain emotion recognition results: The emotion and emotion confidence of the current sentence are obtained via the |
QuickStart
Core resource (client.audio.asr) provides non-streaming and bidirectional streaming call interfaces. Please choose the appropriate calling method based on your actual needs:
- Non-streaming call (
recognize_file): Recognizes local files. The SDK automatically sends the audio in chunks and drives the task to completion. Suitable for processing pre-recorded audio. - Bidirectional streaming call: Recognizes audio streams directly and outputs results in real time. The audio stream can come from an external device (such as a microphone) or be read from a local file. Suitable for scenarios that require immediate feedback.
Non-streaming calls
Submit a single real-time speech transcription task and obtain the transcription result synchronously by passing in a local file.
Call the recognize_file method of Core resource (client.audio.asr) to bind request parameters and pass in the local file path, iterating over server-side events to obtain Recognition result (RecognitionResult).
Click to view the full example
import os
import dashscope
# 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
client = dashscope.Client(
# 若没有将API Key配置到环境变量中,请将下行替换为自己的API Key:api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
# 识别本地语音文件:recognize_file自动分块发送音频并驱动到任务结束
for event in client.audio.asr.recognize_file(
'{YOUR_AUDIO_FILE}',
model='paraformer-realtime-v2',
format='wav',
sample_rate=16000,
# “language_hints”只支持paraformer-realtime-v2模型
parameters={'language_hints': ['zh', 'en']}):
payload = event.get('payload') or {}
sentence = (payload.get('output') or {}).get('sentence') or {}
if sentence.get('text') and not sentence.get('heartbeat'):
print('识别结果:', sentence['text'])
recognize_file yields server-side events (Dict[str, Any]) one by one: the event type is located at event['header']['event'], and the recognized text is located at event['payload']['output']['sentence'] (sentence_end being true indicates that the sentence has ended; begin_time / end_time are timestamps and words contains word-level timestamps — see single-sentence information (Sentence) for other fields). Heartbeat and empty-text events are still yielded and can be ignored as needed.
In a bidirectional streaming session, besides events(), you can use results() to iterate only recognition result frames (returning typed Recognition result (RecognitionResult), with heartbeat frames filtered out). For more information, see the get_sentence method description.
Bidirectional streaming calls
Submit a single real-time speech transcription task and obtain real-time recognition results streamed by iterating over events.
-
Start streaming speech recognition
Call the
recognizemethod of Core resource (client.audio.asr) to create a recognition session and bind request parameters, then enter thewithcontext (which automatically calls thestartmethod to establish the connection and send the task) to start streaming speech recognition. -
Streaming
Call the session's
send_audio_framemethod in a loop to send the binary audio stream read from a local file or device (such as a microphone) to the server in segments. Sending and receiving must proceed concurrently: the receiving thread iterates over server-side events via event iteration (events()/results()) and returns recognition results to the client in real time.It is recommended that each send contain approximately 100 milliseconds of audio, with the data size kept between 1 KB and 16 KB.
-
Finish processing
Call the session's
stopmethod to end speech recognition.This method only notifies the server that input has ended; the receiving thread must continue consuming
events()until thetask-finishedevent to obtain the final recognition results and statistics. Errors at the ws layer are raised asDashScopeErrorexceptions, which can be caught with try/except where you send or receive.
Click to view the full example
import os
import signal # for keyboard events handling (press "Ctrl+C" to terminate recording)
import sys
import dashscope
import pyaudio
from concurrent.futures import ThreadPoolExecutor
# 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
client = dashscope.Client(
# 若没有将API Key配置到环境变量中,请将下行替换为自己的API Key:api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
mic = None
stream = None
# Set recording parameters
sample_rate = 16000 # sampling rate (Hz)
channels = 1 # mono channel
dtype = 'int16' # data type
format_pcm = 'pcm' # the format of the audio data
block_size = 3200 # number of frames per buffer
# Real-time speech recognition event receiver
def receive_events(rec):
for event in rec.events():
payload = event.get('payload') or {}
sentence = (payload.get('output') or {}).get('sentence') or {}
if sentence.get('text') and not sentence.get('heartbeat'):
print('Recognition text: ', sentence['text'])
if sentence.get('sentence_end'):
print(
'Recognition sentence end, request_id:%s, usage:%s'
% (rec.request_id, rec.usage))
def signal_handler(sig, frame):
print('Ctrl+C pressed, stop recognition ...')
# Stop recognition
recognition.stop()
print('Recognition stopped.')
print(
'[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
.format(
recognition.request_id,
recognition.first_package_delay,
recognition.last_package_delay,
))
# Forcefully exit the program
sys.exit(0)
# main function
if __name__ == '__main__':
print('Initializing ...')
signal.signal(signal.SIGINT, signal_handler)
print("Press 'Ctrl+C' to stop recording and recognition...")
# Call recognition service, you can customize the recognition parameters, like model, format,
# sample_rate
with client.audio.asr.recognize(
model='paraformer-realtime-v2',
format=format_pcm,
# 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr', you can check the supported formats in the document
sample_rate=sample_rate,
# support 8000, 16000
parameters={'semantic_punctuation_enabled': False},
) as recognition:
# Open the microphone
mic = pyaudio.PyAudio()
stream = mic.open(format=pyaudio.paInt16,
channels=1,
rate=16000,
input=True)
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, recognition)
try:
# Send audio from the microphone until "Ctrl+C" is pressed
while stream:
data = stream.read(3200, exception_on_overflow=False)
recognition.send_audio_frame(data)
recognition.stop()
receiver.result()
finally:
# close must run inside the pool context to unblock the receiver
recognition.close()
stream.stop_stream()
stream.close()
mic.terminate()
stream = None
mic = None
import os
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor
# 以下为华北2(北京)地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
client = dashscope.Client(
# 若没有将API Key配置到环境变量中,请将下行替换为自己的API Key:api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
from datetime import datetime
def get_timestamp():
now = datetime.now()
formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
return formatted_timestamp
# Real-time speech recognition event receiver
def receive_events(rec):
for event in rec.events():
payload = event.get('payload') or {}
sentence = (payload.get('output') or {}).get('sentence') or {}
if sentence.get('text') and not sentence.get('heartbeat'):
print(get_timestamp() + ' Recognition text: ', sentence['text'])
if sentence.get('sentence_end'):
print(get_timestamp() +
'Recognition sentence end, request_id:%s, usage:%s'
% (rec.request_id, rec.usage))
with client.audio.asr.recognize(
model='paraformer-realtime-v2',
format='wav',
sample_rate=16000,
# “language_hints”只支持paraformer-realtime-v2模型
parameters={'language_hints': ['zh', 'en']},
) as recognition:
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, recognition)
try:
audio_data: bytes = None
f = open("{YOUR_AUDIO_FILE}", 'rb')
if os.path.getsize("{YOUR_AUDIO_FILE}"):
while True:
audio_data = f.read(3200)
if not audio_data:
break
else:
recognition.send_audio_frame(audio_data)
time.sleep(0.1)
else:
raise Exception(
'The supplied file was empty (zero bytes long)')
f.close()
recognition.stop()
receiver.result()
finally:
# close must run inside the pool context to unblock the receiver
recognition.close()
print(
'[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
.format(
recognition.request_id,
recognition.first_package_delay,
recognition.last_package_delay,
))
Concurrent calls
In Python, due to the global interpreter lock, only one thread can execute Python code at a time (although some performance-oriented libraries may lift this restriction). To make better use of the computing resources of multi-core machines, we recommend using multiprocessing or concurrent.futures.ProcessPoolExecutor. Multithreading significantly increases SDK call latency under high concurrency.
Request parameters
Request parameters are set via the recognize/recognize_file methods of Core resource (client.audio.asr): model, format, sample_rate, vocabulary_id, and disfluency_removal_enabled are named parameters, and the remaining parameters (such as language_hints and semantic_punctuation_enabled) are passed in via the parameters dictionary.
Parameter | Type | Default Value | Required | Description |
|---|---|---|---|---|
model | str | - | Yes | The model used for Real-time Speech Recognition (see Models). |
sample_rate | int | - | Yes | Set the sample rate of the audio to recognize (in Hz). Varies by model:
|
format | str | - | Yes | Set the format of the audio to recognize. Supported audio formats: pcm, wav, mp3, opus, speex, aac, amr. opus/speex: must use Ogg encapsulation; wav: must be PCM encoding; amr: only the AMR-NB type is supported. |
vocabulary_id | str | - | No | Set the hotword ID. It does not take effect if not set. Use this field when setting a hotword ID for v2 and later models. In this speech recognition session, the hotword information corresponding to this hotword ID will be applied. For more information, see Customize Hotwords. |
disfluency_removal_enabled | bool | False | No | Set whether to filter filler words:
|
language_hints | list[str] | ["zh", "en"] | No | Set the language code of the audio to recognize. If the language cannot be determined in advance, you can leave it unset, and the model will automatically detect the language. Currently supported language codes:
This parameter only takes effect for models that support multiple languages (see the Models list). |
semantic_punctuation_enabled | bool | False | No | Specifies whether to enable semantic segmentation, disabled by default.
Semantic segmentation is more accurate and suitable for meeting transcription; VAD (Voice Activity Detection) segmentation has lower latency and is suitable for interactive scenarios. By adjusting the This parameter only takes effect when the model is v2 or later. |
max_sentence_silence | int | 800 | No | Sets the silence duration threshold (in ms) for VAD (Voice Activity Detection) segmentation. When the silence duration after a segment of speech exceeds this threshold, the system determines that the sentence has ended. The parameter ranges from 200 ms to 6000 ms, with a default value of 800 ms. This parameter only takes effect when the |
multi_threshold_mode_enabled | bool | False | No | When this switch is turned on (true), it prevents VAD segmentation from cutting overly long segments. Disabled by default. This parameter only takes effect when the |
punctuation_prediction_enabled | bool | True | No | Specifies whether to automatically add punctuation to recognition results:
This parameter only takes effect when the model is v2 or later. |
heartbeat | bool | False | No | When you need to maintain a long connection with the server, you can control it with this switch:
This parameter only takes effect when the model is v2 or later. This field was introduced in SDK 1.23.1 and is included in version 2.0.1 and later. |
inverse_text_normalization_enabled | bool | True | No | Specifies whether to enable ITN (Inverse Text Normalization). Enabled by default (true). When enabled, Chinese numerals are converted to Arabic numerals. This parameter only takes effect when the model is v2 or later. |
API reference
Core resources (client.audio.asr)
Real-time speech recognition capabilities are mounted on the client.audio.asr resource: recognize creates a bidirectional streaming recognition session (Recognition), and recognize_file performs one-time recognition on local files.
| Member methods | Method signatures | Description |
|---|---|---|
recognize | | Creates a bidirectional streaming recognition session; when entering the Sending audio and consuming events must be performed concurrently (used together with |
recognize_file | | Non-streaming call based on a local file: automatically sends audio in chunks and drives the task to completion, producing server-side events one by one. This method requires the recognized file to have read permission. |
start | | Start speech recognition: establishes the connection, sends the task, and waits for |
send_audio_frame | | Push audio. Each audio chunk pushed should not be too large or too small. We recommend that each audio packet be around 100 ms in duration and between 1KB~16KB in size. Recognition results are obtained through event iteration ( |
stop | | Stop speech recognition: only notifies the server that input has ended. The receiving thread must continue to consume |
events / results | | Iterate server events: |
close | | Closes the recognition session. Automatically called when exiting the |
request_id / first_package_delay / last_package_delay | | Obtain request_id, first-packet latency (the delay from sending the first audio packet to receiving the first recognition result), and last-packet latency (the time from sending the |
Event iteration (events()/results())
During bidirectional streaming calls, the server returns key process information and data to the client as events. You need to iterate the session's events() (raw event dict objects) or results() (typed recognition result frames) in a receiving thread to process the information or data returned by the server.
Click to view example
# 迭代原始事件:识别文本位于 payload.output.sentence
def receive_events(rec):
for event in rec.events():
payload = event.get('payload') or {}
sentence = (payload.get('output') or {}).get('sentence') or {}
if sentence.get('text') and not sentence.get('heartbeat'):
print('识别文本:', sentence['text'])
# 或只迭代识别结果帧(返回 RecognitionResult,心跳帧已过滤)
def receive_results(rec):
for result in rec.results():
sentence = result.get_sentence()
if sentence and 'text' in sentence:
print('识别文本:', sentence['text'])
| Event/iteration method | Output | Return value | Description |
|---|---|---|---|
|
| None | Read internally by |
|
| Iterator | Yields events when the server has a reply. Recognition results are located in |
|
| Iterator | Yields only recognition result frames (heartbeat frames are filtered out); iteration ends after all recognition results have been returned. |
|
| None | Raised in the sending/receiving thread when an exception occurs; you can catch it with try/except. |
|
| None | Yielded by |
Response results
Recognition result (RecognitionResult)
RecognitionResult represents a recognition result frame yielded by the session's results() iteration (it can be used with both bidirectional streaming calls and non-streaming calls; events() yields raw event dict objects—switch to results() if you need this typed view).
| Member methods | Method signatures | Description |
|---|---|---|
get_sentence | | Obtain the currently recognized sentence and its timestamp information. This method returns a Dict[str, Any] (single-sentence information). For more information, see Sentence information (Sentence). |
request_id | | The request_id of the request corresponding to the current event. |
is_sentence_end | | Determines whether the current sentence has ended ( |
Sentence information (Sentence)
The members of the Sentence class are as follows:
Parameter | Type | Description |
|---|---|---|
begin_time | int | The start time of the sentence, in ms. |
end_time | int | The end time of the sentence, in ms. |
text | str | The recognized text. |
words | A list of word timestamp information (Word) | Word timestamp information. |
emo_tag | str | The sentiment of the current sentence:
Emotion recognition is subject to the following constraints:
|
emo_confidence | float | The confidence level of the sentiment recognized for the current sentence, in the range [0.0,1.0]. A larger value indicates higher confidence. Emotion recognition is subject to the following constraints:
|
Word timestamp information (Word)
The members of the Word class are as follows:
Parameter | Type | Description |
|---|---|---|
begin_time | int | The start time of the word, in ms. |
end_time | int | The end time of the word, in ms. |
text | str | The word. |
punctuation | str | Punctuation. |
More examples
For more examples, see GitHub.
Error codes
If you encounter errors, see Error codes for troubleshooting.
If the problem persists, join the developer group to report the issue and provide the Request ID for further troubleshooting.