# 解析转写数据 (/zh-CN/realtime-media/speech-to-text/build/process-transcription-data/how-to-use-protobuf) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). Protobuf（全称 [Protocol Buffers](https://protobuf.dev)）是由 Google 开发的一种高效的、跨语言的序列化数据格式，支持多种编程语言，包括 C++、Java、Python、Go 等，可在不同系统间进行数据交换。具有高效、灵活和易于使用的特点。 声网实时转录翻译支持使用 Protobuf 或 JSON 格式通过数据流传输转写和翻译结果。默认使用 Protobuf 格式；如果调用 [`join`](/zh-CN/api-reference/api-ref/speech-to-text/join) 时将 `enableJsonProtocol` 设置为 `true`，则使用 JSON 格式。本文介绍接收端如何解析 Protobuf 和 JSON 数据，并从解析后的数据结构中提取具体的文本字段。 ## 前提条件 [#前提条件] 请按照以下要求准备开发环境： - 可以访问互联网的计算机。如果你的网络环境部署了防火墙，参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 - 已安装 Protobuf Compiler，详见 [Protobuf Compiler Installation](https://github.com/protocolbuffers/protobuf#protobuf-compiler-installation)。 :::warning[注意] 由于 Protobuf 的格式在不同版本会有差异，声网建议生成代码和客户端反序列化使用的 Protobuf SDK 版本保持一致。 ::: - 一个有效的声网账号以及声网项目。请确保你的项目已开通实时转录翻译功能，并参考[开通服务](/zh-CN/realtime-media/speech-to-text/build/start-transcribing-and-translating/enable-service)从声网控制台获得以下信息： - App ID：声网随机生成的字符串，用于识别你的项目。 - 临时 Token：Token 也称为动态密钥，在客户端加入频道时对用户鉴权。临时 Token 的有效期为 24 小时。 - 作为主播加入频道发流。你可以参考[实现纯语音互动](/zh-CN/realtime-media/rtc/build/audio/audio-quick-start)来在频道中发流。 ## 实现流程 [#实现流程] 本节介绍接收端如何使用 protoc 编译生成不同语言的示例代码来反序列化接收到的 Protobuf 数据。如果你使用 JSON 格式，可直接参考[JSON 协议数据结构](#json-协议数据结构)解析消息。 ### 使用 protoc 生成源代码 [#使用-protoc-生成源代码] 参考下列步骤来编写一个脚本调用 protoc 编译器以生成不同语言的代码。 #### 创建脚本并生成源码 [#创建脚本并生成源码] 你可以根据自己实际的业务需求，选择生成不同语言的代码。下文提供生成 Java、Objective-C、C#、JavaScript 语言的代码脚本。 Java Objective-C C# JavaScript 创建一个 Shell 脚本，将其命名为 `generate_code.sh`，然后在其中添加如下代码： ```shell #!/bin/sh # 指定 protoc 编译器的路径，示例代码中使用的 Protobuf 版本为 21.12，你可以根据你的实际需求替换 PROTOC_PATH=./protoc-21.12-osx-aarch_64/bin/protoc # 指定 .proto 文件的路径，文件中数据结构的详细描述见参考信息 PROTO_FILE=./SttMessage.proto # 指定输出目录 JAVA_OUT_DIR=$(pwd)/code/java # 创建输出目录（如果不存在） mkdir -p $JAVA_OUT_DIR # 生成 Java 代码 $PROTOC_PATH --java_out=$JAVA_OUT_DIR $PROTO_FILE # 生成代码完成后输出提示信息 echo "Generate code finished." ``` 如果你需要生成 Objective-C 代码，请确保在生成代码前已经安装 Protobuf 的相关依赖。你可以参考下列步骤来安装依赖，如果已有依赖，可跳过此步骤。 1. 打开你的项目的 `Podfile` 文件，并在其中添加如下代码： ```ruby # 21.12 表示 Protobuf 版本，你可以根据实际需求选择合适的版本 pod "Protobuf", "3.21.12" ``` 2. 在 Terminal 中进入到包含 `Podfile` 文件的目录下，运行 `pod install` 命令，CocoaPods 会下载、安装指定的依赖库版本。 成功安装后，项目文件夹下会生成一个后缀为 `.xcworkspace` 的文件，通过 Xcode 打开该文件进行后续操作。 创建一个 Shell 脚本，将其命名为 `generate_code.sh`，然后在其中添加如下代码： ```shell #!/bin/sh # 指定 protoc 编译器的路径，示例代码中使用的 Protobuf 版本为 21.12，你可以根据你的实际需求替换 PROTOC_PATH=./protoc-21.12-osx-aarch_64/bin/protoc # 指定 .proto 文件的路径，文件中数据结构的详细描述见参考信息 PROTO_FILE=./SttMessage.proto # 指定输出目录 OBJC_OUT_DIR=$(pwd)/code/objective-c # 创建输出目录（如果不存在） mkdir -p $OBJC_OUT_DIR # 生成 Objective-C 代码 $PROTOC_PATH --objc_out=$OBJC_OUT_DIR $PROTO_FILE # 生成代码完成后输出提示信息 echo "Generate code finished." ``` 创建一个 Shell 脚本，将其命名为 `generate_code.sh`，然后在其中添加如下代码： ```shell #!/bin/sh # 指定 protoc 编译器的路径，示例代码中使用的 Protobuf 版本为 21.12，你可以根据你的实际需求替换 PROTOC_PATH=./protoc-21.12-osx-aarch_64/bin/protoc # 指定 .proto 文件的路径，文件中数据结构的详细描述见参考信息 PROTO_FILE=./SttMessage.proto # 指定输出目录 CSHARP_OUT_DIR=$(pwd)/code/csharp # 创建输出目录（如果不存在） mkdir -p $CSHARP_OUT_DIR # 生成 Objective-C 代码 $PROTOC_PATH --csharp_out=$CSHARP_OUT_DIR $PROTO_FILE # 生成代码完成后输出提示信息 echo "Generate code finished." ``` 如果你需要生成 JavaScript 代码，请确保在生成代码前已经安装 Protobuf 的相关依赖。你可以参考下列步骤来安装依赖，如果已有依赖，可跳过此步骤。 1. 打开你的项目根目录，编辑 `package.json` 文件，添加以下依赖项： ```json { "dependencies": { ... "protobufjs": "^7.2.5" }, "devDependencies": { ... "pbjs": "^0.0.14", "protobufjs-cli": "^1.1.2" } } ``` 你可以根据实际需求指定 Protobuf 库和 protobufjs 命令行工具的版本。 2. 在终端运行以下命令以安装依赖： ```shell npm install ``` 创建一个 Shell 脚本，将其命名为 `generate_code.sh`，然后在其中添加如下代码： ```shell # 将 protobufjs-cli 的可执行文件路径添加到 PATH 环境变量 # 需要将 {absolute path of protobufjs-cli in your node_modules}/bin 替换为 protobufjs-cli 在 node_modules 中的绝对路径 export "PATH=$PATH:{absolute path of protobufjs-cli in your node_modules}/bin" # 生成 javascript 的示例代码 pbjs -t json-module -w es6 ./SttMessage.proto > ./SttMessage_es6.js echo "JavaScript code generation finished." ``` #### 运行脚本 [#运行脚本] 在终端中运行以下命令来运行脚本： ```shell # 将脚本设置为可执行文件 chmod +x generate_code.sh # 运行脚本 ./generate_code.sh ``` ### 反序列化数据 [#反序列化数据] 客户端接收到数据流时，SDK 会触发接收到数据流消息的回调。本节介绍如何对接收到的数据进行反序列化，将其转换回数据结构或对象。以下为不同语言的示例代码： ```java tab="Java" tabGroup="deserialize" // 加入频道，添加回调事件 rtcManager.joinChannel(roomName, localUid, agora_token, roleType.equals(ROLE_TYPE_BROADCAST), new RtcManager.OnChannelListener() { ... // 接收到数据流消息的回调 @Override public void onStreamMessage(int uid, int streamId, byte[] data) { // 检查远端用户 ID 是否为指定的推流机器人 ID，如果是则解码数据流为文本对象 if (String.valueOf(uid).equalsIgnoreCase(RTC_UID_STT_STREAM)) { AgoraSpeech2TextProtobuffer.Text text = STTManager.getInstance().parseTextByte(roomName, data); // 将解析后的文本对象转换为 JSON 格式并打印日志 LogUtil.d(originLogName, mGson.toJson(text)); } } ... }); public AgoraSpeech2TextProtobuffer.Text parseTextByte(String channel, byte[] data) { // 声明一个 AgoraSpeech2TextProtobuffer.Text 类型的变量，用于存储反序列化后的对象 AgoraSpeech2TextProtobuffer.Text textStream; try { // 将字节数组 data 反序列化为 AgoraSpeech2TextProtobuffer.Text 对象 textStream = AgoraSpeech2TextProtobuffer.Text.parseFrom(data); } catch (Exception ex) { notifyErrorHandler(new ErrorInfo("parseTextByte", "-1", "parseTextByte parseFrom error >> " + ex.toString())); return null; } ... } ``` ```csharp tab="C#" tabGroup="deserialize" private void InitRtcEngine() { // 创建一个 RTC 引擎实例 RtcEngine = Agora.Rtc.RtcEngine.CreateAgoraRtcEngine(); // 创建一个事件处理类的实例 AgoraEventHandler handler = new AgoraEventHandler(this); // 创建 RtcEngineContext 对象，并设置频道场景为直播 RtcEngineContext context = new RtcEngineContext(_appID, 0, CHANNEL_PROFILE_TYPE.CHANNEL_PROFILE_LIVE_BROADCASTING, AUDIO_SCENARIO_TYPE.AUDIO_SCENARIO_DEFAULT); // 初始化引擎 RtcEngine.Initialize(context); // 添加回调事件 RtcEngine.InitEventHandler(handler); } // 定义一个类用于处理 RTC 相关回调，继承自 IRtcEngineEventHandler internal class AgoraEventHandler: IRtcEngineEventHandler { // 接收到数据流消息的回调 public override void OnStreamMessage(RtcConnection connection, uint remoteUid, int streamId, byte[] data, uint length, ulong sentTs) { // Debug.Log(String.Format("remoteUid: {0}", remoteUid)); // 如果远端用户 ID 等于指定的推流机器人 ID if (remoteUid == {pusher bot uid}) { // 解析 Protobuf 数据 AgoraSTTSample.Protobuf.Text t = ProtobufUtility.ParseProtobufData(data); ... } } } ``` ```javascript tab="JavaScript" tabGroup="deserialize" import AgoraRTC from "agora-rtc-sdk-ng" import protoRoot from "@/protobuf/SttMessage_es6.js" // 创建 RTC 客户端实例 this.rtc.client = AgoraRTC.createClient({ mode: "live", codec: "vp8", role: this.role }) // 监听数据流事件并绑定事件处理函数 this.rtc.client.on("stream-message", this.onStreamMessage.bind(this)) // 接收到数据流消息的回调 function onStreamMessage(uid, stream) { // 检查远端用户 ID 是否为指定的推流机器人 ID，如果不是则直接返回，不进行后续处理 if (uid != {pusher bot uid}) { return } // 使用 Protobuf 解码收到的数据流 let textstream = protoRoot.Agora.SpeechToText.lookup("Text").decode(data) ... } ``` ```objc tab="Objective-C" tabGroup="deserialize" // Temp.h #import "AgoraRtcKit/AgoraRtcKit.h" #import "./Protobuff/SttMessage.pbobjc.h" NS_ASSUME_NONNULL_BEGIN @interface Temp : NSObject @end NS_ASSUME_NONNULL_END // Temp.m @implementation Temp // 接收到数据流消息的回调 - (void)rtcEngine:(AgoraRtcEngineKit *)engine receiveStreamMessageFromUid:(NSUInteger)uid streamId:(NSInteger)streamId data:(NSData *)data { // 检查远端用户 ID 是否为指定的推流机器人 ID，如果不是则直接返回，不进行后续处理 if (uid != pusherUid) { return; } NSError* error; // 解码收到的数据流 SttText* st = [SttText parseFromData: data error: &error]; ... } @end ``` ```swift tab="Swift" tabGroup="deserialize" // 接收到数据流消息的回调 func rtcEngine(_ engine: AgoraRtcEngineKit, receiveStreamMessageFromUid uid: UInt, streamId: Int, data: Data) { // 检查远端用户 ID 是否为指定的推流机器人 ID，如果不是则直接返回，不进行后续处理 guard uid == {puher bot uid} else { return } // 解码收到的数据流 let text = try? SttText.parse(from: data) ... } ``` ## 参考信息 [#参考信息] 本节提供使用 Protobuf 反序列化数据的其他相关信息。 ### 示例项目 [#示例项目] 声网提供了开源的实时转录翻译示例项目供你参考，你可以前往下载或查看其中的源代码。 ### SttMessage.proto 文件说明 [#sttmessageproto-文件说明] 声网提供的 `SttMessage.proto` 文件中定义了转写后的文本数据结构，各字段说明详见如下： ```protobuf syntax = "proto3"; package Agora.SpeechToText; option objc_class_prefix = "Stt"; option csharp_namespace = "AgoraSTTSample.Protobuf"; option java_package = "io.agora.rtc.speech2text"; option java_outer_classname = "AgoraSpeech2TextProtobuffer"; message Text { reserved 1 to 3, 5, 7 to 9, 11, 17; int64 uid = 4; int64 time = 6; repeated Word words = 10; int32 duration_ms = 12; string data_type = 13; repeated Translation trans = 14; string culture = 15; int64 text_ts = 16; OriginalTranscript original_transcript = 18; int64 sentence_id = 19; } message Word { reserved 2, 3, 5; string text = 1; bool is_final = 4; } message Translation { bool is_final = 1; string lang = 2; repeated string texts = 3; } message OriginalTranscript { string culture = 1; repeated Word words = 2; } ``` #### Text 消息类型及其字段说明 [#text-消息类型及其字段说明] | 字段名称 | 类型 | 含义 | | --- | --- | --- | | `uid` | `int64` | 文本所对应的用户 ID。 | | `time` | `int64` | 该句段转写的起始时间。仅在 `isFinal` 为 `true` 时有值，其他时候为 `0`。 | | `words` | `repeated` | 转写结果的数组，详见 `Word` 消息类型。 | | `duration_ms` | `int32` | 转写文本的时长，单位为毫秒。 | | `data_type` | `string` | [how-to-use-protobuf-markdown-0-5-2 details](#table-slot-how-to-use-protobuf-markdown-0-5-2) | | `trans` | `repeated` | 翻译结果的数组，详见 `Translation` 消息类型。 | | `culture` | `string` | 转写的源语言。 | | `text_ts` | `int64` | 转写结果的时间戳，持续递增，用于实时翻译时原文和译文的对齐。 | | `original_transcript` | `OriginalTranscript` | 转写后的文本，用于翻译，详见 `OriginalTranscript`。 | | `sentence_id` | `int64` | 字幕唯一 ID，字幕在数据流里的唯一标识，用于原文与译文字幕的精准对齐。 | **how-to-use-protobuf-markdown-0-5-2 details** 数据类型： - `transcribe`：转写。 - `translate`：文本翻译。 #### Word 消息类型及其字段说明 [#word-消息类型及其字段说明] | 字段名称 | 类型 | 含义 | | --- | --- | --- | | `text` | `string` | 转写的结果。 | | `is_final` | `bool` | [how-to-use-protobuf-markdown-1-2-2 details](#table-slot-how-to-use-protobuf-markdown-1-2-2) | **how-to-use-protobuf-markdown-1-2-2 details** 该句是否为转写的最终结果： - `true`：已为最终结果。 - `false`：并非最终结果。 该字段为 `true` 时表明转写引擎认为该句的文字转写结果已经确定，无需再进行修改，但并不代表这句话在语义上已经结束。 #### Translation 消息类型及其字段说明 [#translation-消息类型及其字段说明] | 字段名称 | 类型 | 含义 | | --- | --- | --- | | `is_final` | `bool` | [how-to-use-protobuf-markdown-2-1-2 details](#table-slot-how-to-use-protobuf-markdown-2-1-2) | | `lang` | `string` | 翻译的目标语言。 | | `texts` | `repeated` | 翻译的结果。 | **how-to-use-protobuf-markdown-2-1-2 details** 该句是否为翻译的最终结果： - `true`：已为最终结果。 - `false`：并非最终结果。该字段为 `true` 时表明翻译引擎认为该句的翻译结果已经确定，无需再进行修改，但并不代表这句话在语义上已经结束。 #### OriginalTranscript 消息类型及其字段说明 [#originaltranscript-消息类型及其字段说明] | 字段名称 | 类型 | 含义 | | ---------- | ---------- | ------------------------------------------------------------ | | `culture` | `string` | 转写的源语言。 | | `words` | `repeated` | 转写结果的数组，详见 `Word` 消息类型。 | :::info[信息] 使用 Soniox 供应商时，单次 Protobuf `Text` 消息可能承载多个片段。例如，转写消息中的 `words[]` 或翻译消息中的 `trans[]` 长度可能大于 `1`。客户端不应假设一次数据流消息只包含一个转写或翻译片段。 ::: ### JSON 协议数据结构 [#json-协议数据结构] 如果调用 [`join`](/zh-CN/api-reference/api-ref/speech-to-text/join) 时将 `enableJsonProtocol` 设置为 `true`，服务会使用 JSON 格式推送字幕数据。JSON 消息的顶层对象包含 `transcript` 或 `translation` 字段： - `transcript`：转写结果。 - `translation`：翻译结果。 使用 Soniox 供应商时，JSON 协议改为使用 `results[]` 显式承载一个或多个片段。单片段场景下 `results[]` 长度为 `1`；mixed 场景下，单条消息可能同时包含已稳定的前缀片段和仍会变化的后缀片段，此时 `results[]` 长度大于 `1`。 :::warning[注意] 这是 JSON 客户端协议的不兼容变更。如果你的客户端启用了 JSON 协议，需要与服务端一起升级。升级后不要再假设一次数据流消息只对应一个转写或翻译片段，请遍历 `results[]` 处理每个片段，并兼容 `results[]` 为空数组的消息。 ::: #### transcript 字段 [#transcript-字段] | 字段 | 类型 | 含义 | | :--- | :--- | :--- | | `uid` | Number | 用户的音频流 ID。 | | `textTs` | Number | 这批转写结果的主时间戳，取首个片段对应的 `text_id`。 | | `offset` | Number | 这批转写结果的起始时间，单位为毫秒。 | | `duration` | Number | 这批转写结果的时长，单位为毫秒。 | | `language` | String | 首个转写片段的源语言。 | | `text` | String | 转写文本。 | | `isFinal` | Boolean | 转写文本是否为最终结果。 | | `sentenceId` | Number | 句级聚合单元 ID，表示 `results[]` 中的转写片段归属于同一句或同一轮句级聚合单元。 | | `results` | Array | 转写片段数组。详见 [transcript.results 字段](#transcriptresults-字段)。 | #### transcript.results 字段 [#transcriptresults-字段] | 字段 | 类型 | 含义 | | :--- | :--- | :--- | | `text` | String | 当前转写片段的文本。 | | `isFinal` | Boolean | 当前转写片段是否为最终结果。 | | `offset` | Number | 当前转写片段的起始时间，单位为毫秒。 | | `duration` | Number | 当前转写片段的时长，单位为毫秒。 | #### translation 字段 [#translation-字段] | 字段 | 类型 | 含义 | | :--- | :--- | :--- | | `uid` | Number | 用户的音频流 ID。 | | `textTs` | Number | 这批翻译结果的主时间戳，取首个翻译片段对应的 `text_id`。 | | `offset` | Number | 这批翻译结果的起始时间，单位为毫秒。 | | `duration` | Number | 这批翻译结果的时长，单位为毫秒。 | | `isFinal` | Boolean | 翻译结果是否为最终结果。 | | `sentenceId` | Number | 句级聚合单元 ID，表示 `results[]` 中的翻译片段归属于同一句或同一轮句级聚合单元。 | | `results0` | Object | 兼容旧版本的翻译结果字段，结构保持不变。 | | `results` | Array | 翻译片段数组。详见 [translation.results 字段](#translationresults-字段)。 | | `original_transcript` | Object | 原文转写结果。仅在开启原文返回时出现。 | #### translation.results 字段 [#translationresults-字段] | 字段 | 类型 | 含义 | | :--- | :--- | :--- | | `language` | String | 翻译的目标语言。 | | `texts` | Array | 当前翻译片段的译文数组。 | | `isFinal` | Boolean | 当前翻译片段是否为最终结果。 | #### original_transcript 字段 [#original_transcript-字段] | 字段 | 类型 | 含义 | | :--- | :--- | :--- | | `language` | String | 原文的源语言。 | | `text` | String | 合并后的原文文本。 | | `results` | Array | 原文片段数组，字段包括 `text` 和 `isFinal`。| ### 示例数据 [#示例数据] 本节提供 Protobuf 和 JSON 格式下 `transcribe` 和 `translate` 两种数据类型的示例。 **transcribe** protobuf json json mixed ```protobuf time: 1753359518654 words { text: "Hello, how are you?" is_final: true } duration_ms: 770 data_type: "transcribe" culture: "en-US" text_ts: 1753359520754 sentence_id: 1753359518654 ``` ```json { "transcript": { "uid": 42, "textTs": 1710000012345, "offset": 1000, "duration": 200, "language": "zh-CN", "text": "你好。", "isFinal": true, "sentenceId": 1710000012000, "results": [ { "text": "你好。", "isFinal": true, "offset": 1000, "duration": 200 } ] } } ``` 以下示例表示同一条 JSON 消息同时包含已稳定的前缀片段和仍会变化的后缀片段： ```json { "transcript": { "uid": 42, "textTs": 1710000012345, "offset": 1000, "duration": 500, "language": "zh-CN", "text": "你好。", "isFinal": true, "sentenceId": 1710000012000, "results": [ { "text": "你好。", "isFinal": true, "offset": 1000, "duration": 200 }, { "text": "你", "isFinal": false, "offset": 1300, "duration": 200 } ] } } ``` 发送包含 `results[]` 的消息后，服务还会再发送一条 `results` 为空数组的消息： ```json { "transcript": { "uid": 42, "textTs": 1710000012345, "offset": 1000, "duration": 500, "language": "zh-CN", "text": "你好。", "isFinal": true, "sentenceId": 1710000012000, "results": [] } } ``` **translate** ```protobuf tab="protobuf" tabGroup="translate-example" time: 1753359518654 duration_ms: 770 data_type: "translate" trans { is_final: true lang: "es-ES" texts: "Hola, ¿cómo estás? " } text_ts: 1753359520754 sentence_id: 1753359518654 original_transcript { culture: "en-US" words { text: "Hello, how are you?" is_final: true } } ``` ```json tab="json" tabGroup="translate-example" { "translation": { "uid": 42, "isFinal": true, "offset": 1000, "duration": 500, "textTs": 1710000012345, "sentenceId": 1710000012000, "results0": { "language": "en-US", "texts": [ "Hello." ] }, "results": [ { "language": "en-US", "texts": [ "Hello." ], "isFinal": true }, { "language": "en-US", "texts": [ "World." ], "isFinal": false } ], "original_transcript": { "language": "zh-CN", "text": "你好。", "results": [ { "text": "你好。", "isFinal": true }, { "text": "世界", "isFinal": false } ] } } } ``` 发送包含 `results[]` 的消息后，服务还会再发送一条 `results` 为空数组的消息： ```json { "translation": { "uid": 42, "isFinal": true, "offset": 1000, "duration": 500, "textTs": 1710000012345, "sentenceId": 1710000012000, "results0": { "language": "en-US", "texts": [ "Hello." ] }, "results": [], "original_transcript": { "language": "zh-CN", "text": "你好。", "results": [] } } } ```