sonicloud_opensdk README

The project's README from github.com/SonicloudTech/sonicloud_opensdk. As one markdown file: README.md.

声云录音卡 Recorder

一张录音卡片，一套完整的 BLE 接入方案。

声云录音卡 Recorder 是面向硬件厂商、软件开发者和行业集成商的开源示例项目。我们以 录音卡片硬件 为核心产品，同时开放录音卡 BLE 通讯协议 SDK、跨平台接入示例和桌面端 Demo，帮助团队从“连接设备”快速走到“录音、传输、转写和业务落地”。

声云录音卡片

项目定位

本项目提供“标准 BLE 指令 + 厂商适配层 + 跨平台 SDK 封装”的录音硬件接入参考。录音卡负责采集和保存音频，SDK 负责 BLE 会话、协议收发、设备状态和数据流管理，应用负责业务 UI、音频解码、存储、转写及行业集成。杰理、蓝讯、炬芯、BK 等方案的服务 UUID、特征值、分包方式和私有命令差异收敛在适配层，应用开发者面向统一接口接入不同硬件。

本仓库提供四类资源：

资源 适用对象 内容
移动端 SDK Android、iOS、鸿蒙及 Flutter 开发者 平台封装、蓝牙搜索连接、录音控制、实时音频、文件传输、Wi-Fi、OTA、设备信息和事件回调
Windows/macOS Demo PC 应用和工具开发者 Python BLE 协议实现、命令行 REPL、Web 控制台、离线语音转文字
协议与测试资料 需要深度定制的团队 BLE GATT、帧格式、CRC、文件下载、录音事件和兼容策略
集成与方案文档 硬件方案商、App 团队和项目评审人员 三端 SDK 集成流程，以及标准 BLE 指令 SDK 的技术方案说明

能做什么

目录导航

recorder/
├── pnote-android-sdk/                  # Android AAR
├── pnote-ios-sdk/                      # iOS 静态库与头文件
├── pnote-harmony-sdk/                  # 鸿蒙 HAR SDK
├── pnote-sdk-flutter-demo-main/        # Flutter 联调 Demo
├── pnote-web-win&Mac-demo/             # BLE 命令行与 Web Demo
│   ├── recorder/                       # 协议、BLE、设备会话、ASR、Web 后端
│   ├── web/                            # 前端页面
│   ├── tests/                          # 协议与设备模拟测试
│   └── docs/协议.md                    # CB08 通讯协议 V1.0
├── img/                                  # 项目图片资源
│   ├── 录音卡片.png                       # 产品图片
│   ├── 硬件参数.png                       # 硬件参数图
│   └── 企业微信.png                       # 联系二维码
├── SDK 集成引导.docx                     # SDK 集成流程与平台接入引导
├── 声云专利交底书-标准BLE指令SDK方案.docx # 标准 BLE 指令 SDK 技术方案参考
├── demo.mp4                            # 演示视频
└── LICENSE                             # MIT License

五分钟运行桌面 Demo

需要 Python 3.10 以上、可用 BLE 适配器，以及一台处于可连接状态的录音卡。

cd pnote-web-win&Mac-demo
python -m venv .venv
source .venv/bin/activate                 # Windows PowerShell: .venv\\Scripts\\Activate.ps1
pip install -r requirements.txt
python main.py --web

浏览器打开 http://127.0.0.1:8000。命令行也可这样验证：

record> scan
record> connect 0
record> smoke
record> list
record> download 0
record> transcribe 0

完整命令见 桌面 Demo README。离线转写和 Web 页面为可选能力：

pip install -r requirements-asr.txt
pip install -r requirements-web.txt
python -m unittest discover tests -v

首次转写会从 ModelScope 下载约 900 MB 模型，之后可离线运行。

pnote-web-win&Mac-demo

桌面 Demo 位于 pnote-web-win&Mac-demo，同时提供命令行 REPL 和浏览器 Web 控制台，可完成设备扫描、连接巡检、录音控制、文件下载、WAV 试听、实时推流和离线转写。

录音卡 BLE 控制台

移动端接入

开始接入前，请先阅读 SDK 集成引导（Word），了解权限、依赖、初始化、回调、音频处理、文件续传和 OTA 验收流程；需要理解跨厂商标准化设计时，可参考 标准 BLE 指令 SDK 技术方案。

Flutter 联调工程

cd pnote-sdk-flutter-demo-main
flutter pub get
flutter run

请使用真机验证蓝牙、录音、Wi-Fi 和 OTA。核心入口是 lib/provider_record_pen.dart，详见 Flutter Demo README。

Android

将 Android AAR 复制到应用的 app/libs（或 src/main/libs），添加 fileTree 依赖及 SDK 所需的 RxJava、Retrofit、EventBus 等依赖，然后调用：

PNote.init(context, deviceDataListener);
PNote.startSearch();
PNote.connectDevice(name, address);

回调包括 JSON 设备事件、实时录音 OPUS 数据和文件 OPUS 数据。完整接口见 Android SDK 开发文档。

iOS

将 libPNote.a 与 PNode.h 加入 Xcode，实现 WindBleDelegate，调用 startSearch、connectDeviceAndAddress 等接口。完整接口和 OTA 流程见 iOS SDK 开发文档。

鸿蒙

鸿蒙 SDK 以 har_recordersdk.har 提供，当前集成引导按 HarmonyOS API 12+ 编写。将 HAR 引入工程后，申请蓝牙权限并使用扫描回调中的 deviceId 连接；该 deviceId 可能是系统隐私随机标识，address 仅用于展示。业务结果均从 DEVICE_DATA 事件异步返回。

协议实现要点

协议字段、命令表、真实抓包帧和兼容策略见 docs/协议.md。

集成建议

  1. 先用桌面 Demo 对真实样机完成扫描、连接、时间同步、巡检和至少一个文件下载。
  2. 移动端按目标系统申请蓝牙权限；初始化 SDK 后注册设备事件、实时录音和文件数据回调，再开始扫描。
  3. 使用扫描事件返回的连接标识发起连接；连接成功后先同步时间，再读取电量、容量、版本和文件列表。
  4. 把回调转换到应用自己的事件队列或状态管理层，方法调用只代表请求提交，业务完成以异步事件为准。
  5. 音频按 40 字节 Opus 帧交给独立解码任务；文件按完成状态收尾、记录 offset，并校验大小和可解码性后再展示。
  6. OTA 仅在 Wi-Fi/TCP 建链、版本需要更新且电量不低于 20% 时执行；升级中 BLE 或 Wi-Fi 断开都应标记失败，不要无条件重发完整固件。
  7. 硬件新增芯片或型号时优先扩展 VendorAdapter、能力位和版本协商，不要让厂商私有字段渗透到 App 业务层。
  8. 云端 ASR 密钥、设备授权码和真实录音不得硬编码或提交到仓库；日志和抓包应脱敏。

适用场景

适用于会议记录、采访采集、课堂培训、内容创作、巡检记录、智能硬件配套 App、企业礼赠录音设备，以及需要将杰理、蓝讯、炬芯、BK 等方案快速接入同一 App 的软硬件联合项目。硬件方案商可复用标准适配契约，应用团队可复用跨平台业务模型，双方共同扩展录音硬件产品生态。

硬件与商业合作

合作模式可按“硬件方案适配 + SDK 交付 + 项目服务”推进：方案商提供芯片能力、BLE 服务/特征和私有命令约束，声云在 VendorAdapter 中完成标准化映射；App 团队使用 Android、iOS、HarmonyOS 或 Flutter 接口完成业务集成。批量采购、样机验证、外观/固件定制、行业功能、云端转写和交付支持可按项目评估，具体 SDK 包、版本和授权范围以交付清单及商务协议为准。

企业微信

如需获取硬件规格、样机、鸿蒙 SDK、协议完整版、企业微信二维码或技术支持资料，请联系 安徽声云（官网：sinicloud.com）。咨询时请说明目标平台、预计数量和应用场景。

许可与使用边界

仓库示例代码以 MIT License 发布。AAR、静态库、HAR、固件、设备私有协议和部分文档可能包含声云或厂商专有内容，不等同于全部开源，具体使用、再分发和商用范围以随包说明及双方商务协议为准。接口字段、命令编号和行为以最新 SDK、固件、协议版本及真机联调结果为准；SDK 不替代应用侧的 Opus 解码、文件存储、权限管理或安全控制。请勿将私有协议用于未获授权的硬件或产品。

“标准 BLE 指令 SDK 技术方案”文档用于技术交底和方案沟通，不替代专利代理师的现有技术检索、权利要求布局或法律意见。

反馈与问题

提交问题时请附上操作系统与版本、目标平台、SDK/Demo 版本、设备固件版本、复现步骤，以及必要的日志或收发帧 hex。涉及真实设备数据时，请先脱敏序列号、地址、授权码和录音内容。

sonicloud_opensdk (SonicloudTech/sonicloud_opensdk)

Searching Database…

2.6K ·GitHub
Sonicloud_opensdk
这是什么？这是一个开放的 SDK 和参考实现，用于把蓝牙录音卡硬件设备（声云录音卡）接入你自己的应用，涵盖 BLE 协议、设备控制、实时音频、文件传输、OTA 更新和转写，并提供 Android、iOS、HarmonyOS、Flutter 以及 Windows/macOS 桌面端的示例。
这是我要集成的库，还是成品应用？它主要是一个 SDK（Android AAR、iOS 静态库、HarmonyOS HAR、Flutter 插件），外加一个 Windows/macOS 桌面演示应用和一个 Python 参考实现；你需要把 SDK 集成到自己的软件里，与单独的硬件产品通信。
怎么让桌面演示跑起来？安装 Python 3.10+，准备好可用的 BLE 适配器并让录音卡处于可连接范围内，然后运行 'pnote-web-win&Mac-demo' 文件夹中的桌面演示，它同时提供 CLI 交互界面和基于浏览器的网页控制台。
使用它需要真实的录音卡硬件吗？需要，你需要声云录音卡实体设备本身（样品和规格请联系 Anhui Sonicloud）；Android 集成还需要添加 AAR 以及 RxJava、Retrofit 和 EventBus 依赖。
SDK 不会替我处理哪些事情？SDK 只给你原始的 16 kHz 单声道 Opus 音频帧，既不解码也不生成 WAV 头；OTA 固件更新必须通过 Wi-Fi/TCP 链路进行，因为纯 BLE 无法传输固件。
移动端集成支持哪些平台？移动应用支持 Android、iOS、HarmonyOS（API 12+）和 Flutter，另有 Windows/macOS 桌面演示用于 PC 端工具和测试。
VendorAdapter 层到底解决什么问题？Jieli、Lanxun、Bluetrum、BK 等不同 BLE 芯片厂商各自有不同的服务 UUID、特征值和私有指令；VendorAdapter 层吸收了这些差异，应用无论面对哪种芯片都使用同一套统一的 SDK 接口。
录音卡配合 SDK 实际能做什么？按键触发的录音控制、实时 Opus 音频流、可断点续传的文件列表和下载、基于 Wi-Fi 的文件和固件传输、设备信息查询（电量、固件、SN），以及在一次性下载约 900MB 模型之后的离线语音转文字。
BLE 协议是怎么构成的？它使用 GATT 服务 0xAE20，包含写特征 AE21、数据通知 AE22 和按键通知 AE23，采用 MAGIC+SEQ+CRC-16/XMODEM+LEN+TYPE/CMD/PARAMS 帧格式，并为分片的 BLE 包提供重组逻辑。
什么时候触发 OTA 固件更新才是安全的？只有在 Wi-Fi/TCP 链路已建立、确实需要更新版本且设备电量不低于 20% 时才触发；如果更新中途 BLE 或 Wi-Fi 断开，任务应标记为失败，而不是盲目重发整个固件。
What are similar projects?EchoMuse, muse-gadget-sdk, hermes-gadget-sdk, voiceshell-muse-bridge, omi, UFI-TOOLS, deck-as-controller, arduino-esp32
Which topics is it in?harmonyos, bluetooth-le, bluetooth, audio-processing, speech-to-text, firmware, iot, embedded, hardware, audio, sdk, c++
Creator
SonicloudTech
Size
116.6 MB
Stars
2.6K
Updated
CommitOct 19
Age
1mo
Commits · 90 Days