# xiaozhi-client

**Repository Path**: tinytaro/xiaozhi-client

## Basic Information

- **Project Name**: xiaozhi-client
- **Description**: 嵌入式Linux系统上的小智AI客户端
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-04-16
- **Last Updated**: 2025-06-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 小智AI客户端

本项目使用尽可能简单的C代码（500+）实现一个Linux上的小智AI客户端，支持基本的语音对话功能和MCP服务，主要用于嵌入式开发的教学。

## 项目概述

本项目主要包含的组件：
- **客户端程序(client)**: 负责与服务器通信，处理WebSocket连接，管理音频数据传输
- **录音程序(recorder)**: 捕获麦克风输入，使用Opus编码压缩，通过UDP发送给客户端
- **播放程序(player)**: 接收客户端转发的音频数据，解码后通过扬声器播放
- **MCP代理(mcp_proxy)**：转发客户端的MCP请求给MCP服务器(mcp_server.py)

项目使用Mongoose网络库处理WebSocket通信，使用ALSA库进行音频输入输出，使用Opus编解码器处理音频数据。

## 项目优势

- **轻量高效**：C语言实现的轻量级架构，代码简单易懂，特别适合嵌入式教学
- **模块化设计**：客户端、录音器、播放器三大模块各司其职，结构清晰，易于维护和扩展
- **跨平台兼容**：基于标准C库和跨平台网络库实现，依赖项少，适配性强，易于部署
- **扩展方便**：支持本地MCP服务器，可以方便地扩展智能体功能

## 安装依赖库

本项目依赖以下开发库和应用程序：
```bash
sudo apt-get install libasound2-dev libopus-dev libssl-dev
```

## 编译项目

使用CMake编译项目：
```bash
mkdir build
cd build
cmake ..
make
```
## 设备激活

项目提供了设备激活脚本`active`，用于获取设备激活码并绑定到小智AI服务器：

```bash
# 安装依赖
sudo apt install uuid curl jq

# 执行激活脚本
./active
```

执行后会显示设备的激活码，如已激活则显示"已激活"。该脚本通过获取设备MAC地址，向小智AI服务器发送激活请求，完成设备身份验证和功能授权。

## 使用方法

1. 先使用激活脚本激活设备

2. 启动播放器：
```bash
./player
```

3. 启动录音器：
```bash
./recorder
```

4. 启动MCP代理：
```bash
./mcp_proxy
```

5. 最后启动客户端：
```bash
./client
```

客户端会自动连接到小智AI服务器，并开始监听来自录音器的音频输入。当你开始说话时，录音器会捕获语音并发送给客户端，客户端会将语音数据转发给小智AI服务器进行处理。服务器的回复将通过播放器播放出来。

## 架构图

```mermaid
graph TB
    C[小智AI服务器] <-->|WSS| B[客户端程序<br>client]
    A -->|UDP:8888| B
    B -->|UDP:8889| D
    B -->|TCP:8080| E
        subgraph 设备
        A[录音程序<br>recorder]
        D[播放程序<br>player]
        B[客户端程序<br>client]
            subgraph MCP代理
            E[MCP服务器]
            end
        end
```

## 主要文件说明

- `client.c`: 客户端主程序，处理WebSocket通信
- `recorder.c`: 录音程序，负责捕获音频输入
- `player.c`: 音频播放程序，负责输出服务器回复的语音
- `mongoose.c/h`: 轻量级网络库，处理WebSocket和UDP通信
- `macaddr.c/h`: 获取设备MAC地址，用于设备识别
- `active`: 设备激活脚本，用于获取系统激活码并与服务器绑定设备
- `mcp_proxy`: MCP代理，用于调用本地MCP服务器（STDIO协议）
- `mcp_server.py`: MCP服务器