{"id":26818773,"url":"https://github.com/huangjunsen0406/py-xiaozhi","last_synced_at":"2025-05-15T08:04:44.416Z","repository":{"id":278132057,"uuid":"933350408","full_name":"huangjunsen0406/py-xiaozhi","owner":"huangjunsen0406","description":"python版本的小智ai，主要帮助那些没有硬件却想体验小智功能的人,如果可以请点个小星星！","archived":false,"fork":false,"pushed_at":"2025-05-15T02:28:37.000Z","size":51082,"stargazers_count":1405,"open_issues_count":7,"forks_count":280,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-05-15T03:38:24.651Z","etag":null,"topics":["esp32","esp32-s3","xiaozhi-esp32"],"latest_commit_sha":null,"homepage":"https://huangjunsen0406.github.io/py-xiaozhi/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/huangjunsen0406.png","metadata":{"files":{"readme":"README.en.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-15T18:40:27.000Z","updated_at":"2025-05-15T03:34:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"5533ada4-3e57-44a1-aa66-53a6955f8cd3","html_url":"https://github.com/huangjunsen0406/py-xiaozhi","commit_stats":null,"previous_names":["huang-junsen/py-xiaozhi","junsenhuang/py-xiaozhi","huangjunsen0406/py-xiaozhi"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huangjunsen0406%2Fpy-xiaozhi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huangjunsen0406%2Fpy-xiaozhi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huangjunsen0406%2Fpy-xiaozhi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/huangjunsen0406%2Fpy-xiaozhi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/huangjunsen0406","download_url":"https://codeload.github.com/huangjunsen0406/py-xiaozhi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254301422,"owners_count":22047901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp32","esp32-s3","xiaozhi-esp32"],"created_at":"2025-03-30T05:03:19.701Z","updated_at":"2025-05-15T08:04:44.342Z","avatar_url":"https://github.com/huangjunsen0406.png","language":"Python","funding_links":[],"categories":["语音识别与合成_其他","📚 Projects (1974 total)","Python"],"sub_categories":["资源传输下载","MCP Servers"],"readme":"# py-xiaozhi\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/huangjunsen0406/py-xiaozhi/releases/latest\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/huangjunsen0406/py-xiaozhi?style=flat-square\u0026logo=github\u0026color=blue\" alt=\"Release\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-green.svg?style=flat-square\" alt=\"License: MIT\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/huangjunsen0406/py-xiaozhi/stargazers\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/huangjunsen0406/py-xiaozhi?style=flat-square\u0026logo=github\" alt=\"Stars\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/huangjunsen0406/py-xiaozhi/releases/latest\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/downloads/huangjunsen0406/py-xiaozhi/total?style=flat-square\u0026logo=github\u0026color=52c41a1\u0026maxAge=86400\" alt=\"Download\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://gitee.com/huang-jun-sen/py-xiaozhi\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Gitee-FF5722?style=flat-square\u0026logo=gitee\" alt=\"Gitee\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://huangjunsen0406.github.io/py-xiaozhi/guide/00_%E6%96%87%E6%A1%A3%E7%9B%AE%E5%BD%95.html\"\u003e\n    \u003cimg alt=\"Usage Docs\" src=\"https://img.shields.io/badge/Usage Docs-View-blue?labelColor=2d2d2d\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nEnglish | [简体中文](README.md)\n\n## Project Introduction\npy-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).\n\n## Demo\n- [Bilibili Demo Video](https://www.bilibili.com/video/BV1HmPjeSED2/#reply255921347937)\n\n![Image](./documents/docs/guide/images/系统界面.png)\n\n## Features\n- **AI Voice Interaction**: Supports voice input and recognition, enabling smart human-computer interaction with natural conversation flow.\n- **Visual Multimodal**: Supports image recognition and processing, providing multimodal interaction capabilities and image content understanding.\n- **IoT Device Integration**: \n  - Supports smart home device control including lights, volume, temperature sensors, etc.\n  - Integrates with Home Assistant smart home platform to control lights, switches, number controllers, and buttons\n  - Provides countdown timer functionality for delayed command execution\n  - Features built-in virtual devices and physical device drivers, easily extensible\n- **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.\n- **Voice Wake-up**: Supports wake word activation, eliminating manual operation (disabled by default, manual activation required).\n- **Auto Dialogue Mode**: Implements continuous dialogue experience, enhancing user interaction fluidity.\n- **Graphical Interface**: Provides intuitive GUI with Xiaozhi expressions and text display, enhancing visual experience.\n- **Command Line Mode**: Supports CLI operation, suitable for embedded devices or environments without GUI.\n- **Cross-platform Support**: Compatible with Windows 10+, macOS 10.15+, and Linux systems for use anywhere.\n- **Volume Control**: Supports volume adjustment to adapt to different environmental requirements with unified sound control interface.\n- **Session Management**: Effectively manages multi-turn dialogues to maintain interaction continuity.\n- **Encrypted Audio Transmission**: Supports WSS protocol to ensure audio data security and prevent information leakage.\n- **Automatic Verification Code Handling**: Automatically copies verification codes and opens browsers during first use, simplifying user operations.\n- **Automatic MAC Address Acquisition**: Avoids MAC address conflicts and improves connection stability.\n- **Modular Code**: Code is split and encapsulated into classes with clear responsibilities, facilitating secondary development.\n- **Stability Optimization**: Fixes multiple issues including reconnection and cross-platform compatibility.\n\n## System Requirements\n- Python version: 3.9 \u003e= version \u003c= 3.12\n- Supported operating systems: Windows 10+, macOS 10.15+, Linux\n- Microphone and speaker devices\n\n## Read This First!\n- Carefully read [项目文档](https://huangjunsen0406.github.io/py-xiaozhi/) for startup tutorials and file descriptions\n- The main branch has the latest code; manually reinstall pip dependencies after each update to ensure you have new dependencies\n\n[Zero to Xiaozhi Client (Video Tutorial)](https://www.bilibili.com/video/BV1dWQhYEEmq/?vd_source=2065ec11f7577e7107a55bbdc3d12fce)\n\n## Configuration System\nThe project uses a layered configuration system, including:\n\n1. **Basic Configuration**: Sets basic runtime parameters, located in `config/config.json`\n2. **Device Activation**: Device identity information, stored in `config/efuse.json`\n3. **Wake Word Settings**: Voice wake-up related configuration\n4. **IoT Devices**: Configuration for various IoT devices, including temperature sensors and Home Assistant integration\n\nFor detailed configuration instructions, please refer to [Configuration Documentation](./documents/docs/guide/02_配置说明.md)\n\n## IoT Functionality\npy-xiaozhi provides rich IoT device control features:\n\n- **Virtual Devices**: Light control, volume adjustment, countdown timers, etc.\n- **Physical Device Integration**: Temperature sensors, cameras, etc.\n- **Home Assistant Integration**: Connect to smart home systems via HTTP API\n- **Custom Device Extension**: Complete framework for device definition and registration\n\nFor supported device types and usage examples, please refer to [IoT Functionality Guide](./documents/docs/guide/05_IoT功能说明.md)\n\n## State Transition Diagram\n\n```\n                        +----------------+\n                        |                |\n                        v                |\n+------+  Wake/Button  +------------+   |   +------------+\n| IDLE | -----------\u003e | CONNECTING | --+-\u003e | LISTENING  |\n+------+              +------------+       +------------+\n   ^                                            |\n   |                                            | Voice Recognition Complete\n   |          +------------+                    v\n   +--------- |  SPEAKING  | \u003c-----------------+\n     Playback +------------+\n     Complete\n```\n\n## Upcoming Features\n- [ ] **New GUI (Electron)**: Provides a more modern and beautiful user interface, optimizing the interaction experience.\n\n## FAQ\n- **Can't find audio device**: Please check if your microphone and speakers are properly connected and enabled.\n- **Wake word not responding**: Check if the `USE_WAKE_WORD` setting in `config.json` is set to `true` and the model path is correct.\n- **Network connection failure**: Check network settings and firewall configuration to ensure WebSocket or MQTT communication is not blocked.\n- **Packaging failure**: Make sure PyInstaller is installed (`pip install pyinstaller`) and all dependencies are installed. Then re-execute `python scripts/build.py`\n- **IoT devices not responding**: Check if the corresponding device configuration information is correct, such as Home Assistant URL and Token.\n\n## Related Third-party Open Source Projects\n[Xiaozhi Mobile Client](https://github.com/TOM88812/xiaozhi-android-client)\n\n[xiaozhi-esp32-server (Open source server)](https://github.com/xinnan-tech/xiaozhi-esp32-server)\n\n[XiaoZhiAI_server32_Unity(Unity Development)](https://gitee.com/vw112266/XiaoZhiAI_server32_Unity)\n\n[IntelliConnect(Aiot Middleware)](https://github.com/ruanrongman/IntelliConnect)\n\n[open-xiaoai(Xiaoai Audio Access Xiaozhi)](https://github.com/idootop/open-xiaoai.git)\n\n\n## Project Structure\n\n```\n├── .github                 # GitHub related configurations\n├── assets                  # Resource files (emotion animations, etc.)\n├── cache                   # Cache directory (music and temporary files)\n├── config                  # Configuration directory\n├── documents               # Documentation directory\n├── hooks                   # PyInstaller hooks directory\n├── libs                    # Dependencies directory\n├── scripts                 # Utility scripts directory\n├── src                     # Source code directory\n│   ├── audio_codecs        # Audio encoding/decoding module\n│   ├── audio_processing    # Audio processing module\n│   ├── constants           # Constants definition\n│   ├── display             # Display interface module\n│   ├── iot                 # IoT device related module\n│   │   └── things          # Specific device implementation directory\n│   ├── network             # Network communication module\n│   ├── protocols           # Communication protocol module\n│   └── utils               # Utility classes module\n```\n\n## Contribution Guidelines\nWe welcome issue reports and code contributions. Please ensure you follow these specifications:\n\n1. Code style complies with PEP8 standards\n2. PR submissions include appropriate tests\n3. Update relevant documentation\n\n## Community and Support\n\n### Thanks to the Following Open Source Contributors\n\u003e In no particular order\n\n[Xiaoxia](https://github.com/78)\n[zhh827](https://github.com/zhh827)\n[SmartArduino-Li Honggang](https://github.com/SmartArduino)\n[HonestQiao](https://github.com/HonestQiao)\n[vonweller](https://github.com/vonweller)\n[Sun Weigong](https://space.bilibili.com/416954647)\n[isamu2025](https://github.com/isamu2025)\n[Rain120](https://github.com/Rain120)\n[kejily](https://github.com/kejily)\n[Radio bilibili Jun](https://space.bilibili.com/119751)\n\n### Sponsorship Support\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003eThanks to All Sponsors ❤️\u003c/h3\u003e\n  \u003cp\u003eWhether it's API resources, device compatibility testing, or financial support, every contribution makes the project more complete\u003c/p\u003e\n  \n  \u003ca href=\"https://huangjunsen0406.github.io/py-xiaozhi/sponsors/\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/View-Sponsors-brightgreen?style=for-the-badge\u0026logo=github\" alt=\"View Sponsors\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://huangjunsen0406.github.io/py-xiaozhi/sponsors/\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Become-Sponsor-orange?style=for-the-badge\u0026logo=heart\" alt=\"Become a Sponsor\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n## Project Statistics\n[![Star History Chart](https://api.star-history.com/svg?repos=huangjunsen0406/py-xiaozhi\u0026type=Date)](https://www.star-history.com/#huangjunsen0406/py-xiaozhi\u0026Date)\n\n## License\n[MIT License](LICENSE) ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuangjunsen0406%2Fpy-xiaozhi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhuangjunsen0406%2Fpy-xiaozhi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuangjunsen0406%2Fpy-xiaozhi/lists"}