# SoundCommand

**Repository Path**: ffedu/SoundCommand

## Basic Information

- **Project Name**: SoundCommand
- **Description**: Command from Sound
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-27
- **Last Updated**: 2026-07-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 声学掌托鼠标控制系统

这是一个基于音频识别的掌托鼠标控制系统，通过识别手掌在桌面上敲击产生的声音来控制鼠标点击。

## 功能特点

- **音频录制工具**：图形化界面录制训练数据
- **模型训练**：使用机器学习分类模型识别不同敲击声音
- **实时推理**：根据音频实时控制鼠标左键/右键点击
- **打字抑制**：自动识别打字声音，避免误触发

## 系统要求

- Python 3.8+
- macOS（已测试）或支持的系统
- 立体声麦克风（推荐）

## 安装依赖

```bash
pip install -r requirements.txt
```

## 使用方法

### 1. 录制训练数据

#### 方法一：使用启动脚本（推荐）
```bash
# macOS/Linux
./start_gui.sh

# Windows
start_gui.bat
```

#### 方法二：直接运行Python脚本
```bash
# 使用 python3（如果你的系统需要）
python3 gui_recorder.py

# 或者使用 python（如果可用）
python gui_recorder.py
```

#### 方法三：使用命令行工具
```bash
# 录制左键点击样本
python3 record.py --label left --count 20

# 录制右键点击样本  
python3 record.py --label right --count 20

# 录制打字声音样本
python3 record.py --label typing --count 20

# 一次性录制所有类别
python3 record.py --label all --count 20
```

### 2. 训练模型

```bash
python3 train.py
```

训练完成后会生成 `model.pkl` 文件。

### 3. 运行实时推理

```bash
python3 infer.py
```

## 文件说明

- `gui_recorder.py` - 图形化录制工具
- `record.py` - 命令行录制工具
- `train.py` - 模型训练脚本
- `infer.py` - 实时推理脚本
- `audio_features.py` - 音频特征提取工具
- `data/` - 训练数据目录
  - `left/` - 左键点击音频样本
  - `right/` - 右键点击音频样本
  - `typing/` - 打字声音样本

## 工作原理

1. **音频采集**：使用0.5秒滑动窗口实时采集立体声音频
2. **特征提取**：提取MFCC、频谱质心、过零率等音频特征
3. **分类识别**：使用随机森林分类器识别左键、右键、打字三种类别
4. **鼠标控制**：根据识别结果触发相应的鼠标点击事件

## 权限设置（macOS）

### 1. 麦克风权限
- 系统设置 → 隐私与安全性 → 麦克风
- 为终端/Trae/Python添加权限

### 2. 辅助功能权限
- 系统设置 → 隐私与安全性 → 辅助功能
- 为终端/Trae/Python添加权限（用于控制鼠标）

## 注意事项

1. 确保使用立体声麦克风以获得最佳效果
2. 录制时保持环境相对安静
3. 每个类别建议录制至少20个样本
4. 首次运行需要授予系统权限

## 故障排除

### 常见问题

1. **"zsh: command not found: python"**
   - 在macOS上，Python命令通常是 `python3`
   - 尝试使用：`python3 gui_recorder.py`
   - 或者创建别名：`alias python=python3`
   - 或者使用启动脚本：`./start_gui.sh`

2. **"Error opening input stream"**
   - 检查麦克风权限
   - 确认麦克风支持立体声
   - 尝试指定设备：`python3 record.py --list-devices`

3. **模型准确率低**
   - 增加训练样本数量
   - 确保录制质量
   - 调整环境噪音

4. **鼠标点击不触发**
   - 检查辅助功能权限
   - 调整置信度阈值：`python3 infer.py --confidence-threshold 0.6`

## 开发说明

### 添加新功能
1. 音频特征提取在 `audio_features.py`
2. 模型训练参数在 `train.py`
3. 实时推理参数在 `infer.py`

### 测试
```bash
# 测试音频录制
python -c "import sounddevice as sd; print(sd.query_devices())"

# 测试模型加载
python -c "import joblib; bundle = joblib.load('model.pkl'); print('模型加载成功')"
```

## 许可证

本项目仅供学习和研究使用。