Py-Xiaozhi 项目架构

基于 Python 实现的小智语音客户端，采用模块化设计，支持多种通信协议和设备集成

核心架构

核心架构图：展示了应用核心、资源管理器、MCP服务器、通信协议层、音频处理系统、用户界面系统、IoT设备管理等模块的关系

状态管理

IDLE

空闲状态，等待用户交互或唤醒词

CONNECTING

正在建立连接

LISTENING

正在监听用户输入

SPEAKING

正在播放语音回复

数据流

音频输入流程

从用户到服务器

麦克风捕获音频并进行采样率转换

VAD检测语音活动判断是否有语音

使用Opus编码器压缩音频数据

通过WebSocket/MQTT协议发送到服务器

音频输出流程

从服务器到用户

服务器返回经过Opus编码的音频数据

使用Opus解码器解码音频数据

通过SoXR进行高质量重采样

输出到音频设备进行播放

MCP工具执行流程

命令处理与执行

用户发送语音或文本命令

MCP服务器解析命令和参数

路由到相应的工具执行器

执行结果返回给用户界面

模块详情

src/application.py

应用主类，采用单例模式管理全局状态
使用asyncio.Task池进行任务管理
实现设备状态机(IDLE/CONNECTING/LISTENING/SPEAKING)
通过命令队列实现线程安全的异步操作

src/core/resource_manager.py

中央化资源生命周期管理
依赖关系跟踪和优先级清理
资源健康监控和统计
自动清理和错误恢复

src/mcp/mcp_server.py

基于JSON-RPC 2.0的MCP服务器
可扩展的工具插件系统
类型安全的参数验证
支持系统、日历、定时器、音乐等多种工具

src/protocols/

抽象协议接口设计
WebSocket协议：实时双向通信
MQTT协议：IoT设备通信
TLS加密和自动重连机制

src/audio_codecs/

基于Opus的实时音频编解码
SoXR高质量音频重采样
异步音频流处理
低延迟音频缓冲管理

src/audio_processing/

基于Vosk的语音活动检测(VAD)
多语言唤醒词检测
相似度算法和拼音匹配
实时音频处理回调

src/display/

策略模式的UI系统架构
PyQt5 + qasync的GUI实现
异步CLI界面支持
情感表情和状态显示

src/iot/

基于Thing抽象的IoT设备框架
统一设备管理器和状态同步
属性和方法的动态发现
支持智能家居设备控制

技术栈

Python

3.9-3.12

AsyncIO

异步编程框架

PyQt5

GUI框架

qasync

Qt异步集成

Vosk

语音识别

OpusLib

音频编解码

SoXR

高质量重采样

SoundDevice

音频设备

WebSockets

实时通信

MQTT

IoT通信

Paho-MQTT

MQTT客户端

Cryptography

加密库

架构特点

单例模式

应用核心采用线程安全的单例模式，保证全局唯一实例

异步架构

全面采用asyncio异步编程，支持高并发和高性能

资源管理

中央化资源管理器，依赖跟踪和优雅清理

状态机模式

设备状态管理采用状态机模式，清晰的状态转换逻辑

插件化设计

MCP工具和IoT设备采用插件化设计，支持动态扩展

跨平台兼容

支持Windows、macOS、Linux多平台，优雅降级处理

Py-Xiaozhi 项目架构 ​

核心架构 ​

状态管理 ​