在进行实时对话式 AI 场景下，你可以通过字幕功能，实时收到真人用户和智能体语音对话对应的文本内容，可用于应用终端实时显示字幕，保存对话记录用于分析、根据字幕返回时机手动触发新一轮对话等场景。
通过服务端和客户端均可实现该功能，你可根据字幕的使用场景选择对应的方式，如你选择在应用终端实时显示字幕，建议使用客户端实现该功能。

应用场景

前提条件

你已参考方案集成 构建一个完整的 AI 应用。

计费说明

该功能不额外收费，该场景计费项参看实时对话式 AI 计费。

客户端实现

你可按照以下步骤实现该场景下字幕功能：
步骤 1：开启字幕功能。
步骤 2：对收到的字幕结果进行解析。

步骤 1：开启字幕功能

你需要在调用 StartVoiceChat 接口开启智能体任务前，通过 Config.SubtitleConfig 结构配置以下字段开启客户端接收字幕功能和智能体字幕回调是否对齐时间戳功能：

你可以参考以下示例代码进行请求：

POST https://rtc.volcengineapi.com?Action=StartVoiceChat&Version=2024-12-01
{
    "AppId": "661e****543cf",
    "RoomId": "Room1",
    "TaskId": "task1",
    "Config": {
        "ASRConfig": {
            "Provider": "volcano",
            "ProviderParams": {
                "Mode": "bigmodel",
                "AppId": "93****21",
                "AccessToken": "MOaOa*****HA4h5B",
                "ApiResourceId": "volc.bigasr.sauc.duration",
                "StreamMode": 0
            }
        },
        "TTSConfig": {
            "Provider": "volcano_bidirection",
            "ProviderParams": {
                "app": {
                    "appid": "94****11",
                    "token": "OaO****ws1"
                },
                "audio": {
                    "voice_type": "zh_male_qingshuangnanda_mars_bigtts",
                    "speech_rate": 0,
                    "pitch_rate": 0
                },
                "ResourceId": "volc.service_type.10029"
            }
        },
        "LLMConfig": {
            "Mode": "ArkV3",
            "EndPointId": "epid****212",
            "MaxTokens": 1024,
            "Temperature": 0.1,
            "TopP": 0.3,
            "SystemMessages": [
                "你是小宁，性格幽默又善解人意。你在表达时需简明扼要，有自己的观点。"
            ],
            "UserPrompts": [
                {
                    "Role": "user",
                    "Content": "你好"
                },
                {
                    "Role": "assistant",
                    "Content": "有什么可以帮到你的？"
                }
            ],
            "HistoryLength": 3
        },
        "SubtitleConfig": {
            "DisableRTSSubtitle": false,
            "SubtitleMode": 0
        }
    },
    "AgentConfig": {
        "TargetUserId": [
            "user1"
        ],
        "WelcomeMessage": "Hello",
        "UserId": "BotName001"
    }
}

配置完成后，在真人用户与智能体对话期间，你可通过 onRoomBinaryMessageReceived （硬件场景下使用on_message_received）回调接收字幕结果。该回调中的 message 字段中的内容为字幕结果，格式为二进制，使用前需解析。

步骤 2：解析字幕结果

收到的字幕结果为二进制，你需要阅读下文了解其结构进行解析。
字幕回调格式如下：

二进制消息格式如下：

subtitle_message 格式：

data

subtitle_message 的示例如下：

{
"type": "subtitle",
"data" :[{
    "text": "上海天气炎热。气温为"
    "language": "zh"
    "userId": "bot1",
    "sequence":1,
    "definite":false,
    "paragraph":false
}]
}
{
"type": "subtitle",
"data" :[{
    "text": "上海天气炎热。气温为 30 摄氏度。"
    "language": "zh"
    "userId": "bot1",
    "sequence":2,
    "definite":true,
    "paragraph":false
}]
}

你可以参考以下示例代码对回调信息中的message内容进行解析。

//定义结构体
struct SubtitleMsgData {
    bool definite;
    std::string language;
    bool paragraph;
    int sequence;
    std::string text;
    std::string userId;
};

//回调事件
void onRoomBinaryMessageReceived(const char* uid, int size, const uint8_t* message) {
    std::string subtitles;
    bool ret = Unpack(message, size, subtitles);
    if(ret) {
        ParseData(subtitles);
    }
}

//拆包校验
bool Unpack(const uint8_t *message, int size, std::string& subtitles) {
    int kSubtitleHeaderSize = 8;
    if(size < kSubtitleHeaderSize) { 
        return false;
    }
    // magic number "subv"
    if(static_cast<uint32_t>((static_cast<uint32_t>(message[0]) << 24) 
           | (static_cast<uint32_t>(message[1]) << 16) 
           | (static_cast<uint32_t>(message[2]) << 8) 
           | static_cast<uint32_t>(message[3])) != 0x73756276U) {
        return false;
    }
    
    uint32_t length = static_cast<uint32_t>((static_cast<uint32_t>(message[4]) << 24) 
           | (static_cast<uint32_t>(message[5]) << 16) 
           | (static_cast<uint32_t>(message[6]) << 8) 
           | static_cast<uint32_t>(message[7]));
           
    if(size - kSubtitleHeaderSize != length) {
        return false;
    }

    if(length) {
        subtitles.assign((char*)message + kSubtitleHeaderSize, length);
    } else {
        subtitles = "";
    }
    return true;
}

//解析
void ParseData(const std::string& msg) {
    // 解析 JSON 字符串
    nlohmann::json json_data = nlohmann::json::parse(msg);
    // 存储解析后的数据
    std::vector<SubtitleMsgData> subtitles;
    // 遍历 JSON 数据并填充结构体
    for (const auto& item : json_data["data"]) {
        SubtitleMsgData subData;
        subData.definite = item["definite"];
        subData.language = item["language"];
        subData.paragraph = item["paragraph"];
        subData.sequence = item["sequence"];
        subData.text = item["text"];
        subData.userId = item["userId"];
        subtitles.push_back(subData);
    }
}

服务端实现

你可按照以下步骤实现该场景下字幕功能：
步骤 1：开启字幕功能。
步骤 2：对收到的字幕结果进行解析。

步骤 1：开启字幕功能

你需要在调用 StartVoiceChat 接口开启智能体任务前，通过 Config.SubtitleConfig 结构配置以下字段开启服务端接收字幕功能和智能体字幕回调是否对齐时间戳功能：