Upload 169 files

.gitattributes

@@ -33,3 +33,38 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/emojis/angry.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/confident.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/confused.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/cool.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/crying.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/delicious.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/embarrassed.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/funny.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/happy.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/kissy.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/laughing.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/loving.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/neutral.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/relaxed.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/sad.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/shocked.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/silly.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/sleepy.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/surprised.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/thinking.gif filter=lfs diff=lfs merge=lfs -text
+assets/emojis/winking.gif filter=lfs diff=lfs merge=lfs -text
+documents/docs/ecosystem/projects/open-xiaoai/images/logo.png filter=lfs diff=lfs merge=lfs -text
+documents/docs/ecosystem/projects/xiaozhi-android-client/images/界面2.jpg filter=lfs diff=lfs merge=lfs -text
+documents/docs/ecosystem/projects/xiaozhi-unity/images/界面1.png filter=lfs diff=lfs merge=lfs -text
+documents/docs/ecosystem/projects/xiaozhi-unity/images/界面2.png filter=lfs diff=lfs merge=lfs -text
+documents/docs/ecosystem/projects/xiaozhi-unity/images/logo.png filter=lfs diff=lfs merge=lfs -text
+libs/libopus/linux/arm64/libopus.so filter=lfs diff=lfs merge=lfs -text
+libs/libopus/linux/x64/libopus.so filter=lfs diff=lfs merge=lfs -text
+libs/libopus/mac/arm64/libopus.dylib filter=lfs diff=lfs merge=lfs -text
+libs/libopus/mac/x64/libopus.dylib filter=lfs diff=lfs merge=lfs -text
+libs/libopus/win/x86_64/opus.dll filter=lfs diff=lfs merge=lfs -text
+libs/webrtc_apm/linux/x64/libwebrtc_apm.so filter=lfs diff=lfs merge=lfs -text
+libs/webrtc_apm/mac/arm64/libwebrtc_apm.dylib filter=lfs diff=lfs merge=lfs -text
+libs/webrtc_apm/mac/x64/libwebrtc_apm.dylib filter=lfs diff=lfs merge=lfs -text
+libs/webrtc_apm/win/x86_64/libwebrtc_apm.dll filter=lfs diff=lfs merge=lfs -text

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug 报告（Bug Report）
+about: 反馈项目中的缺陷或问题
+title: "[Bug] 简短描述问题"
+labels: bug
+assignees: ''
+---
+
+## 🐛 问题描述
+<!-- 清晰简洁地描述问题是什么 -->
+
+## 🔍 复现步骤
+<!-- 详细描述复现问题的步骤 -->
+1. 打开 '...'
+2. 点击 '...'
+3. 滚动到 '...'
+4. 看到错误
+
+## 🤔 预期行为
+<!-- 简要描述预期的正确行为 -->
+
+## 😯 截图
+<!-- 如果适用，添加问题的截图 -->
+
+## 🖥️ 环境信息
+- 操作系统: [例如 Windows 10]
+- 项目版本: [例如 1.0.0]
+- Python版本: [例如 3.9.13]
+- Nodejs版本: [例如 v20.14.0]
+
+## 📋 其他信息
+<!-- 在此添加关于此问题的任何其他上下文信息 -->

.github/ISSUE_TEMPLATE/code_improvement.md

@@ -0,0 +1,19 @@
+---
+name: 代码优化建议（Code Improvement）
+about: 提出对现有代码的优化或改进建议
+title: "[Improvement] 简短描述改进内容"
+labels: refactor
+assignees: ''
+---
+
+## 💡 改进描述
+<!-- 描述需要改进的代码部分以及存在的问题 -->
+
+## 🌟 改进建议
+<!-- 提出具体的改进方案或思路 -->
+
+## 🛠️ 相关代码
+<!-- 如果可能，提供相关代码片段或链接 -->
+
+## 📋 其他信息
+<!-- 在此添加任何其他相关信息 -->

.github/ISSUE_TEMPLATE/documentation_improvement.md

@@ -0,0 +1,16 @@
+---
+name: 文档改进建议（Documentation Improvement）
+about: 提出对项目文档的改进或补充建议
+title: "[Docs] 简短描述改进内容"
+labels: documentation
+assignees: ''
+---
+
+## 📚 改进描述
+<!-- 描述需要改进的文档部分以及存在的问题 -->
+
+## ✨ 改进建议
+<!-- 提出具体的改进方案或内容 -->
+
+## 📋 其他信息
+<!-- 在此添加任何其他相关信息 -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: 功能请求（Feature Request）
+about: 提出新的功能或改进建议
+title: "[Feature] 简短描述功能"
+labels: enhancement
+assignees: ''
+---
+
+## 🚀 需求描述
+<!-- 清晰简洁地描述你希望发生什么 -->
+
+## 🎯 解决方案
+<!-- 描述你认为可行的解决方案或实现方式 -->
+
+## 📝 备选方案
+<!-- 描述你考虑过的替代方案或功能 -->
+
+## 📋 其他信息
+<!-- 在此添加关于需求的任何其他上下文信息 -->

.github/workflows/vitepress.yml

@@ -0,0 +1,46 @@
+# workflow 名称，可以自定义
+name: Deploy GitHub Pages
+
+# 触发条件：在代码 push 到 master 分支后，自动执行该 workflow
+on:
+  push:
+    branches:
+      - main
+
+# 任务
+jobs:
+  build-and-deploy:
+    # 服务器环境：最新版 Ubuntu，也可以自定义版本
+    runs-on: ubuntu-latest
+    steps:
+      # 拉取代码
+      - name: Checkout
+        uses: actions/checkout@v2
+        with: 
+          fetch-depth: 0
+
+      # 设置 Node.js 版本
+      - name: Setup Node.js environment
+        uses: actions/setup-node@v1
+        with:
+          node-version: "18.20.3"
+      # 安装yarn
+      - name: Install yarn
+        run: npm i yarn -g
+
+      # 如果缓存没有命中，安装依赖
+      - name: Install dependencies
+        run: cd documents && yarn install
+
+      # 生成静态文件
+      - name: Build
+        run: cd documents && yarn docs:build
+
+      # 部署到 GitHub Pages
+      - name: Deploy
+        uses: crazy-max/ghaction-github-pages@v2
+        env:
+         GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }} # ACCESS_TOKEN 是创建的 Secret 名称，替换为你自己创建的名称
+        with:
+          target-branch: gh-pages # 部署到 gh-pages 分支，master 分支存放的是项目源码，而 gh-pages 分支则用来存放生成的静态文件
+          build_dir: documents/docs/.vitepress/dist # vuepress 生成的静态文件存放的地方

.gitignore

@@ -0,0 +1,32 @@
+/logs
+/config
+
+.venv
+**/__pycache__/
+
+.idea/
+venv/
+
+# 音乐缓存
+cache/
+
+
+/models
+
+# 打包相关
+/build
+/dist
+
+# MACOS
+.DS_Store
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+xiaozhi.spec
+
+/installer

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Junsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.en.md

@@ -0,0 +1,165 @@
+# py-xiaozhi
+<p align="center">
+  <a href="https://github.com/huangjunsen0406/py-xiaozhi/releases/latest">
+    <img src="https://img.shields.io/github/v/release/huangjunsen0406/py-xiaozhi?style=flat-square&logo=github&color=blue" alt="Release"/>
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <img src="https://img.shields.io/badge/License-MIT-green.svg?style=flat-square" alt="License: MIT"/>
+  </a>
+  <a href="https://github.com/huangjunsen0406/py-xiaozhi/stargazers">
+    <img src="https://img.shields.io/github/stars/huangjunsen0406/py-xiaozhi?style=flat-square&logo=github" alt="Stars"/>
+  </a>
+  <a href="https://github.com/huangjunsen0406/py-xiaozhi/releases/latest">
+    <img src="https://img.shields.io/github/downloads/huangjunsen0406/py-xiaozhi/total?style=flat-square&logo=github&color=52c41a1&maxAge=86400" alt="Download"/>
+  </a>
+  <a href="https://gitee.com/huang-jun-sen/py-xiaozhi">
+    <img src="https://img.shields.io/badge/Gitee-FF5722?style=flat-square&logo=gitee" alt="Gitee"/>
+  </a>
+</p>
+
+English | [简体中文](README.md)
+
+## Project Introduction
+py-xiaozhi is a Python-based Xiaozhi voice client, designed to learn coding and experience AI voice interaction without hardware requirements. This repository is ported from [xiaozhi-esp32](https://github.com/78/xiaozhi-esp32).
+
+## Demo
+- [Bilibili Demo Video](https://www.bilibili.com/video/BV1HmPjeSED2/#reply255921347937)
+
+![Image](https://github.com/user-attachments/assets/df8bd5d2-a8e6-4203-8084-46789fc8e9ad)
+
+## Features
+- **AI Voice Interaction**: Supports voice input and recognition, enabling smart human-computer interaction with natural conversation flow.
+- **Visual Multimodal**: Supports image recognition and processing, providing multimodal interaction capabilities and image content understanding.
+- **IoT Device Integration**: Supports smart home device control, enabling more IoT functions and building a smart home ecosystem.
+- **Online Music Playback**: Advanced Music Player: A high-performance music player built on Pygame, supporting play/pause/stop, progress control, lyric display, and local caching, delivering a more stable and smooth listening experience.
+- **Voice Wake-up**: Supports wake word activation, eliminating manual operation (disabled by default, manual activation required).
+- **Auto Dialogue Mode**: Implements continuous dialogue experience, enhancing user interaction fluidity.
+- **Graphical Interface**: Provides intuitive GUI with Xiaozhi expressions and text display, enhancing visual experience.
+- **Command Line Mode**: Supports CLI operation, suitable for embedded devices or environments without GUI.
+- **Cross-platform Support**: Compatible with Windows 10+, macOS 10.15+, and Linux systems for use anywhere.
+- **Volume Control**: Supports volume adjustment to adapt to different environmental requirements with unified sound control interface.
+- **Session Management**: Effectively manages multi-turn dialogues to maintain interaction continuity.
+- **Encrypted Audio Transmission**: Supports WSS protocol to ensure audio data security and prevent information leakage.
+- **Automatic Verification Code Handling**: Automatically copies verification codes and opens browsers during first use, simplifying user operations.
+- **Automatic MAC Address Acquisition**: Avoids MAC address conflicts and improves connection stability.
+- **Modular Code**: Code is split and encapsulated into classes with clear responsibilities, facilitating secondary development.
+- **Stability Optimization**: Fixes multiple issues including reconnection and cross-platform compatibility.
+
+## System Requirements
+- Python version: 3.9 >= version <= 3.12
+- Supported operating systems: Windows 10+, macOS 10.15+, Linux
+- Microphone and speaker devices
+
+## Read This First!
+- Carefully read [项目文档](https://huangjunsen0406.github.io/py-xiaozhi/) for startup tutorials and file descriptions
+- The main branch has the latest code; manually reinstall pip dependencies after each update to ensure you have new dependencies
+
+[Zero to Xiaozhi Client (Video Tutorial)](https://www.bilibili.com/video/BV1dWQhYEEmq/?vd_source=2065ec11f7577e7107a55bbdc3d12fce)
+
+## State Transition Diagram
+
+```
+                        +----------------+
+                        |                |
+                        v                |
++------+  Wake/Button  +------------+   |   +------------+
+| IDLE | -----------> | CONNECTING | --+-> | LISTENING  |
++------+              +------------+       +------------+
+   ^                                            |
+   |                                            | Voice Recognition Complete
+   |          +------------+                    v
+   +--------- |  SPEAKING  | <-----------------+
+     Playback +------------+
+     Complete
+```
+
+## Upcoming Features
+- [ ] **New GUI (Electron)**: Provides a more modern and beautiful user interface, optimizing the interaction experience.
+
+## FAQ
+- **Can't find audio device**: Please check if your microphone and speakers are properly connected and enabled.
+- **Wake word not responding**: Check if the `USE_WAKE_WORD` setting in `config.json` is set to `true` and the model path is correct.
+- **Network connection failure**: Check network settings and firewall configuration to ensure WebSocket or MQTT communication is not blocked.
+- **Packaging failure**: Make sure PyInstaller is installed (`pip install pyinstaller`) and all dependencies are installed. Then re-execute `python scripts/build.py`
+
+## Related Third-party Open Source Projects
+[Xiaozhi Mobile Client](https://github.com/TOM88812/xiaozhi-android-client)
+
+[xiaozhi-esp32-server (Open source server)](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+
+[XiaoZhiAI_server32_Unity(Unity Development)](https://gitee.com/vw112266/XiaoZhiAI_server32_Unity)
+
+[IntelliConnect(Aiot Middleware)](https://github.com/ruanrongman/IntelliConnect)
+
+[open-xiaoai(Xiaoai Audio Access Xiaozhi)](https://github.com/idootop/open-xiaoai.git)
+
+## Related Branches
+- main: Main branch
+- feature/v1: First version
+- feature/visual: Visual branch
+- feature/raspberry_pi embedded device branch
+## Project Structure
+
+```
+├── .github                 # GitHub related configurations
+├── assets                  # Resource files (emotion animations, etc.)
+├── cache                   # Cache directory (music and temporary files)
+├── config                  # Configuration directory
+├── documents               # Documentation directory
+├── hooks                   # PyInstaller hooks directory
+├── libs                    # Dependencies directory
+├── scripts                 # Utility scripts directory
+├── src                     # Source code directory
+│   ├── audio_codecs        # Audio encoding/decoding module
+│   ├── audio_processing    # Audio processing module
+│   ├── constants           # Constants definition
+│   ├── display             # Display interface module
+│   ├── iot                 # IoT device related module
+│   │   └── things          # Specific device implementation directory
+│   ├── network             # Network communication module
+│   ├── protocols           # Communication protocol module
+│   └── utils               # Utility classes module
+```
+
+## Contribution Guidelines
+We welcome issue reports and code contributions. Please ensure you follow these specifications:
+
+1. Code style complies with PEP8 standards
+2. PR submissions include appropriate tests
+3. Update relevant documentation
+
+## Community and Support
+
+### Thanks to the Following Open Source Contributors
+> In no particular order
+
+[Xiaoxia](https://github.com/78)
+[zhh827](https://github.com/zhh827)
+[SmartArduino-Li Honggang](https://github.com/SmartArduino)
+[HonestQiao](https://github.com/HonestQiao)
+[vonweller](https://github.com/vonweller)
+[Sun Weigong](https://space.bilibili.com/416954647)
+[isamu2025](https://github.com/isamu2025)
+[Rain120](https://github.com/Rain120)
+[kejily](https://github.com/kejily)
+[Radio bilibili Jun](https://space.bilibili.com/119751)
+
+### Sponsorship Support
+
+<div align="center">
+  <h3>Thanks to All Sponsors ❤️</h3>
+  <p>Whether it's API resources, device compatibility testing, or financial support, every contribution makes the project more complete</p>
+  
+  <a href="https://huangjunsen0406.github.io/py-xiaozhi/sponsors/" target="_blank">
+    <img src="https://img.shields.io/badge/View-Sponsors-brightgreen?style=for-the-badge&logo=github" alt="View Sponsors">
+  </a>
+  <a href="https://huangjunsen0406.github.io/py-xiaozhi/sponsors/" target="_blank">
+    <img src="https://img.shields.io/badge/Become-Sponsor-orange?style=for-the-badge&logo=heart" alt="Become a Sponsor">
+  </a>
+</div>
+
+## Project Statistics
+[![Star History Chart](https://api.star-history.com/svg?repos=huangjunsen0406/py-xiaozhi&type=Date)](https://www.star-history.com/#huangjunsen0406/py-xiaozhi&Date)
+
+## License
+[MIT License](LICENSE) 

README.md

@@ -1,12 +1,167 @@
----
-title: Xiaozhi
-emoji: 🌖
-colorFrom: blue
-colorTo: blue
-sdk: gradio
-sdk_version: 5.29.0
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# py-xiaozhi
+<p align="center">
+  <a href="https://github.com/huangjunsen0406/py-xiaozhi/releases/latest">
+    <img src="https://img.shields.io/github/v/release/huangjunsen0406/py-xiaozhi?style=flat-square&logo=github&color=blue" alt="Release"/>
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <img src="https://img.shields.io/badge/License-MIT-green.svg?style=flat-square" alt="License: MIT"/>
+  </a>
+  <a href="https://github.com/huangjunsen0406/py-xiaozhi/stargazers">
+    <img src="https://img.shields.io/github/stars/huangjunsen0406/py-xiaozhi?style=flat-square&logo=github" alt="Stars"/>
+  </a>
+  <a href="https://github.com/huangjunsen0406/py-xiaozhi/releases/latest">
+    <img src="https://img.shields.io/github/downloads/huangjunsen0406/py-xiaozhi/total?style=flat-square&logo=github&color=52c41a1&maxAge=86400" alt="Download"/>
+  </a>
+  <a href="https://gitee.com/huang-jun-sen/py-xiaozhi">
+    <img src="https://img.shields.io/badge/Gitee-FF5722?style=flat-square&logo=gitee" alt="Gitee"/>
+  </a>
+</p>
+
+
+
+简体中文 | [English](README.en.md)
+
+## 项目简介
+py-xiaozhi 是一个使用 Python 实现的小智语音客户端，旨在通过代码学习和在没有硬件条件下体验 AI 小智的语音功能。
+本仓库是基于[xiaozhi-esp32](https://github.com/78/xiaozhi-esp32)移植
+
+## 演示
+- [Bilibili 演示视频](https://www.bilibili.com/video/BV1HmPjeSED2/#reply255921347937)
+
+![Image](https://github.com/user-attachments/assets/df8bd5d2-a8e6-4203-8084-46789fc8e9ad)
+
+## 功能特点
+- **AI语音交互**：支持语音输入与识别，实现智能人机交互，提供自然流畅的对话体验。
+- **视觉多模态**：支持图像识别和处理，提供多模态交互能力，理解图像内容。
+- **IoT 设备集成**：支持智能家居设备控制，实现更多物联网功能，打造智能家居生态。
+- **联网音乐播放**：基于pygame实现的高性能音乐播放器，支持歌词显示和本地缓存，支持播放／暂停／停止、进度控制、歌词显示和本地缓存，提供更稳定的音乐播放体验。
+- **语音唤醒**：支持唤醒词激活交互，免去手动操作的烦恼（默认关闭需要手动开启）。
+- **自动对话模式**：实现连续对话体验，提升用户交互流畅度。
+- **图形化界面**：提供直观易用的 GUI，支持小智表情与文本显示，增强视觉体验。
+- **命令行模式**：支持 CLI 运行，适用于嵌入式设备或无 GUI 环境。
+- **跨平台支持**：兼容 Windows 10+、macOS 10.15+ 和 Linux 系统，随时随地使用。
+- **音量控制**：支持音量调节，适应不同环境需求，统一声音控制接口。
+- **会话管理**：有效管理多轮对话，保持交互的连续性。
+- **加密音频传输**：支持 WSS 协议，保障音频数据的安全性，防止信息泄露。
+- **自动验证码处理**：首次使用时，程序自动复制验证码并打开浏览器，简化用户操作。
+- **自动获取 MAC 地址**：避免 MAC 地址冲突，提高连接稳定性。
+- **代码模块化**：拆分代码并封装为类，职责分明，便于二次开发。
+- **稳定性优化**：修复多项问题，包括断线重连、跨平台兼容等。
+
+## 系统要求
+- 3.9 >= Python版本 <= 3.12
+- 支持的操作系统：Windows 10+、macOS 10.15+、Linux
+- 麦克风和扬声器设备
+
+## 请先看这里！
+- 仔细阅读 [项目文档](https://huangjunsen0406.github.io/py-xiaozhi/) 启动教程和文件说明都在里面了
+- main是最新代码，每次更新都需要手动重新安装一次pip依赖防止我新增依赖后你们本地没有
+
+[从零开始使用小智客户端（视频教程）](https://www.bilibili.com/video/BV1dWQhYEEmq/?vd_source=2065ec11f7577e7107a55bbdc3d12fce)
+
+## 状态流转图
+
+```
+                        +----------------+
+                        |                |
+                        v                |
++------+  唤醒词/按钮  +------------+   |   +------------+
+| IDLE | -----------> | CONNECTING | --+-> | LISTENING  |
++------+              +------------+       +------------+
+   ^                                            |
+   |                                            | 语音识别完成
+   |          +------------+                    v
+   +--------- |  SPEAKING  | <-----------------+
+     完成播放 +------------+
+```
+
+## 待实现功能
+- [ ] **新 GUI（Electron）**：提供更现代、美观的用户界面，优化交互体验。
+
+## 常见问题
+- **找不到音频设备**：请检查麦克风和扬声器是否正常连接和启用。
+- **唤醒词不响应**：请检查`config.json`中的`USE_WAKE_WORD`设置是否为`true`，以及模型路径是否正确。
+- **网络连接失败**：请检查网络���置和防火墙配置，确保WebSocket或MQTT通信未被阻止。
+- **打包失败**：确保已安装PyInstaller (`pip install pyinstaller`)，并且所有依赖项都已安装。然后重新执行`python scripts/build.py`
+
+## 相关第三方开源项目
+[小智手机端](https://github.com/TOM88812/xiaozhi-android-client)
+
+[xiaozhi-esp32-server（开源服务端）](https://github.com/xinnan-tech/xiaozhi-esp32-server)
+
+[XiaoZhiAI_server32_Unity(Unity开发)](https://gitee.com/vw112266/XiaoZhiAI_server32_Unity)
+
+[IntelliConnect(Aiot中间件)](https://github.com/ruanrongman/IntelliConnect)
+
+[open-xiaoai(小爱音响接入小智)](https://github.com/idootop/open-xiaoai.git)
+
+## 相关分支
+- main 主分支
+- feature/v1 第一个版本
+- feature/visual 视觉分支
+- feature/raspberry_pi 嵌入式设备分支
+## 项目结构
+
+```
+├── .github                 # GitHub 相关配置
+├── assets                  # 资源文件（表情动画等）
+├── cache                   # 缓存目录（音乐等临时文件）
+├── config                  # 配置文件目录
+├── documents               # 文档目录
+├── hooks                   # PyInstaller钩子目录
+├── libs                    # 依赖库目录
+├── scripts                 # 实用脚本目录
+├── src                     # 源代码目录
+│   ├── audio_codecs        # 音频编解码模块
+│   ├── audio_processing    # 音频处理模块
+│   ├── constants           # 常量定义
+│   ├── display             # 显示界面模块
+│   ├── iot                 # IoT设备相关模块
+│   │   └── things          # 具体设备实现目录
+│   ├── network             # 网络通信模块
+│   ├── protocols           # 通信协议模块
+│   └── utils               # 工具类模块
+```
+
+## 贡献指南
+欢迎提交问题报告和代码贡献。请确保遵循以下规范：
+
+1. 代码风格符合PEP8规范
+2. 提交的PR包含适当的测试
+3. 更新相关文档
+
+## 社区与支持
+
+### 感谢以下开源人员
+> 排名不分前后
+
+[Xiaoxia](https://github.com/78)
+[zhh827](https://github.com/zhh827)
+[四博智联-李洪刚](https://github.com/SmartArduino)
+[HonestQiao](https://github.com/HonestQiao)
+[vonweller](https://github.com/vonweller)
+[孙卫公](https://space.bilibili.com/416954647)
+[isamu2025](https://github.com/isamu2025)
+[Rain120](https://github.com/Rain120)
+[kejily](https://github.com/kejily)
+[电波bilibili君](https://space.bilibili.com/119751)
+
+### 赞助支持
+
+<div align="center">
+  <h3>感谢所有赞助者的支持 ❤️</h3>
+  <p>无论是接口资源、设备兼容测试还是资金支持，每一份帮助都让项目更加完善</p>
+  
+  <a href="https://huangjunsen0406.github.io/py-xiaozhi/sponsors/" target="_blank">
+    <img src="https://img.shields.io/badge/查看-赞助者名单-brightgreen?style=for-the-badge&logo=github" alt="赞助者名单">
+  </a>
+  <a href="https://huangjunsen0406.github.io/py-xiaozhi/sponsors/" target="_blank">
+    <img src="https://img.shields.io/badge/成为-项目赞助者-orange?style=for-the-badge&logo=heart" alt="成为赞助者">
+  </a>
+</div>
+
+## 项目统计
+[![Star History Chart](https://api.star-history.com/svg?repos=huangjunsen0406/py-xiaozhi&type=Date)](https://www.star-history.com/#huangjunsen0406/py-xiaozhi&Date)
+
+## 许可证
+[MIT License](LICENSE)

build.json

@@ -0,0 +1,46 @@
+{
+    "name": "xiaozhi",
+    "version": "1.0.0",
+    "publisher": "Junsen",
+    "entry": "main.py",
+    "icon": "assets/xiaozhi_icon.ico",
+    "hooks": "hooks",
+    "onefile": false,
+    "additional_pyinstaller_args": "--add-data assets;assets --add-data libs;libs --add-data src;src --add-data models;models --hidden-import=PyQt5",
+    "inno_setup_path": "E:\\application\\Inno Setup 6\\ISCC.exe",
+    "platform_specific": {
+        "windows": {
+            "format": "exe",
+            "additional_pyinstaller_args": "--add-data assets;assets --add-data libs;libs --add-data src;src --add-data models;models --hidden-import=PyQt5 --noconsole",
+            "desktop_entry": true,
+            "installer_options": {
+                "languages": ["ChineseSimplified", "English"],
+                "license_file": "LICENSE",
+                "readme_file": "README.md",
+                "create_desktop_icon": true,
+                "allow_run_after_install": true
+            }
+        },
+        "linux": {
+            "format": "deb",
+            "desktop_entry": true,
+            "categories": "Utility;Development;",
+            "description": "小智Ai客户端",
+            "requires": "libc6,libgtk-3-0,libx11-6,libopenblas-dev",
+            "additional_pyinstaller_args": "--add-data assets:assets --add-data libs:libs --add-data src:src --add-data models:models --hidden-import=PyQt5"
+        },
+        "macos": {
+            "format": "app",
+            "additional_pyinstaller_args": "--add-data assets:assets --add-data libs:libs --add-data src:src --add-data models:models --hidden-import=PyQt5 --windowed",
+            "app_bundle_name": "XiaoZhi.app",
+            "bundle_identifier": "com.junsen.xiaozhi",
+            "sign_bundle": false,
+            "create_dmg": true,
+            "installer_options": {
+                "license_file": "LICENSE",
+                "readme_file": "README.md"
+            }
+        }
+    },
+    "build_installer": true
+}

documents/.gitignore

@@ -0,0 +1,2 @@
+dist
+node_modules

documents/README.md

@@ -0,0 +1,74 @@
+# py-xiaozhi 文档
+
+这是 py-xiaozhi 项目的文档网站，基于 VitePress 构建。
+
+## 功能
+
+- 项目指南：提供项目的详细使用说明和开发文档
+- 赞助商页面：展示并感谢项目的所有赞助者
+- 贡献指南：说明如何为项目贡献代码
+- 贡献者名单：展示所有为项目做出贡献的开发者
+- 响应式设计：适配桌面和移动设备
+
+## 本地开发
+
+```bash
+# 安装依赖
+pnpm install
+
+# 启动开发服务器
+pnpm docs:dev
+
+# 构建静态文件
+pnpm docs:build
+
+# 预览构建结果
+pnpm docs:preview
+```
+
+## 目录结构
+
+```
+documents/
+├── docs/                  # 文档源文件
+│   ├── .vitepress/        # VitePress 配置
+│   ├── guide/             # 指南文档
+│   ├── sponsors/          # 赞助商页面
+│   ├── contributing.md    # 贡献指南
+│   ├── contributors.md    # 贡献者名单
+│   └── index.md           # 首页
+├── package.json           # 项目配置
+└── README.md              # 项目说明
+```
+
+## 赞助商页面
+
+赞助商页面通过以下方式实现：
+
+1. `/sponsors/` 目录包含了赞助商相关的内容
+2. `data.json` 文件存储赞助商数据
+3. 使用 Vue 组件在客户端动态渲染赞助商列表
+4. 提供成为赞助者的详细说明和支付方式
+
+## 贡献指南
+
+贡献指南页面提供了以下内容：
+
+1. 开发环境准备指南
+2. 代码贡献流程说明
+3. 编码规范和提交规范
+4. Pull Request 创建和审核流程
+5. 文档贡献指南
+
+## 贡献者名单
+
+贡献者名单页面展示了所有为项目做出贡献的开发者，包括：
+
+1. 核心开发团队成员
+2. 代码贡献者
+3. 文档贡献者
+4. 测试和反馈提供者
+
+## 部署
+
+文档网站通过 GitHub Actions 自动部署到 GitHub Pages。 

documents/docs/.vitepress/config.mts

@@ -0,0 +1,74 @@
+import { defineConfig } from 'vitepress'
+import { getGuideSideBarItems } from './guide'
+import tailwindcss from '@tailwindcss/vite'
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "PY-XIAOZHI",
+  description: "py-xiaozhi 是一个使用 Python 实现的小智语音客户端，旨在通过代码学习和在没有硬件条件下体验 AI 小智的语音功能。",
+  base: '/py-xiaozhi/',
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: '主页', link: '/' },
+      { text: '指南', link: '/guide/00_文档目录' },
+      { text: '系统架构', link: '/architecture/' },
+      { text: '相关生态', link: '/ecosystem/' },
+      { text: '团队', link: '/about/team' },
+      { text: '贡献指南', link: '/contributing' },
+      { text: '赞助', link: '/sponsors/' }
+    ],
+
+    sidebar: {
+      '/guide/': [
+        {
+          text: '指南',
+          // 默认展开
+          collapsed: false,
+          items: getGuideSideBarItems(),
+        },
+        {
+          text: '旧版文档',
+          collapsed: true,
+          items: [
+            { text: '使用文档', link: '/guide/old_docs/使用文档' }
+          ]
+        }
+      ],
+      '/ecosystem/': [
+        {
+          text: '生态系统概览',
+          link: '/ecosystem/'
+        },
+        {
+          text: '相关项目',
+          collapsed: false,
+          items: [
+            { text: '小智手机端', link: '/ecosystem/projects/xiaozhi-android-client/' },
+            { text: 'xiaozhi-esp32-server', link: '/ecosystem/projects/xiaozhi-esp32-server/' },
+            { text: 'XiaoZhiAI_server32_Unity', link: '/ecosystem/projects/xiaozhi-unity/' },
+            { text: 'IntelliConnect', link: '/ecosystem/projects/intelliconnect/' },
+            { text: 'open-xiaoai', link: '/ecosystem/projects/open-xiaoai/' }
+          ]
+        },
+      ],
+      '/about/': [],
+      // 赞助页面不显示侧边栏
+      '/sponsors/': [],
+      // 贡献指南页面不显示侧边栏
+      '/contributing': [],
+      // 系统架构页面不显示侧边栏
+      '/architecture/': [],
+      // 团队页面不显示侧边栏
+      '/about/team': []
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/huangjunsen0406/py-xiaozhi' }
+    ]
+  },
+  vite: {
+    plugins: [
+        tailwindcss()
+    ]
+  }
+})

documents/docs/.vitepress/guide/index.ts

@@ -0,0 +1,15 @@
+import { getMdFilesAsync } from "../utils";
+import path from 'path';
+import { DefaultTheme } from 'vitepress';
+
+export function getGuideSideBarItems(): (DefaultTheme.SidebarItem)[] {
+  return getMdFilesAsync(path.resolve(__dirname, '../../guide'))
+  .map(item => {
+    return {
+      text: item,
+      link: `/guide/${item}`
+    }
+  }).filter(item => {
+    return !item.text.includes('使用文档')
+  })
+}

documents/docs/.vitepress/theme/index.ts

@@ -0,0 +1,7 @@
+import DefaultTheme from 'vitepress/theme'
+import './styles/index.css'
+import './styles/custom.scss'
+
+export default {
+  ...DefaultTheme,
+}

documents/docs/.vitepress/theme/styles/badges.css

@@ -0,0 +1,28 @@
+.vt-badge.wip:before {
+  content: 'WIP';
+}
+
+.vt-badge.ts {
+  background-color: #3178c6;
+}
+.vt-badge.ts:before {
+  content: 'TS';
+}
+
+.vt-badge.dev-only,
+.vt-badge.experimental {
+  color: var(--vt-c-text-light-1);
+  background-color: var(--vt-c-yellow);
+}
+
+.vt-badge.dev-only:before {
+  content: 'Dev only';
+}
+
+.vt-badge.experimental:before {
+  content: 'Experimental';
+}
+
+.vt-badge[data-text]:before {
+  content: attr(data-text);
+}

documents/docs/.vitepress/theme/styles/custom.scss

@@ -0,0 +1,26 @@
+.architecture-page-class {
+  @media (min-width: 1440px) {
+
+    .VPDoc:not(.has-sidebar) .content {
+
+      max-width: 1284px !important; /* <-- update your values */
+
+    }
+
+    .VPDoc:not(.has-sidebar) .container {
+
+      max-width: 1604px !important;
+
+    }
+    .VPDoc.has-aside .content-container {
+        max-width: 1188px !important;
+    }
+
+    .vp-doc h3 {
+      margin: 0;
+    }
+    .vp-doc ul {
+      padding-left: 0;
+    }
+  }
+}

documents/docs/.vitepress/theme/styles/index.css

@@ -0,0 +1,7 @@
+@import "./pages.css";
+@import "./badges.css";
+@import "./options-boxes.css";
+@import "./inline-demo.css";
+@import "./utilities.css";
+@import "./style-guide.css";
+@import "tailwindcss";

documents/docs/.vitepress/theme/styles/inline-demo.css

@@ -0,0 +1,90 @@
+.vt-doc a[href^="https://play.vuejs.org"]:before
+{
+  content: '▶';
+  width: 20px;
+  height: 20px;
+  display: inline-flex;
+  border-radius: 10px;
+  vertical-align: middle;
+  position: relative;
+  top: -2px;
+  color: var(--vt-c-green);
+  border: 2px solid var(--vt-c-green);
+  margin-right: 8px;
+  margin-left: 4px;
+  line-height: 16px;
+  padding-left: 4.2px;
+  font-size: 11px;
+}
+
+.demo {
+  padding: 22px 24px;
+  border-radius: 8px;
+  box-shadow: var(--vt-shadow-2);
+  margin-bottom: 1.2em;
+  transition: background-color 0.5s ease;
+}
+
+.dark .demo {
+  background-color: var(--vt-c-bg-soft);
+}
+
+.demo p {
+  margin: 0;
+}
+
+.demo button {
+  background-color: var(--vt-c-bg-mute);
+  transition: background-color 0.5s;
+  padding: 5px 12px;
+  border: 1px solid var(--vt-c-divider);
+  border-radius: 8px;
+  font-size: 0.9em;
+  font-weight: 600;
+}
+
+.demo button + button {
+  margin-left: 1em;
+}
+
+.demo input,
+.demo textarea,
+.demo select {
+  border: 1px solid var(--vt-c-divider);
+  border-radius: 4px;
+  padding: 0.2em 0.6em;
+  margin-top: 10px;
+  background: transparent;
+  transition: background-color 0.5s;
+}
+
+.dark .demo select {
+  background: var(--vt-c-bg-soft);
+}
+
+.dark .demo select option {
+  background: transparent;
+}
+
+.demo input:not([type]):focus,
+.demo textarea:focus,
+.demo select:focus {
+  outline: 1px solid blue;
+}
+
+.demo select {
+  /* this was set by normalize.css */
+  -webkit-appearance: listbox;
+}
+
+.demo label {
+  margin: 0 1em 0 0.4em;
+}
+
+.demo select[multiple] {
+  width: 100px;
+}
+
+.demo h1 {
+  margin: 10px 0 0;
+}

documents/docs/.vitepress/theme/styles/options-boxes.css

@@ -0,0 +1,27 @@
+.next-steps {
+  margin-top: 3rem;
+}
+
+.next-steps .vt-box {
+  border: 1px solid var(--vt-c-bg-soft);
+}
+
+.next-steps .vt-box:hover {
+  border-color: var(--vt-c-green-light);
+  transition: border-color 0.3s cubic-bezier(0.25, 0.8, 0.25, 1);
+}
+
+.vt-doc .next-steps-link {
+  font-size: 20px;
+  line-height: 1.4;
+  letter-spacing: -0.02em;
+  margin-bottom: 0.75em;
+  display: block;
+  color: var(--vt-c-green);
+}
+
+.vt-doc .next-steps-caption {
+  margin-bottom: 0;
+  color: var(--vt-c-text-2);
+  transition: color 0.5s;
+}

documents/docs/.vitepress/theme/styles/pages.css

@@ -0,0 +1,15 @@
+/* always show anchors on /api/ and /style-guide/ pages */
+.vt-doc.api h2 .header-anchor,
+.vt-doc.style-guide h2 .header-anchor {
+  opacity: 1;
+}
+
+.vt-doc.sponsor h3 {
+  text-align: center;
+  padding-bottom: 1em;
+  border-bottom: 1px solid var(--vt-c-divider-light);
+}
+
+.vt-doc.sponsor h3 .header-anchor {
+  display: none;
+}

documents/docs/.vitepress/theme/styles/style-guide.css

@@ -0,0 +1,65 @@
+.style-example {
+  border-radius: 8px 8px 12px 12px;
+  margin: 1.6em 0;
+  padding: 1.6em 1.6em 0.1px;
+  position: relative;
+  border: 1px solid transparent;
+  transition: background-color 0.25s ease, border-color 0.25s ease;
+}
+
+.vt-doc .style-example h3 {
+  margin: 0;
+  font-size: 1.1em;
+}
+
+.style-example-bad {
+  background: #f7e8e8;
+}
+.dark .style-example-bad {
+  background: transparent;
+  border-color: var(--vt-c-red);
+}
+
+.style-example-bad h3 {
+  color: var(--vt-c-red);
+}
+
+.style-example-good {
+  background: #ecfaf7;
+}
+.dark .style-example-good {
+  background: transparent;
+  border-color: var(--vt-c-green);
+}
+
+.style-example-good h3 {
+  color: var(--vt-c-green);
+}
+
+.details summary {
+  font-weight: bold !important;
+}
+
+.style-verb {
+  font-size: 0.6em;
+  display: inline-block;
+  border-radius: 6px;
+  font-size: 0.65em;
+  line-height: 1;
+  font-weight: 600;
+  padding: 0.35em 0.4em 0.3em;
+  position: relative;
+  top: -0.15em;
+  margin-right: 0.5em;
+  color: var(--vt-c-bg);
+  transition: color 0.5s;
+  background-color: var(--vt-c-brand);
+}
+
+.style-verb.avoid {
+  background-color: var(--vt-c-red);
+}
+.vt-doc summary {
+  width: fit-content;
+  cursor: pointer;
+}

documents/docs/.vitepress/theme/styles/utilities.css

@@ -0,0 +1,14 @@
+.nowrap {
+  white-space: nowrap;
+}
+
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  border: 0;
+}

documents/docs/.vitepress/theme/styles/vue-mastery.css

@@ -0,0 +1,65 @@
+.vue-mastery-link {
+  background-color: var(--vt-c-bg-soft);
+  border-radius: 8px;
+  padding: 8px 16px 8px 8px;
+  transition: color 0.5s, background-color 0.5s;
+}
+
+.vue-mastery-link a {
+  display: flex;
+  align-items: center;
+}
+
+.vue-mastery-link .banner {
+  background-color: var(--vt-c-white-soft);
+  border-radius: 4px;
+  width: 96px;
+  height: 56px;
+  object-fit: cover;
+}
+
+.vue-mastery-link .description {
+  flex: 1;
+  font-weight: 500;
+  font-size: 14px;
+  line-height: 20px;
+  color: var(--vt-c-text-1);
+  margin: 0 0 0 16px;
+  transition: color 0.5s;
+}
+
+.vue-mastery-link .description span {
+  color: var(--vt-c-brand);
+}
+
+.vue-mastery-link .logo-wrapper {
+  position: relative;
+  width: 48px;
+  height: 48px;
+  border-radius: 50%;
+  background-color: var(--vt-c-white);
+  display: flex;
+  justify-content: center;
+  align-items: center;
+}
+
+.vue-mastery-link .logo-wrapper img {
+  width: 25px;
+  object-fit: contain;
+}
+
+@media (max-width: 576px) {
+  .vue-mastery-link .banner {
+    width: 56px;
+  }
+
+  .vue-mastery-link .description {
+    font-size: 12px;
+    line-height: 18px;
+  }
+  .vue-mastery-link .logo-wrapper {
+    position: relative;
+    width: 32px;
+    height: 32px;
+  }
+}

documents/docs/.vitepress/utils/index.ts

@@ -0,0 +1,26 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+export function getMdFilesAsync(rootDir: string) {
+    const results: string[] = [];
+    
+    function traverse(currentDir) {
+        const entries =  fs.readdirSync(currentDir, { withFileTypes: true });
+        
+        entries.map(async (entry) => {
+          const entryPath = path.join(currentDir, entry.name);
+          
+          if (entry.isDirectory()) {
+              traverse(entryPath); // 递归子目录[3](@ref)
+          } else if (path.extname(entry.name).toLowerCase() === '.md') {
+              const relativePath = path.relative(rootDir, entryPath);
+              results.push(relativePath);
+          }
+      })
+    }
+    
+    traverse(rootDir);
+    return results.map(item => {
+      return item.replace('.md', '');
+    });
+}

documents/docs/about/team.md

@@ -0,0 +1,11 @@
+---
+page: true
+title: Py-xiaozhi团队
+layout: home
+---
+
+<script setup>
+import TeamPage from './team/TeamPage.vue'
+</script>
+
+<TeamPage />