跳转到主要内容
千问AI平台 home page
文档
Sambert

语音合成Sambert Android SDK

本文档提供了语音合成Sambert Android SDK的详细使用指南，帮助您将文本转换为高质量、富有表现力的语音。

**用户指南：**关于模型介绍和选型建议请参见语音合成-Sambert。 在线体验：暂不支持。

NativeNui

本SDK基于NativeNui单例架构，通过回调机制处理语音合成事件。 架构特点：

使用流程

  1. tts_initialize() - 初始化SDK，设置回调接口和连接参数
  2. setparamTts() - 设置语音合成效果参数（模型、音色、音量等）
  3. startTts() - 启动语音合成任务
  4. onTtsDataCallback() - 接收音频数据
  5. tts_release() - 释放SDK资源

Sambert 方法

tts_initialize

初始化语音合成SDK实例。SDK为单例模式，在调用 tts_release() 前禁止重复初始化。 此接口会引起阻塞，应在非UI线程调用。 方法签名： 
public synchronized int tts_initialize(INativeTtsCallback callback,
                                       String ticket,
                                       final Constants.LogLevel level,
                                       boolean save_log)
参数说明：
参数类型说明
callbackINativeTtsCallback事件和数据回调接口的实现。
ticketStringJSON字符串，包含鉴权、连接和调试参数。详见下方 ticket 参数说明。
levelConstants.LogLevel控制SDK自身日志的打印级别。
save_logboolean是否保存本地日志。若为true，须在 ticket 参数中通过debug_path指定路径，并可通过max_log_file_size设置文件大小。
ticket JSON 示例： 
{
    "url": "wss://maas.qianwenaiapi.com/api-ws/v1/inference",
    "apikey": "sk-****",
    "device_id": "my_device_id",
    "mode_type": "2"
}
ticket 参数说明：
参数类型是否必须说明
urlString是服务地址，固定为 wss://maas.qianwenaiapi.com/api-ws/v1/inference。
apikeyString是API Key。建议使用时效性短、安全性更高的临时API Key，以降低长期有效Key泄露的风险。
mode_typeString是模式类型。必须设置为字符串 "2"，代表在线语音合成模式。
device_idString是用于标识终端用户的唯一字符串，可设为应用内用户ID或客户端生成的设备唯一标识符。此ID主要用于日志追踪和问题排查。
debug_pathString否日志文件的存储路径。
此参数仅在调用tts_initialize接口时将save_log设为true时生效。此时必须设置日志文件路径，否则将报错。
本地最多保留两个日志文件。
max_log_file_sizeint否设定日志文件的最大字节数。
此参数仅在调用tts_initialize接口时将save_log设为true时生效。
默认值：104857600（100 * 1024 * 1024 字节, 即 100MiB）。
log_track_levelint否控制通过日志回调（onTtsLogTrackCallback）对外发送的日志内容的过滤级别。
默认值：2。
取值范围：
  • 0：LOG_LEVEL_VERBOSE
  • 1：LOG_LEVEL_DEBUG
  • 2：LOG_LEVEL_INFO
  • 3：LOG_LEVEL_WARNING
  • 4：LOG_LEVEL_ERROR
  • 5：LOG_LEVEL_NONE（表示关闭此功能）
注意：log_track_level与log_level（通过tts_initialize接口设置）共同决定最终回调的日志。一条日志的级别数值必须同时大于或等于log_track_level和log_level的值，才会被回调。例如，log_track_level设为2 (INFO)，log_level设为3 (WARNING)，则只有WARNING及以上级别（数值>=3）的日志才会被回调。

setparamTts

以键值对的形式设置语音合成效果参数。在 startTts() 之前调用。 方法签名： 
public synchronized int setparamTts(String param, String value)
参数说明：
参数类型说明
paramString参数名。
valueString参数值。
可用参数说明：
参数类型是否必须说明
modelString是模型名称，如 sambert-zhichu-v1。
formatString否音频编码格式。
取值范围：
  • pcm
  • wav（默认）
  • mp3
volumeString否音量。
默认值：50。
取值范围：[0, 100]。
sample_rateString否音频采样率（Hz）。
取值范围：8000, 16000（默认）, 22050, 24000。
rateString否语速。
默认值：1.0。
取值范围：[0.5, 2.0]。
pitchString否音调。
默认值：1.0。
取值范围：[0.5, 2.0]。
word_timestamp_enabledString否是否开启字级别时间戳。
默认值：false。
适用范围：所有 Sambert 模型。
phoneme_timestamp_enabledString否是否开启音素级别时间戳。
默认值：false。
需要先开启 word_timestamp_enabled。
enable_audio_decoderString否是否开启内置音频解码器。
默认值：0。
取值范围：
  • 1：开启。当 format 为 mp3 时，设为 "1" 可开启SDK内置解码器，此时 onTtsDataCallback 将返回解码后的PCM数据。
  • 0：关闭。

getparamTts

获取参数值。主要用于错误排查。 方法签名： 
public String getparamTts(String param);
参数说明：
参数类型说明
paramString参数名。目前仅支持"error_msg"。
返回值说明： 返回参数值。

startTts

启动语音合成任务。合成结果通过回调返回。 方法签名： 
public synchronized int startTts(String priority, String taskid, String text)
参数说明：
参数类型说明
priorityString任务优先级。请将其设为1。
taskidString任务ID。传入 null 时由SDK自动生成。
textString待合成文本。

pauseTts

暂停当前语音合成任务。任务暂停后，可通过 resumeTts() 恢复，或通过 cancelTts() 彻底取消。在任务暂停期间，SDK不支持启动新的合成任务。 注意：此操作仅暂停从服务端的数据拉取，播放器中已缓存的音频数据会继续播放。 方法签名： 
public synchronized int pauseTts()

resumeTts

恢复处于暂停的语音合成任务。 方法签名： 
public synchronized int resumeTts()

cancelTts

取消合成任务。 注意：此操作仅取消从服务端的数据拉取，播放器中已缓存的音频数据会继续播放。 方法签名： 
public synchronized int cancelTts(String taskid)
参数说明：
参数类型说明
taskidString要取消的任务ID。若传入 null，则取消所有正在暂停/进行中的合成任务。

tts_release

释放SDK所有内部资源，并强制终止所有正在进行的合成任务。此方法调用后，SDK实例将变为不可用状态，如需再次使用，必须重新调用 tts_initialize() 进行初始化。 方法签名： 
public synchronized int tts_release()

INativeTtsCallback

Sambert 语音合成回调接口，用于接收合成事件和音频数据。

onTtsEventCallback：监听事件

方法签名： 
void onTtsEventCallback(TtsEvent event, String task_id, int ret_code);
参数说明：
参数类型说明
eventTtsEvent回调事件。
task_idString语音合成任务ID。
ret_codeint仅在出现 TTS_EVENT_ERROR 事件时有效。

onTtsDataCallback：监听音频数据和时间戳信息

合成过程中，SDK 会连续触发此回调，需在回调中获取音频数据。 方法签名： 
void onTtsDataCallback(String info, int info_len, byte[] data);
参数说明：
参数类型说明
infoStringJSON格式的时间戳结果。word_timestamp_enabled设为"1"时生效。
info_lenintinfo字段的数据长度，可忽略。
databyte[]返回当前片段的音频数据。

onTtsLogTrackCallback：监听追踪日志

此回调用于接收 SDK 内部的详细日志，方便进行问题定位和调试。 方法签名： 
default void onTtsLogTrackCallback(Constants.LogLevel level, String log)

TtsEvent

Sambert 语音合成事件类型枚举。
事件说明
TTS_EVENT_START合成任务开始，即将有音频数据返回。
TTS_EVENT_END合成任务正常结束，所有音频数据已通过回调送出。
TTS_EVENT_CANCEL合成任务已取消。
TTS_EVENT_PAUSE合成任务已暂停。
TTS_EVENT_RESUME合成任务已恢复。
TTS_EVENT_ERROR合成过程中发生错误。此时可通过getparamTTS("error_msg")获取详细错误信息。 示例 1 请参见表格下方
示例 1（说明）： 
{
  "header": {
    "task_id": "xxxxxxxxx",
    "event": "task-failed",
    "error_code": "InvalidParameter",
    "error_message": "Please ensure input text is valid.",
    "attributes": {}
  },
  "payload": {}
}

示例代码

  1. 获取API Key：获取与配置 API Key，为安全起见，推荐将API Key配置到环境变量。
    当需要为第三方应用或用户提供临时访问权限，或者希望严格控制敏感数据访问、删除等高风险操作时，建议使用临时API Key。临时API Key默认拥有60秒有效期，过期后需重新获取。
  2. 下载SDK并运行示例代码：
    • 下载最新SDK整合包。
    • 解压 ZIP 包。在 app/libs 目录中获取 AAR 格式 SDK，并添加到项目依赖。
      需要 Android CPP 接入时，使用 ZIP 包内的 android_libs 与 android_include 获取动态库和头文件。

    • 用 Android Studio 打开工程。示例代码位于DashSambertTtsActivity.java，替换 API Key 后体验功能。

调用步骤

  1. 初始化 SDK。
  2. 按业务需求设置参数：通过tts_initialize接口的ticket参数设置连接与控制参数；通过setparamTts接口设置语音合成效果参数。
  3. 调用 startTts 开始语音合成。
  4. 在onTtsDataCallback回调中获取音频数据，建议使用流式播放。如需保存本地，按追加模式将音频写入同一文件，直到合成完成。
  5. 任务结束后，调用 tts_release 释放SDK资源。