# Speaker_Recognizer

**Repository Path**: liu7777/speaker_-recognizer

## Basic Information

- **Project Name**: Speaker_Recognizer
- **Description**: 基于 SpeechBrain 和 ECAPA-TDNN 模型的中文说话人识别系统，用于判断两个音频是否来自同一说话人。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-11-17
- **Last Updated**: 2025-11-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 说话人识别系统

[![Python](https://img.shields.io/badge/Python-3.12%2B-blue)](https://www.python.org/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-orange)](https://pytorch.org/)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

基于 SpeechBrain 和 ECAPA-TDNN 模型的中文说话人识别系统，用于判断两个音频是否来自同一说话人。

## ✨ 特性

- 🎯 **高准确率** - 使用预训练的 ECAPA-TDNN 模型（LanceaKing/spkrec-ecapa-cnceleb）
- ⚡ **GPU 加速** - 支持 CUDA 加速推理
- 🇨🇳  **中文优化** - 针对中文音频训练，识别效果更好
- 📊 **完整评估** - 提供模型评估工具，支持阈值优化
- 🔧 **易于使用** - 支持命令行、Python API 和脚本三种使用方式

## 📋 环境要求

- Python 3.8+（推荐 3.12+）
- CUDA 11.8+ （可选，用于 GPU 加速）
- 4GB+ 可用内存

## 🚀 快速开始

### 1. 安装依赖

```bash
# 克隆项目
git clone https://gitee.com/liu7777/speaker_-recognizer.git
cd speaker-recognition

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 安装 PyTorch（CUDA 版本）
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu118

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

# 验证安装
python check_dependencies.py
```

> 💡 **提示**: 访问 [PyTorch 官网](https://pytorch.org/) 获取适合你 CUDA 版本的安装命令

### 2. 基本使用

```python
from src.speaker_recognizer import SpeakerRecognizer

# 初始化识别器
recognizer = SpeakerRecognizer(device="cuda")

# 执行识别
result = recognizer.verify_speaker("audio1.wav", "audio2.wav")

# 查看结果
print(f"相似度: {result['similarity']}")
print(f"结论: {result['message']}")
```

### 3. 命令行使用

```bash
# 基本用法
python main.py --audio1 speaker1.wav --audio2 speaker2.wav

# 自定义阈值
python main.py --audio1 audio1.wav --audio2 audio2.wav --threshold 0.3

# 使用 CPU
python main.py --audio1 audio1.wav --audio2 audio2.wav --device cpu
```

## 📖 使用方式

### 方式 1: Python API（推荐）

```python
from src.speaker_recognizer import SpeakerRecognizer

recognizer = SpeakerRecognizer(device="cuda")
result = recognizer.verify_speaker("audio1.wav", "audio2.wav", threshold=0.25)

print(result)
# {
#   "similarity": 0.7234,
#   "is_same_speaker": True,
#   "message": "两个音频来自同一说话人（相似度: 0.7234）"
# }
```

### 方式 2: 命令行

```bash
python main.py --audio1 <path1> --audio2 <path2> [--threshold 0.25] [--device cuda]
```

**参数说明**:
- `--audio1`: 第一个音频文件路径（必需）
- `--audio2`: 第二个音频文件路径（必需）
- `--threshold`: 判断阈值，默认 0.25（可选）
- `--device`: 运行设备，cuda 或 cpu，默认 cuda（可选）

## 📊 模型评估

评估模型性能并找到最优阈值：

```bash
# 生成详细报告和图表
python evaluate_model.py
```

**输出指标**:
- 准确率 (Accuracy)
- 精确率 (Precision)
- 召回率 (Recall)
- F1 分数
- ROC 曲线和 AUC
- 混淆矩阵
- 最优阈值推荐

## 🎯 阈值选择指南

| 阈值范围 | 适用场景 | 特点 |
|---------|---------|------|
| 0.35-0.40 | 高安全性场景 | 减少误判，宁可漏判 |
| 0.25-0.30 | 平衡场景 | 平衡准确率和召回率 |
| 0.15-0.20 | 用户体验优先 | 减少漏判，提升体验 |

**相似度分数参考**:
- `≥ 0.40`: 很可能是同一说话人
- `0.25-0.40`: 可能是同一说话人
- `< 0.25`: 很可能是不同说话人

## 📁 项目结构

```
speaker-recognition/
├── src/                      # 核心模块
│   ├── speaker_recognizer.py # 说话人识别
│   └── audio_validator.py    # 音频验证
├── date/                     # 测试数据
│   ├── test/                 # 测试音频
│   └── test_pairs.csv        # 测试配置
├── main.py                   # 命令行入口
├── evaluate_model.py         # 模型评估
├── check_dependencies.py     # 依赖检查
└── requirements.txt          # 依赖配置
```

## 🔧 技术栈

- **[SpeechBrain](https://speechbrain.github.io/)** - 语音处理工具包
- **[PyTorch](https://pytorch.org/)** - 深度学习框架
- **[ECAPA-TDNN](https://arxiv.org/abs/2005.07143)** - 说话人识别模型
- **[scikit-learn](https://scikit-learn.org/)** - 模型评估

## ❓ 常见问题

<details>
<summary><b>首次运行很慢？</b></summary>
首次运行需要下载模型文件（约 200MB），模型会缓存到本地，后续运行会很快。
</details>

<details>
<summary><b>CUDA 不可用？</b></summary>
1. 检查 NVIDIA 驱动: `nvidia-smi`
2. 确认 PyTorch 版本与 CUDA 版本匹配
3. 或使用 CPU 模式: `device="cpu"`
</details>

<details>
<summary><b>支持哪些音频格式？</b></summary>
目前仅支持 WAV 格式。其他格式请先转换
</details>

<details>
<summary><b>如何提高识别准确度？</b></summary>
- 使用清晰、无噪音的音频
- 确保音频时长足够（建议 2-5 秒）
- 使用相同录音条件的音频
- 根据实际场景调整阈值
</details>

## 📄 许可证

本项目采用 [MIT License](LICENSE) 开源协议。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📮 联系方式

如有问题或建议，请提交 [Issue](../../issues)。

---

⭐ 如果这个项目对你有帮助，请给个 Star！