UDP2Mic AI 继任者指南
写给下一个接手这个项目的 AI / 开发者
最后更新: 2026-06-04 | 状态: v1.0.4 — 高并发安全、免重启热更新、无缝热重连
一、你现在接手的是什么
一个工业级稳定、低延迟且高度解耦的局域网麦克风系统，支持高级智能 AGC 与动态噪声门：
[Android 手机] ──{非对称AGC → 噪声门}──→ Opus 线程锁 ──→ UDP热重连 ──→ [Windows PC] ──WASAPI──→ [VB-Cable]
↓
微信/Zoom/OBS/游戏
双端均已编译通过。无任何残留的神经网络降噪，全管线高度精简。
二、编译命令
Windows
build_windows.bat
# 产物: udp2mic.exe (根目录)
Android
build_android.bat
# 产物: udp2mic-release.apk (根目录，已签名)
编译前提: Rust 1.96+, VS Build Tools 2022 (C++), CMake 3.22+, JDK 17, Android SDK 35, NDK 27.0.12077973
本地 SDK 路径: C:\Android\sdk
三、架构精要与并发避坑指南（核心技术资产）
1. JNI 与音频流的高并发互斥防线（防闪退）
在 CaptureService.kt 的 while(isActive) 循环体（IO 协程线程池）中，系统会极高频地调用 encoder?.encode(...)。与此同时，用户可能在 UI 二级菜单中疯狂滑动或切换属性，触发 encoder?.update(...)。
- 核心防线：
OpusEncoder.kt 中的 encode、update、start 和 stop 方法全部强制加有 @Synchronized 锁挡板。这确保了底层的 C++ 指针句柄（handle）绝不会被两个线程同时操作，彻底封死了因内存越界导致系统爆出 SIGSEGV (Fatal Signal 11) 闪退的隐患。
2. 免重启音频管线与“无缝热重连”
过去任何参数（IP、端口、音频属性）的修改都需要彻底掐断 AudioRecord 硬件流并重启协程。现在已被全面改造为数据驱动架构：
- 网络热重连：当用户修改主界面的“目标 IP”或“端口”时，
MainActivity 仅将数据写入 Prefs，绝不调用 restart()。CaptureService 在每一帧的交替间隙会进行 Hash 挡板比对，发现网络变更后原地静默销毁并重建 UdpSender，麦克风和编码器全程保持常驻。
- 参数热更新：Opus 二级菜单的所有参数更改同样通过计算参数指纹（
Hash）边缘触发。在不破坏当前帧状态的前提下，通过 JNI 的 encoderUpdate 实时灌入底层。
3. 智能 AGC 与滑块的彻底解耦
- 边缘触发重置：当 AGC 状态从“关闭”切到“开启”的瞬间，系统触发边缘检测，直接清空旧的 RMS 蓄水池并将增益重置到健康的 10.0x 启动点，避免直接继承用户之前在固定模式下拉出的 200x 巨型暴音。
- 上限绝对独立：自动 AGC 的动态调整上限被死死限制在 100.0x（防止硬件啸叫与过载），手动固定增益滑块的范围为
0~200x，两者在算法内部彻底解耦。
4. Compose 状态流高频重绘优化
- 问题背景：
CaptureService 每秒会向 StateFlow 抛出包含 bitrateKbps、agcGainDb 的全新大状态实例。
- 优化策略：
MainActivity 内部的 MainScreen 通过 LaunchedEffect 精细化监听并分流赋值给局部 remember 变量，避免了每秒一次的全局强刷对 UI 组件（如用户正在拖动的 Slider）造成卡顿或跳变。
四、历史重大变更记录 (Changelog)
版本 | 变更点 | 核心目的 / 解决的痛点 |
|---|
v1.0.4 | JNI 同步锁 / 网络无缝热重连 | 引入 @Synchronized 彻底根除多线程并发闪退；主页修改 IP 绝不重启录音流，后台静默重连，UI 滑块零卡顿。 |
v1.0.3 | AGC 解耦 / Opus 免重启参数热更新 | 彻底剥离 restart() 逻辑，引入参数指纹挡板；修复自动码率传 0 导致底层死锁漏洞；AGC 上限与固定滑块彻底松绑。 |
v1.0.2 | 移除了 RNN/TFLite 降噪 | 斩断过度设计的神经网络，回归轻量化、无延迟的经典语音信号处理管线。 |
v1.0.1 | 重构为 Kotlin 协程常驻服务 | 废除频繁销毁重建线程的重型逻辑，改为常驻后台前台服务。 |
五、接手后推荐的后续演进方向
- JNI 层指针健壮性（可选）：目前 Kotlin 层已经提供了完美的同步锁保护。如果未来需要对底层 C++ 进行大规模重构，可以在
opus_jni.c 的 EncoderState 结构体中加入 pthread_mutex_t 锁，实现双向保险。
- 局域网多播自动发现（可选）：由于目前网络层支持了免断流的静默热重连，未来可以非常轻松地通过
MDNS 或 UDP 广播实现一键搜索 PC 接收端并热连接，完全消灭手动输入 IP 的步骤。
