智能语音交互语音合成 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 { SpeechSynthesizer } from "alibabacloud-nls";

代码示例

示例使用 alibabacloud-nls 1.0.4，完成一次短文本合成，将音频保存到程序工作目录中的 output.wav。运行前，在程序运行环境中设置 NLS_APP_KEY 和 NLS_TOKEN，分别用于项目 Appkey 和访问 Token。

"use strict";

const fs = require("fs/promises");
const Nls = require("alibabacloud-nls");

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 client = new Nls.SpeechSynthesizer({
    url: "wss://nls-gateway.cn-shanghai.aliyuncs.com/ws/v1",
    appkey,
    token
  });
  const params = client.defaultStartParams("aixia");
  params.text = "欢迎使用智能语音交互。";
  const chunks = [];
  let timer;
  let finished = false;

  client.on("data", (data) => chunks.push(data));
  client.on("meta", (message) => console.log("Subtitle:", message));
  client.on("completed", () => { finished = true; });

  try {
    await new Promise((resolve, reject) => {
      timer = setTimeout(() => reject(new Error("Synthesis timed out.")), 60000);
      client.on("failed", (message) => reject(new Error(message)));
      client.on("closed", () => {
        if (!finished) reject(new Error("Connection closed before completion."));
      });
      client.start(params, true, 6000).then(resolve, reject);
    });
    await fs.writeFile("output.wav", Buffer.concat(chunks));
    console.log("Saved output.wav");
  } finally {
    clearTimeout(timer);
    client.shutdown();
  }
}

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

接口与参数

SpeechSynthesizer

SpeechSynthesizer 类用于语音合成，通过构造函数传入连接配置：

const client = new Nls.SpeechSynthesizer({ 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。

合成参数

在调用 start(params) 前设置合成参数。

参数	类型	必填	说明
`text`	String	是	待合成文本，采用 UTF-8 编码，长度不超过 300 个字符。英文文本按正常单词间隔书写。
`voice`	String	否	发音人。省略该字段时，服务端使用 `xiaoyun`。可选音色请参见音色列表。
`format`	String	否	音频编码格式，支持 `pcm`、`wav` 和 `mp3`。服务端在未收到该字段时使用 `pcm`；SDK 的 `defaultStartParams()` 返回 `wav`。
`sample_rate`	Integer	否	音频采样率，默认 16000 Hz。
`volume`	Integer	否	音量，取值范围为 0～100，默认 50。
`speech_rate`	Integer	否	语速，取值范围为 -500～500，默认 0。默认语速因音色而异。
`pitch_rate`	Integer	否	语调，取值范围为 -500～500，默认 0。
`enable_subtitle`	Boolean	否	是否开启字级别时间戳，默认 `false`。需使用支持该功能的音色，详情请参见时间戳功能。

说明

使用多情感音色时，在 text 中通过 SSML 的 <emotion> 标签设置情感。该标签仅适用于支持多情感的音色，其他音色使用该标签会导致合成失败。用法请参见emotion 标签。

可选择以下任一方式准备参数，并将得到的 params 对象传给 start()。两种方式的片段用于替换完整示例中的参数配置。

修改默认参数

defaultStartParams(voice) 返回以下对象。voice 为传入的音色；省略该参数时，该字段为 undefined，发送请求时不包含该字段。

{
  voice: voice,
  format: "wav",
  sample_rate: 16000,
  volume: 50,
  speech_rate: 0,
  pitch_rate: 0,
  enable_subtitle: false
}

获取默认对象后，可直接修改字段：

const params = client.defaultStartParams("aixia");
params.text = "欢迎使用智能语音交互。";
params.speech_rate = 100;

自定义参数对象

const params = {
  text: "欢迎使用智能语音交互。",
  voice: "aixia",
  format: "wav",
  sample_rate: 16000,
  volume: 50,
  speech_rate: 100,
  pitch_rate: 0,
  enable_subtitle: false
};

on(which, handler)

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

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

事件	说明	回调参数
`meta`	字幕信息，需开启 `enable_subtitle` 并使用支持该功能的音色。	1 个 String 参数。
`data`	合成音频分片。	1 个 Buffer 参数。
`completed`	语音合成完成。	1 个 String 参数。
`closed`	连接已关闭。	无参数。
`failed`	任务失败，返回错误信息。	1 个 String 参数。

String 参数为 JSON 字符串。data 事件可以触发多次，按接收顺序保存音频分片；完整示例在合成完成后将分片写入文件。

async start(param, enablePing, pingInterval)

发起语音合成。音频通过 data 事件返回；返回的 Promise 在 completed 事件发生时 resolve，值为完成事件的 JSON 字符串。任务错误或连接错误通过 reject 返回。

参数	类型	说明
`param`	Object	合成参数，见前面的合成参数说明。
`enablePing`	Boolean	是否自动发送 Ping 请求。默认 `false`；`true` 表示发送，`false` 表示不发送。
`pingInterval`	Number	Ping 间隔，单位为毫秒。开启 Ping 且未指定该值时，使用 6000。

shutdown()

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