在 AI 进行语音播报时，您可以通过服务端 API 或客户端发送指令，随时暂停或恢复其音频播放，实现类似音乐播放器的暂停/继续效果。

应用场景

场景	描述
互动教学	在 AI 老师讲解时，学生可以随时暂停以记录笔记或深入思考，完成后再恢复播放。
内容收听	用户在收听长篇文章或故事时，可根据需要暂停和继续，自由控制收听节奏。
任务指导	在多步操作指导中，用户可以暂停每一步指令，待当前操作完成后再获取下一步指引。

使用限制

生效范围：该功能仅在 AI 正在进行 TTS 语音播报时生效，且仅对当前正在进行的对话轮次有效。当用户打断并开始新一轮对话时，上一轮的暂停状态会自动失效。

功能互斥：开启音频快速发送（AgentConfig.Burst）功能后，暂停或恢复 AI 音频播放功能将失效。

实现方式

您可以根据业务需求，选择通过服务端 API 或客户端 SDK 发送指令来控制 AI 的播报状态。

方式一：通过服务端实现

通过调用 UpdateVoiceChat 接口，将 Command 设置为 AudioCtrl，并通过 AudioConfig.Action 来控制暂停或恢复播放。

{​
    "AppId": "Your_AppId",​
    "RoomId": "Your_RoomId",​
    "TaskId": "Your_TaskId",​
    "Command": "AudioCtrl",​
    "AudioConfig": {​
         "Action": "pause"  // 暂停为 "pause"，恢复为 "play"​
    }​
}​

方式二：通过客户端实现

在客户端调用 ByteRTC SDK 的 sendUserBinaryMessage（以 Android 端为例）接口发送一个特定格式的二进制消息来实现打断。

userId：填入 AI 的 ID（即 StartVoiceChat 配置的 AgentConfig.UserId）。

buffer：需要传入特定格式的内容。

参数名	类型	描述
magic_number	binary	消息标识，固定为 ctrl。
length	binary	control_message 的长度，4 字节，大端序。
control_message	binary	JSON 格式的控制指令，采用 JSON 格式，包含内容如下： { "Command": "AudioCtrl", //固定值 "AudioConfig": { "Action": "pause" // 暂停为 "pause"，恢复为 "play" } }

代码示例：

Java
C++
TypeScript

// 暂停播放示例
public void pauseAudio(String botUserId) {
JSONObject json = new JSONObject();
try {
JSONObject audioConfig = new JSONObject();
audioConfig.put("Action", "pause");

json.put("Command", "AudioCtrl");
json.put("AudioConfig", audioConfig);
} catch (JSONException e) {
e.printStackTrace();
}

byte[] buildBinary = buildBinaryMessage("ctrl", json.toString());
rtcRoom.sendUserBinaryMessage(botUserId, buildBinary, MessageConfig.RELIABLE_ORDERED);
}

private byte[] buildBinaryMessage(String magic_number, String content) {
byte[] prefixBytes = magic_number.getBytes(StandardCharsets.UTF_8);
byte[] contentBytes = content.getBytes(StandardCharsets.UTF_8);

ByteBuffer buffer = ByteBuffer.allocate(prefixBytes.length + 4 + contentBytes.length);
buffer.order(ByteOrder.BIG_ENDIAN);
buffer.put(prefixBytes);
buffer.putInt(contentBytes.length);
buffer.put(contentBytes);
return buffer.array();
}

进阶：音频和字幕同步暂停和续播

暂停和恢复播放功能本身不依赖于字幕。若希望在暂停/恢复时，字幕也能同步暂停和恢复渲染，您必须在调用 StartVoiceChat 接口时，将 SubtitleConfig.SubtitleMode 设置为 2（音频帧对齐字幕）。详情请参见音频和字幕同步（音频帧对齐字幕）。

实时音视频