Skip to content

Latest commit

 

History

History
222 lines (177 loc) · 5.63 KB

NEW_FEATURES_GUIDE.md

File metadata and controls

222 lines (177 loc) · 5.63 KB

新功能使用指南 (New Features Guide)

本文档介绍了最新添加的麦克风检测和语音活动检测功能。

新功能概述

1. 麦克风启动测试 (Microphone Startup Test)

  • 功能: 在程序启动时自动测试麦克风是否正常工作
  • 默认状态: 启用
  • 用途: 帮助您快速发现麦克风问题，避免录音后发现没有声音

2. 语音活动检测 (Voice Activity Detection - VAD)

  • 功能: 自动检测录音中是否包含实际语音
  • 默认状态: 启用
  • 用途:
    • 防止发送空白/静音录音到服务器
    • 节省网络带宽
    • 避免误识别

配置说明

在 config.json 中添加了以下新配置项：

{
  "enable_vad": true,
  "vad_energy_threshold": 500.0,
  "vad_min_speech_duration": 0.3,
  "silence_timeout": 2.0,
  "test_mic_on_startup": true
}

配置项详解

test_mic_on_startup (麦克风启动测试)

  • 类型: true/false
  • 默认值: true
  • 说明:
    • 启用时，程序启动会录制2秒音频进行测试
    • 如果检测到麦克风静音或不工作，会显示警告
    • 建议首次使用时保持启用
    • 如果确认麦克风正常工作，可设为 false 以加快启动速度

enable_vad (启用语音活动检测)

  • 类型: true/false
  • 默认值: true
  • 说明:
    • 启用后会检测录音中是否有实际语音
    • 如果没有检测到语音，不会发送到服务器
    • 建议保持启用以节省带宽和避免误识别

vad_energy_threshold (语音能量阈值)

  • 类型: 数字
  • 默认值: 500.0
  • 调整建议:
    • 太多无声录音被跳过: 降低数值 (如 300.0)
    • 环境噪音导致误触发: 提高数值 (如 800.0)
    • 正常使用: 保持默认值 500.0

vad_min_speech_duration (最小语音时长)

  • 类型: 数字 (秒)
  • 默认值: 0.3
  • 说明:
    • 检测到的语音必须持续至少这么长时间才会发送
    • 防止短暂的点击声或噪音被误认为语音
    • 建议保持默认值

silence_timeout (静音超时)

  • 类型: 数字 (秒)
  • 默认值: 2.0
  • 说明: 预留功能，暂未使用

使用示例

场景 1: 首次运行

$ python hotmic.py

[hotmic] Testing microphone...
[hotmic] Recording for 2.0 seconds to test microphone...
[hotmic] Please make some noise (speak, tap the mic, etc.)
[hotmic] Microphone test results:
[hotmic]   - Collected 87 audio chunks
[hotmic]   - Average audio energy: 1234.56
[hotmic] Microphone is working correctly!

Hotkey Configuration:
  Toggle mode: <ctrl>+u
  ...

场景 2: 麦克风静音时

$ python hotmic.py

[hotmic] Testing microphone...
[hotmic] Recording for 2.0 seconds to test microphone...
[hotmic] Please make some noise (speak, tap the mic, etc.)
[hotmic] Microphone test results:
[hotmic]   - Collected 87 audio chunks
[hotmic]   - Average audio energy: 5.23
[hotmic] WARNING: Microphone audio level is very low!
[hotmic]    The microphone might be muted or not working properly.
[hotmic]    Please check your microphone settings.

[hotmic] Warning: Microphone test failed!
[hotmic] The program will continue, but recording may not work properly.

场景 3: 录音无语音时

[hotmic] start recording ...
[hotmic] stop recording ...
[hotmic] No speech detected (avg energy: 123.45)
[hotmic] Skipping empty audio - not sending to server

场景 4: 录音有语音时

[hotmic] start recording ...
[hotmic] stop recording ...
[hotmic] Speech detected (avg energy: 1523.78)
[hotmic] copied transcript to clipboard
[hotmic] pasted at cursor

故障排除

问题 1: 太多有效录音被跳过

现象: 正常说话的录音也显示"No speech detected"

解决方案:

  1. 在 config.json 中降低 vad_energy_threshold 
    "vad_energy_threshold": 300.0
  2. 或临时禁用 VAD 
    "enable_vad": false

问题 2: 环境噪音导致误触发

现象: 没有说话时也检测到"语音"

解决方案:

  1. 在 config.json 中提高 vad_energy_threshold 
    "vad_energy_threshold": 800.0
  2. 改善录音环境，减少背景噪音

问题 3: 麦克风测试总是失败

现象: 启动时总是显示麦克风测试失败

解决方案:

  1. 检查系统麦克风设置
  2. 确认麦克风未被静音
  3. 尝试在其他程序中测试麦克风
  4. 如果确认麦克风正常，可以禁用测试 
    "test_mic_on_startup": false

技术细节

音频能量计算

系统使用 RMS (Root Mean Square) 方法计算音频能量：

RMS = sqrt(mean(samples^2))

VAD 工作流程

  1. 录音过程中，每个音频块都会计算能量值
  2. 如果能量值超过阈值，标记为包含语音
  3. 录音结束时检查：
    • 是否检测到语音
    • 语音持续时间是否足够长
  4. 只有满足条件的录音才会发送到服务器

性能影响

  • CPU: 极小 (仅增加简单的数学计算)
  • 内存: 可忽略
  • 网络: 可能减少 (跳过空白录音)
  • 启动时间: 增加约 2 秒 (如果启用麦克风测试)

Windows 和 macOS 兼容性

所有新功能在两个平台上都经过测试，完全兼容：

  • ✓ Windows 10/11
  • ✓ macOS 12+
  • ✓ Linux (理论上支持，但未经全面测试)

依赖项更新

新功能需要 numpy 库进行音频处理：

pip install numpy>=1.24.0

或者使用：

pip install -r requirements.txt

测试工具

运行测试脚本验证新功能：

python test_vad.py

这将测试：

  • 音频能量计算
  • VAD 配置加载
  • 麦克风可用性

如有任何问题或建议，请访问项目主页。