功能介绍

通过实时字幕功能，可以将用户的语音实时转换为文字，并支持将文字翻译成其他语言，可用于直播字幕、会议记录生成、跨语言沟通实时翻译等场景。

• 支持通过客户端或服务端实现该功能。

• 根据使用场景的不同，可生成以下 2 种类型的字幕：

  特性	按源语言生成字幕（无需翻译）	生成指定语言的字幕（将语音转为文字后并翻译）
  作用	识别用户语音，直接按照源语言转为文字，适用于实时字幕显示场景。	识别用户语音，先按照源语言转为文字，再被翻译为指定目标语言，适用于跨语言实时翻译场景。
  所用服务	火山的流式语音识别	火山的机器翻译
  可识别的语种	不同场景，支持的语言不同，具体请参见语种支持	仅支持 zh、ja、en
  翻译字幕	不支持	支持。支持翻译为的目标语言，请参见语言支持
  返回的字幕数据	仅返回字幕原文	同时返回字幕原文和字幕译文
  费用	音频订阅费、流式语音识别费	音频订阅费、实时语音翻译费

计费说明

使用实时字幕功能除基础音视频通话费以外，还会产生以下费用：

生成字幕

以下分别介绍识别模式和翻译模式下的字幕生成方法。

按源语言生成字幕（识别模式）

1. 开通服务。

   1. 开通流式语音识别服务：前往语音技术控制台_流式语音识别，创建流式语音识别应用，服务类型选择 流式语音识别，并记录 APP ID，Access Token，和语言的 Cluster ID，以备使用。
   2. 开启实时字幕：前往 RTC 控制台_实时字幕进行以下操作：
      • 实时字幕：开启开关。
      • 流式语音识别：开启开关，并按照提示填入 APP ID、Access Token 和语言的 Cluster ID。

        注意

        • 语种的 Cluster ID：即设置待识别的源语种代号，系统已经预设了 4 种常用语言。若不满足需求，可自定义语种代号。
        • 支持识别的语言，请参见语种支持。

2. 生成字幕并接收字幕。

   • 通过客户端实现：字幕结果仅可返回至客户端，但是无需解析。
   • 通过服务端实现：字幕结果仅可返回至客户端或服务端，字幕为二进制数据，使用前需先解析。
   通过客户端实现

   通过服务端（openAPI）实现

   实现步骤：

   相关接口说明，请参见相关API。

   1. （可选）调用 joinRoom 接口进房时，设置源语言。
      通过 extraInfo 参数传入 "source_language": "语种代号"。如未指定源语言，SDK 会将系统语种设定为源语言。如果你的系统语种不是中文、英文和日文，此时 SDK 会自动将中文设为源语言。
   2. 进房后，调用 startSubtitle 启动字幕服务，模式（mode）设置为识别模式，无需设置目标翻译语言。
   3. 通过 onSubtitleStateChanged 回调获取字幕内容，包括用户 ID、字幕文本、语言、是否为完整句子等。
   4. 当不再需要字幕功能时，调用 stopSubtitle 关闭字幕。

   实现步骤：

   1. 准备字幕接收地址。
      字幕数据可通过客户端或服务端接收：
      • 当接收地址包括客户端：必须在客户端监听 onRoomBinaryMessageReceived 回调来接收字幕数据。
      • 当接收地址包括服务端：准备服务端接收的 Url 地址，字幕会按照每句话返回给该地址。
   2. 调用 StartSubtitle 生成字幕。
      服务端生成的字幕数据为 Base64 编码的二进制格式，使用前需解析。字幕格式和解析示例，请参见解析字幕。

   以用户语音的源语言为中文，字幕结果同时回调客户端和服务器为例，接口调用示例如下：

   POST https://rtc.volcengineapi.com?Action=StartSubtitle&Version=2024-06-01
   {
     "AppId": "661e****543cf", // 你的音视频应用的唯一标志，从控制台获取
     "RoomId": "Room1", // 房间 ID
     "TaskId": "Task1", // 自定义任务 ID，用于标识任务
     "LanguageConfig": {
       "SourceLanguages": [
         {
           "UserId": "user1", // 用户 ID
           "LanguageCode": ["zh"] // 用户语音的源语言为中文
         }
       ]
     },
     "DistributionMode": 3, // 字幕结果同时回调给客户端和服务器
     
   // 配置业务服务器
     "ServerMessage": {
       "Signature": "TestSignature", // 鉴权签名
       "Url": "http://127.0.0.1:8080/subtitlemsg"  // 接收字幕的服务器地址
     },  
    
    // 回调地址包含客户端时，可指定字幕接收用户
     "ReceiverList": ["user1", "user2"]  // 若指定了用户，只有指定用户可以看到字幕；若未指定，房间内所有用户都可以看到字幕 
   }
   

生成指定语言的字幕（翻译模式）

1. 开通服务。

   1. 开通机器翻译服务：具体操作，请参见开通服务。
   2. 开通实时字幕服务：前往 RTC 控制台_实时字幕，开启实时字幕和实时语音翻译的开关。

2. 生成字幕并接收字幕结果。

   • 客户端生成：字幕结果仅可返回至客户端，但是无需解析。
   • 服务端生成：字幕结果仅可返回至客户端或服务端，字幕为二进制数据，使用前需先解析。
   通过客户端实现

   通过服务端（openAPI）实现

   实现步骤：

   相关接口说明，请参见相关API。

   1. （可选）调用 joinRoom 接口进房时，设置源语言。
   2. 进房后，调用 startSubtitle 启动字幕服务。模式（mode）选择翻译模式，并指定字幕要翻译的语言。
   3. 通过 onSubtitleStateChanged 回调接收字幕生成结果。
   4. 当不再需要字幕功能时，调用 stopSubtitle 关闭字幕。

   实现步骤：

   1. 准备字幕接收地址。
      字幕数据可通过客户端或服务端接收：
      • 当接收地址包括客户端：必须在客户端监听 onRoomBinaryMessageReceived 回调来接收字幕数据。
      • 当接收地址包括服务端：准备服务端接收的 Url 地址，字幕会按照每句话返回给该地址。
   2. 调用 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"]  // 若指定了用户，只有指定用户可以看到字幕；若未指定，房间内所有用户都可以看到字幕 
   }
   

停止字幕生成

• 单个房间停止字幕生成：调用 stopSubtitle 接口停止。
• 整个应用停止字幕生成：前往 RTC 控制台_实时字幕，直接关闭实时字幕开关。

解析字幕

解析回调到服务端的字幕

• 字幕回调格式
  返回的字幕回调格式如下：

  参数名	类型	描述
  message	String	生成的字幕数据，格式为Base 64 编码的二进制，具体说明参看二进制消息格式。
  signature	String	鉴权签名。可与 startSubtitle 接口中传入的 signature 字段值进行对比，以进行鉴权验证。

  • 二进制消息格式：
    

    参数名	类型	描述
    magic number	binary	消息格式标识，固定为 subc。
    length	binary	字幕消息（subtitle_message）的长度，单位为 bytes，存放方式为大端序（Big-Endian）。
    subtitle_message	binary	字幕详细信息，格式参看 subtitle_message。

  • subtitle_message：
    

    参数名	类型	描述
    type	String	消息类型，固定为 subtitle（表示消息类型为字幕）。
    data	data	字幕详细信息，包含字幕的文本、语言、说话人 ID 等具体信息。

  • data：
    

    参数名	类型	描述
    text	String	字幕文本。
    language	String	字幕语言。
    userId	String	说话人 ID。
    sequence	Int	字幕序号。
    definite	Boolean	字幕是否为完整的一句话： true：是 false：否
    paragraph	Boolean	字幕是否为一段完整的文本： true：是 false：否

• 字幕解析示例

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

  Golang

  Python

  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)