如何10分钟跑通uMouse SDK:Windows/macOS快速开始完整教程

原创2026-11-17 00:00:011,748 阅读

如何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 是得不到这些能力的;它也不是通用鼠标驱动。

uMouse SDK 智能鼠标 SDK 数据输出:按键事件、JSON 设备信息与 PCM 音频

快速开始前的环境准备: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()

新手最容易踩的三个点,提前记住:

  1. 回调必须在 um_sdk_init() 之前注册,否则会错过设备连接等早期事件;
  2. 回调中的指针参数仅在本回调期间有效,需要留存请立即拷贝(strdup / memcpy);
  3. 回调运行在 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 技术支持与商务联系微信二维码(声云智能鼠标 SDK)

总结:uMouse SDK 快速开始要点回顾

  • 📦 选对包:Windows x64 与 macOS ARM64 包不可互换,解压到仓库根目录得到 uMouseSdk/;
  • 🚀 跑通 demo:编译 demo.c,见到 [connected] 与回调数据才算真正打通;
  • 🧩 记住调用顺序:注册回调 → um_sdk_init() → 业务处理 → um_sdk_close();
  • 🛠️ 遇到问题:优先查动态库加载与依赖完整性,再查设备触发与权限授权。

按照本教程,你现在已经能在 Windows 或 macOS 上完成 uMouse SDK 的最小闭环,接下来可以按 docs/第三方接入说明.md 把按键事件与 PCM 音频接入到自己的语音输入或会议应用里。

登录后查看全文
mouse-sdk