# 智能语音助手系统使用说明

## 功能概述
这是一个完整的智能语音助手系统，集成了语音录制、语音识别、大语言模型和文本转语音功能，实现语音对话交互。

## 完整工作流程
1. 🎙️ **语音录制** - 基于ZCR的智能语音检测
2. 📝 **保存录音** - 自动保存为WAV文件
3. 🤖 **语音识别** - 使用字节跳动ASR将语音转为文字
4. 💬 **AI回复** - 使用豆包大模型生成智能回复
5. 🔊 **语音回复** - 使用字节跳动TTS将AI回复转为语音

## 环境配置

### 1. 安装依赖
```bash
pip install websockets requests pyaudio numpy
```

### 2. 安装音频播放器（树莓派/Linux系统）
系统使用PCM格式音频，只需要安装基础的音频播放工具：

```bash
# 安装 alsa-utils（包含aplay播放器）
sudo apt-get update
sudo apt-get install alsa-utils
```

> **优势**: PCM格式无需额外解码器，兼容性更好，资源占用更少。
> **注意**: macOS和Windows系统通常内置支持音频播放，无需额外安装。

### 3. 设置API密钥
为了启用大语言模型功能，需要设置环境变量：

```bash
# Linux/Mac
export ARK_API_KEY='your_api_key_here'

# Windows
set ARK_API_KEY=your_api_key_here
```

> **注意**: 语音识别和文本转语音功能使用内置的API密钥，无需额外配置。

## 使用方法

### 基本使用
```bash
python recorder.py
```

### 功能说明
- 🎯 **自动检测语音**：系统会自动检测声音并开始录音
- ⏱️ **智能停止**：静音3秒后自动停止录音
- 🔊 **自动播放**：录音完成后自动播放音频
- 📝 **语音识别**：自动将语音转为文字
- 🤖 **AI助手**：自动调用大语言模型生成回复

### 配置参数
- `energy_threshold=200` - 能量阈值（调整灵敏度）
- `silence_threshold=3.0` - 静音阈值（秒）
- `min_recording_time=2.0` - 最小录音时间（秒）
- `max_recording_time=30.0` - 最大录音时间（秒）
- `enable_asr=True` - 启用语音识别
- `enable_llm=True` - 启用大语言模型
- `enable_tts=True` - 启用文本转语音

## 输出示例
```
🎤 开始监听...
能量阈值: 200 (已弃用)
静音阈值: 3.0秒
📖 使用说明:
- 检测到声音自动开始录音
- 持续静音3秒自动结束录音
- 最少录音2秒，最多30秒
- 录音完成后自动进行语音识别和AI回复
- 按 Ctrl+C 退出
==================================================
🎙️ 检测到声音，开始录音...
📝 录音完成，时长: 3.45秒 (包含预录音 2.0秒)
✅ 录音已保存: recording_20250920_163022.wav
==================================================
📡 音频输入已保持关闭状态
🔄 开始处理音频...
🤖 开始语音识别...
📝 识别结果: 你好，今天天气怎么样？
--------------------------------------------------
🤖 调用大语言模型...
💬 AI助手回复: 你好！我无法实时获取天气信息，建议你查看天气预报或打开天气应用来了解今天的天气情况。有什么其他我可以帮助你的吗？
--------------------------------------------------
🔊 开始文本转语音...
TTS句子信息: {'code': 0, 'message': '', 'data': None, 'sentence': {'phonemes': [], 'text': '你好！我无法实时获取天气信息，建议你查看天气预报或打开天气应用来了解今天的天气情况。有什么其他我可以帮助你的吗？', 'words': [...]}}
✅ TTS音频已保存: tts_response_20250920_163022.pcm
📁 文件大小: 128.75 KB
🔊 播放AI语音回复...
✅ AI语音回复完成
🔄 准备重新开启音频输入
✅ 音频设备初始化成功
📡 音频输入已重新开启
```

## 注意事项
1. **网络连接**：需要网络连接来使用语音识别、大语言模型和文本转语音服务
2. **API密钥**：需要有效的ARK_API_KEY才能使用大语言模型功能
3. **音频设备**：确保麦克风和扬声器工作正常
4. **权限**：确保程序有访问麦克风、网络和存储的权限
5. **文件存储**：系统会保存录音文件和TTS生成的音频文件

## 故障排除
- 如果语音识别失败，检查网络连接和API密钥
- 如果大语言模型失败，检查ARK_API_KEY是否正确设置
- 如果文本转语音失败，检查TTS服务状态
- 如果录音失败，检查麦克风权限和设备
- 如果播放失败，检查音频设备权限
- 如果PCM文件无法播放，检查是否安装了alsa-utils：
  ```bash
  # 树莓派/Ubuntu/Debian系统
  sudo apt-get install alsa-utils
  
  # 或检查aplay是否安装
  which aplay
  ```

## 技术特点
- 🎯 基于ZCR的精确语音检测
- 🚀 低延迟实时处理
- 💾 环形缓冲区防止音频丢失
- 🔧 自动调整能量阈值
- 📊 实时性能监控
- 🌐 完整的语音对话链路
- 📁 自动文件管理和权限设置
- 🔊 PCM格式音频，无需额外解码器

## 生成的文件
- `recording_*.wav` - 录制的音频文件
- `tts_response_*.pcm` - AI语音回复文件（PCM格式）

## PCM格式优势
- **兼容性好**：aplay原生支持，树莓派开箱即用
- **资源占用少**：无需解码过程，CPU占用更低
- **延迟更低**：直接播放，无需格式转换
- **稳定性高**：减少依赖组件，提高系统稳定性