本次测试使用小智通信协议的第三方客户端项目：

https://huangjunsen0406.github.io/py-xiaozhi/

最新的仓库地址: https://github.com/huangjunsen0406/py-xiaozhi.git

一、功能特点

• AI语音交互：支持语音输入与识别，实现智能人机交互，提供自然流畅的对话体验。

• 视觉多模态：支持图像识别和处理，提供多模态交互能力，理解图像内容。

• IoT 设备集成：

  • 支持智能家居设备控制，包括灯光、音量、温度传感器等

  • 集成Home Assistant智能家居平台，控制灯具、开关、数值控制器和按钮设备

  • 提供倒计时器功能，支持延时执行命令

  • 内置多种虚拟设备和物理设备驱动，可轻松扩展

• 联网音乐播放：基于pygame实现的高性能音乐播放器，支持播放／暂停／停止、进度控制、歌词显示和本地缓存，提供更稳定的音乐播放体验。

• 语音唤醒：支持唤醒词激活交互，免去手动操作的烦恼（默认关闭需要手动开启）。

• 自动对话模式：实现连续对话体验，提升用户交互流畅度。

• 图形化界面：提供直观易用的 GUI，支持小智表情与文本显示，增强视觉体验。

• 命令行模式：支持 CLI 运行，适用于嵌入式设备或无 GUI 环境。

• 跨平台支持：兼容 Windows 10+、macOS 10.15+ 和 Linux 系统，随时随地使用。

• 音量控制：支持音量调节，适应不同环境需求，统一声音控制接口。

• 会话管理：有效管理多轮对话，保持交互的连续性。

• 加密音频传输：支持 WSS 协议，保障音频数据的安全性，防止信息泄露。

• 自动验证码处理：首次使用时，程序自动复制验证码并打开浏览器，简化用户操作。

• 自动获取 MAC 地址：避免 MAC 地址冲突，提高连接稳定性。

• 代码模块化：拆分代码并封装为类，职责分明，便于二次开发。

• 稳定性优化：修复多项问题，包括断线重连、跨平台兼容等。

二、系统要求

• 3.9 >= Python版本 <= 3.12

• 支持的操作系统：Windows 10+、macOS 10.15+、Linux

• 麦克风和扬声器设备

三、Linux系统基础环境安装

版本要求

• Python: 3.9.13+ (推荐3.10，最高3.11)

• PyQt5: 5.15+

• SoundDevice: 0.4.4+

• FFmpeg: 4.0+

• Opus: 1.3+

• PortAudio: 19.0+

Linux (Debian/Ubuntu)

RK3588开发板使用的系统版本：

1、核心依赖

# 更新包管理器
sudo apt-get update

# 安装核心依赖
sudo apt-get install portaudio19-dev ffmpeg libopus0 libopus-dev \
                     build-essential python3-venv python3-pip \
                     libasound2-dev

2、音频系统依赖

PulseAudio（推荐）

sudo apt-get install pulseaudio-utils

3、GUI支持

# PyQt5 GUI依赖
sudo apt-get install python3-pyqt5 python3-pyqt5.qtmultimedia \
                     qtbase5-dev qt5-qmake qtmultimedia5-dev

4、开发工具（可选）

# 编译依赖
sudo apt-get install gcc g++ make cmake pkg-config

项目依赖安装（需先下载项目源码）

注意源码目录不能是root用户与组

1. 下载项目源码

# 克隆项目

git clone https://github.com/huangjunsen0406/py-xiaozhi.git

#国内仓库可以在gitee上查找
git clone https://gitee.com/lilongyang/py-xiaozhi.git

cd py-xiaozhi

2. 安装Python依赖（进入项目源码目录）

# pip install -r requirements.txt

3. 验证安装

# 检查关键依赖
python -c "import sounddevice; print('SoundDevice OK')"
python -c "import opuslib; print('Opus OK')"
python -c "import PyQt5.QtCore; print('PyQt5 OK')"

# 如果没有sounddevice模块，需重新安装
pip3 install --user sounddevice

4. 运行程序

# 运行程序
python main.py

#如果没有python，使用指向python3的链接
sudo ln -s /usr/bin/python3 /usr/bin/python

5. 激活设备

首次在设备上运行程序，会根据设备信息生成一个6位的注册码，使用注册码登录https://xiaozhi.me/注册添加设备。

硬件后台添加设备：https://xiaozhi.me/

6. 客户端交互

2次运行时，首先进行项目源码目录。

# 运行程序

python main.py