# HearingAssist

**Repository Path**: anlinxi/hearing-assist

## Basic Information

- **Project Name**: HearingAssist
- **Description**: 基于 UniApp（Vue 3）的实时助听器应用：麦克风采集 → 9 段 EQ 处理 → 耳机实时回放，支持后台持续运行。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-16
- **Last Updated**: 2026-11-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 听力助手 HearingAssist

基于 UniApp（Vue 3）的实时助听器应用：麦克风采集 → 9 段 EQ 处理 → 耳机实时回放，支持后台持续运行。

- H5 端：WebAudio（AudioWorklet / ScriptProcessor 回退）实现，用于开发调试与桌面临时使用
- App 端：原生插件 `HearingAudio`（Android：AudioRecord + AudioTrack + 前台服务），低延迟链路

## 一、功能状态

| 优先级 | 功能 | 状态 |
| --- | --- | --- |
| P0 | 实时透传（麦克风 → 耳机） | H5 / Android 均已实现 |
| P0 | 9 段 EQ 调节（80Hz ~ 20480Hz） | H5 / Android 均已实现 |
| P0 | 后台持续运行 | H5 受浏览器限制；Android 前台服务已实现 |
| P1 | 频谱可视化 | H5 / Android 均已实现（原生 30Hz 推送，P2 流畅度优化） |
| P1 | 环境声预览（未启动时） | Android 已实现（原生采集 + 频谱分析，首页每秒刷新展示环境声）；H5 不支持 |
| P1 | 预设与自定义配置持久化 | 已实现 |
| P1 | 耳机插拔检测与路由提示 | 已实现（原生 `getRoute` + 事件） |
| P2 | 降噪 / AGC | 已实现（NS 软噪声门，强度 0~1 可调；AGC 自动增益，目标电平 -30 ~ -6 dBFS 可调） |
| P2 | AEC 回声 / 啸叫消除 | 已实现（AEC：NLMS 自适应滤波；啸叫抑制：FFT 频点检测 + 陷波） |
| P2 | 听力测试（纯音测听） | 未实现 |
| P2 | iOS 原生实现 | 未实现（见下文「已知限制」） |

## 二、目录结构

```
hearing-assist/
├─ src/
│  ├─ pages/            首页（启停+频谱）、EQ 调节、设置
│  ├─ components/       spectrum-view / eq-slider / preset-selector / device-status
│  ├─ utils/
│  │  ├─ audio-engine.js     引擎门面：native / web / unsupported 后端选择与统一接口
│  │  ├─ audio-processor.js  H5 WebAudio 实现
│  │  ├─ native-bridge.js    原生插件桥接（uni.requireNativePlugin）
│  │  ├─ device-monitor.js   耳机路由检测
│  │  ├─ eq-presets.js       9 段频点与预设
│  │  └─ storage.js          配置持久化
│  ├─ stores/config.js
│  └─ manifest.json          已声明 nativePlugins.HearingAudio
└─ nativeplugins/HearingAudio/        原生插件（本地插件，非云端插件）
   ├─ package.json                    插件描述（Android: source 集成）
   └─ android/
      ├─ AndroidManifest.xml          权限 + 前台服务声明
      ├─ build.gradle                 自行编译 aar 时使用
      └─ src/main/java/com/marvis/hearing/
         ├─ HearingAudioModule.java   插件门面（JS 方法 + 事件 + 权限）
         ├─ HearingAudioEngine.java   音频链路主循环 + 环境声预览
         ├─ HearingAudioService.java  前台服务（后台保活 + 常驻通知）
         ├─ EqProcessor.java          9 段 Biquad EQ + 前置增益 + 软限幅
         ├─ NoiseSuppressor.java      NS 环境降噪（软噪声门，强度可调）
         ├─ AgcProcessor.java         AGC 自动增益（目标电平可调）
         ├─ EchoCanceller.java        AEC 回声消除（NLMS 自适应）
         ├─ HowlingSuppressor.java    啸叫抑制（FFT 频点检测 + 陷波）
         └─ SpectrumAnalyzer.java     FFT 频谱分析
```

另：`scripts/check_plugin.py` 为插件结构/契约校验脚本（F2 收编，替代开发期手工核对）。

## 三、H5 端运行

```bash
npm install
npm run dev:h5     # 开发（vite.config.js 已开 server.host，便于手机同局域网访问）
npm run build:h5   # 构建，产物 dist/build/h5
```

注意：浏览器调用麦克风要求 HTTPS 或 localhost；页面切后台后浏览器会限流 AudioContext，无法保证后台持续运行，正式使用请用 App 端。

## 四、App 端打包

1. 用 HBuilderX 打开本项目（Vue 3 项目直接打开根目录）。
2. `manifest.json` 中已配置自定义原生插件 `HearingAudio`，插件位于 `nativeplugins/HearingAudio`。
3. 需要录音、蓝牙、前台服务、通知等权限，已在插件 `AndroidManifest.xml`、`manifest.json` 的 android 权限列表中同步声明。
4. 云打包（Android）即可，插件以 **源码集成**（`integrateType: "source"`）参与编译，无需预先产出 aar。

如需改为 aar 集成：

```bash
cd nativeplugins/HearingAudio/android
mkdir libs   # 把 HBuilderX 的 uniapp-v8-release.aar 放进来
gradlew :assembleRelease
# 产物 build/outputs/aar/*.aar → 重命名为 HearingAudio.aar 放到 nativeplugins/HearingAudio/android/
# 然后把 package.json 中 android.integrateType 改为 "aar"
```

## 五、原生插件接口

JS 侧统一通过 `src/utils/native-bridge.js` 调用，方法名与原生一一对应：

| 方法 | 说明 |
| --- | --- |
| `isSupported` | 平台与能力探测 |
| `requestPermissions` | 申请录音权限（原生内部处理权限回调） |
| `start(options)` | 启动链路；无权限时自动申请并续跑 |
| `stop` | 停止链路并释放设备 |
| `setEqGains(gains)` | 实时更新 9 段增益（dB） |
| `setPreamp(db)` / `setOutputVolume(v)` | 前置增益 / 输出音量 |
| `updateOptions(options)` | 批量更新运行参数 |
| `setSpectrumEnabled(enabled)` | 开关频谱推送 |
| `getRoute` | 当前输出路由（有线 / 蓝牙 / 扬声器） |
| `getStats` | 延迟、采样率、欠载次数 |
| `setNoiseSuppression(enabled)` / `setNoiseLevel(level)` | NS 环境降噪开关 / 强度（0~1） |
| `setAgc(enabled)` / `setAgcTargetDb(db)` | AGC 自动增益开关 / 目标电平（dBFS） |
| `startPreview` / `stopPreview` | 环境声预览（未启动时，原生采集 + 频谱分析，App 端生效） |
| `startBackground` / `stopBackground` | 前台服务保活开关 |

原生 → JS 事件：`HearingAudioRoute`、`HearingAudioSpectrum`、`HearingAudioError`、`HearingAudioState`。

## 六、已知限制

- **iOS 原生实现缺失**：`package.json` 中 iOS `plugins` 已置空，避免云打包 iOS 时报找不到类。补齐 `HearingAudioModule.swift`（AVAudioEngine + AVAudioUnitEQ + `.playAndRecord` + `.measurement` 模式 + Background Audio）后，再在 `package.json` 的 `ios.plugins` 中注册即可（B2，后续版本）。
- **环境声预览仅限 App 端**：预览模式依赖原生 `HearingAudio` 插件（Android），H5 端不支持；未授予录音权限时预览静默退出，不提示错误。
- **延迟**：已做代码侧低延迟加固——采集「设备缓冲」与「每次读取块」解耦（256 帧 ≈ 5ms 读取）、`AudioTrack` 低延迟标志 + 补写防欠载、启动淡入（E1/E2/E3/C4/C5）。`latencyMs` 仍为基于当前读写块大小的估算值，非实测端到端延迟；端到端 ≤20ms 目标需真机回环实测确认（D1/D12）。
- **蓝牙协议**：当前通过 `USAGE_MEDIA` 走系统默认路由，未干预 A2DP/SCO 选择；蓝牙场景延迟与协议表现需真机验证（E6）。
- **外放啸叫**：未检测到耳机时（`getRoute` 的 `speaker = true`），外放会形成声反馈啸叫，UI 已给出告警，请务必佩戴耳机。
- **第三方 App 无法采集**：受 Android 沙箱限制，仅能采集本应用麦克风，不能直接转接系统内其它 App 的音频。

## 七、免责声明

本应用为听力辅助工具，非医疗器械，不能替代专业助听器与医学诊断。长时间高音量使用可能损伤听力，请从低音量开始调节。

## 八、版本信息

当前版本：**v1.2.0**

| 版本 | 主要变更 |
| --- | --- |
| v1.2.0 | C19：划掉任务后后台采集停止修复（`onTaskRemoved` + 状态同步）；C20：返回键退出后透传未停止、反复切换无法关闭修复（引擎静态单例 + `onActivityDestroy` 停止引擎与服务 + 前端 `stop` 兜底下发） |
| v1.1.1 | 降噪优化（NS 温和降噪参数调整）+ 频谱预览（未启动时每秒刷新展示环境声） |
| v1.1.0 | P2 音频处理：环境降噪 NS + 自动增益 AGC；频谱流畅度优化（原生 30Hz 推送、UI 40/100ms 刷新） |
| v1.0.0 | 初版：实时透传 + 9 段 EQ + 后台保活 + 频谱可视化 |

### 仓库地址

- 前端工程：https://gitee.com/anlinxi/hearing-assist.git
- 安卓离线打包壳工程：https://gitee.com/anlinxi/HearingAssistAndriod.git