实时音视频
实时音视频
文档指南
请输入
- 文档首页
实时音视频实时音视频开发指南实时通话字幕和翻译
复制全文
下载 pdf实时通话字幕和翻译
文档反馈
问问助手注意
功能介绍
通过实时字幕功能，可以将用户的语音实时转换为文字，并支持将文字翻译成其他语言，可用于直播字幕、会议记录生成、跨语言沟通实时翻译等场景。
- 支持通过客户端或服务端实现该功能。
- 根据使用场景的不同，可生成以下 2 种类型的字幕：
-
-
计费说明
使用实时字幕功能除基础音视频通话费以外，还会产生以下费用：
生成字幕
按源语言生成字幕（识别模式）
- 开通服务。
- 开通流式语音识别服务：前往豆包语音控制台_流式语音识别，创建流式语音识别应用，服务类型选择 流式语音识别，并记录 APP ID，Access Token，和语言的 Cluster ID，以备使用。
- 开启实时字幕：前往 RTC 控制台_实时字幕进行以下操作：
- 实时字幕：开启开关。
- 流式语音识别：开启开关，并按照提示填入 APP ID、Access Token 和语言的 Cluster ID。
- 生成字幕并接收字幕。
- 通过客户端实现：字幕结果仅可返回至客户端，但是无需解析。
- 通过服务端实现：字幕结果仅可返回至客户端或服务端，字幕为二进制数据，使用前需先解析。
-
- （可选）调用 joinRoom 接口进房时，设置源语言。
- 进房后，调用 startSubtitle 启动字幕服务。模式（mode）选择翻译模式，并指定字幕要翻译的语言。
- 通过 onSubtitleStateChanged 回调接收字幕生成结果。
- 准备字幕接收地址。
- 字幕数据可通过客户端或服务端接收：
- 当接收地址包括客户端：必须在客户端监听 onRoomBinaryMessageReceived 回调来接收字幕数据。
- 当接收地址包括服务端：准备服务端接收的 Url 地址，字幕会按照每句话返回给该地址。
- 调用 StartSubtitle 生成字幕。
- 以用户源语言分别为中文和日语，示例如下：
{"AppId": "661e****543cf","RoomId": "Room1","TaskId": "Task1", //自定义任务 ID"LanguageConfig": {// 指定说话者的原始语言（源语言）// 若为用户设置了源语言，生成的字幕文本为用户源语言；若未设置，则默认生成的字幕文本为中文，如果用户语言不是中文，生成的字幕结果可能会异常"SourceLanguages": [ {"UserId": "user1", //用户1 的 ID"LanguageCode": ["zh"] // 源语言为中文（仅支持 zh、ja、en）},{"UserId": "user2", //用户2 的 ID"LanguageCode": ["ja"] // 源语言为日语（仅支持 zh、ja、en）}]},"DistributionMode": 3, // 字幕结果同时回调给客户端和服务器// 配置服务器"ServerMessage": {"Signature": "TestSignature", // 鉴权签名"Url": "http://127.0.0.1:8080/subtitlemsg" // 接收字幕结果的服务器地址},// 回调地址包含客户端时，可指定字幕接收用户"ReceiverList": ["user1", "user2"] // 若指定了用户，只有指定用户可以看到字幕；若未指定，房间内所有用户都可以看到字幕 }
生成指定语言的字幕（翻译模式）
- 开通服务。
- 开通机器翻译服务：具体操作，请参见开通服务。
- 开通实时字幕服务：前往 RTC 控制台_实时字幕，开启实时字幕和实时语音翻译的开关。
- 生成字幕并接收字幕结果。
- 客户端生成：字幕结果仅可返回至客户端，但是无需解析。
- 服务端生成：字幕结果仅可返回至客户端或服务端，字幕为二进制数据，使用前需先解析。
-
- （可选）调用 joinRoom 接口进房时，设置源语言。
- 进房后，调用 startSubtitle 启动字幕服务。模式（mode）选择翻译模式，并指定字幕要翻译的语言。
- 通过 onSubtitleStateChanged 回调接收字幕生成结果。
- 当不再需要字幕功能时，调用 stopSubtitle 关闭字幕。
- 准备字幕接收地址。
- 字幕数据可通过客户端或服务端接收：
- 当接收地址包括客户端：必须在客户端监听 onRoomBinaryMessageReceived 回调来接收字幕数据。
- 当接收地址包括服务端：准备服务端接收的 Url 地址，字幕会按照每句话返回给该地址。
- 调用 StartSubtitle 生成字幕。
- 服务端生成的字幕数据为 Base64 编码的二进制格式，使用前需解析。字幕格式和解析示例，请参见解析字幕。
以用户源语言分别为中文和日语，字幕翻译为英文为例，示例如下：{"AppId": "661e****543cf","RoomId": "Room1","TaskId": "Task1", //自定义任务 ID"LanguageConfig": {// 指定说话者的原始语言（源语言）// 若为用户设置了源语言，生成的字幕文本为用户源语言；若未设置，则默认生成的字幕文本为中文，如果用户语言不是中文，生成的字幕结果可能会异常"SourceLanguages": [ {"UserId": "user1", //用户1 的 ID"LanguageCode": ["zh"] // 源语言为中文（仅支持 zh、ja、en）}{"UserId": "user2", //用户2 的 ID"LanguageCode": ["ja"] // 源语言为日语（仅支持 zh、ja、en）}],"RoomTargetLanguages": ["en"] // 字幕翻译为英文},"DistributionMode": 3, // 字幕结果同时回调给客户端和服务器// 配置服务器"ServerMessage": {"Signature": "TestSignature", // 鉴权签名"Url": "http://127.0.0.1:8080/subtitlemsg" // 接收字幕结果的服务器地址},// 回调地址包含客户端时，可指定字幕接收用户"ReceiverList": ["user1", "user2"] // 若指定了用户，只有指定用户可以看到字幕；若未指定，房间内所有用户都可以看到字幕 }
解析字幕
解析回调到服务端的字幕
字幕消息会通过 HTTP(S) POST 请求发送给您指定的 URL 地址。
参数名 | 类型 | 描述 |
message | String | |
signature | String | 鉴权签名。可与 startSubtitle 接口中传入的 signature 字段值进行对比，以进行鉴权验证。 |
message 解析示例
你可以参考以下示例代码对回调信息中的message内容进行解析。
const (
subtitleHeader = "subc"
exampleSignature = "example_signature"
)
type RtsMessage struct {
Message string `json:"message"`
Signature string `json:"signature"`
}
type subc struct {
Type string `json:"type"`
Data []Data `json:"data"`
}
type Data struct {
Definite bool `json:"definite"`
Paragraph bool `json:"paragraph"`
Language string `json:"language"`
Sequence int `json:"sequence"`
Text string `json:"text"`
UserID string `json:"userId"`
}
func HandleSubtitle(c *gin.Context) {
msg := &RtsMessage{}
if err := c.BindJSON(&msg); err != nil {
fmt.Printf("BindJson failed,err:%v\\n", err)
return
}
if msg.Signature != exampleSignature {
fmt.Printf("Signature not match\\n")
return
}
subc, err := Unpack(msg.Message)
if err != nil {
fmt.Printf("Unpack failed,err:%v\\n", err)
return
}
fmt.Println(subc)
//业务逻辑
c.String(200, "ok")
}
func Unpack(msg string) (*subc, error) {
data, err := base64.StdEncoding.DecodeString(msg)
if err != nil {
return nil, fmt.Errorf("DecodeString failed,err:%v", err)
}
if len(data) < 8 {
return nil, fmt.Errorf("Data invalid")
}
dataHeader := string(data[:4])
if dataHeader != subtitleHeader {
return nil, fmt.Errorf("Header not match")
}
dataSize := binary.BigEndian.Uint32(data[4:8])
if dataSize+8 != uint32(len(data)) {
return nil, fmt.Errorf("Size not match")
}
subData := data[8:]
subc := &subc{}
err = json.Unmarshal(subData, subc)
if err != nil {
return nil, fmt.Errorf("Unmarshal failed,err:%v\\n", err)
}
return subc, nil
}
func main() {
r := gin.Default()
r.POST("/example_domain/vertc/subtitle", HandleSubtitle)
r.Run()
}
import base64
import json
import struct
from flask import Flask, request, jsonify
app = Flask(__name__)
# 固定的参数值
SUBTITLE_HEADER = "subc"
EXAMPLE_SIGNATURE = "此处替换为客户调用StartSubtitle接口传入的signature即可"
# 定义字幕消息的数据结构
class SubtitleMessage:
def __init__(self, type: str, data: list):
self.type = type
self.data = data
class SubtitleData:
def __init__(self, text: str, language: str, user_id: str, sequence: int, definite: bool, paragraph: bool):
self.text = text
self.language = language
self.user_id = user_id
self.sequence = sequence
self.definite = definite
self.paragraph = paragraph
def parse_subtitle_message(message: str) -> SubtitleMessage:
try:
decoded_data = base64.b64decode(message)
except Exception as e:
raise ValueError(f"Base64 decoding failed: {e}")
if len(decoded_data) < 8:
raise ValueError("Data invalid: length is less than 8 bytes")
magic_number = decoded_data[:4].decode() # 前4个字节为 magic number
if magic_number != SUBTITLE_HEADER:
raise ValueError(f"Invalid magic number. Expected '{SUBTITLE_HEADER}', but got '{magic_number}'")
# 提取字幕消息长度（4字节，Big-endian）
length = struct.unpack(">I", decoded_data[4:8])[0]
if len(decoded_data) != length + 8:
raise ValueError(f"Size mismatch. Expected {length + 8}, but got {len(decoded_data)}")
# 提取字幕消息详细信息
subtitle_message_data = decoded_data[8:]
try:
subtitle_message_dict = json.loads(subtitle_message_data)
except Exception as e:
raise ValueError(f"JSON parsing failed: {e}")
# 验证字幕消息的 type
if subtitle_message_dict.get("type") != "subtitle":
raise ValueError(f"Invalid type. Expected 'subtitle', but got '{subtitle_message_dict.get('type')}'")
# 构造 SubtitleMessage 对象
data_list = subtitle_message_dict.get("data", [])
subtitle_data_objects = [
SubtitleData(
text=item.get("text"),
language=item.get("language"),
user_id=item.get("userId"),
sequence=item.get("sequence"),
definite=item.get("definite"),
paragraph=item.get("paragraph")
)
for item in data_list
]
return SubtitleMessage(type=subtitle_message_dict["type"], data=subtitle_data_objects)
@app.route("/", methods=["POST"])
def handle_subtitle():
try:
request_data = request.get_json(force=True)
message = request_data.get("message")
signature = request_data.get("signature")
except Exception as e:
print(f"Request JSON parsing failed: {e}")
return jsonify({"error": "Invalid request format"}), 400
if signature != EXAMPLE_SIGNATURE:
print("Signature mismatch")
return jsonify({"error": "Unauthorized"}), 403
# 解析字幕消息
try:
subtitle_message = parse_subtitle_message(message)
print("Parsed subtitle message:", subtitle_message)
for subtitle_data in subtitle_message.data:
print(f"[Subtitle] Text: {subtitle_data.text}, Language: {subtitle_data.language}, "
f"User ID: {subtitle_data.user_id}, Sequence: {subtitle_data.sequence}, "
f"Definite: {subtitle_data.definite}, Paragraph: {subtitle_data.paragraph}")
return jsonify({"status": "ok"}), 200
except Exception as e:
print(f"Subtitle message parsing failed: {e}")
return jsonify({"error": str(e)}), 500
if __name__ == "__main__":
app.run(debug=True)
解析回调到客户端的字幕
字幕回调消息格式如下：
参数名 | 类型 | 描述 |
uid | String | 消息发送者 ID。 |
message | String |
message 解析示例
你可以参考以下示例代码对回调信息中的 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 "subc"
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(subtitles);
// 存储解析后的数据
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);
}
}
//数据格式
public class SubtitleMsgData {
public boolean definite;
public String language;
public boolean paragraph;
public int sequence;
public String text;
public String userId;
@Override
public String toString() {
return "SubtitleMsgData{" +
"definite=" + definite +
", language='" + language + "'" +
", paragraph=" + paragraph +
", sequence=" + sequence +
", text='" + text + '\'' +
", userId='" + userId + '\'' +
'}';
}
}
//回调
public void onRoomBinaryMessageReceived(String uid, ByteBuffer buffer) {
StringBuilder subtitles = new StringBuilder();
boolean ret = unpack(buffer, subtitles);
if (ret) {
parseData(subtitles.toString());
}
}
// 拆包校验
public static boolean unpack(ByteBuffer message, StringBuilder subtitles) {
final int kSubtitleHeaderSize = 8;
if (message.remaining() < kSubtitleHeaderSize) {
return false;
}
// 魔法数字 "subc"
int magicNumber = (message.get() << 24) | (message.get() << 16) | (message.get() << 8) | (message.get());
if (magicNumber != 0x73756276) {
return false;
}
int length = message.getInt();
if (message.remaining() != length) {
return false;
}
// 读取字幕内容
byte[] subtitleBytes = new byte[length];
message.get(subtitleBytes);
subtitles.append(new String(subtitleBytes, StandardCharsets.UTF_8));
return true;
}
// 解析字幕消息
public static void parseData(String msg) {
try {
// 解析 JSON 字符串
ObjectMapper objectMapper = new ObjectMapper();
JsonNode jsonData = objectMapper.readTree(msg);
// 存储解析后的数据
List<SubtitleMsgData> subtitles = new ArrayList<>();
// 遍历 JSON 数据并填充结构体
for (JsonNode item : jsonData.get("data")) {
SubtitleMsgData subData = new SubtitleMsgData();
subData.definite = item.get("definite").asBoolean();
subData.language = item.get("language").asText();
subData.paragraph = item.get("paragraph").asBoolean();
subData.sequence = item.get("sequence").asInt();
subData.text = item.get("text").asText();
subData.userId = item.get("userId").asText();
subtitles.add(subData);
}
} catch (Exception e) {
e.printStackTrace();
}
}
//数据格式
@interface SubtitleMsgData : NSObject
@property (nonatomic, assign) BOOL definite;
@property (nonatomic, copy) NSString *language;
@property (nonatomic, assign) BOOL paragraph;
@property (nonatomic, assign) NSInteger sequence;
@property (nonatomic, copy) NSString *text;
@property (nonatomic, copy) NSString *userId;
@end
@implementation SubtitleMsgData
@end
//回调
- (void)rtcRoom:( ByteRTCRoom *_Nonnull)rtcRoom onRoomBinaryMessageReceived:(NSString *_Nonnull)uid message:(NSData *_Nonnull)message {
NSString *subtitles = unpack(message);
if (subtitles) {
parseData(subtitles);
}
}
// 大端序转换
uint32_t swapUInt32(uint32_t value) {
return ((value & 0x000000FF) << 24) |
((value & 0x0000FF00) << 8) |
((value & 0x00FF0000) >> 8) |
((value & 0xFF000000) >> 24);
}
//拆包校验
NSString *unpack(NSData *data) {
const int kSubtitleHeaderSize = 8;
NSUInteger size = data.length;
if (size < kSubtitleHeaderSize) {
return nil;
}
const uint8_t *message = data.bytes;
// Check magic number "subc"
uint32_t magic = (message[0] << 24) | (message[1] << 16) | (message[2] << 8) | message[3];
if (magic != 0x73756276) {
return nil;
}
// Get length
uint32_t length = (message[4] << 24) | (message[5] << 16) | (message[6] << 8) | message[7];
if (size - kSubtitleHeaderSize != length) {
return nil;
}
// Get subtitles
NSString *subtitles = nil;
if (length > 0) {
subtitles = [[NSString alloc] initWithBytes:message + kSubtitleHeaderSize length:length encoding:NSUTF8StringEncoding];
} else {
subtitles = @"";
}
return subtitles;
}
//解析
void parseData(NSString *msg) {
NSError *error = nil;
NSDictionary *json_data = [NSJSONSerialization JSONObjectWithData:[msg dataUsingEncoding:NSUTF8StringEncoding] options:0 error:&error];
if (error) {
NSLog(@"JSON Parse Error: %@", error);
return;
}
NSMutableArray<SubtitleMsgData *> *subtitles = [NSMutableArray array];
for (NSDictionary *item in json_data[@"data"]) {
SubtitleMsgData *subData = [[SubtitleMsgData alloc] init];
subData.definite = [item[@"definite"] boolValue];
subData.language = item[@"language"];
subData.paragraph = [item[@"paragraph"] boolValue];
subData.sequence = [item[@"sequence"] integerValue];
subData.text = item[@"text"];
subData.userId = item[@"userId"];
[subtitles addObject:subData];
}
}
停止字幕生成
- 单个房间停止字幕生成：调用 stopSubtitle 接口停止。
- 整个应用停止字幕生成：前往 RTC 控制台_实时字幕，直接关闭实时字幕开关。
- 任务自动停止：为避免资源占用，若系统检测到房间内连续 3 分钟无音频上行，将自动停止房间内的实时字幕任务。
字幕数据二进制格式
通过客户端和服务端接收的字幕回调，解码后的 message 字段均遵循以下二进制格式。
参数名 | 类型 | 描述 |
magic number | binary | 消息格式标识，固定为 subc。 |
length | binary | 字幕消息（subtitle_message）的长度，单位为 bytes，存放方式为大端序（Big-Endian）。 |
subtitle_message | binary |
subtitle_message
参数名 | 类型 | 描述 |
type | String | 消息类型，固定为 subtitle（表示消息类型为字幕）。 |
data | data | 字幕详细信息，包含字幕的文本、语言、说话人 ID 等具体信息。 |
data
参数名 | 类型 | 描述 |
text | String | 字幕文本。 |
language | String | 字幕语言。 |
userId | String | 说话人 ID。 |
sequence | Int | 字幕序号。 |
definite | Boolean | 字幕是否为完整的一句话：
|
paragraph | Boolean | 字幕是否为一段完整的文本：
|
字幕使用建议
实时 UI 展示
字段组合状态 | UI 处理 |
paragraph: false、definite: false | 用序号大的字幕覆盖序号小的。 |
paragraph: false、definite: true | 重新开始新的一句话，覆盖前一句话。 |
paragraph: true | 此时如果继续解析显示字幕，字幕会重复显示。 |
存储字幕
仅在解析到 paragraph: true 且 definite: true 时存储，减少存储的数据量，并确保保存的字幕是完整的。
相关 API
FAQ
- **Q1：同一个房间内，不同用户可以分别调用服务端 OpenAPI **** StartSubtitle ** 吗？会互相覆盖吗？
- 可以，但需要保证每次调用使用不同的 TaskId。只要 AppId + RoomId + TaskId 唯一，不同字幕任务的配置不会因为 RoomId 相同而互相覆盖。
- Q2：服务端最多可以开启多少个实时字幕任务？
- 单账号下 OpenAPI QPS 不得超过 60。字幕任务的实际并发能力还受 RTC 资源、流式语音识别、机器翻译等依赖服务的并发额度影响。
- Q3：实时字幕无法生成时，客户端如何感知？
- 客户端调用 startSubtitle 接入时，可通过 onSubtitleStateChanged 监听字幕状态和错误码；服务端调用 StartSubtitle 接入时，请结合接口返回、客户端状态回调和业务服务端回调日志排查。
最近更新时间：2026.10.08 11:23:36
这个页面对您有帮助吗？
有用
有用
无用
无用