智能语音交互一句话识别 Node.js SDK 使用说明-智能语音交互(ISI)-阿里云帮助中心

使用一句话识别 Node.js SDK 将音频转换为文本。本页提供安装方法、完整调用示例，以及连接配置、参数和事件说明。

前提条件

已安装 Node.js 14 或以上版本及 npm，并完成环境配置。
已获取项目 Appkey 和访问 Token。项目配置请参见管理项目，Token 获取方法请参见获取 Token。
了解音频要求和服务参数，详情请参见一句话识别接口说明。

安装 SDK

在项目目录中安装 SDK：

npm install alibabacloud-nls

代码示例使用 CommonJS 导入 SDK。ES Module 项目可以使用命名导入：

import { SpeechRecognition } from "alibabacloud-nls";

代码示例

示例使用 alibabacloud-nls 1.0.4，识别一次本地音频。运行前，在程序运行环境中设置 NLS_APP_KEY 和 NLS_TOKEN，分别用于项目 Appkey 和访问 Token。

下载官方 SDK 提供的示例音频 test1.pcm，放到程序工作目录。该文件为 16 kHz、单声道、16 bit PCM 音频，内容为中文数字。使用其他音频时，需相应调整文件路径、音频参数和发送间隔。

"use strict";

const fs = require("fs/promises");
const Nls = require("alibabacloud-nls");
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function main() {
  const appkey = process.env.NLS_APP_KEY;
  const token = process.env.NLS_TOKEN;
  if (!appkey || !token) {
    throw new Error("Set NLS_APP_KEY and NLS_TOKEN.");
  }
  const audio = await fs.readFile("test1.pcm");
  const client = new Nls.SpeechRecognition({
    url: "wss://nls-gateway.cn-shanghai.aliyuncs.com/ws/v1",
    appkey,
    token
  });
  let timer;
  let finished = false;

  try {
    await new Promise((resolve, reject) => {
      timer = setTimeout(() => reject(new Error("Recognition timed out.")), 60000);
      client.on("failed", (message) => reject(new Error(message)));
      client.on("closed", () => {
        if (!finished) reject(new Error("Connection closed before completion."));
      });
      client.on("changed", (message) => {
        console.log("Intermediate:", JSON.parse(message).payload.result);
      });
      client.on("completed", (message) => {
        finished = true;
        console.log("Result:", JSON.parse(message).payload.result);
        resolve(message);
      });

      (async () => {
        await client.start(client.defaultStartParams(), true, 6000);
        for (let offset = 0; offset < audio.length; offset += 1024) {
          if (!client.sendAudio(audio.subarray(offset, offset + 1024))) {
            throw new Error("Audio could not be sent.");
          }
          await sleep(32);
        }
        await client.close();
      })().catch(reject);
    });
  } finally {
    clearTimeout(timer);
    client.shutdown();
  }
}

main().catch((error) => {
  console.error(error.message || error);
  process.exitCode = 1;
});

示例按该 PCM 文件的数据速率，每 32 毫秒发送 1024 字节，并将本次调用的最长等待时间设为 60 秒。最终结果通过 completed 事件获取。

接口与参数

SpeechRecognition

SpeechRecognition 类用于一句话识别，通过构造函数传入连接配置：

const client = new Nls.SpeechRecognition({ url, appkey, token });

参数	类型	说明
`config`	Object	连接配置对象，包含以下必填字段。
`config.url`	String	服务地址，需显式配置。示例使用 `wss://nls-gateway.cn-shanghai.aliyuncs.com/ws/v1`。
`config.appkey`	String	项目 Appkey。
`config.token`	String	访问 Token。

defaultStartParams()

无参数，返回默认识别参数对象：PCM 格式、16000 Hz 采样率，中间结果、标点预测和逆文本标准化（ITN）均开启。可结合一句话识别接口说明增减或修改字段。

{
  "format": "pcm",
  "sample_rate": 16000,
  "enable_intermediate_result": true,
  "enable_punctuation_prediction": true,
  "enable_inverse_text_normalization": true
}

on(which, handler)

注册事件回调，无返回值。应在发起任务前完成注册。

参数	类型	说明
`which`	String	事件名称，见下表。
`handler`	Function	事件处理函数。

事件	说明	回调参数
`started`	一句话识别已开始，返回开始事件。	1 个 String 参数。
`changed`	返回中间识别结果。	1 个 String 参数。
`completed`	一句话识别完成，返回最终识别结果。	1 个 String 参数。
`closed`	连接已关闭。	无参数。
`failed`	任务失败，返回错误信息。	1 个 String 参数。

String 参数为 JSON 字符串，可通过 JSON.parse(message) 读取事件字段。

async start(param, enablePing, pingInterval)

发起一次一句话识别。返回 Promise，在 started 事件发生时 resolve，值为开始事件的 JSON 字符串；连接错误通过 reject 返回。任务错误通过 failed 事件返回，连接关闭通过 closed 事件通知。

参数	类型	说明
`param`	Object	一句话识别参数，可从 `defaultStartParams()` 获取默认对象。
`enablePing`	Boolean	是否自动发送 Ping 请求。默认 `false`；`true` 表示发送，`false` 表示不发送。
`pingInterval`	Number	Ping 间隔，单位为毫秒。开启 Ping 且未指定该值时，使用 6000。

重要

在 alibabacloud-nls 1.0.4 中，任务在开始前失败时，failed 事件仍会触发，但 start() 的 Promise 可能保持等待。调用方需同时处理 failed、意外关闭和超时；前面的完整示例已包含这些处理。

async close(param)

发送结束指令，停止一句话识别。返回 Promise，在 completed 事件发生时 resolve，值为完成事件的 JSON 字符串；等待完成期间收到的任务错误通过 reject 返回。应同时保留 failed 和 closed 事件处理。

参数	类型	说明
`param`	Object	可选的结束参数，详情请参见一句话识别接口说明。

sendAudio(data)

发送音频数据，音频格式、采样率等需与开始参数一致。

参数	类型	说明
`data`	Buffer	二进制音频数据。

返回 Boolean：客户端不存在时返回 false；客户端存在并调用发送时返回 true。识别结果通过事件回调获取。

shutdown()

强制断开连接。无参数，无返回值。在调用结束或异常退出时释放连接。