> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

扣子编程 Realtime 嵌入式 SDK 集成火山引擎 RTC 技术，专为智能穿戴设备、网络摄像头、智能门铃、AI 玩具等各类 IoT 设备量身定制，旨在助力开发者快速搭建稳定可靠的实时音视频通话功能。你只需通过简洁易用的 API 接口，即可轻松使用低代码智能体，无缝实现适配不同硬件设备的 AI 实时通话服务，降低了开发门槛与成本。
## 场景描述 {#3f6a852e}
当前硬件设备正以前所未有的速度智能化升级，成为人工智能领域成长最快的赛道之一。AI 与硬件的结合正逐渐渗透到我们生活的方方面面，如陪伴类玩具、智能家居、教育硬件以及智能穿戴设备等。

* **让硬件会聊天**：通过将硬件与低代码智能体相连，实现与硬件语音交互。以玩具领域为例，通过嵌入低代码智能体，玩具直接化身为专业的英语陪练，陪伴孩子进行口语练习；还能凭借生动的语音语调，绘声绘色地讲述各类有趣故事；或是与孩子愉快地开展成语接龙游戏，在寓教于乐中给予孩子温暖关怀与心灵陪伴。
* **通过语音实现设备控制**：传统硬件设备主要依赖按键操作或屏幕点击等交互方式，而融入低代码智能体后，仅通过语音指令就能轻松控制硬件设备，畅享便捷、智能的全新操控体验。
* **设备个性化定制或教学场景**：开发者能够利用扣子编程，通过简单直观的拖拽操作，快速搭建 AI 应用开发教具，无论是趣味十足的互动玩具，还是带有舵机的编程盒子类设备均可实现。搭建完成的智能体赋予了教具丰富的语音交互能力与灵活的运动控制能力，家长能够直观地看到实物成果，显著增强与学生在学习过程中的互动沟通，有效提升设备的可玩性与用户粘性，进而扩大产品市场竞争力，形成良好的自传播效应。

## 前提条件 {#eb71ddef}
开始集成 SDK 前，请确保已完成如下操作：
<!-- @cols-width: 158,658 -->
| | | \
|**操作** |**说明** |
|---|---|
| | | \
|发布智能体 |已成功搭建并发布智能体为 API 服务。搭建步骤可参考[搭建可视化智能体](/tutorial/video_bot)或[搭建低延时语音助手](/tutorial/low_latency_voice_assistant)，发布步骤请参见[发布为 API 服务](/guides/publish_agent_api)。 |\
| |:::tip 说明 |\
| |若需使用视频理解能力，请为智能体配置一个视觉模型，例如**豆包视觉理解**模型。  |\
| |::: |
| | | \
|获取访问密钥 |获取访问密钥，用于身份认证与鉴权。 |\
| | |\
| |* **体验或调试场景**：建议生成短期的个人访问令牌（PAT），以快速完成 Realtime SDK 的整体流程。个人访问令牌的获取方法请参见[添加个人访问令牌](/developer_guides/pat)。 |\
| |* **线上环境**：在线上环境中，应使用服务访问令牌（SAT）或 OAuth 鉴权方案，各鉴权方式的详细说明请参考[鉴权方式概述](/developer_guides/authentication)。 |\
| | |\
| |:::tip 说明 |\
| |扣子编程 SDK 封装了多种鉴权方式，能够有效简化鉴权流程，你可以参考[鉴权示例代码](https://github.com/coze-dev/coze-js/tree/main/examples/coze-js-node/src/auth)实现不同方式的 OAuth 认证，以获取和管理访问扣子编程 API 所需的令牌。 |\
| |::: |
| | | \
|开发环境 |支持乐鑫 ESP32S3、全志 XR872、移远 ASR1606 等主流芯片平台及 Linux 系统，特殊 Linux 平台需提供交叉编译工具链。 |

## API 时序图 {#068a7741}
![Image=600x1069](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/041a3cb6ecc1436cbcc57ddbefb5e06a~tplv-goo7wpa0wc-image.image)
## 实现方式 {#2bf30438}
### 步骤一：引入 SDK {#29ad4e28}

1. 扣子编程 Realtime 嵌入式需要使用火山引擎 RTC SDK，请根据目标硬件平台获取对应的 SDK：
   * 全志 XR872、移远 ASR1606 等嵌入式 Linux 系统：请[联系技术支持获取](https://console.volcengine.com/workorder/create?step=2&SubProductID=P00000081)的 RTC SDK 。
   * 乐鑫ESP32：建议基于 esp-adf 示例项目源码进行实现，具体请参见[esp-adf 示例项目源码](https://github.com/espressif/esp-adf)，实现方法请参见[基于乐鑫 ESP32 实现音视频通话](/tutorial/esp32)。
2. 根据目标硬件平台配置编译工具链，并将 SDK 拷贝至对应的工程目录。

### 步骤二：创建扣子房间 {#140afeee}

1. 调用[创建房间](/developer_guides/create_room)接口创建扣子房间，并设置智能体的音色。
   创建房间时可以通过 `voice_id` 参数指定智能体使用的音色，扣子编程提供一系列系统音色，如果没有合适的系统音色，你也可以调用[复刻音色](/developer_guides/clone_voices)API，复刻指定音频文件中的人声音色。此外，你还可以设置房间内的音频编码格式，提高音频通话质量。
   
   :::: tabs
   @tab 请求示例
   ```Bash
   curl --location --request POST 'https://api.coze.cn/v1/audio/rooms' \
   --header 'Authorization: Bearer pat_OYDacMzM3WyOWV3Dtj2bHRMymzxP****' \
   --header 'Content-Type: application/json' \
   --data-raw '{
       "bot_id": "734829333445931****"
   }'
   ```
   
   
   @tab 响应示例
   ```JSON
   {
       "detail": {
           "logid": "202410291302044CD1CC3B4AE0897***"
       },
       "data": {
           "room_id": "room_id_743105798342****3",   // 房间 id
           "app_id": "6705332c79516e01****",       // app_id
           "token": "0016705********cANTE1MjkFAAAAAAAAAAEAAAAAAAIAAAAAAAMAAAAAAAQAAAAAACAA58QEAvxdy3LHNzSwq6apM9PUKM2rOsxIg/VB4b1xEFA=",
           "uid": "uid_743105798*****29"
       },
       "code": 0,
       "msg": ""
   }
   ```
   
   
   ::::

   :::tip 说明
   你还可以通过[代码转换智能体](https://www.coze.cn/store/agent/7468939989536702483?bot_id=true&bid=6fk0k0olc2g17)，将 curl 命令转换成其他编程语言的代码，例如 JavaScript、 Go、 Java 等。
   :::
2. 智能体加入房间。
   成功创建房间后，智能体会自动加入房间。
   :::tip 说明
   * 创建房间后返回的 Token，其默认有效期为 3 分钟，如果 3 分钟内没有用户加入房间，或者用户静音 3 分钟，智能体将自动退出房间，房间随即被释放，后续若要再次和智能体对话，则需重新创建房间。
   * 若有用户进入房间，智能体在房间中最长可以持续 24 小时，直至用户主动退出房间或用户设备异常断电等导致连接断开。
   :::

### 步骤三：采集并编码音视频信号 {#5be707f0}
你需要自行实现音视频信号的采集，扣子编程支持的音视频编码格式如下表所示。
<!-- @cols-width: 100,242,161 -->
| | | | \
|**类别** |**编码格式** |**说明** |
|---|---|---|
| | | | \
|音频 |OPUS、 G711A、 AACLC、 G722 |默认为 OPUS |
| | | | \
|视频 |H.264、ByteVC1 |默认为 H.264 |

:::tip 说明
[创建房间](/developer_guides/create_room)时设置的音视频编码格式，需要和采集的音视频编码格式保持一致。
:::
### 步骤四：客户端加入房间 {#1068028c}
嵌入式硬件客户端调用 Realtime 嵌入式 SDK 加入房间。

1. 调用 `byte_rtc_create` 创建引擎。
2. 调用 `byte_rtc_init`初始化引擎实例。
3. 调用`byte_rtc_set_audio_codec` 设置音频编码格式。
4. 调用 `byte_rtc_set_video_codec` 设置视频编码格式。
5. 调用 `byte_rtc_join_room` 加入房间。
   :::tip 说明
   客户端加入房间时需要指定 room_id、uid、app_id 和 token ，这些参数的值可以从[步骤一：创建房间](/dev_how_to_guides/realtime_embedded#4799a8c4)接口的返回参数中获取。
   :::
6. 加入房间后，SDK 通过 `on_join_room_success` 回调，告知客户端加入房间成功。

### 步骤五：进行双向通话 {#c3e172e1}

1. 客户端通过 `byte_rtc_send_audio_data` 或 `byte_rtc_send_video_data`将采集到的音频和视频信息传给智能体，智能体收到音视频后会进行语音 ＋ 文本回复。
   :::tip 说明
   默认 20ms 发送一次编码后的音频数据，硬件设备自动订阅对话消息。
   :::
2. 通话期间，客户端通过 `byte_rtc_rts_send_message` 给 SDK 发送[Realtime 上行事件](/developer_guides/signaling_uplink_event)，在上行信令中支持如下操作：
   * [中断 Agent 语音输出](/developer_guides/signaling_uplink_event#53d0ec2d)：可取消正在进行的对话。
   * [手动提交对话内容](/developer_guides/signaling_uplink_event#91751ce0)：适合”帮我解析xx链接“、”帮我分析这个图片的内容“等场景。
   :::tip 说明
   给智能体发送上行事件时需要指定智能体的 ID。
   :::
3. 通话期间，客户端通过 `on_message_received` 接收 SDK 返回的[Realtime 下行事件](/developer_guides/signaling_downlink_event)，在下行信令中你可以根据需要执行相关操作，例如：
   *  [用户语音识别字幕](/developer_guides/signaling_downlink_event#e86ff517)：语音识别字幕，可用作接收字幕消息。
   * [端插件请求](/developer_guides/signaling_downlink_event#8283f036)：端插件请求，可用作控制硬件设备。

### 步骤六：结束通话 {#52390ef7}

1. 调用 `byte_rtc_leave_room` 接口退出房间。
2. 调用 `byte_rtc_destory` 接口销毁引擎实例。

## 进阶功能 {#fc4d23ac}
### 修改音色 {#8f889c1e}
系统默认采用`柔美女友`音色，音色 ID 为 7426720361733046281，你可以修改音色，操作如下：

1. 调用 [查看音色列表](/developer_guides/list_voices)接口查看可用的音色列表。
   :::tip 说明
   扣子编程提供一系列系统预制音色，如果没有合适的系统音色，你也可以调用 [复刻音色](/developer_guides/clone_voices)API，复刻指定音频文件中的人声音色。
   :::
2. [创建房间](/developer_guides/create_room)时可以通过 `voice_id` 参数指定智能体使用的音色。

### 语音输入完成后播放提示音 {#642ffa39}
你可以在用户完成语音输入后播放提示音，向用户反馈语音指令已被系统成功接收、系统即将进入下一步操作，从而提升用户体验并增强交互的流畅性。实现方案如下：

* 收到[用户结束说话](/developer_guides/signaling_downlink_event#7d06741d)的下行信令后，客户端自动播放一段预先设定好的提示音。
* 在[更新安抚配置](/developer_guides/signaling_uplink_event#8fd934aa)的上行信令中定义提示音的播放时间，系统将根据此配置在指定时间点播放提示音。

### 禁止语音打断 {#baa0a23b}
系统默认开启语音打断功能，如果希望禁止语音输入打断智能体的播放，可以在[更新房间配置](/developer_guides/signaling_uplink_event#2340bb0d)的上行信令中，将 `allow_voice_interrupt` 设置为 `false`，禁止语音打断功能。
### 通过文字输入时让智能体进行语音回复 {#a2c11a1f}
参考[手动提交对话内容](/developer_guides/signaling_uplink_event#91751ce0)的上行信令，提交事件后就会生成语音回复。
## API 接口列表 {#6cae2b64}
<!-- @cols-width: 100,212,354 -->
| | | | \
|**功能** |**函数名** |**说明** |
|---|---|---|
| | | | \
|加房 |`byte_rtc_join_room` |用户进入房间。 |
| | | | \
|发送信令 |`byte_rtc_rts_send_message` |给服务端发送[Realtime 上行事件](/developer_guides/signaling_uplink_event)，例如更新房间配置以及手动提交对话内容等。 |\
| | |向智能体发送事件的时候需要指定智能体的 ID。 |
| | | | \
|接收信令 |`on_message_received` |接收服务端发送的[Realtime 下行事件](/developer_guides/signaling_downlink_event)。例如用户开始说话事件，用户结束事件，以及对话文本内容等。 |
| | | | \
|发送音频 |`byte_rtc_send_audio_data` |推送音频到智能体，智能体收到音频后会进行**语音 + 文本**回复。 |
| | | | \
|发送视频 |`byte_rtc_send_video_data` |推送视频给到智能体，智能体理解视频内容后会进行**语音 + 文本**回复。 |

## 常见问题 {#8a4a9651}
### 如何处理卡顿延迟？ {#23d2add1}
音视频通话卡顿或延迟时，你可以参考如下步骤进行排查：

1. 检查网络状况。
   当遇到卡顿延迟问题时，建议使用网络工具或其他网络相关产品，对当前网络状况进行辅助诊断，以确定网络是否存在异常。
2. 检查回调耗时操作。
   1. 将日志级别设置为 `INFO`，在日志中搜索关键字 **used too many times**。
   2. 如果出现大量相关日志输出，或者日志中时间的输出值较大，这表明 `VolcEngineRTCLite` 的回调中存在大量长耗时操作。日志中时间的单位为毫秒。
      由于一个 `byte_rtc_engine_t` 实例采用单线程结构，若应用层操作耗时过多，可能会对 `VolcEngineRTCLite` 的正常逻辑产生影响。在正常情况下，不应出现此类日志输出。
3. 检查发送帧率。
   1. 将日志级别设置为 `INFO`，在日志中搜索关键字 **fps**。
   2. 检查发送帧率是否符合你的预期，若帧率设置不合理，例如低于 15 fps，可能是导致卡顿延迟的原因之一。
4. 确认发送码率与网络带宽匹配情况。
   1. 将日志级别设置为 `INFO`，在日志中搜索关键字 **lite - cc bw**。
   2. 确认发送码率与当前网络实际带宽是否相符，日志中带宽的单位为 kbps。如果发送码率明显高于网络实际带宽，可能会引发卡顿延迟问题。

### 如何处理首帧加载缓慢？ {#d0b3071b}

1. 检查网络状况。
   当出现首帧加载缓慢的情况时，建议你借助网络工具或其他网络相关产品，对当前网络的运行状况进行辅助诊断，以此判断网络是否存在不稳定、带宽不足等问题影响首帧加载。
2. 请确认推流端和拉流端都处于正式环境中。
3. 及时处理关键帧。
   针对关键帧请求`on_key_frame_gen_req`，你需要及时进行处理，并迅速编出 I 帧。I 帧作为视频中的关键帧，对于首帧的快速显示起着至关重要的作用，及时编出 I 帧可以有效提升首帧加载速度。

### 如何处理拉流端无法接收到音频流？ {#22707b0e}
当拉流端遇到无法接收到音频流的情况时，你可以按照以下步骤进行排查和处理：

1. **检查发流端状态**：请仔细确认嵌入式硬件客户端是否正常运行。嵌入式硬件客户端作为音频流的发流端，若其出现故障或运行异常，将直接导致拉流端无法接收到音频流。
2. **确认音频格式一致性**：请核实收发双方所使用的音频格式是否相同。扣子编程默认的音频格式为 opus。若嵌入式硬件客户端采用其他音频格式，你需调用 SDK 的 `byte_rtc_set_audio_codec` 接口设置音频编码格式。只有当收发两端的音频格式保持一致时，拉流端才能正确接收和解码音频流。

### 如何处理拉流端无法接收到视频流？ {#22e1eaf7}
当拉流端遇到无法接收到视频流的情况时，你可以按照以下步骤进行排查和处理：

1. **检查发流端状态**：请仔细确认嵌入式硬件客户端是否正常运行。嵌入式硬件客户端作为视频流的发流端，若其出现故障或运行异常，将直接导致拉流端无法接收到视频流。
2. **确认视频格式一致性**：请核实收发双方所使用的视频格式是否相同。扣子编程默认的视频格式为 H.264。若嵌入式硬件客户端采用其他音频格式，你需调用 SDK 的 `byte_rtc_send_video_data` 接口设置视频编码格式。只有当收发两端的视频格式保持一致时，拉流端才能正确接收和解码视频流。

### 如何处理音频延迟大？ {#189ce884}
当遇到音频延迟较大的问题时，请确认设备端发送的音频格式及采样率是否与下表中的默认值一致：
<!-- @cols-width: 100,171,503 -->
| | | | \
|**音频格式** |**默认采样率** |**每帧采样点数** |
|---|---|---|
| | | | \
|OPUS |48,000 |960 |
| | | | \
|AACLC |48,000 |1024 |
| | | | \
|G722 |8,000 |160 |
| | | | \
|G711A |8,000 |160 |

### 为什么用户加入房间后未触发回调？ {#1a3d8823}
用户调用 `byte_rtc_join_room` 接口加入房间后未触发回调的排查思路如下：

1. 检查网络是否可用。
   不稳定或不可用的网络可能会阻碍回调的正常触发。你可以尝试打开网页、访问其他网络服务或者使用网络诊断工具来判断网络连接是否正常。
2. 用户未及时加入房间导致房间已释放。
   创建房间后返回的 Token，其默认有效期为 3 分钟，如果 3 分钟内没有用户加入房间，房间会被释放，你需重新创建房间。
3. 检查域名解析是否正常。
   域名解析异常也可能导致回调无法触发。你可以使用网络工具（如 `ping` 或 `dig`）来检查域名解析是否正常。具体操作方法如下：
   * **使用** **`ping` 命令**：在命令行中输入 `ping <目标域名>`，例如 `ping example.com`，查看网络是否能够正常响应。若出现请求超时或无法解析等提示信息，则表明域名解析可能存在问题。
   * **使用** **`dig` 命令**：在命令行中输入 `dig <目标域名>`，例如 `dig example.com`，该命令会返回详细的域名解析信息，你可以根据返回结果判断域名解析是否正常。
4. 检查 UDP 端口是否被封禁。
   某些公司、学校等特殊网络环境可能会对 UDP 端口进行限制或封禁，这也可能导致回调无法触发。

### 如何修改静音退出房间的时间设置？ {#7a1f51f7}
默认情况下，用户在静音状态持续 3 分钟后，智能体将自动退出房间。若需调整该时间设置，你可以在[更新房间配置](/developer_guides/signaling_uplink_event#2340bb0d)上行事件中，修改 `data.longest_silence_ms` 参数的值。
## 相关文档 {#f4b5895d}
[基于乐鑫 ESP32 实现音视频通话](/tutorial/esp32)
[RTC 实时对话式 AI 场景搭建（嵌入式硬件）](https://www.volcengine.com/docs/6348/1438400)