🏠 home › concepts › agora-rtsa-sdk
tags
[IoT, Agora, RTSA, C SDK, 嵌入式, 实时音视频, 加密, 数据流]
created
2026-04-17
updated
2026-04-17
sources
[raw/snippets/agora-rtsa/implement-transmission.md, raw/snippets/agora-rtsa/data-stream.md, raw/snippets/agora-rtsa/encryption.md]

定义

RTSA = Real-Time Streaming Acceleration（"实时码流加速"，声网官方现称"媒体流加速"）。Agora 面向 IoT 嵌入式设备的轻量级 C SDK，只承担音视频码流传输加速，不承担采集和编解码——开发者自己出 OPUS / H.264 编码后的数据，RTSA 通过 Agora SD-RTN 实时传输网络送出去，与移动端 RTC SDK / WebRTC 协议互通。

与 RTC SDK 的核心差异：

维度 RTC SDK RTSA SDK
全称 Real-Time Communication Real-Time Streaming Acceleration
定位 通用音视频实时通信 IoT 嵌入式设备的码流传输加速
语言 主要 C++ C 语言（轻量化）
包体积 较大，功能完备 极小（< 400KB）
编解码 SDK 内置音视频采集与编解码 自带编码后的数据，SDK 只负责传输
平台 Android/iOS/Web/Windows/macOS Linux / Windows / iOS / Android / freeRTOS / 嵌入式 RTOS

核心观察：RTSA 不是"RTC 的精简版"，是 RTC 的"删功能版"——把采集与编解码彻底踢出 SDK 范围，留给设备自己。这是 first-principles-deletion "必须这样做吗"在 SDK 设计上的范例。

在 Sentino 链路中的位置

Sentino BK7258 设备固件 bk7258-firmware 确定走 RTSA Lite 路径——已有 Sentino 官方实现 sentino-jp/sentino-iot-sample（GitHub private），fork 自声网/Agora 官方示例工程并定制。这是行业标准组合的 Sentino 实现版：Agora Convo AI Device Kit R1 = BK7258 + RTSA Lite + ConvoAI。

声网官方原始仓库有两个 mirror（Agora 与声网是同一家公司，海外品牌名 Agora、国内品牌名声网，组织名分别用 AgoraIO-Community 与 Shengwang-Community）： - 海外：AgoraIO-Community/Conversational-AI-IOT-Sample - 国内：Shengwang-Community/Conversational-AI-IOT-Sample（Sentino fork 致谢的是这一份——但代码相同）

详见 sentino-iot "硬件接入路径"段。

完整链路：

BK7258 设备
  ├─ CPU0 应用层：MQTT 信令 → 获取 RTC 凭证（[[concepts/agora-convoai-server]]）
  ├─ CPU1 媒体层：音频采集 → OPUS 编码（16kHz/单声道/20ms/640B 帧）
  └─ RTSA SDK：把编码后的帧通过 SD-RTN 送出
       ↕（协议互通）
Agora Conversational AI Engine（[[concepts/agora-convoai-join-api]]）
  └─ 在同一频道里有一个 Agora Agent 实例
       └─ ASR → LLM 推理（指向 Sentino api / 第三方 endpoint）→ TTS → 音频回传
       └─ 同样通过 RTSA 协议送回 BK7258 设备播放

关键事实：agora-rtc-voice 已记录的"OPUS / 16kHz / 单声道 / 16bit PCM / 20ms 帧长" = RTSA implement-transmission 文档第一性约束——音频参数不是某个产品决定的，是 RTSA SDK 的发送约束本身。

API 调用生命周期

agora_rtc_init()
  ↓
agora_rtc_create_connection()
  ↓
agora_rtc_join_channel()
  ↓
[发送 / 接收音视频数据 或 登录 RTM 发送信令]
  ↓
agora_rtc_leave_channel() + agora_rtc_destroy_connection()
  ↓
agora_rtc_fini()

音视频帧发送约束（硬约束）

音频

视频

关键回调

这是 information-theory Shannon-Hartley 信道容量约束的具体工程化：弱网时 RTSA 不能"魔法地"压缩出更小的流，只能反向请求应用层调码率或重发关键帧。SDK 边界就是物理带宽。

Data Stream（旁路控制通道）

RTSA 在音视频通道之外提供数据流，用于状态同步、控制信令、文件碎片等。

三种合法可靠性 / 有序组合（第四种被 SDK 拒绝）

reliable ordered 接受 含义
true true ✅ 可靠有序
true false ❌ 矛盾，SDK 拒绝
false true ✅ 不可靠有序
false false ✅ 不可靠无序

"可靠 + 无序"在协议上不存在——重传必然带顺序约束，否则重传到达后位置无意义。这是协议层面的逻辑约束，不是工程缺陷。

速率限制（极低，定位为旁路而非数据通道）

Agora ConvoAI 的 parameters.data_channel: rtm 信令 vs rtc datastream 配置（agora-convoai-join-api）选 datastream 时走的就是这套约束——只够送 turn_detection 状态、字幕事件、控制位标记等稀疏信令，承载不了任何业务数据。

收发 API

agora_rtc_create_data_stream(conn_id, &stream_id, reliable, ordered)
agora_rtc_send_stream_message(conn_id, stream_id, data, length)
// 接收：on_stream_message 回调

端到端加密（E2EE）

8 种模式

AES_128_XTS / AES_128_ECB / AES_256_XTS / SM4_128_ECB（国密）/ AES_128_GCM / AES_256_GCM / AES_128_GCM2（推荐） / AES_256_GCM2（推荐）

这是 agora-convoai-join-api rtc.encrypt 字段所列的 8 种加密模式的底层实现——配置在 join API 是上层声明，在 RTSA C SDK 是下层执行（crypto_option_t）。

密钥与盐分发模型

关键事实：Agora 服务端不持有密钥

加密发生在 RTSA SDK 层——离开设备前已加密、进入设备后才解密、Agora 服务端只看到密文。 即使 Agora 系统被入侵，攻击者拿到的也只是密文。这一条是隐私敏感客户场景对外承诺的硬技术保证。

反直觉副作用：与服务端 ASR 互斥（推断），与 TTS 不互斥（Sentino 半自定义模式）

文档未明说，但加密原理决定：端到端加密一旦启用，Agora 服务端能看到的依赖明文媒体的服务理论上不可用——

TTS 一侧不构成问题：agora-convoai-join-api 已记录 Sentino 走"半自定义模式"——llm.output_modalities=["text","audio"]，Agora 本就不调度 TTS，音频由 Sentino LLM endpoint 内部生成（Minimax/ElevenLabs/Qwen3）。所以 E2E 加密只对 ASR 一侧构成互斥假设，TTS 一侧本来就在 Sentino 内部，不受 Agora E2E 加密影响。

对 sentino-tenga 这种"性健康对话需要隐私答案"的客户场景，硬权衡只剩 ASR 一侧：要么端到端加密 + 设备端做 ASR（重量级，BK7258 不一定撑得住）+ Sentino LLM 内部出 audio 经 RTSA 加密回传，要么走 Agora 服务端 ASR + 信任 Agora 数据治理（ASR 段隐私答案需要换叙事，从"端到端"降级为"Agora 内部加密 + 数据合规承诺"）。文档未明确，需要实测或问 Agora 工程支持。

加密参数不匹配的失败模式

"同一频道内所有用户必须使用相同的加密模式、密钥和盐，否则黑屏或音频丢失"

加密参数不匹配在用户端表现为"完全没有内容"，而不是"听不清"——这是判断 E2E 加密配置是否正确的快速诊断信号。

SDK 边界设计：环境层做什么、不做什么

RTSA 的 SDK 边界设计是 harness-engineering "Environment（能干事）"层做工具划分的范例：

设计哲学：把"通用且不可省"的东西封进 SDK（网络层抗弱网是开发者写不好的），把"设备相关 + 编码格式百花齐放"的东西留给应用——这与 Claude Code 决定哪些是 Tool / 哪些是 SubAgent 是同构的边界设计判断（agent-tool-design）。

反常识 / 工程细节

  1. Token 参数可为空：仅用 App ID 也可入会（生产环境强烈不推荐，但设计上是可省略的）
  2. 可禁用事件回调：仅发信令不收音视频时设回调指针为 0
  3. 自动订阅模式：auto_subscribe_audio = true 等加入即收所有远端流
  4. RTM 登录成功 = event_id=0, event_code=0：非典型事件编码约定
  5. RTC + RTM 双独立连接生命周期：RTC 基于 Connection，RTM 基于全局登录状态——不是同一套
  6. License 必需：RTSA 通过 License 对设备鉴权，不是 App ID 一个就够

与 SD-RTN / RTC 的协议互通

RTSA 与运行 Agora RTC SDK 的任何应用（Android/iOS/Web）协议互通，底层走同一张 Agora SD-RTN。

含义：BK7258 IoT 设备（RTSA 端）可以与手机 App / 浏览器（RTC / WebRTC 端）直接进行实时音视频互通，不需要中间转码服务。这是 Sentino 同时做"设备端"和"Web 端"两条产品路径但能共享 Agora 基础设施的关键技术前提（sentino-iot / sentino-agent）。

待办与开放问题

相关概念