# 猫咪翻译器优化版使用指南

## 简介

猫咪翻译器优化版是在原有猫咪翻译器V2基础上，根据米兰大学研究团队的最佳实践进行全面优化的系统。本系统集成了时序调制特征、统计静音检测、混合特征提取和DAG-HMM分类方法，显著提高了猫叫声检测和意图分类的准确率。

## 系统优化亮点

1. **时序调制特征提取**：基于米兰大学研究，实现了捕捉猫叫声时序调制特征的提取方法
2. **统计模型静音检测**：优化了静音检测算法，提高了猫叫声分割的准确性
3. **混合特征提取器**：结合MFCC、YAMNet嵌入和时序调制特征，创建更全面的声学特征表示
4. **DAG-HMM与优化特征集成**：将最佳分类方法与优化特征结合，实现最高准确率
5. **调整梅尔滤波器数量**：从64调整到23，与米兰大学研究一致，更适合猫叫声分析

## 安装依赖

```bash
pip install numpy==1.24.3 librosa==0.10.1 scikit-learn==1.3.0 tensorflow==2.12.0 pyaudio==0.2.13 matplotlib==3.7.2 hmmlearn==0.3.0 sounddevice==0.4.6
```

## 使用方法

### 1. 分析音频文件

```bash
python optimized_main.py analyze path/to/audio.wav --detector models/optimized_cat_detector_svm.pkl --intent-model models/optimized_dag_hmm_temporal_modulation.pkl --feature-type temporal_modulation
```

参数说明：
- `--detector`: 猫叫声检测器模型路径
- `--intent-model`: 意图分类器模型路径
- `--feature-type`: 特征类型，可选 'temporal_modulation'(推荐), 'mfcc', 'yamnet', 'hybrid'
- `--threshold`: 猫叫声检测阈值，默认0.5

### 2. 实时麦克风分析

```bash
python optimized_main.py live --detector models/optimized_cat_detector_svm.pkl --intent-model models/optimized_dag_hmm_temporal_modulation.pkl --duration 3.0 --interval 1.0
```

参数说明：
- `--duration`: 每次录音持续时间（秒）
- `--interval`: 分析间隔时间（秒）
- `--device`: 录音设备ID（可选）

### 3. 添加训练样本

```bash
# 添加猫叫声样本
python optimized_main.py add-sample path/to/cat_sound.wav "快乐" --is-cat-sound --cat "我的猫咪"

# 添加非猫叫声样本
python optimized_main.py add-sample path/to/non_cat_sound.wav "环境噪音"
```

### 4. 训练猫叫声检测器

```bash
python optimized_main.py train-detector --cat-samples samples/cat_sounds --non-cat-samples samples/non_cat_sounds --model-type svm --output models/my_cat_detector.pkl
```

参数说明：
- `--model-type`: 模型类型，可选 'svm'(推荐), 'rf', 'nn'

### 5. 训练意图分类器

```bash
python optimized_main.py train-intent --samples intent_samples --feature-type temporal_modulation --output models/my_intent_classifier.pkl
```

样本目录结构：
```
intent_samples/
├── 快乐_满足/
│   ├── sample1.wav
│   ├── sample2.wav
├── 愤怒/
│   ├── sample1.wav
│   ├── sample2.wav
...
```

### 6. 系统验证

```bash
# 验证意图分类器
python optimized_system_validator.py --test-files test_data/manifest.json --validate-intent --intent-feature-type temporal_modulation --plot

# 验证猫叫声检测器
python optimized_system_validator.py --test-files test_data/manifest.json --validate-detector --detector-model-type svm --plot

# 同时验证两者
python optimized_system_validator.py --test-files test_data/manifest.json --validate-intent --validate-detector --plot
```

测试文件JSON格式：
```json
[
  {"path": "path/to/audio1.wav", "intent": "快乐", "is_cat_sound": true},
  {"path": "path/to/audio2.wav", "intent": "愤怒", "is_cat_sound": true},
  {"path": "path/to/audio3.wav", "is_cat_sound": false}
]
```

## 特征类型选择指南

1. **时序调制特征 (temporal_modulation)**：
   - 优势：最适合猫叫声分析，捕捉时序模式
   - 推荐用于：意图分类，尤其是区分不同情感状态

2. **MFCC特征 (mfcc)**：
   - 优势：计算效率高，适合资源受限设备
   - 推荐用于：简单场景和快速原型开发

3. **YAMNet嵌入 (yamnet)**：
   - 优势：通用声音识别能力强
   - 推荐用于：复杂环境中的猫叫声检测

4. **混合特征 (hybrid)**：
   - 优势：结合所有特征的优点，最全面
   - 推荐用于：追求最高准确率，不考虑计算资源

## 模型类型选择指南

1. **SVM**：
   - 优势：小样本(10-30)效果好，训练快，模型小
   - 推荐用于：初始阶段，样本数量有限时

2. **随机森林(RF)**：
   - 优势：中等样本(30-100)效果好，特征重要性分析
   - 推荐用于：需要了解关键声学特征时

3. **神经网络(NN)**：
   - 优势：大样本(100+)效果最佳，持续学习能力强
   - 推荐用于：长期使用，有大量样本时

4. **DAG-HMM**：
   - 优势：最适合猫叫声时序分析，准确率最高
   - 推荐用于：意图分类，尤其是与时序调制特征结合

## 性能优化建议

1. 每个类别收集至少10个高质量样本
2. 使用统计静音检测进行精确分段
3. 对于意图分类，优先使用时序调制特征+DAG-HMM组合
4. 对于猫叫声检测，在样本数量<30时使用SVM，>100时考虑神经网络
5. 定期使用系统验证工具评估性能并调整参数

## 故障排除

1. **未检测到猫叫声**：
   - 降低检测阈值（--threshold 0.3）
   - 确保录音质量良好，背景噪音较小
   - 添加更多当前环境下的猫叫声样本

2. **意图分类不准确**：
   - 为特定意图添加更多样本
   - 尝试不同特征类型，特别是temporal_modulation
   - 调整DAG-HMM参数（状态数和混合成分数）

3. **系统运行缓慢**：
   - 使用计算效率更高的特征类型（如mfcc）
   - 减少音频分段重叠
   - 降低采样率（但不低于16kHz）