企业官网建设流程全解析

声云uMouse智能鼠标SDK接入指南：C、Python、C#、Node.js四语言调用纯C ABI动态库

【免费下载链接】sonicloud_opensdk声云录音卡 Recorder 是一套面向开发者和行业客户的智能录音硬件接入方案。 项目以录音卡片硬件为核心，开放 BLE 协议 SDK 及 Android、iOS、鸿蒙、Flutter 接入示例，同时提供 Windows/macOS 桌面端 Demo，支持设备连接、录音控制、实时音频、文件传输、OTA 升级和语音转写等能力，帮助开发者快速将录音硬件接入自己的 App、桌面软件或行业系统。 如需获取硬件规格、样机、完整协议、SDK 资料或定制服务，请联系安徽声云项目地址: https://gitcode.com/gh_mirrors/recorder24/sonicloud_opensdk

声云uMouse智能鼠标SDK以「一个纯 C ABI 动态库 + 一个头文件」的极简形态交付，支持 C、C++、C#、Python、Node.js 等主流语言直接调用，覆盖 USB 与 BLE 双通道，向上输出原始按键事件、JSON 离散事件和 16 kHz PCM 音频流。本指南带你 5 分钟跑通 Demo，并完成四语言集成、平台选包与避坑。

🖱️ SDK 能做什么：三类数据输出

SDK 负责把硬件数据「忠实搬运」出来，不做任何业务映射——M 键按下后触发截图还是语音转文字，完全由你的程序决定：

核心设计原则：SDK 只搬运数据，业务逻辑由调用方实现。这样对外接口可以长期稳定，硬件升级只需在 JSON 里新增字段。

📦 平台选包：二进制不互通，按目标系统选

各平台动态库针对目标系统编译，不可互换：

以 Windows 包为例，结构为include/umouse_sdk.h（唯一对外头文件）+bin/*.dll（主库与 FFmpeg 运行期依赖）+lib/uMouseSdk.lib（MSVC 链接用导入库）；Linux/macOS 包则是include/+lib/libuMouseSdk.so|.dylib，并附带umouse_demo最小可执行示例。

⚡ 标准调用顺序：四语言通用

无论哪种语言，核心流程一致：

注册回调 →um_sdk_init()→（SDK 自动探测设备并回调）→ 业务处理 →um_sdk_close()

⚠️ 两个必记要点：

1. 回调必须在um_sdk_init()之前注册，否则可能错过设备连接等早期事件；
2. 回调内严禁长时间阻塞、反向调用um_sdk_close()（会死锁），推荐「回调只拷贝、业务在工作线程处理」。

拿到包后建议先运行自带的umouse_demo验证硬件通路，运行后应打印[connected] … via USB、[message] … deviceInfo与音频数据，音频会写入out.pcm，可用 Audacity 按Signed 16-bit PCM / Little-endian / Mono / 16000 Hz导入播放。

C / C++：直接链接，CMake 消除平台差异

将include/加入头文件搜索路径，Windows 链接uMouseSdk.lib并把 dll 放到可执行文件同目录，Linux/macOS 链接-luMouseSdk。最小示例：

um_register_connected(on_connected); // 1. init 前注册回调 um_register_disconnected(on_disconnected); um_register_message(on_message); um_register_audio(on_audio); um_sdk_init(1); // 2. 初始化（debug=1 开日志） /* 3. 业务运行…… */ um_sdk_close(); // 4. 释放（幂等）

CMake 工程三行搞定链接：target_include_directories指向include，target_link_directories指向lib，target_link_libraries链接uMouseSdk。完整含音频落盘的示例见 第三方接入说明.md 附录 A。

C# (.NET)：P/Invoke 零依赖调用

通过DllImport直接声明um_sdk_init、um_register_*等导出函数，无需第三方库。Windows 库名为uMouseSdk，Linux 改libuMouseSdk.so，macOS 改.dylib后缀。

关键避坑：用于 P/Invoke 的回调委托必须存为字段或静态成员，否则 CLR 的 GC 会回收它，SDK 回调时访问已释放内存直接崩溃。

Python：ctypes 标准库即可

用ctypes.CDLL加载动态库，CFUNCTYPE定义回调签名后注册：

lib = ctypes.CDLL("./libuMouseSdk.so") # 按平台改库名 ON_MESSAGE = CFUNCTYPE(None, c_char_p, c_char_p) @ON_MESSAGE def on_message(device_id, json): print(device_id.decode(), json.decode()) lib.um_register_message(on_message) # 保持引用存活！ lib.um_sdk_init(1)

⚠️ 用@CFUNCTYPE装饰的回调对象必须保持引用存活（写成模块级变量即可），不要作为临时变量传给 register——这是 Python 集成闪退的头号原因。

Node.js / Electron：koffi 加载动态库

Node 生态推荐用支持回调注册的koffi库：koffi.load()加载动态库，lib.func()声明函数签名，回调需用koffi.register()注册并保持引用，即可在 JS 中解析um_on_message上报的 JSON 事件。

📋 按键事件协议速查：keyEvent字段一览

所有离散事件统一为{"type":"...", ...}结构，扩展性由type字段保证向后兼容：

示例：收到{"type":"keyEvent","key":"speech","action":"down"}开始录音，action:"up"时停止并送识别；收到{"key":"m","action":"hold","index":1}触发第一个 M 键的自定义功能。此外还有deviceInfo（序列号/电量/连接类型）、dpiChanged、meetingCreated/Destroyed等事件。

🚨 平台注意事项与高频坑位

• Windows：uMouseSdk.dll、avcodec-58.dll、avutil-56.dll需与.exe同目录或可被PATH找到；报缺VCRUNTIME140.dll时安装 VC++ 运行库即可。
• Linux（UOS/麒麟）：USB HID 设备节点默认仅 root 可读写，必须一次性安装 udev 规则（按 VID/PIDabc9:ca89匹配hidraw*并设MODE="0666"），否则只能sudo运行；动态链接依赖libavcodec、libavutil、libudev、libdbus-1，UOS/麒麟通常软件源可装。
• macOS：需要系统 FFmpeg 权限提示（蓝牙、输入监听、辅助功能）；做 codesign 公证时libuMouseSdk.dylib须一并纳入签名。
• 数据生命周期：回调中的device_id、json、pcm指针仅在回调期间有效，需要留存立即strdup/memcpy。
• 验证加载：调用um_sdk_version()应返回"0.1.0"，返回 NULL 或崩溃说明动态库未正确加载。

📚 延伸阅读

• 完整 API 参考、平台注意事项、FAQ 与附录示例：第三方接入说明.md
• SDK 模块划分、事件码体系与按键定制规则：ReadMe.md
• 各平台交付包（Windows / UOS / 麒麟 / macOS 等）：uMouse/

💡 遇到集成问题，请用um_sdk_init(1)打开内部日志，附带目标平台、SDK 版本号与复现步骤反馈，可快速定位是权限、依赖还是调用时序问题。

【免费下载链接】sonicloud_opensdk声云录音卡 Recorder 是一套面向开发者和行业客户的智能录音硬件接入方案。 项目以录音卡片硬件为核心，开放 BLE 协议 SDK 及 Android、iOS、鸿蒙、Flutter 接入示例，同时提供 Windows/macOS 桌面端 Demo，支持设备连接、录音控制、实时音频、文件传输、OTA 升级和语音转写等能力，帮助开发者快速将录音硬件接入自己的 App、桌面软件或行业系统。 如需获取硬件规格、样机、完整协议、SDK 资料或定制服务，请联系安徽声云项目地址: https://gitcode.com/gh_mirrors/recorder24/sonicloud_opensdk