# go-xiaozhi

**Repository Path**: longcat99/go-xiaozhi

## Basic Information

- **Project Name**: go-xiaozhi
- **Description**: 在嵌入式设备sogou E1录音笔上上利用alsl实现的小智客户端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-15
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小智语音识别程序 (PTT版本)

基于Go语言开发的语音识别程序，支持PTT按键触发，专为Buildroot系统设计。

## 🎯 项目简介

小智语音识别程序是一个轻量级的语音交互系统，采用Push-to-Talk(PTT)模式，通过物理按键触发语音识别。程序将音频数据实时编码为Opus格式并通过WebSocket传输到服务器进行语音识别处理。

## ✨ 功能特性

- ✅ **PTT按键触发**: 支持按键长按触发语音识别
- ✅ **Opus音频编码**: 使用libopus进行高效音频压缩
- ✅ **WebSocket通信**: 与服务器进行实时音频传输
- ✅ **音频设备管理**: 支持指定录音和播放设备
- ✅ **配置化管理**: YAML配置文件，支持灵活配置
- ✅ **交叉编译**: 支持ARM64架构的Buildroot系统
- ✅ **状态管理**: 完善的设备状态管理机制
- ✅ **自动重连**: 网络异常时自动重连服务器
- ✅ **日志系统**: 分级日志输出，便于调试

## 🛠️ 系统要求

- **操作系统**: Linux (Buildroot系统)
- **架构**: ARM64
- **音频设备**: ALSA音频设备
- **输入设备**: Linux输入设备 (/dev/input/event*)
- **Go版本**: 1.21+

## 🚀 快速开始

### 1. 安装依赖

确保系统已安装以下依赖：

```bash
# ALSA音频库
sudo apt-get install libasound2-dev

# Opus音频编码库
sudo apt-get install libopus-dev
```

### 2. 配置设置

编辑 `config.yaml` 文件，配置您的设备信息：

```yaml
audio:
  record_device: "plughw:2,0"  # 录音设备 (使用 arecord -l 查看可用设备)
  play_device: "plughw:0,0"    # 播放设备 (使用 aplay -l 查看可用设备)
  input_sample_rate: 16000     # 输入采样率 (Hz)
  output_sample_rate: 24000    # 输出采样率 (Hz)
  channels: 1                   # 声道数
  frame_duration: 20           # 帧时长 (ms)

ptt:
  input_device: "/dev/input/event3"  # PTT按键输入设备
  key_code: 2                        # 按键代码 (KEY_1=2)
  hold_duration: 500                 # 长按触发时间(毫秒)

websocket:
  url: "wss://your-server.com/ws"    # WebSocket服务器地址
  access_token: "your-access-token"  # 访问令牌
  device_id: "your-device-id"        # 设备ID
  client_id: "your-client-id"        # 客户端ID

system:
  log_level: "info"                  # 日志级别
  auto_reconnect: true               # 自动重连
  max_reconnect_attempts: 5          # 最大重连次数
```

### 3. 编译程序

#### 本地编译 (开发环境)

```bash
cd xiaozhi-ptt
go build -o xiaozhi-ptt cmd/main.go
```

#### 交叉编译 (Buildroot系统)

```bash
# 使用提供的构建脚本
./build.sh

# 或者手动交叉编译
GOOS=linux GOARCH=arm64 go build -o xiaozhi-ptt cmd/main.go
```

### 4. 运行程序

```bash
# 使用默认配置
./xiaozhi-ptt

# 指定配置文件
./xiaozhi-ptt -config /path/to/config.yaml

# 设置日志级别
./xiaozhi-ptt -log-level debug
```

## 📁 项目结构

```
xiaozhi-ptt/
├── cmd/
│   └── main.go                 # 程序入口
├── internal/
│   ├── activation/            # 设备激活模块
│   ├── config/               # 配置管理
│   ├── controller/           # 主控制器
│   ├── opus/                 # Opus编码器
│   ├── utils/                # 工具函数
│   ├── vad/                  # 语音活动检测
│   └── websocket/            # WebSocket客户端
├── pkg/
│   ├── audio/                # 音频设备管理
│   └── ptt/                  # PTT按键处理
├── opus-lib/                 # Opus库文件
├── config.yaml               # 配置文件
├── go.mod                    # Go模块定义
└── README.md                 # 项目文档
```

## 🔧 核心模块说明

### 音频设备管理 (pkg/audio/device.go)

负责音频设备的初始化和控制：
- 录音设备管理
- 播放设备管理
- 音频数据缓冲
- 设备状态跟踪

### PTT控制器 (internal/controller/controller.go)

核心控制逻辑：
- PTT按键状态监控
- 录音/播放状态切换
- 音频数据编码和传输
- 设备状态管理

### WebSocket客户端 (internal/websocket/client.go)

与服务器通信：
- WebSocket连接管理
- 音频数据传输
- 消息协议处理
- 自动重连机制

### Opus编码器 (internal/opus/codec.go)

音频编码处理：
- Opus编码/解码
- 音频帧处理
- 编码参数配置

## 🔍 调试和故障排除

### 查看音频设备

```bash
# 查看录音设备
arecord -l

# 查看播放设备
aplay -l

# 查看输入设备
cat /proc/bus/input/devices
```

### 日志级别设置

支持以下日志级别：
- `debug`: 详细调试信息
- `info`: 一般信息（推荐）
- `warn`: 警告信息
- `error`: 错误信息

### 常见问题

1. **设备权限问题**
   ```bash
   # 确保对音频设备和输入设备有访问权限
   sudo chmod 666 /dev/snd/*
   sudo chmod 666 /dev/input/event*
   ```

2. **音频设备未找到**
   - 检查 `config.yaml` 中的设备名称
   - 使用 `arecord -l` 和 `aplay -l` 确认设备存在

3. **WebSocket连接失败**
   - 检查网络连接
   - 验证服务器地址和访问令牌
   - 查看防火墙设置

## 📊 状态机说明

程序使用状态机管理设备状态：

```
空闲(Idle) → 监听中(Listening) → 播放中(Playing) → 空闲(Idle)
```

- **空闲状态**: 等待PTT按键触发
- **监听状态**: 录音并传输音频数据
- **播放状态**: 播放服务器返回的音频

## 🔄 构建脚本

项目提供多个构建脚本：

- `build.sh`: Linux环境构建
- `build-wsl.sh`: WSL环境构建
- `build-windows.bat`: Windows环境构建

## 📝 开发指南

### 添加新功能

1. 在相应的包中实现功能模块
2. 在控制器中集成新功能
3. 更新配置文件结构（如需要）
4. 添加相应的测试

### 代码规范

- 使用Go标准代码格式
- 添加必要的注释
- 遵循错误处理最佳实践
- 使用结构化的日志输出

## 🤝 贡献指南

欢迎提交Issue和Pull Request来改进项目！

## 📄 许可证

本项目采用MIT许可证。

## 📞 联系方式

如有问题或建议，请通过以下方式联系：
- 项目Issue: [GitHub Issues]
- 邮箱: [项目维护者邮箱]

---

**小智语音识别程序** - 让语音交互更简单！ 🎤