官方 SDK 集成指引--实时音视频-火山引擎

文档中心

立即注册

实时音视频

请输入

快速集成

官方 SDK 集成指引

本文旨在帮助开发者快速掌握硬件对话智能体 SDK 的集成流程，包括方案选择、SDK 初始化及核心交互流程的实现，助您高效构建具备多模态交互能力的智能硬件产品。

方案特性对比

硬件对话智能体为智能硬件提供高质量和低负载两种官方 SDK 集成方案：

高质量方案：一种基于 UDP 协议（通过 RTC 技术实现）的高性能接入方式，传输延时低、稳定性高、抗弱网能力强，适用于对实时交互体验有极致要求的业务场景（如智能眼镜、教育机器人、车载助手等）。
说明
视频通信场景建议选择高质量方案。
低负载方案：一种基于 TCP 协议（通过 WebSocket 实现）的轻量化接入方式，资源消耗较低，适用于资源受限、成本敏感、网络条件相对稳定的业务场景。

两种方案的具体对比如下表所示：

对比项	高质量方案	低负载方案
传输层协议	基于 UDP（RTC）协议	基于 TCP（WebSocket）协议
延时分析
建连延时	相对较高	更低（略优）
传输延时	更低（更优）	相对较高
整体延时	无明显差异
稳定性
弱网环境	抗弱网能力强（带宽估计、纠错重传等），显著更优	稳定性较差
优质网络	高可靠性，无明显差异	高可靠性，无明显差异
实时互动场景	显著更优，适合音视频等多媒体场景	表现较差，建议仅用于音频场景
资源消耗	相对较高（RAM < 300KB）	更低（更优），适合低配置硬件（RAM < 100KB）
接入成本	无明显差异

资源准备

在开始集成前，请根据您的硬件平台获取相应的开发资源：

获取 SDK 与 Demo

我们提供了适配乐鑫等主流芯片的 SDK 及示例工程。请参考获取 Demo 和 SDK 下载所需资源。

确定集成路径

使用官方 SDK（推荐）：开发效率高，支持高质量/低负载双模式切换。下文将重点介绍此方式的通用集成流程。
使用标准协议：
如果您的硬件平台暂未被 SDK 支持，或您需要深度定制底层通信逻辑，可选择基于 WebSocket 标准协议自行封装。相比于集成官方 SDK，直接对接标准协议具有更高的灵活性，但同时也要求开发者自行处理鉴权签名、连接保活、协议封装等底层逻辑。详情请参考通过标准协议自定义接入。

SDK 集成说明

下文将为您介绍在自有项目中集成官方 SDK 的通用流程和主要 API。完整的客户端 API，请参见概述。

交互流程

集成主要涉及设备端应用与硬件对话智能体 SDK 之间的交互。下图展示了从初始化 SDK 到通话结束的完整调用流程：

流程详解

初始化
应用层需先准备配置参数（config_json），包括鉴权信息（ProductKey, Secret 等）和功能配置。
- 定义 volc_event_handler_t 结构体，注册关键回调函数，用于接收 SDK 的状态更新和数据流。
- 调用 volc_create 创建引擎实例。SDK 内部会初始化资源并返回结果。
建立连接
- 调用 volc_start 启动智能体。SDK 会自动进行鉴权并建立与云端的长连接。
- 连接成功后，SDK 依次触发 on_volc_event(CONNECTED) 事件和 on_volc_conversation_status(LISTENING) 状态，表示智能体已就绪并进入聆听模式。
对话交互循环
- 上行发送：
  - 音频采集：应用层需持续采集经编码的音频数据，并通过 volc_send_audio_data 发送给 SDK。
  - 视频采集：如需视频通话，通过 volc_send_video_data 发送视频帧。
- 下行接收：
  - SDK 通过异步回调下发对话状态：智能体先进入思考中 (THINKING)，随后进入说话中 (SPEAKING)。
  - 在说话状态下，SDK 会并行下发多模态数据：
    - 通过 on_volc_audio_data 下发音频流，应用层需进行播放。
    - 通过 on_volc_video_data 下发视频流，应用层需进行渲染。
    - 通过 on_volc_message_data 下发字幕或指令，应用层需进行展示或处理。
结束与释放
- 调用 volc_stop 停止当前会话。SDK 会触发 on_volc_conversation_status(IDLE) 恢复空闲状态，并触发 on_volc_event(DISCONNECTED) 断开连接。
- 不再使用时，调用 volc_destroy 销毁实例并释放所有资源。

示例代码

以集成高质量方案为例，快速集成的参考代码如下：

static void __on_volc_audio_data(volc_engine_t handle, const void *data_ptr, size_t data_len, volc_audio_frame_info_t *info_ptr, void *user_data)
{
        play_audio_data(data_ptr, data_len);
}


char config_buf[1024]; //配置文件，详情参见 https://www.volcengine.com/docs/6348/1806633#config

volc_event_handler_t volc_event_handler = (volc_event_handler_t){
        .on_volc_event = __on_volc_event,
        .on_volc_conversation_status = __on_volc_conversation_status,
        .on_volc_audio_data = __on_volc_audio_data,
        .on_volc_video_data = __on_volc_video_data,
        .on_volc_message_data = __on_volc_message_data,
    };
volc_engine_t engine;


//   设备注册  volc_device_register
//   返回的是 rtc的appid 和 device_secret    
int ret = volc_create(&engine, config_buf, &volc_event_handler, &conv_service);

 volc_opt_t opt = {
        .mode = VOLC_MODE_RTC,
        .bot_id = CONFIG_VOLC_BOT_ID,
    };
    
//    volc_get_rtc_config  获取rtc配置
//    加入房间 byte_rtc_join_room
ret = volc_start(engine, &opt);

while(1){
    //  采集音频并发送
    int len = capture_audio_data(data);
    volc_audio_frame_info_t info = {0};
    info.commit = false;
    info.data_type = type;
    volc_send_audio_data(engine, data, len, &info);
}

最近更新时间：2025.12.30 10:34:39

这个页面对您有帮助吗？

有用

无用