Py-Xiaozhi Project Architecture
A Python-based Xiaozhi voice assistant client with modular design, supporting multiple communication protocols and device integrations
Core Architecture
Core: container → plugins / protocol / audio / UI
Module Details
src/bootstrap/
- ServiceContainer orchestrates start/shutdown
- Session, health, and plugin wiring split out
- Plugins load by dependency order
src/core/
- EventBus for decoupled messaging
- Device state machine and protocol manager
- Tasks and resources cleaned up together
src/plugins/
- Plugin lifecycle and failure isolation
- Audio, UI, shortcuts, wake word, MCP
src/protocols/
- WebSocket and MQTT
- Realtime audio and text
src/audio_codecs/
- Opus codec and resampling
- Hot refresh and reload of devices
src/audio_processing/
- Offline wake-word detection
- Reuses microphone PCM
src/mcp/
- Music, camera, screenshot, volume, and more
- Container injection; optional external plugins
- Camera: USB and Raspberry Pi CSI
src/ui/
- GUI / CLI / GPIO via ViewPort
- PySide6 + QML main window and settings
- Cold start does not steal focus (macOS)
src/activation/
- Device activation and OTA
- Standalone activation window
src/logging/
- Leveled logs and rotation
- Explicit initialization
src/utils/
- Config (audio devices matched by name)
- Resource paths and cross-platform helpers
Technology Stack
Python
>= 3.10
AsyncIO
异步编程框架
PySide6
Qt6 GUI框架
QML/QtQuick
声明式UI
qasync
Qt异步集成
uv
包管理器
Sherpa-ONNX
唤醒词检测
OpusLib
音频编解码
SoXR
高质量重采样
SoundDevice
音频设备管理
WebSockets
实时通信协议
MQTT
IoT消息传输
MCP Protocol
模型上下文协议
EventBus
事件驱动架构
Quartz
macOS快捷键
Architecture Features
Event-driven
Modules talk via EventBus with less direct coupling
Async
asyncio + qasync for realtime voice
Multi UI
GUI / CLI / GPIO share one ViewPort
State machine
Idle / listening / speaking transitions
Plugins
Audio, MCP, UI, shortcuts, wake word
Cross-platform
Windows / macOS / Linux (incl. Raspberry Pi)