自定义语音播放--实时音视频-火山引擎

文档中心

实时音视频

进阶功能

自定义语音播放

在与智能体通话过程中，可随时传入自定义文本让智能体播报，并支持设置播报优先级来精确控制是立即插播，还是等待后播报。该功能可用于引导用户互动、提醒用户注意事项、或系统延迟时安抚用户等场景。

应用场景

场景	描述	示例
AI 陪练	用户长时间不说话时，智能体播放内容吸引用户继续互动。	"我注意到你有一会儿没说话了，需要我解释一下刚才的内容吗？"
桌游主持	智能体扮演主持人角色，引导用户完成游戏流程。	“现在轮到玩家 A 发言，请开始。”
安全监管	用户问题或大模型生成内容不合规时，引导用户调整会话内容。	"抱歉，对话内容不符合社区规范。"
延迟安抚	触发 Function Calling 或联网造成智能体回答延迟偏大时，引导用户耐心等待。	"正在处理，请稍等。"

实现方法

注意

建议传入完整分句或整句进行播放，高频送入碎片化文本可能会导致播放顺序错乱。

通过服务端实现

调用 UpdateVoiceChat 接口传入要播报的内容，并控制智能体的播报行为：

参数详细说明参见接口文档：音视频互动智能体-UpdateVoiceChat（2025-06-01）、实时对话式 AI-UpdateVoiceChat（2024-12-01）。

{
   "AppId": "YOUR_AppId", // 与 StartVoiceChat 的一致
  "RoomId": "YOUR_RoomId", // 与 StartVoiceChat 的一致
  "TaskId": "YOUR_TaskId", // 与 StartVoiceChat 的一致   
    "Command": "ExternalTextToSpeech", //必须为该值
    "Message": "你刚才的故事讲的真棒，能再讲一个吗。", // 要播报的文本内容，长度不超过 200 个字符。
    "InterruptMode": 1   // 按需选择播放优先级，可为 1、2、3
}

通过客户端实现

在客户端调用 RTC SDK 接口 sendUserBinaryMessage（以 Android 为例）发送需要播报的自定义文本给指定智能体。其中，

userId：填入智能体 ID（即 StartVoiceChat 配置的 AgentConfig.UserId）。
buffer：需遵循如下格式：

参数名	类型	描述
magic number	binary	消息格式，此处填入 `ctrl`。
length	binary	自定义文本消息长度，单位为 bytes。存放方式为大端序。
control_message	binary	自定义文本配置信息。JSON 格式，具体内容格式参看 control_message 格式。

control_message

参数名	类型	描述
Command	String	控制命令，此处填入 `ExternalTextToSpeech`。
Message	String	自定义文本内容，长度不超过 200 个字符。
InterruptMode	Int	文本内容播报的优先级。 `1`：高优先级。智能体会终止当前交互，直接播放传入的文本内容。 `2`：中优先级。智能体会在当前交互结束后，播放传入的文本内容。 `3`：低优先级。如果此时智能体正在交互，智能体会直接丢弃传入的文本内容。如果未在交互，智能体会播放传入的文本内容

参数名

类型

描述

Command

String

控制命令，此处填入 ExternalTextToSpeech。

Message

String

自定义文本内容，长度不超过 200 个字符。

InterruptMode

Int

文本内容播报的优先级。

1：高优先级。智能体会终止当前交互，直接播放传入的文本内容。
2：中优先级。智能体会在当前交互结束后，播放传入的文本内容。
3：低优先级。如果此时智能体正在交互，智能体会直接丢弃传入的文本内容。如果未在交互，智能体会播放传入的文本内容

你可参看以下示例传入自定义文本内容进行播放：

C++

Java

TypeScript

// 发送文本转语音（TTS）指令，让智能体播报指定的文本内容。
void sendTTSMessage(const std::string &uid, const std::string& content) {
    nlohmann::json json_data;
    json_data["Command"] = "ExternalTextToSpeech";
    json_data["Message"] = content;
    json_data["InterruptMode"] = 1; // InterruptMode 可选值1,2,3
    sendUserBinaryMessage(uid, json_data.dump());
}

void buildBinaryMessage(const std::string& magic_number, const std::string& message, size_t& binary_message_length, std::shared_ptr<uint8_t[]>& binary_message) {
    auto magic_number_length = magic_number.size();
    auto message_length = message.size();

    binary_message_length = magic_number_length + 4 + message_length;
    binary_message = std::shared_ptr<uint8_t[]>(new uint8_t[binary_message_length]);
    std::memcpy(binary_message.get(), magic_number.data(), magic_number_length);
    binary_message[magic_number_length] = static_cast<uint8_t>((message_length >> 24) & 0xFF);
    binary_message[magic_number_length+1] = static_cast<uint8_t>((message_length >> 16) & 0xFF);
    binary_message[magic_number_length+2] = static_cast<uint8_t>((message_length >> 8) & 0xFF);
    binary_message[magic_number_length+3] = static_cast<uint8_t>(message_length & 0xFF);
    std::memcpy(binary_message.get()+magic_number_length+4, message.data(), message_length);
}

int sendUserBinaryMessage(const std::string &uid, const std::string& message) {
    if (rtcRoom_ != nullptr)
    {
        size_t length = 0;
        std::shared_ptr<uint8_t[]> binary_message = nullptr;
        buildBinaryMessage("ctrl", message, length, binary_message);
        return rtcRoom_->sendUserBinaryMessage(uid.c_str(), static_cast<int>(length), binary_message.get());
    }
    return -1;
}

// 发送文本转语音（TTS）指令，让智能体播报指定的文本内容。
public void sendTTSMessage(String userId, String content) {
    JSONObject json = new JSONObject();
    try {
        json.put("Command", "ExternalTextToSpeech");
        json.put("Message", content);
        json.put("InterruptMode", 1); // InterruptMode 可选值1,2,3
    } catch (JSONException e) {
        throw new RuntimeException(e);
    }
    String jsonString = json.toString();
    byte[] buildBinary = buildBinaryMessage("ctrl", jsonString);
    sendUserBinaryMessage(userId, buildBinary);
}


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

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

public void sendUserBinaryMessage(String userId, byte[] buffer) {
    if (rtcRoom_ != null) {
        rtcRoom_.sendUserBinaryMessage(userId, buffer, MessageConfig.RELIABLE_ORDERED);
    }
}

import VERTC from '@volcengine/rtc';


const BotName = 'RobotMan_'; // 自定义智能体名称
const CommandKey = 'ctrl'; 
const engine = VERTC.createEngine('Your AppID'); // 你的 RTC 应用 APPId

/**
 * @brief 指令类型
 */
enum COMMAND {
  /**
   * @brief 发送文本转语音（TTS）指令，让智能体播报指定的文本内容。
   */
  EXTERNAL_TEXT_TO_SPEECH = 'ExternalTextToSpeech',
};

/**
 * @brief 打断的类型
 */
enum INTERRUPT_PRIORITY {
  /**
   * @brief 占位
   */
  NONE,
  /**
   * @brief 高优先级。智能体会终止当前交互，直接播放传入的文本内容。
   */
  HIGH,
  /**
   * @brief 中优先级。智能体会在当前交互结束后，播放传入的文本内容。
   */
  MEDIUM,
  /**
   * @brief 低优先级。如果此时智能体正在交互，智能体会直接丢弃传入的文本内容。如果未在交互，智能体会播放传入的文本内容
   */
  LOW,
};

/**
 * @brief 将字符串包装成 TLV
 */
function stringToTLV(inputString: string, type = '') {
  const typeBuffer = new Uint8Array(4);

  for (let i = 0; i < type.length; i++) {
    typeBuffer[i] = type.charCodeAt(i);
  }

  const lengthBuffer = new Uint32Array(1);
  const valueBuffer = new TextEncoder().encode(inputString);

  lengthBuffer[0] = valueBuffer.length;

  const tlvBuffer = new Uint8Array(typeBuffer.length + 4 + valueBuffer.length);

  tlvBuffer.set(typeBuffer, 0);

  tlvBuffer[4] = (lengthBuffer[0] >> 24) & 0xff;
  tlvBuffer[5] = (lengthBuffer[0] >> 16) & 0xff;
  tlvBuffer[6] = (lengthBuffer[0] >> 8) & 0xff;
  tlvBuffer[7] = lengthBuffer[0] & 0xff;

  tlvBuffer.set(valueBuffer, 8);

  return tlvBuffer.buffer;
};


/**
 * @brief 发送文本转语音（TTS）指令，让智能体播报指定的文本内容
 */
engine.sendUserBinaryMessage(
  BotName,
  stringToTLV(
    JSON.stringify({
      Command: COMMAND.EXTERNAL_TEXT_TO_SPEECH,
      Message: '自定义文本内容',
      InterruptMode: INTERRUPT_PRIORITY.HIGH,
    }),
    CommandKey,
  )
);

FAQ

Q1：如果设置智能体支持语音打断，自定义文本内容不打断智能体输出。本次交互被语音打断时，自定义文本内容何时播放？
A1：此时自定义文本内容会被丢弃。
Q2：播放的自定义文本内容是否会放入历史对话？
A2：会。
Q3：如果设置智能体支持语音打断，自定义文本内容不打断智能体输出。自定义文本内容播放时被打断，该文本内容是否会放在历史对话中？
A3：已输出的内容会放入历史对话中。

最近更新时间：2025.12.26 00:14:41

这个页面对您有帮助吗？

有用

无用