What is PY-XIAOZHI?
PY-XIAOZHI This is an AI-powered voice client developed using Python. By porting the code from the native Xiaozhi ESP32, it directly migrates voice interaction functions that originally required specific hardware to general-purpose computer platforms. This means that users do not need to purchase or assemble complex hardware devices; they can enjoy a smooth, real-time voice dialogue experience simply by running it on a desktop or laptop computer.
In terms of protocol support, the project is natively compatible with both MQTT and WSS protocols, supporting not only real-time interruption during conversations but also maintaining a continuous interactive stream. Thanks to its modular design, developers can easily extend the protocol by referencing the official implementation.
Core Functions Explained
Smooth voice interaction experience
The system integrates a complete voice input, recognition, and synthesis chain, capable of simulating natural conversational rhythm. Thanks to... Interrupted interaction With this mechanism, AI responds more promptly; and with the "automatic dialogue" mode enabled, users do not need to be repeatedly woken up during multiple rounds of communication, resulting in a more seamless interactive experience.
Multimodal vision processing
By integrating image recognition capabilities, PY-XIAOZHI can convert static images into understandable text information and combine it with voice output to create rich interactive scenarios. Users only need to configure the API Key of the Zhipu large model to enable advanced vision tasks such as object recognition and face detection.
IoT Smart Home Integration
The project is deeply integrated with the Home Assistant platform, enabling remote control of lights, switches, and various sensors via HTTP API. In addition to physical hardware, it also supports the integration of virtual devices (such as countdown timers), and its modular registration process greatly reduces the difficulty of device expansion.
High-performance network music playback
use pygame The player built with this library supports play, pause, progress adjustment, and lyrics display. Through a local caching mechanism, it effectively reduces playback interruptions caused by network fluctuations, ensuring the stability of the audio stream.
Secure transmission and wake-up mechanism
The system has a built-in wake word activation function (disabled by default), enabling true touchless interaction. To ensure privacy and data security, all audio data is transmitted via the encrypted WSS protocol, effectively preventing data eavesdropping or tampering.
Deployment and usage features
多模式交互界面
- GUI 模式： 提供直观的图形界面，通过 AI 表情和对话文本增强沉浸感。
- CLI 模式： 支持纯命令行运行，完美适配资源受限或无显示器的环境。
跨平台兼容性
PY-XIAOZHI 广泛兼容主流操作系统，包括 Windows 10+、macOS 10.15+ 以及各类 Linux 发行版。部署门槛较低，仅需安装 Python 3.9–3.12 环境并确保麦克风与扬声器正常工作即可。
自动化与稳定性优化
为了提升用户体验，项目实现了多项自动化细节：自动管理 MAC 地址以规避网络冲突；首次启动时自动复制验证码并唤起浏览器完成认证。同时，通过类封装和模块化开发，解决了断线重连等关键稳定性问题，为二次开发提供了便利。
资源获取
客户端下载： 点击跳转网盘
