帮你快速理解、总结文档立即下载
文档中心>物联网开发平台>录音卡>跑通设备端

跑通设备端

最近更新时间：2026-09-09 09:27:02
我的收藏

本页目录：

本文将介绍如何将录音卡 SDK 集成到您的设备固件中，跑通录音会话功能。全文分为三个部分：
SDK 下载：了解支持平台与获取对应平台的 SDK 交付包。
SDK 对接指引：完成 SDK 集成与录音会话能力对接。
跑通 Demo：以 ESP32S3 为例，介绍如何编译烧录，完成设备与 App 联调。

SDK 下载

芯片原厂
芯片型号
SDK 下载地址
乐鑫
ESP32S3
下载
注意：
如果您的项目使用其它芯片，请填写 芯片适配需求表，我们将尽快适配。
芯片需要满足如下要求：
前提项
要求
BLE
BLE4.2及以上。
Flash/RAM
100KB 以上 Flash，50KB 以上 RAM（SDK 用，不含 BLE 协议栈）。
存储介质
已挂载的文件系统（如 SD 卡 + FAT），提供录音文件落盘目录。
音频能力
麦克风采集 + Opus 编码（16kHz / 单声道 / 60ms 帧）。
操作系统
FreeRTOS 或其他 pthread 风格的 RTOS。

SDK 对接指引

这部分主要介绍录音卡 API 的对接，方便集成到自己项目中去。
集成方需完成：调用5个 API、实现3个回调、按固定格式送帧。

步骤1: 引入录音卡头文件

/* 只需要引入这一个头文件即可 */
#include "tc_iot_audio_recorder.h"

步骤2: 初始化

/* 回调运行在 SDK 内部 message loop 线程：只做入队/置标志，勿阻塞、勿直连硬件 */

static void on_rec_start(const char *params, void *user_data)
{
    /* App 下发开始（或本地 start 被接受）：打开麦克风采集 + Opus 编码器，
     * 之后开始向 SDK 送帧 */
}

static void on_rec_stop(const char *params, void *user_data)
{
    /* App 下发停止（或本地 stop）：请求停止采集，停止送帧 */
}

static void on_rec_message(tc_iot_error_e error_code, const char *json_msg, void *user_data)
{
    /* 统一事件入口：解析 json_msg 驱动 UI/业务状态，如果没有UI则不需要关注error_code>0的json_msg */
}

static void on_log(tc_iot_log_level_e level, const char *log)
{
    /* SDK 日志：按需转发到客户日志系统,调试的时候使用，量产只打印Info级别日志即可 */
}

void recorder_init(void)
{
    tc_iot_audio_recorder_params_s params = {
        .storage_path = "/sdcard/voice",          /* 录音文件落盘目录（SD 卡挂载点下） */
        .log_level    = TC_IOT_LOG_LEVEL_INFO,    /* 调试阶段可以开Debug */
        .on_log       = on_log,
    };
    tc_iot_audio_recorder_observer_s obs = {
        .on_audio_recorder_start = on_rec_start, // 本地主动触发录音和APP发起录音都会走这个回调
        .on_audio_recorder_stop  = on_rec_stop,  // 本地主动触发结束录音或APP结束录音都会走这个回调
        .on_message              = on_rec_message, // 错误或者事件通知统一走这个回调
    };
    tc_iot_error_e err = tc_iot_audio_recorder_init(&params, &obs, NULL);
    if (err != TC_IOT_ERR_SUCCESS) {
        /* 初始化失败 */
    }
    /* init 成功后 SDK 自动开始 BLE 广播，等待 App 连接 */
}

步骤3: 设备主动发起录音/结束录音

/* 设备本地主动发起录音，如按键开始录音，调用此函数，sdk内部准备好后会通过on_audio_recorder_start告知，然后才可以推音频流 */
tc_iot_error_e tc_iot_audio_recorder_start(tc_iot_audio_recorder_operation_cb callback);
/* 设备本地主动结束录音，如按键结束录音，调用此函数，sdk内部处理完成后会通过on_audio_recorder_stop告知，此时可以结束推音频流 */
tc_iot_error_e tc_iot_audio_recorder_stop(void);

步骤4: 推音频流

当收到 on_audio_recorder_start 的回调后，就可以推送音频。
/* 需要在收到on_audio_recorder_start的回调之后才可以推音频流，在这之前推的音频流都会返回错误，但不影响正常调用 */
  const tc_iot_audio_frame frame = {
    .codec = TC_IOT_AUDIO_CODEC_OPUS, // 当前只接收Opus音频
    .sample_rate = TC_IOT_AUDIO_SAMPLE_RATE_16000,
    .channels = TC_IOT_AUDIO_CHANNEL_MONO,
    .frame_duration_ms = TC_IOT_AUDIO_FRAME_DURATION_MS, // 60ms
    .data = (uint8_t *)opus,
    .data_size = len,
    };
tc_iot_audio_recorder_send_audio(&frame);

步骤5: 退出，反初始化

/* 停止录音/设备休眠时调用，释放init时的资源，退出SDK */
tc_iot_error_e tc_iot_audio_recorder_deinit(void);

跑通 Demo

这节介绍如何跑通录音卡设备端 Demo，我们以 立创实战派 ESP32S3开发版 为例，来介绍录音卡设备端 SDK 的使用。跑通本 Demo 后，您可以验证 BLE 录音卡绑定、实时录音、离线文件同步，以及云端语音识别能力。

前置条件

您已经成功 跑通了应用端 APP，手机已经装好了 APP 并可以正常运行。

下载 Demo

git clone https://github.com/Tencent-RTC/IoT_VoiceRecordingCard.git

步骤1: 准备 ESP-IDF 编译构建环境

本项目基于乐鑫官方 ESP-IDF 框架开发，版本要求 6.2（或者 master 分支）：
1. 打开 乐鑫官方入门教程。
2. 按文档安装 ESP-IDF v6.2（master 也可以） 及工具链：
Windows：下载「ESP-IDF 安装器」一路下一步，完成后桌面会出现 ESP-IDF 终端。
macOS / Linux：按文档执行 install.sh，之后在终端执行 . $HOME/esp/esp-idf/export.sh 激活环境。
3. 验证安装：在 ESP-IDF 终端中执行 idf.py --version，应输出 6.2。
说明：
后续所有命令都在「ESP-IDF 终端」（或已执行 export.sh 的终端）中输入。

步骤2: 编译&烧录

在终端中进入本工程目录 devices/ESP32S3，依次执行：
idf.py set-target esp32s3        # 第 1 步：指定芯片型号（仅需一次）
idf.py build                     # 第 2 步：编译（首次会联网下载依赖，需几分钟）
idf.py -p <串口> flash monitor   # 第 3 步：烧录并打开串口监视器
<串口> 的查看方式：
系统
串口
查看方法
macOS
/dev/cu.usbmodem*
ls /dev/cu.usbmodem*
Windows
COMx
设备管理器 → 端口(COM 和 LPT)。
Linux
/dev/ttyACM0
ls /dev/ttyACM*；若无权限执行 sudo usermod -aG dialout $USER 后重新登录。
烧录完成后设备自动重启，串口监视器中可见启动日志（按 Ctrl+] 退出监视器）。

步骤3: 上电使用

连接手机 App

1. 用 USB 线给开发板上电，屏幕点亮并显示设备就绪表情。
2. 打开手机 App，在设备列表中选择 TXVR-XXXX（XXXX 为屏幕/串口日志中 显示的设备 MAC 地址后两位）。
3. 连接成功后，屏幕表情切换为“已就绪”，即可开始使用。

开始录音

手机操作：在 App 中点击“开始录音”，对开发板上的麦克风说话；点击“停止”结束。
按键操作：短按板上 BOOT 键 等效开始/停止录音。
录音过程中屏幕显示“聆听中”表情；停止后录音自动上传，文件同时保存在 SD 卡中，可在 App 内回放或下载。
中国站