企业官网建设流程全解析

MicYou Native 插件开发指南：C ABI、实时安全声明与虚拟设备深度集成

【免费下载链接】MicYouMicYou is a powerful tool that turns your Android device into a high-quality microphone for your PC.项目地址: https://gitcode.com/gh_mirrors/mi/MicYou

MicYou 可以把你的安卓手机变成电脑的高质量麦克风，而它的插件系统让开发者能深度扩展音频处理能力。本篇是面向新手的MicYou Native 插件开发指南，带你从零理解 C ABI 接口、realtimeSafe实时安全声明，以及如何把插件接进虚拟麦克风输出流。

一、为什么选择 Native 插件运行时

MicYou 插件系统提供双运行时：Native（cdylib 动态库）与WASM（沙箱模块）。两者统一使用plugin.json清单与消息协议，区别在于加载方式和能力边界：

一句话选型：要碰实时音频数据、要深度系统集成就选 Native；写面板、自动化、跨平台通用逻辑就选 WASM。

架构上，插件由 PluginManager 加载后，通过 PluginBus 总线发布订阅、与 DSP 处理链协同工作，完整说明见 docs/plugins/overview.md。

二、插件目录结构与 plugin.json 清单

每个 Native 插件就是一个目录，结构极简：

<插件目录>/ ├── plugin.json # 清单（必需） ├── <entry> # 动态库产物（与清单 entry 一致） └── assets/ # 可选私有资源

插件目录放在宿主插件目录下（Linux/macOS 为~/.config/micyou/plugins/，Windows 为%APPDATA%\micyou\plugins\），目录名建议与插件 id 一致。

清单中最关键的几个字段：

• id：反向域名，如dev.micyou.example.gain，必须含点
• runtime: "native"+entry：入口产物名。跨平台分发时省略后缀与lib前缀（如my_plugin），宿主会按当前系统自动补全.dll/.so/.dylib，一个 ZIP 包即可全平台通用
• apiVersion：Host API 版本，当前为 1，不匹配会被拒绝加载
• capabilities：只申请需要的能力（如dsp.node、config.read、audio.play），越权调用会收到MPL_ERR_PERMISSION错误
• kind: "dsp"+dsp.realtimeSafe: true：声明为实时 DSP 节点
• arches：Native 插件必须声明支持的 CPU 架构

完整字段表和校验规则见 docs/plugins/development-guide.md。官方示例 plugins/examples/native-soundpad/plugin.json 是一个可直接对照的 Native 清单模板。

三、C ABI 接口：三个必需符号 + 宿主函数表

Native 插件通过版本化 C ABI 与宿主交互，ABI 头文件定义在 tauri-app/crates/micyou-plugin/include/micyou_plugin_abi.h，当前MPL_ABI_VERSION = 1。插件只需导出3 个必需符号：

// 插件身份：abiVersion、apiVersion、id 必须与 plugin.json 一致 const mpl_plugin_info_t *micyou_plugin_info(void); // 初始化：宿主把 host 回调表交给你（注意：要按值完整拷贝，不能只存指针） mpl_result_t micyou_plugin_init(const mpl_host_api_t *host); // 库卸载前调用一次 void micyou_plugin_deinit(void);

另有 3 个可选符号，缺省视为旁路/无操作：

宿主通过mpl_host_api_t函数表反向提供服务：读写配置、发布事件、跨端发消息、查询音频状态与设备列表、播放音效、注册全局快捷键、读写插件目录内文件、HTTP 请求等。API v2 还追加了静音控制、耳返监听、DSP 参数读写等控制面接口（新字段严格追加在ctx之后，旧插件无需重新编译）。完整能力清单与缓冲区契约见 docs/plugins/api-reference.md。

写 Rust 插件时有两个硬性细节（Rust 官方示例在 plugins/examples/native-soundpad/src/lib.rs）：

• panic 必须被catch_unwind捕获，绝不跨 FFI 边界传播
• host 结构体在init中按值拷贝到全局状态，因为宿主在init返回后可能释放原内存

四、realtimeSafe：实时安全声明不是"装饰"

dsp.realtimeSafe: true是宿主信任依据——宿主会默认你的process函数是实时的，不做额外保护。这意味着以下规则是硬性要求，违反可能导致爆音或卡顿：

1. 不分配堆内存：process内禁止Vec、String、格式化等任何堆分配
2. 不调用阻塞 host API：get_config涉及锁与 I/O，只能在init中使用；process里调用任何 host API 都可能导致死锁
3. 单帧处理时间 < 1 ms：48 kHz 下一帧为 480 样本（约 10 ms），预算必须远低于此
4. 状态预先分配：滤波器系数、历史缓冲在初始化时建好
5. 出错返回错误码并保持输出可预测（静音或旁路），绝不 panic

对比之下，WASM 插件因解释执行无法保证实时性，宿主强制按 best-effort 处理并禁止其声明realtimeSafe。官方降噪门示例（native-noisegate）展示了正确姿势：全程无分配、无 host 调用，配置经原子变量无锁读取。

五、深度集成虚拟设备：从 DSP 链到虚拟麦克风输出

这是 Native 插件最"深度"的部分——插件直接参与虚拟麦克风的数据通路。

1. 插入 DSP 处理链

音频线程解码后依次经过处理链（AEC 回声消除 → 降噪 → 去混响 → EQ → 放大 → AGC → VAD），插件系统通过合成节点Plugins注入链中，由 tauri-app/crates/micyou-plugin/src/dsp.rs 中的PluginDspRegistry管理节点顺序：

• dsp.insertAfter指定插入位置（如"AEC"之后），或first: true排在最前
• 节点顺序确定性强（first优先，再按插件 id 排序）
• 单节点失败只记日志并旁路，不影响整条链

2. 音效混入虚拟麦克风流

调用 host 的play_sound（需audio.play能力）播放 WAV 文件，声音会混入虚拟麦克风输出流——电话对方和你本人都能听到，等同于真实麦克风输入。典型用法：

• 按钮面板（ui.route: "buttons"）渲染按钮网格，点击 → 收到ui:play消息 →play_sound
• 全局快捷键（register_hotkey("ctrl+shift+s")）按下 → 总线投递hotkey:<id>消息 → 播放指定音效

官方示例 plugins/examples/native-soundpad/ 完整演示了这条链路：init时自动生成三个正弦波 WAV，注册快捷键，点击按钮或按下 Ctrl+Shift+S 即可从虚拟麦克风输出音效。

3. 跨端消息：手机传感器 → 电脑处理

手机与电脑连接后，两端插件通过 protobufPluginMessage总线通信（发布订阅 + RPC 请求响应），可把手机传感器数据送进电脑侧 DSP 插件处理，详见 docs/plugins/architecture-extensibility.md。

六、快速开发流程（micyou-cli 工具链）

micyou-cli plugin create dev.micyou.mynative --runtime native # 生成骨架 micyou-cli plugin dev ./myplugin # 监听变更，保存即热重装 micyou-cli plugin validate ./myplugin # 校验清单与入口产物 micyou-cli plugin package ./myplugin -o myplugin.zip # 打包导入

安装到宿主后，在设置-插件页「刷新」→ 启用 → 查看日志即可验证；加载失败时list_plugins会返回error字段说明原因。集成测试夹具可参考 tauri-app/crates/micyou-plugin/tests/native_loader.rs。

七、版本兼容策略速览

• ABI 冻结：破坏性变更才升级MPL_ABI_VERSION并拒绝旧插件
• Host 函数表追加式演进：新字段只加在ctx之后，旧插件按旧偏移读取，无需重编译
• 能力逐调用校验：未声明的能力返回错误码 8，未声明的未知能力在清单校验阶段即被拒绝

参考文档

• 开发指南：docs/plugins/development-guide.md
• API 与错误码：docs/plugins/api-reference.md
• 架构与扩展说明：docs/plugins/architecture-extensibility.md
• ABI 头文件：tauri-app/crates/micyou-plugin/include/micyou_plugin_abi.h
• Native 示例源码：plugins/examples/native-soundpad/src/lib.rs

【免费下载链接】MicYouMicYou is a powerful tool that turns your Android device into a high-quality microphone for your PC.项目地址: https://gitcode.com/gh_mirrors/mi/MicYou