通過一句話識別Java SDK發送音頻流並接收識別結果。本文提供SDK安裝、用戶端初始化和完整調用樣本,以及發送音頻、結束識別和排查依賴問題的說明。
使用前準備
安裝SDK
在Maven專案的pom.xml中添加以下依賴。樣本使用Java SDK 2.2.1。
<dependency>
<groupId>com.alibaba.nls</groupId>
<artifactId>nls-sdk-recognizer</artifactId>
<version>2.2.1</version>
</dependency>
<!-- JDK 9及以上版本還需添加以下依賴。 -->
<dependency>
<groupId>javax.xml.bind</groupId>
<artifactId>jaxb-api</artifactId>
<version>2.3.1</version>
</dependency>
從2.1.0起,nls-sdk-short-asr更名為nls-sdk-recognizer。從舊版本升級時,移除nls-sdk-short-asr依賴,並按編譯提示補齊回調方法。如果專案已依賴Netty,使用4.1.17.Final或更高版本。
程式碼範例
下載nls-sample-16k.wav,放到程式的工作目錄。該檔案為單聲道、16 kHz WAV音頻;專案中需選擇與音頻語種和採樣率匹配的模型。使用其他音頻時,同步調整代碼中的檔案名稱、編碼格式和採樣率。
配置以下環境變數。AccessKey與Appkey需屬於用於調用服務的帳號。
|
環境變數 |
含義 |
|
|
AccessKey ID,用於申請NLS Token。 |
|
|
AccessKey Secret,用於申請NLS Token。 |
|
|
Intelligent Speech Interaction專案的Appkey。 |
AccessKey用於身份認證,避免將其寫入程式碼在程式中或寫入日誌。NLS Token有有效期間,長期啟動並執行應用需在到期前重新擷取Token,並通過NlsClient.setToken()更新用戶端。
import com.alibaba.nls.client.AccessToken;
import com.alibaba.nls.client.protocol.InputFormatEnum;
import com.alibaba.nls.client.protocol.NlsClient;
import com.alibaba.nls.client.protocol.SampleRateEnum;
import com.alibaba.nls.client.protocol.asr.SpeechRecognizer;
import com.alibaba.nls.client.protocol.asr.SpeechRecognizerListener;
import com.alibaba.nls.client.protocol.asr.SpeechRecognizerResponse;
import java.io.FileInputStream;
import java.io.InputStream;
public class SpeechRecognizerDemo {
public static void main(String[] args) throws Exception {
String appKey = requireEnv("NLS_APP_KEY");
String accessKeyId = requireEnv("ALIYUN_AK_ID");
String accessKeySecret = requireEnv("ALIYUN_AK_SECRET");
String audioFile = "nls-sample-16k.wav";
// 擷取NLS Token;在有效期間結束前重新擷取並更新用戶端。
AccessToken accessToken = new AccessToken(accessKeyId, accessKeySecret,
"nlsmeta.ap-southeast-1.aliyuncs.com", "ap-southeast-1", "2019-07-17");
accessToken.apply();
NlsClient client = new NlsClient(
"wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1", accessToken.getToken());
SpeechRecognizer recognizer = null;
try {
recognizer = new SpeechRecognizer(client, createListener());
recognizer.setAppKey(appKey);
// 編碼格式和採樣率須與音頻檔案及專案模型一致。
recognizer.setFormat(InputFormatEnum.WAV);
recognizer.setSampleRate(SampleRateEnum.SAMPLE_RATE_16K);
recognizer.setEnableIntermediateResult(true);
recognizer.addCustomedParam("enable_voice_detection", true);
recognizer.start();
try (InputStream audio = new FileInputStream(audioFile)) {
// 從檔案類比即時音頻:每次發送3200位元組,間隔100毫秒。
recognizer.send(audio, 3200, 100);
}
recognizer.stop();
} finally {
if (recognizer != null) {
recognizer.close();
}
client.shutdown();
}
}
private static SpeechRecognizerListener createListener() {
return new SpeechRecognizerListener() {
@Override
public void onStarted(SpeechRecognizerResponse response) {
System.out.println("Task ID: " + response.getTaskId());
}
@Override
public void onRecognitionResultChanged(SpeechRecognizerResponse response) {
System.out.println("RecognitionResultChanged: " + response.getRecognizedText());
}
@Override
public void onRecognitionCompleted(SpeechRecognizerResponse response) {
System.out.println("RecognitionCompleted: " + response.getRecognizedText());
}
@Override
public void onFail(SpeechRecognizerResponse response) {
System.err.println("Task ID: " + response.getTaskId()
+ ", status: " + response.getStatus()
+ ", message: " + response.getStatusText());
}
};
}
private static String requireEnv(String name) {
String value = System.getenv(name);
if (value == null || value.isEmpty()) {
throw new IllegalArgumentException("Missing environment variable: " + name);
}
return value;
}
}
識別結果通過onRecognitionResultChanged和onRecognitionCompleted回調返回;請求失敗時,通過onFail擷取任務ID、狀態代碼和錯誤資訊。
關鍵介面
|
介面 |
用途與生命週期 |
|
|
語音處理用戶端,支援一句話識別、即時語音辨識和語音合成。安全執行緒,建議全域複用一個執行個體,在應用退出時調用 |
|
|
設定一句話識別參數、發送音頻和結束識別。非安全執行緒,每個識別任務建立一個對象,不重複用於其他任務;任務結束後調用 |
|
|
接收開始、中間結果、完成和失敗事件。非安全執行緒,與 |
NlsClient使用Netty,建立執行個體會消耗時間和資源。用戶端的建立和關閉可與應用生命週期保持一致;識別任務則分別建立和關閉SpeechRecognizer。更多方法,請參見Java API介面說明。
運行完整樣本包
也可以下載完整樣本工程,使用其中的調用程式和壓測程式。
解壓後,在工程根目錄運行mvn package。產生的可執行檔位於nls-example-recognizer/target/nls-example-recognizer-2.0.0-jar-with-dependencies.jar。將JAR包和配套音頻複製到目標伺服器後,運行以下命令,並按提示提供Appkey、NLS Token和可選的服務地址。程式會在工作目錄產生logs/nls.log。
java -cp nls-example-recognizer-2.0.0-jar-with-dependencies.jar com.alibaba.nls.client.SpeechRecognizerDemo
需要壓測時,使用以下命令,並按提示設定並發數:
java -jar nls-example-recognizer-2.0.0-jar-with-dependencies.jar
服務地址為wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1。
壓測使用16 kHz PCM音頻,並發數需在已開通服務的並發額度內。壓測調用同樣適用服務的計費規則,運行前確認服務版本、計費方式和並發額度。
常見問題
何時調用stop()?
音頻發送完成後,調用recognizer.stop()發送StopRecognition指令,並等待識別完成。開啟語音檢測(VAD)時,服務端也可以在檢測到語音結束後返回RecognitionCompleted事件。
語音發送期間需保持連續、即時的資料流;長時間未發送資料會觸發空閑逾時。需要中間結果時,在start()前調用setEnableIntermediateResult(true)。
如何識別本地音頻檔案?
本頁樣本從本地檔案讀取音頻,並按即時速度發送給服務端。也可以通過RESTful API上傳音頻檔案,調用方式請參見一句話識別RESTful API。
如何使用send()發送音頻?
一句話識別提供以下四個send()重載:
public void send(byte[] data);
public void send(byte[] data, int length);
public void send(InputStream ins);
public void send(InputStream ins, int batchSize, int sleepInterval);
send(byte[])、send(byte[], int)和send(InputStream)按資料到達或讀取的速度發送,不自動按音頻時間長度設定間隔。即時採集音頻時,按採集速度連續發送;從檔案類比即時資料流時,可使用帶batchSize和sleepInterval的方法控制發送速度。
16位、單聲道PCM音頻在16 kHz採樣率下,每100毫秒對應3200位元組;8 kHz時,3200位元組對應200毫秒。其他編碼格式需按壓縮後的資料量調整每批位元組數和發送間隔。發送間隔過大可能增加延遲或導致斷連,過小會增加服務端和網路資源消耗。
基於前面的完整樣本,發送16 kHz音頻檔案流可使用:
recognizer.send(audio, 3200, 100);
自行迴圈讀取檔案時,也可以使用send(byte[], int),或為完整的100毫秒音頻資料調用send(byte[]):
recognizer.send(data);
Thread.sleep(100);
上述data表示16 kHz、16位、單聲道PCM的3200位元組音頻;最後一批不足3200位元組時,使用send(data, length)傳入實際長度。
如何通過日誌分析延遲?
一句話識別的結束延遲,可以用發送StopRecognition到收到RecognitionCompleted的時間差計算。例如,兩條日誌的時間分別為14:24:44.844和14:24:44.984,對應延遲為140毫秒。
同樣的方法也適用於其他語音處理任務:
即時語音辨識使用
StopTranscription和TranscriptionCompleted的時間差。語音合成的首包延遲使用發送
StartSynthesis到收到首個音頻包的時間差。例如,14:32:13.813到14:32:14.035對應222毫秒。
完整樣本包已配置日誌。自行整合SDK時,按應用的日誌架構配置日誌輸出。通過RESTful API調用時,可在用戶端記錄請求和回應時間來計算延遲。
找不到com.alibaba的JAR包怎麼辦?
通過Alibaba Cloud SDK for Java擷取Token時,需安裝相應依賴。安裝方法,請參見V1.0 Java SDK。
org.json.JSONArray.iterator()報錯怎麼辦?
舊工程通過Alibaba Cloud SDK for Java擷取用戶端或Token時,若出現org.json.JSONArray.iterator()Ljava/util/Iterator方法不存在的錯誤,檢查運行時載入的JSON庫與SDK所需版本是否一致,並排除重複依賴。檢查org.json:json和com.google.code.gson:gson等相關依賴是否完整,使用與當前Alibaba Cloud SDK相容的版本。