语音合成 Python SDK 安装与调用-智能语音交互(ISI)-阿里云帮助中心

使用智能语音交互 Python SDK 将文本合成为音频，通过回调接收音频数据、合成结果和字幕信息。

前提条件

已创建项目并获取 Appkey。具体操作，请参见管理项目。
已获取有效的 NLS Token。获取方式，请参见获取 Token。

服务地址、音色和输入文本等要求，请参见语音合成接口说明。

获取和安装 SDK

SDK 仅支持 Python 3，不支持 Python 2。以下示例使用 SDK 1.1.0。

从 GitHub 获取源码，或下载Python SDK 源码包并解压。
安装构建工具 setuptools。
```
python -m pip install setuptools
```

进入 SDK 根目录，安装依赖和 SDK。

python -m pip install -r requirements.txt
python -m pip install .

安装完成后，在 Python 代码中导入 SDK：

import nls

代码示例

在程序运行环境中，将项目 Appkey 和 NLS Token 分别设置为环境变量 NLS_APP_KEY 和 NLS_TOKEN。以下示例使用 ailun 音色合成文本，并将音频保存为 output.pcm。

import os

import nls

URL = "wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1"
APPKEY = os.environ["NLS_APP_KEY"]
TOKEN = os.environ["NLS_TOKEN"]
TEXT = "你好，欢迎使用语音合成。"

def on_metainfo(message, *args):
    print("Subtitle information:", message)

def on_completed(message, *args):
    print("Synthesis completed:", message)

def on_error(message, *args):
    print("Synthesis failed:", message)

def on_close(*args):
    print("Connection closed.")

nls.enableTrace(False)

with open("output.pcm", "wb") as audio_file:
    synthesizer = nls.NlsSpeechSynthesizer(
        url=URL,
        token=TOKEN,
        appkey=APPKEY,
        on_metainfo=on_metainfo,
        on_data=lambda data, *args: audio_file.write(data),
        on_completed=on_completed,
        on_error=on_error,
        on_close=on_close,
    )
    try:
        synthesizer.start(TEXT, voice="ailun")
    finally:
        synthesizer.shutdown()

对实时播放延迟要求较高时，可以在 on_data 回调中边接收音频边播放。

说明

华东 2（上海）地域的 ECS 实例通过 VPC 内网访问时，将 URL 设置为 ws://nls-gateway-cn-shanghai-internal.aliyuncs.com:80/ws/v1。

说明

使用多情感音色时，在 text 中通过 SSML 的 <emotion> 标签设置情感。该标签仅适用于支持多情感的音色；用于其他音色时，请求会返回 Illegal ssml text。具体用法，请参见SSML 标记语言介绍。

获取字幕和时间戳

使用支持时间戳的音色时，将基础示例中的 start 调用替换为以下代码。字幕信息通过 on_metainfo 回调返回。

synthesizer.start(TEXT, voice="ailun", ex={"enable_subtitle": True})

需要音素级时间戳时，同时传入 enable_phoneme_timestamp=True：

synthesizer.start(
    TEXT,
    voice="ailun",
    ex={"enable_subtitle": True, "enable_phoneme_timestamp": True},
)

音色支持范围和时间戳字段说明，请参见时间戳功能介绍。

关键接口

语音合成使用 nls.NlsSpeechSynthesizer 类。

初始化（init）

创建合成对象，设置服务地址、鉴权信息和回调函数。

参数	类型	说明
`url`	str	WebSocket 服务地址。SDK 默认值为 `wss://nls-gateway.cn-shanghai.aliyuncs.com/ws/v1`。
`token`	str	用于服务鉴权的 NLS Token，必填。
`appkey`	str	项目 Appkey，必填。
`long_tts`	bool	是否使用实时长文本语音合成。`True` 表示长文本模式，`False` 表示短文本模式，默认为 `False`。
`on_metainfo`	Callable	收到 `MetaInfo` 事件时调用。第一个参数是包含字幕等信息的 JSON 字符串，后续参数为展开后的 `callback_args`。返回内容取决于请求配置和音色支持情况。
`on_data`	Callable	收到音频数据时调用。第一个参数是 `bytes` 类型的音频数据，格式由 `start()` 的 `aformat` 指定，后续参数为展开后的 `callback_args`。
`on_completed`	Callable	收到 `SynthesisCompleted` 事件时调用。第一个参数是合成完成事件的 JSON 字符串，后续参数为展开后的 `callback_args`。
`on_error`	Callable	收到服务端 `TaskFailed` 事件时调用。第一个参数是错误事件的 JSON 字符串，后续参数为展开后的 `callback_args`。
`on_close`	Callable	连接关闭时调用，参数为展开后的 `callback_args`。
`callback_args`	list	自定义回调参数列表，默认为空列表。列表元素通过 `*callback_args` 展开传入回调；例如 `["a", "b"]` 对应两个位置参数。

回调函数未设置时，不执行相应的用户回调。初始化方法无返回值。

start

开始语音合成。默认等待合成结束；wait_complete=False 时，等待连接建立后返回，合成数据和事件继续通过回调接收。

参数	类型	说明
`text`	str	待合成文本。
`voice`	str	音色，默认为 `xiaoyun`。
`aformat`	str	输出音频格式，支持 `pcm`、`wav` 和 `mp3`，默认为 `pcm`。
`sample_rate`	int	合成输出音频采样率，单位为 Hz，默认为 `16000`。
`volume`	int	音量，取值范围为 0～100，默认为 `50`。
`speech_rate`	int	语速，取值范围为 -500～500，默认为 `0`。
`pitch_rate`	int	语调，取值范围为 -500～500，默认为 `0`。
`wait_complete`	bool	是否等待合成完成，默认为 `True`。设置为 `False` 时，应用需保留连接和音频接收资源，直至合成结束。
`start_timeout`	int	等待连接建立的超时时间，单位为秒，默认为 `10`。
`completed_timeout`	int	等待合成完成的超时时间，单位为秒，默认为 `60`。在 `wait_complete=True` 时生效。
`ex`	dict	额外请求参数，默认为 `None`。字典内容合并到请求的 `payload` 中，例如 `enable_subtitle` 和 `enable_phoneme_timestamp`。参数及其适用条件取决于对应服务和音色。

start() 无返回值。合成完成时调用 on_completed，服务端任务失败时调用 on_error。参数校验失败或等待超时时，调用可能抛出 InvalidParameter、StartTimeoutException 或 CompleteTimeoutException 等异常。

shutdown

关闭当前请求的连接；未完成的合成随连接关闭而终止。调用 start() 创建连接后，可以重复调用 shutdown()。

无参数，无返回值。

多线程与并发

在启用全局解释器锁（GIL）的 CPython 中，同一时刻只有一个线程执行 Python 代码，部分扩展库可释放 GIL。处理多个 I/O 密集型任务时，可以使用多线程；需要利用多核执行 CPU 密集型任务时，建议使用 multiprocessing 或 concurrent.futures.ProcessPoolExecutor。

单个解释器中的线程过多会增加线程切换开销，也可能导致 SDK 运行异常。不建议在单个解释器中使用超过 200 个线程；需要更多线程时，推荐使用多进程或启动多个解释器。

并发合成时，为每个任务创建独立的合成对象，并使用不同的音频输出文件。