SDK 简介

Dialog语音对话 SDK 是基于豆包端到端实时语音大模型，使用设备自身的录音机与播放器，提供低延迟、双向流式语音交互能力，可用于构建语音到语音的对话工具。

SDK版本

Android: com.bytedance.speechengine:speechengine_tob:0.0.7
iOS: pod 'SpeechEngineToB', '0.0.7'
该版本需要自行添加TTNet 依赖，否则Android 会崩溃，iOS 会编译报错。示例如下：
Android:

implementation 'com.bytedance.boringssl.so:boringssl-so:1.3.6'
implementation('org.chromium.net:cronet:4.2.210.3-tob') {
    exclude group: 'com.bytedance.common', module: 'wschannel'
}
implementation 'com.bytedance.frameworks.baselib:ttnet:4.2.210.3-tob'

iOS:

pod 'TTNetworkManager', '4.2.210.20'

Maven仓库

maven {
    url "https://artifact.bytedance.com/repository/Volcengine/"
}

组件依赖

// Network
implementation 'com.bytedance.boringssl.so:boringssl-so:{LATEST_VERSION}'
implementation('org.chromium.net:cronet:{LATEST_VERSION}') {
    exclude group: 'com.bytedance.common', module: 'wschannel'
}
implementation 'com.bytedance.frameworks.baselib:ttnet:{LATEST_VERSION}'

// Speech Engine
implementation 'com.bytedance.speechengine:speechengine_tob:{LATEST_VERSION}'

兼容性

AndroidManifest.xml 文件

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

混淆规则

-keep class com.bytedance.speech.speechengine.SpeechEngineImpl {*;}

初始化环境依赖

创建语音对话 SDK 引擎实例前调用，完成网络环境等相关依赖配置。APP 生命周期内仅需执行一次。

SpeechEngineGenerator.PrepareEnvironment(getApplicationContext(), getApplication());

创建引擎实例

SpeechEngine engine = SpeechEngineGenerator.getInstance();
engine.createEngine();

参数配置

其中 APPID 、TOKEN 获取方式参考 控制台使用FAQ-Q1 ，RESOURCE ID 设置为 volc.speech.dialog。

//【必需配置】Engine Name
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_ENGINE_NAME_STRING, SpeechEngineDefines.DIALOG_ENGINE);

//【可选配置】本地日志文件路径，SDK会在该路径文件夹下生成名为 speech_sdk.log 的日志文件，开发时设置，线上关闭。
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_DEBUG_PATH_STRING, "已存在的文件夹路径，或者空字符串");
//【可选配置】日志级别，开发时设置为 TRACE（最低级别），线上设置 WARN；
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_LOG_LEVEL_STRING, SpeechEngineDefines.LOG_LEVEL_TRACE);

//【必需配置】鉴权相关：Appid
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_APP_ID_STRING, "APPID");
//【必需配置】鉴权相关：AppKey
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_APP_KEY_STRING, "APPKEY");
//【必需配置】鉴权相关：Token
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_APP_TOKEN_STRING, "ACCESS TOKEN");
//【必需配置】对话服务资源信息ResourceId
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_RESOURCE_ID_STRING, "RESOURCE ID");
//【必需配置】User ID（用以辅助定位线上用户问题，如无法提供可提供固定字符串）
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_UID_STRING, "UID");
//【必需配置】对话服务域名
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_DIALOG_ADDRESS_STRING, "wss://openspeech.bytedance.com");
//【必需配置】对话服务Uri
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_DIALOG_URI_STRING, "/api/v3/realtime/dialogue");
//【可选配置】启用录音机音频回调，开启后录音音频数据将通过MESSAGE_TYPE_DIALOG_RECORDER_AUDIO消息回调，默认不启用
engine.setOptionBoolean(SpeechEngineDefines.PARAMS_KEY_DIALOG_ENABLE_RECORDER_AUDIO_CALLBACK_BOOL, false);
//【可选配置】启用播放器音频回调，开启后播放音频数据将通过MESSAGE_TYPE_DIALOG_PLAYER_AUDIO消息回调，默认不启用
engine.setOptionBoolean(SpeechEngineDefines.PARAMS_KEY_DIALOG_ENABLE_PLAYER_AUDIO_CALLBACK_BOOL, false);
//【可选配置】录音文件保存路径，如不为空字符串，则SDK会将录音机音频保存到该路径下，文件格式为 .wav
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_DIALOG_RECORDER_PATH_STRING, "已存在的文件夹路径，或者空字符串");
//【可选配置】播放文件保存路径，如不为空字符串，则SDK会将播放器音频保存到该路径下，文件格式为 .wav
engine.setOptionString(SpeechEngineDefines.PARAMS_KEY_DIALOG_PLAYER_PATH_STRING, "已存在的文件夹路径，或者空字符串");

初始化引擎实例

初始化引擎对象并设置回调监听。

// 初始化引擎实例
int ret = engine.initEngine();
if (ret != SpeechEngineDefines.ERR_NO_ERROR) {
    Log.e(SpeechDemoDefines.TAG, "初始化失败，返回值: " + ret);
    return;
}
engine.setContext(getApplicationContext());
engine.setListener(this);

发送指令

语音对话 SDK 通过发送指令接口 sendDirective 触发各种操作，需要注意不建议在 SDK 的回调线程中调用该接口。

启动引擎

启动引擎的传参，请参考端到端实时语音大模型API接入文档中 客户端事件 -> StartSession 的参数说明。

// 注意这里先调用同步停止，避免SDK内部异步线程带来的问题
engine.sendDirective(SpeechEngineDefines.DIRECTIVE_SYNC_STOP_ENGINE, "");
// 启动Dialog引擎
int ret = engine.sendDirective(SpeechEngineDefines.DIRECTIVE_START_ENGINE, "{\"dialog\":{\"bot_name\":\"豆包\"}}");
if (ret != SpeechEngineDefines.ERR_NO_ERROR) {
    Log.e(SpeechDemoDefines.TAG, "启动失败，返回值: " + ret);
    return;
}

播报开场白

播报开场白的传参，请参考端到端实时语音大模型API接入文档中 客户端事件 -> SayHello 的参数说明。

int ret = engine.sendDirective(SpeechEngineDefines.DIRECTIVE_DIALOG_SAY_HELLO, "{\"content\": \"我是你的AI助手，请问有什么可以帮你。\"}");
if (ret != SpeechEngineDefines.ERR_NO_ERROR) {
    Log.e(SpeechDemoDefines.TAG, "播报开场白失败，返回值: " + ret);
    return;
}

自定义TTS ：使用自定义文本回复

仅开启DIALOG_WORK_MODE_DELEGATE_CHAT_TTS_TEXT模式时可用：开启DIALOG_WORK_MODE_DELEGATE_CHAT_TTS_TEXT模式后，每轮TTS回复都需要选择 自定义文本回复 或 默认文本回复 ，否则将不会进行TTS播报。
自定义文本回复：播报自定义的文本内容，会替换Dialog 助手自动回复的文本。
自定义文本回复的传参，请参考端到端实时语音大模型API接入文档中 客户端事件 -> ChatTTSText 的参数说明。

// 初始化前，设置参数开启 DIALOG_WORK_MODE_DELEGATE_CHAT_TTS_TEXT 模式
engine.setOptionInt(SpeechEngineDefines.PARAMS_KEY_DIALOG_WORK_MODE_INT, SpeechEngineDefines.DIALOG_WORK_MODE_DELEGATE_CHAT_TTS_TEXT);

// ... 初始化引擎实例 ...

// ... 启动引擎 ...

// ... 接收到 MESSAGE_TYPE_DIALOG_ASR_ENDED 事件。标志用户已经说完一句话，等待回复 ...

// Directive：发送ChatTtsText指令以播放自定义回复文本，可以流式不断补充文本内容。首包需要包含start:true，end:false 。
String chatTtsTextJson = "{\"start\": true, \"content\": \"这里是自定义回复内容\", \"end\": false}";
int ret = engine.sendDirective(SpeechEngineDefines.DIRECTIVE_DIALOG_CHAT_TTS_TEXT, chatTtsTextJson);
if (ret != SpeechEngineDefines.ERR_NO_ERROR) {
    Log.e(SpeechDemoDefines.TAG, "自定义TTS回复失败: " + ret);
    return;
}
// Directive：发送ChatTtsText指令以播放自定义回复文本，可以流式不断补充文本内容。尾包需要包含start:false，end:true 。
chatTtsTextJson = "{\"start\": false, \"content\": \"\", \"end\": true}";
ret = engine.sendDirective(SpeechEngineDefines.DIRECTIVE_DIALOG_CHAT_TTS_TEXT, chatTtsTextJson);
if (ret != SpeechEngineDefines.ERR_NO_ERROR) {
    Log.e(SpeechDemoDefines.TAG, "自定义TTS回复失败: " + ret);
    return;
}

自定义TTS ：使用默认文本回复

仅开启DIALOG_WORK_MODE_DELEGATE_CHAT_TTS_TEXT模式时可用：开启DIALOG_WORK_MODE_DELEGATE_CHAT_TTS_TEXT模式后，每轮TTS回复都需要选择 自定义文本回复 或 默认文本回复 ，否则将不会进行TTS播报。
默认文本回复：播报Dialog 助手自动回复的文本。
默认文本回复的传参，使用空字符串即可。

// 初始化前，设置参数开启 DIALOG_WORK_MODE_DELEGATE_CHAT_TTS_TEXT 模式
engine.setOptionInt(SpeechEngineDefines.PARAMS_KEY_DIALOG_WORK_MODE_INT, SpeechEngineDefines.DIALOG_WORK_MODE_DELEGATE_CHAT_TTS_TEXT);

// ... 初始化引擎实例 ...

// ... 启动引擎 ...

// ... 接收到 MESSAGE_TYPE_DIALOG_ASR_ENDED 事件。标志用户已经说完一句话，等待回复 ...

// Directive：发送ChatTtsTextAuto指令以播放Dialog自身的回复文本。
int ret = engine.sendDirective(SpeechEngineDefines.DIRECTIVE_DIALOG_CHAT_TTS_TEXT_AUTO, "");
if (ret != SpeechEngineDefines.ERR_NO_ERROR) {
    Log.e(SpeechDemoDefines.TAG, "播放Dialog自动回复失败: " + ret);
    return;
}

停止引擎

// 会等待回调函数执行完成，不可在回调线程中执行。
engine.sendDirective(SpeechEngineDefines.DIRECTIVE_SYNC_STOP_ENGINE, "");

回调接收返回数据

启动引擎后，SDK会不断回调消息。其中Dialog类回调的消息内容，请参考端到端实时语音大模型API接入文档中 服务事件 说明。

@Override
public void onSpeechMessage(int type, byte[] data, int len) {
    String strData = new String(data);
    switch (type) {
        case SpeechEngineDefines.MESSAGE_TYPE_ENGINE_START:
            // Callback: 引擎启动成功回调
            Log.i(SpeechDemoDefines.TAG, "Callback: 引擎启动成功: " + strData);
            break;
        case SpeechEngineDefines.MESSAGE_TYPE_ENGINE_STOP:
            // Callback: 引擎关闭回调，启动引擎成功后，此消息必定发生且为最后一个回调消息
            Log.i(SpeechDemoDefines.TAG, "Callback: 引擎关闭: " + strData);
            break;
        case SpeechEngineDefines.MESSAGE_TYPE_ENGINE_ERROR:
            // Callback: 错误信息回调
            Log.e(SpeechDemoDefines.TAG, "Callback: 错误信息: " + type + " data: " + strData);
            break;
        case SpeechEngineDefines.MESSAGE_TYPE_DIALOG_ASR_INFO:
            // Callback: ASR语音识别开始,用户开始说话
            Log.i(SpeechDemoDefines.TAG, "Callback: ASR 识别开始");
            break;
        case SpeechEngineDefines.MESSAGE_TYPE_DIALOG_ASR_RESPONSE:
            // Callback: ASR语音识别结果回调
            Log.i(SpeechDemoDefines.TAG, "Callback: ASR 识别结果: " + strData);
            break;
        case SpeechEngineDefines.MESSAGE_TYPE_DIALOG_ASR_ENDED:
            // Callback: ASR语音识别结束，用户停止说话
            Log.i(SpeechDemoDefines.TAG, "Callback: ASR 识别结束");
            break;
        case SpeechEngineDefines.MESSAGE_TYPE_DIALOG_CHAT_RESPONSE:
            // Callback: Chat对话内容回调
            Log.i(SpeechDemoDefines.TAG, "Callback: Chat 回复内容: " + strData);
            break;
        case SpeechEngineDefines.MESSAGE_TYPE_DIALOG_CHAT_ENDED:
            // Callback: Chat回复结束
            Log.i(SpeechDemoDefines.TAG, "Callback: Chat 回复结束");
            break;
        default:
            break;
    }
}

销毁引擎实例

当不再需要语音对话后，建议对引擎实例进行销毁，释放内存资源。

// 内部会执行SYNC_STOP，不可在回调线程中执行。
engine.destroyEngine();
engine = null;

SpeechDemoAndroid.zip

未知大小

运行方法

1. 首先使用Android Studio 打开工程，修改 app/build.gradle 文件中的SDK依赖版本，并添加TTNet 依赖：

2. 打开 app/src/main/java/com/bytedance/speech/speechdemo/utils/SensitiveDefines.java ，要运行语音对话功能，至少需修改下述内容：

其中 APPID 、APPKEY、TOKEN 获取方式参考 控制台使用FAQ-Q1

RESOURCE ID 设置为 volc.speech.dialog。

3. 连接Android真机，点击三角号执行demo 构建即可。

4. 选择 语音交互 -> 对话交互 进入Dialog 测试页，对应的页面代码文件为 app/src/main/java/com/bytedance/speech/speechdemo/DialogActivity.java 。

5. 点击 Init Engine -> Start Engine 即可体验语音对话功能。