Py-Xiaozhi 项目架构

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

核心架构

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

模块详情

src/application.py

应用主类，单例模式管理全局状态
异步任务管理和状态机控制
设备状态(IDLE/CONNECTING/LISTENING/SPEAKING)
线程安全的命令队列处理

src/mcp/

基于JSON-RPC 2.0的MCP服务器
丰富的工具生态系统(系统、日历、地图等)
可扩展的插件架构
类型安全的参数验证

src/protocols/

抽象协议接口设计
WebSocket和MQTT协议实现
TLS加密和自动重连机制
统一的通信抽象层

src/audio_codecs/

基于Opus的实时音频编解码
WebRTC音频回声消除(AEC)处理器
SoXR高质量音频重采样
系统音频录制与环回处理
异步音频流处理
低延迟音频缓冲管理

src/audio_processing/

AEC声学回声消除处理器
基于Sherpa-ONNX的语音活动检测(VAD)
多语言唤醒词检测
实时音频处理和回调机制

src/display/

策略模式的UI系统架构
PyQt5 GUI和CLI界面实现
异步界面更新
状态显示和用户交互

src/iot/

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

src/utils/

配置管理和设备指纹
日志系统和资源查找
音量控制和通用工具
跨平台兼容性处理

技术栈

Python

3.9-3.12

AsyncIO

异步编程框架

PyQt5

GUI框架

qasync

Qt异步集成

Sherpa-ONNX

语音识别引擎

WebRTC AEC

WebRTC音频处理模块

OpusLib

音频编解码

SoXR

高质量重采样

SoundDevice

音频设备管理

WebSockets

实时通信协议

MQTT

IoT消息传输

MCP Protocol

模型上下文协议

Cryptography

加密安全库

Thing抽象

IoT设备抽象

JSON-RPC

远程过程调用

架构特点

单例模式

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

异步架构

全面采用asyncio异步编程，支持高并发处理和实时音频流

资源管理

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

状态机模式

设备状态管理采用状态机模式，清晰的状态转换和错误恢复

插件化生态

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

跨平台兼容

支持Windows、macOS、Linux多平台，智能特性检测和优雅降级