listen-ghost

Windows 桌面小程序，监听声卡输出（WASAPI Loopback），实时解析并显示当前播放音乐中的音高。

┌─────────────────────────────┐
│  [       START / STOP      ]│
│  场景： [通用]  [人声]        │
│  设备名（状态提示）           │
│                             │
│        D4   F#5   A3        │
│                             │
│  ▁▃▇▅▂▁▁▄▆▃▁▁▁            │
└─────────────────────────────┘

窗口固定 400×400 px，始终置顶，悬浮于桌面右下角。

功能

• 通用场景：FFT 多音检测，最多同时显示 6 个音名，适用于钢琴、吉他、和声等场景
• 人声场景：YIN 单音检测，针对流行音乐混音中演唱者音高优化

环境要求

• Windows 10/11
• Python 3.12+
• 声卡支持 WASAPI Loopback（大多数 Windows 内置及独立声卡均支持）

安装与运行

# 创建并激活虚拟环境
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 安装依赖
pip install -r requirements.txt

# 运行
python main.py

测试

python -m pytest tests/ -v

测试不依赖音频硬件，全部使用 numpy 合成信号，共 86 个用例。

打包为 .exe

pip install pyinstaller
pyinstaller build.spec
# 输出：dist/listen-ghost.exe

技术实现

组件	方案
音频捕获	soundcard（WASAPI Loopback）
通用检测	Hann 窗 + 零填充 FFT → 谐波抑制 → 谐波覆盖度过滤 → 5 帧多数投票
人声检测	高通滤波（150 Hz）→ YIN 自相关 → FFT 回退 → 中位数平滑
GUI	tkinter，固定尺寸，~30 fps 轮询
依赖	numpy、soundcard（仅两个外部库）

详细技术规格见 SPEC.md，AI 协作约定见 CLAUDE.md。