如何10分钟跑通uMouse SDK:Windows/macOS快速开始完整教程
如何10分钟跑通uMouse SDK:Windows/macOS快速开始完整教程
uMouse SDK(声云智能鼠标 SDK)是一个跨平台 USB HID / BLE 智能鼠标接入 SDK,提供纯 C ABI 接口,可读取按键事件、JSON 设备信息和 PCM 音频数据。本教程带你在 Windows 或 macOS 上快速跑通官方最小示例:下载 SDK 包 → 编译 demo → 连接设备验证数据链路,全程约 10 分钟,适合新手和普通用户上手。
uMouse SDK 是什么?适合谁用
一句话概括:uMouse SDK 把你的智能鼠标硬件数据「忠实搬运」到你的程序里,包括三类输出:
- 🔘 原始按键事件 —— 语音 / 翻译 / M / AI / 截图键的按下、抬起、长按、单击,不做业务映射;
- 📋 JSON 离散事件 —— 设备序列号(SN)、电量、DPI 变更、会议状态等;
- 🎙️ 音频数据 —— 内置解码为 PCM(16 kHz / 16 bit / 单声道),也可透传原始编码块。
它统一封装 USB(HID) 与 BLE(蓝牙低功耗) 两种连接方式,支持多设备并发,可从 C/C++、C#、Python、Electron / Node.js 调用。适用于语音输入、翻译工具、会议记录应用开发者,以及做硬件厂商集成。
⚠️ 提前说明:uMouse SDK 需要兼容的声云硬件(或按 RAW 模式完成适配的自有硬件),普通鼠标仅安装 SDK 是得不到这些能力的;它也不是通用鼠标驱动。
快速开始前的环境准备:5 分钟自查清单
在动手前,对照下面清单确认环境:
| 检查项 | 要求 |
|---|---|
| 操作系统 | Windows 10 / 11(x64)或 macOS 11+(Apple Silicon / ARM64) |
| 硬件 | 兼容的声云智能鼠标(USB 2.4G 接收器或 BLE 配对) |
| Windows 工具 | x64 版本的 MSVC 开发者命令提示符(Developer Command Prompt) |
| macOS 工具 | Xcode Command Line Tools |
| 网络 | 可正常解压仓库内 SDK 包 |
SDK 二进制包已放在仓库的 packages/ 目录中,两个平台包分别是:
💡 注意:各平台二进制包不能互换,请一定选择与你系统架构匹配的包(Windows x64 / macOS ARM64)。
uMouse SDK 三步快速开始:从克隆到跑通
第 1 步:获取示例源码并解压 SDK 包
先克隆仓库拿到 C 示例源码:
git clone https://gitcode.com/gh_mirrors/mo/mouse-sdk
cd mouse-sdk
然后从 packages/ 下载对应平台的 ZIP,解压到仓库根目录,确认目录结构满足:
mouse-sdk/
├── uMouseSdk/ ← 解压后得到的 SDK 目录
│ ├── include/umouse_sdk.h
│ └── (动态库 / 导入库 / 运行期依赖)
├── demo/demo.c ← 最小示例
└── ...
第 2 步:编译官方最小示例 demo.c
仓库自带 demo.c 是最简接入示例(约 60 行),第一次接入从它开始。
Windows x64(在 MSVC 开发者命令提示符中,位于仓库根目录):
cl /I uMouseSdk\include demo\demo.c /Fe:umouse-demo.exe /link /LIBPATH:uMouseSdk uMouseSdk.lib
set "PATH=%CD%\uMouseSdk;%PATH%"
umouse-demo.exe
macOS ARM64:
cc -IuMouseSdk/include demo/demo.c -LuMouseSdk -luMouseSdk -Wl,-rpath,@executable_path/uMouseSdk -o umouse-demo
./umouse-demo
⚠️ 关键细节:保留包内所有运行库与 SDK 主库的相对位置(Windows 包内含 FFmpeg 与 VC++ 运行库 DLL,macOS 包内含裁剪版 FFmpeg dylib),不要只复制主 DLL / dylib。
第 3 步:连接设备,验证数据链路
插入 USB 接收器(或完成蓝牙配对)后,终端应依次出现:
uMouseSdk demo, version 0.4.20
[connected] 000AEB20... via USB
[message] 000AEB20... {"type":"deviceInfo","sn":"000AEB20...","battery":50,"deviceType":"usb","status":"normal"}
[audio len=] 320
示例会打印 SDK 版本;设备上线后出现 [connected],之后输出按键 / 设备事件与音频长度,并把收到的 PCM 保存为 out.pcm(可用 Audacity「导入原始数据」,选 Signed 16-bit PCM / Little-endian / Mono / 16000 Hz 播放验证)。按回车退出。
🔍 判断标准:能读到版本号只说明库已加载;看到
[connected]和回调数据,才说明硬件链路真正打通。
uMouse SDK 核心调用顺序:一分钟看懂 C ABI
无论用什么语言,uMouse SDK 的核心调用顺序都是:
注册回调 →
um_sdk_init()→ 业务处理 →um_sdk_close()
新手最容易踩的三个点,提前记住:
- 回调必须在
um_sdk_init()之前注册,否则会错过设备连接等早期事件; - 回调中的指针参数仅在本回调期间有效,需要留存请立即拷贝(
strdup/memcpy); - 回调运行在 SDK 内部事件派发线程,不要在回调里做阻塞操作(网络请求、大文件读写),也不要反调
um_sdk_close()。
完整 API 与 JSON 事件协议速查见 docs/第三方接入说明.md,公共接口声明全部在 include/umouse_sdk.h 中,它是 SDK 唯一对外头文件(纯 C ABI)。
按场景选择 uMouse SDK 示例:4 个 demo 怎么选
仓库 demo/ 提供四个单文件纯 C 示例,按你的场景选择:
| 你的情况 | 用哪个 |
|---|---|
| 接声云智能鼠标,按键 / 音频 / 设备信息直接能用 | demo.c —— FULL 模式最小示例 |
| 声云鼠标,但原始帧要自己解析 | demo2.c —— RAW 模式、握手与通道切换 |
| 声云设备与自定义设备同时在线 | demo3.c —— 多规则、FULL / RAW 共存 |
| 完全自有的外部硬件(USB/BLE 全是自己的) | demo4.c —— 替换默认规则的完整配方 |
各示例的适用场景与构建说明详见 demo/README.md。自有硬件接入需替换设备识别配置、握手与解析逻辑,USB 自定义硬件的数据通道须位于所选接口的首个 HID 顶层集合或独占接口。
uMouse SDK 常见问题排查:加载失败 / 没声音怎么办
Q:明明有 uMouseSdk.dll,为什么仍然加载失败?
检查三件事:① 进程架构是否与包匹配(Windows x64 进程用 x64 包);② 动态库搜索路径是否正确(按包内 README 配置 PATH 或加载方式);③ 是否保留了包内全部运行依赖(FFmpeg 与 VC 运行库 DLL),而不是只复制主 DLL。
Q:设备已连接,但收不到音频?
- 确认已注册音频回调(
um_register_audio); - 部分设备需先触发一次按键(如语音键)才开始推送音频流;
- 检查电量,低电量可能暂停音频。
Q:macOS 首次使用 BLE 没反应? 首次运行需授权「蓝牙」权限;USB / 2.4G 接收器连接则无需任何授权。
Q:Python / C# 集成后闪退或「访问非法内存」? 几乎都是回调委托被垃圾回收——把回调对象存为字段或模块级变量,保持引用长期存活,不要用临时变量注册。
Q:如何确认 SDK 正常加载?
调用 um_sdk_version() 应返回 "0.4.20";返回 NULL 或崩溃说明动态库未正确加载。更多 FAQ 见 docs/第三方接入说明.md。
参考资料与技术支持
跑通最小示例后,建议按这份清单深入:
| 资料 | 说明 |
|---|---|
| docs/第三方接入说明.md | 完整中文接入指南 v2.2:API 参考、JSON 事件协议、线程模型、各平台注意事项 |
| docs/Integration-Guide.en.md | 英文接入指南 v2.2 |
| include/umouse_sdk.h | 公共 C ABI 头文件(唯一对外头文件) |
| demo/README.md | 四个示例的适用场景与构建说明 |
| packages/ | Windows x64 / macOS ARM64 的 SDK 0.4.20 交付包 |
Linux / UOS / 麒麟 / 方德等平台包、兼容硬件样机与技术支持,可联系安徽声云智能科技有限公司(SoniCloud),请说明目标系统与架构、设备型号和应用场景:
总结:uMouse SDK 快速开始要点回顾
- 📦 选对包:Windows x64 与 macOS ARM64 包不可互换,解压到仓库根目录得到
uMouseSdk/; - 🚀 跑通 demo:编译 demo.c,见到
[connected]与回调数据才算真正打通; - 🧩 记住调用顺序:注册回调 →
um_sdk_init()→ 业务处理 →um_sdk_close(); - 🛠️ 遇到问题:优先查动态库加载与依赖完整性,再查设备触发与权限授权。
按照本教程,你现在已经能在 Windows 或 macOS 上完成 uMouse SDK 的最小闭环,接下来可以按 docs/第三方接入说明.md 把按键事件与 PCM 音频接入到自己的语音输入或会议应用里。
