This topic describes how to use the Python software development kit (SDK) for the Short-sentence Speech Recognition service of Intelligent Speech Interaction and provides installation instructions and code examples.
Prerequisites
Before you use the SDK, make sure that you have read the API reference. For more information, see API reference.
The SDK supports only Python 3. Python 2 is not supported.
Ensure that the Python package management tool setuptools is installed. If it is not installed, execute the following command in the terminal to install it.
pip install setuptools
Download and installation
Run the following commands in the root directory of the SDK.
Download the Python SDK.
Download the Python SDK from Github, or download streamInputTts-github-python directly.
Install SDK dependencies.
Navigate to the SDK root directory and run the following command to install the dependencies:
python -m pip install -r requirements.txtInstall the SDK.
After the dependencies are installed, run the following command to install the SDK:
python -m pip install .After the installation is complete, import the SDK using the following code.
# -*- coding: utf-8 -*- import nls
Multi-threading and concurrency
In CPython, due to the Global Interpreter Lock, only one thread can execute Python code at a time. Some performance-oriented libraries may remove this restriction. To make better use of the computing resources of a multi-core computer, you can use multiprocessing or concurrent.futures.ProcessPoolExecutor. If you want to run multiple I/O-intensive tasks at the same time, multi-threading is still a suitable model.
If a single interpreter has too many threads, the overhead from switching between them increases and may cause SDK errors. We recommend that you do not use more than 200 threads. To avoid this issue, use the multiprocessing technique or manually create multiple interpreters using a script.
Key interfaces
The nls.NlsSpeechRecognizer class is used for Short Utterance Recognition. Its core methods are as follows:
1. Initialization (__init__)
Parameters
Parameter
Type
Description
url
String
The WebSocket URL of the gateway. The default value is
wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1.appkey
String
The AppKey. For more information about how to obtain an AppKey, see Manage projects.
token
String
The access token. For more information, see Overview of how to obtain a token.
on_start
Function
The callback for when Short-sentence Speech Recognition is ready. The callback receives the following arguments:
A JSON-formatted string
User-defined parameter
The user-defined parameter is the value returned in the callback_args field below.
on_result_changed
Function
The callback for when Short-sentence Speech Recognition returns an intermediate result. The callback receives the following arguments:
A JSON-formatted string
User-defined parameter
The user-defined parameter is the content of the callback_args field below.
on_completed
Function
The callback for when Short-sentence Speech Recognition returns the final recognition result. The callback receives the following arguments:
A JSON-formatted string
User-defined parameters
The user-defined parameter is the value returned in the callback_args field below.
on_error
Function
The callback for when an error occurs in the SDK or on the server-side. The callback receives the following arguments:
A JSON-formatted string
User-defined parameter
The user-defined parameter is the value of the callback_args field described below.
on_close
Function
The callback for when the connection to the server is disconnected. The callback receives only the user-defined arguments from the callback_args parameter.
callback_args
List
A list of user-defined parameters. The content of the list is packed into a List data structure and passed as the last argument to each callback.
Return value: None
2. start
This method synchronously starts Short-sentence Speech Recognition. This method blocks the current thread until the recognition process is ready. The process is ready when the on_start callback is returned.
Parameters
Parameter
Type
Description
aformat
String
The format of the audio to be recognized. Supported formats are PCM, OPUS, and OPU. The default value is PCM.
The SDK does not automatically encode PCM into OPUS or OPU. To use OPUS or OPU, you must implement the encoding yourself.
sample_rate
Integer
The audio sampling rate for recognition. The default value is 16000 Hz.
ch
Integer
The number of audio channels. The default value is 1. Only single-channel audio is supported.
enable_intermediate_result
Boolean
Specifies whether to return intermediate results. The default value is False.
enable_punctuation_prediction
Boolean
Specifies whether to predict punctuation for the recognition result. The default value is False.
enable_inverse_text_normalization
Boolean
Specifies whether to enable inverse text normalization (ITN) to convert Chinese numerals to Arabic numerals. If set to True, Chinese numerals are converted to Arabic numerals in the output. The default value is False.
timeout
Integer
The blocking timeout period. The default value is 10 seconds.
ping_interval
Integer
The interval for sending ping packets. The default value is 8 seconds. To send no pings, set this to 0 or None.
ping_timeout
Integer
The timeout period for ping packets. The default value is 0, which means ping timeouts are not checked. If you set this to a value x greater than 0, a timeout error is reported if a ping packet is sent but no response is received within x seconds. Unit: seconds.
ex
Dict
Extra parameters provided by the user. The content of this dictionary is merged into the `payload` field of the request as
key:valuepairs. For more information, see the request data in the 2. Start recognition section.
Return value: A Boolean value. True indicates success. False indicates failure.
3. stop
This method stops Short-sentence Speech Recognition and synchronously waits for the on_completed callback to finish.
Parameters
Parameter
Type
Description
timeout
Integer
The blocking timeout period. The default value is 10 seconds.
Return value: A Boolean value. True indicates success. False indicates failure.
4. shutdown
This method forcibly closes the current request. Repeated calls to this method have no side effects.
Parameters: None
Return value: None
5. send_audio
This method sends binary audio data. The data format must match the value of the aformat parameter in the start method.
Parameters
Parameter
Type
Description
pcm_data
Bytes
The binary audio data to send. The format must correspond to the aformat parameter from the last call to start.
The SDK does not automatically encode PCM into OPUS or OPU. To use OPUS or OPU, you must implement the encoding yourself.
Return value: A Boolean value. True indicates success. False indicates failure.
Code example
The audio file used in this example is in PCM format with a sample rate of 16000 Hz. You can use the test1.pcm file in the tests folder. In the Intelligent Speech Interaction console, set the model for the project that corresponds to your AppKey to the General model to obtain accurate recognition results. If you use other audio files, you must set the model to one that supports the audio scenario. For more information about model settings, see Manage projects.
This example uses the default public URL built into the SDK to access the server. If you use an Alibaba Cloud ECS instance in the China (Shanghai) region and need to access the server over the internal network, use the following URL:
URL="ws://nls-gateway-cn-shanghai-internal.aliyuncs.com/ws/v1".
import time
import threading
import sys
import nls
URL="wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1"
TOKEN="yourToken" # For information about how to obtain a token, see https://help.aliyun.com/document_detail/450255.html
APPKEY="yourAppkey" # To obtain an AppKey, go to the console: https://nls-portal.console.aliyun.com/applist
# The following code repeatedly performs Short-sentence Speech Recognition based on the content of the audio file.
class TestSr:
def __init__(self, tid, test_file):
self.__th = threading.Thread(target=self.__test_run)
self.__id = tid
self.__test_file = test_file
def loadfile(self, filename):
with open(filename, "rb") as f:
self.__data = f.read()
def start(self):
self.loadfile(self.__test_file)
self.__th.start()
def test_on_start(self, message, *args):
print("test_on_start:{}".format(message))
def test_on_error(self, message, *args):
print("on_error args=>{}".format(args))
def test_on_close(self, *args):
print("on_close: args=>{}".format(args))
def test_on_result_chg(self, message, *args):
print("test_on_chg:{}".format(message))
def test_on_completed(self, message, *args):
print("on_completed:args=>{} message=>{}".format(args, message))
def __test_run(self):
print("thread:{} start..".format(self.__id))
sr = nls.NlsSpeechRecognizer(
url=URL,
token=TOKEN,
appkey=APPKEY,
on_start=self.test_on_start,
on_result_changed=self.test_on_result_chg,
on_completed=self.test_on_completed,
on_error=self.test_on_error,
on_close=self.test_on_close,
callback_args=[self.__id]
)
print("{}: session start".format(self.__id))
r = sr.start(aformat="pcm", ex={"hello":123})
self.__slices = zip(*(iter(self.__data),) * 640)
for i in self.__slices:
sr.send_audio(bytes(i))
time.sleep(0.01)
r = sr.stop()
print("{}: sr stopped:{}".format(self.__id, r))
time.sleep(1)
def multiruntest(num=500):
for i in range(0, num):
name = "thread" + str(i)
t = TestSr(name, "tests/test1.pcm")
t.start()
# Enable log output
nls.enableTrace(False)
multiruntest(1)