{"id":25833594,"url":"https://github.com/huang-junsen/py-xiaozhi","last_synced_at":"2025-03-23T04:03:07.742Z","repository":{"id":278132057,"uuid":"933350408","full_name":"Huang-junsen/py-xiaozhi","owner":"Huang-junsen","description":"python版本的小智ai，主要帮助那些没有硬件却想体验小智功能的人","archived":false,"fork":false,"pushed_at":"2025-03-13T10:08:44.000Z","size":690,"stargazers_count":360,"open_issues_count":10,"forks_count":85,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-13T11:22:59.172Z","etag":null,"topics":["esp32","esp32-s3","xiaozhi-esp32"],"latest_commit_sha":null,"homepage":"","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/Huang-junsen.png","metadata":{"files":{"readme":"README.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}},"created_at":"2025-02-15T18:40:27.000Z","updated_at":"2025-03-13T11:02:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"5533ada4-3e57-44a1-aa66-53a6955f8cd3","html_url":"https://github.com/Huang-junsen/py-xiaozhi","commit_stats":null,"previous_names":["huang-junsen/py-xiaozhi"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Huang-junsen%2Fpy-xiaozhi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Huang-junsen%2Fpy-xiaozhi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Huang-junsen%2Fpy-xiaozhi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Huang-junsen%2Fpy-xiaozhi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Huang-junsen","download_url":"https://codeload.github.com/Huang-junsen/py-xiaozhi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245052671,"owners_count":20553172,"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-02-28T23:18:00.922Z","updated_at":"2025-03-23T04:03:07.716Z","avatar_url":"https://github.com/Huang-junsen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# py-xiaozhi\n\n\n## 项目简介\npy-xiaozhi 是一个使用 Python 实现的小智语音客户端，旨在通过代码学习和在没有硬件条件下体验 AI 小智的语音功能。\n本仓库是基于[xiaozhi-esp32](https://github.com/78/xiaozhi-esp32)移植\n\n## 请先看这里！\n- 仔细阅读/docs/使用文档.md 启动教程和文件说明都在里面了\n- main是最新代码，每次更新都需要手动重新安装一次pip依赖防止我新增依赖后你们本地没有\n\n## 有没有大佬可以加入的\n- 目前在树莓派b4、b5、jetson等设备运行有问题\n- mac的话 m1、m2等会出现找不到opuslib，目前有人提示说是python版本问题\n- 跪求大佬加入！！！\n\n[从零开始使用小智客户端（视频教程）](https://www.bilibili.com/video/BV1dWQhYEEmq/?vd_source=2065ec11f7577e7107a55bbdc3d12fce)\n\n\n## 环境要求\n- Python 3.9.13+（推荐 3.9.13）最大支持版本3.12\n- Windows/Linux/macOS\n\n## 相关分支\n- main 主分支\n- feature/v1 第一个版本\n- feature/visual 视觉分支\n\n\n## 相关第三方开源项目\n[小智手机端](https://github.com/TOM88812/xiaozhi-android-client)\n\n[xiaozhi-esp32-server（第三方服务端）](https://github.com/xinnan-tech/xiaozhi-esp32-server)\n\n\n## 演示\n- [Bilibili 演示视频](https://www.bilibili.com/video/BV1HmPjeSED2/#reply255921347937)\n\n![Image](https://github.com/user-attachments/assets/df8bd5d2-a8e6-4203-8084-46789fc8e9ad)\n## 功能特点\n- **语音交互**：支持语音输入与识别，实现智能人机交互。  \n- **图形化界面**：提供直观易用的 GUI，方便用户操作。  \n- **音量控制**：支持音量调节，适应不同环境需求。  \n- **会话管理**：有效管理多轮对话，保持交互的连续性。  \n- **加密音频传输**：保障音频数据的安全性，防止信息泄露。  \n- **CLI 模式**：支持命令行运行，适用于嵌入式设备或无 GUI 环境。  \n- **自动验证码处理**：首次使用时，程序自动复制验证码并打开浏览器，简化用户操作。  \n- **唤醒词**：支持语音唤醒，免去手动操作的烦恼。  \n- **键盘按键**：监听可以最小化视口\n\n## 状态流转图\n\n```\n                        +----------------+\n                        |                |\n                        v                |\n+------+  唤醒词/按钮  +------------+   |   +------------+\n| IDLE | -----------\u003e | CONNECTING | --+-\u003e | LISTENING  |\n+------+              +------------+       +------------+\n   ^                                            |\n   |                                            | 语音识别完成\n   |          +------------+                    v\n   +--------- |  SPEAKING  | \u003c-----------------+\n     完成播放 +------------+\n```\n\n## 项目结构\n\n```\n├── .github                          # GitHub 相关配置\n│   └── ISSUE_TEMPLATE               # Issue 模板目录\n│       ├── bug_report.md            # Bug 报告模板\n│       ├── code_improvement.md      # 代码改进建议模板\n│       ├── documentation_improvement.md  # 文档改进建议模板\n│       └── feature_request.md       # 功能请求模板\n├── config                           # 配置文件目录\n│   └── config.json                  # 应用程序配置文件\n├── docs                             # 文档目录\n│   ├── images                       # 文档图片资源\n│   │   ├── QQ音乐接口配置.png       # QQ音乐接口配置示例图\n│   │   ├── 唤醒词.png               # 唤醒词设置示例图\n│   │   └── 群聊.jpg                 # 社区交流群图片\n│   ├── 使用文档.md                  # 用户使用指南\n│   └── 异常汇总.md                  # 常见错误及解决方案\n├── libs                             # 依赖库目录\n│   └── windows                      # Windows 平台特定库\n│       └── opus.dll                 # Opus 音频编解码库\n├── scripts                          # 实用脚本目录\n│   ├── dir_tree.py                  # 生成目录树结构脚本\n│   └── py_audio_scanner.py          # 音频设备扫描工具\n├── src                              # 源代码目录\n│   ├── audio_codecs                 # 音频编解码模块\n│   │   └── audio_codec.py           # 音频编解码器实现\n│   ├── audio_processing             # 音频处理模块\n│   │   ├── vad_detector.py          # 语音活动检测实现（用于实时打断）\n│   │   └── wake_word_detect.py      # 语音唤醒词检测实现\n│   ├── constants                    # 常量定义\n│   │   └── constants.py             # 应用程序常量（状态、事件类型等）\n│   ├── display                      # 显示界面模块\n│   │   ├── base_display.py          # 显示界面基类\n│   │   ├── cli_display.py           # 命令行界面实现\n│   │   └── gui_display.py           # 图形用户界面实现\n│   ├── iot                          # IoT设备相关模块\n│   │   ├── things                   # 具体设备实现目录\n│   │   │   ├── CameraVL             # 摄像头与视觉识别模块\n│   │   │   │   ├── Camera.py        # 摄像头控制实现\n│   │   │   │   └── VL.py            # 视觉识别实现\n│   │   │   ├── lamp.py              # 智能灯具控制实现\n│   │   │   ├── music_player.py      # 音乐播放器实现\n│   │   │   └── speaker.py           # 智能音箱控制实现\n│   │   ├── thing.py                 # IoT设备基类定义\n│   │   └── thing_manager.py         # IoT设备管理器（统一管理各类设备）\n│   ├── protocols                    # 通信协议模块\n│   │   ├── mqtt_protocol.py         # MQTT 协议实现（用于设备通信）\n│   │   ├── protocol.py              # 协议基类\n│   │   └── websocket_protocol.py    # WebSocket 协议实现\n│   ├── utils                        # 工具类模块\n│   │   ├── config_manager.py        # 配置管理器（单例模式）\n│   │   ├── logging_config.py        # 日志配置\n│   │   ├── system_info.py           # 系统信息工具（处理 opus.dll 加载等）\n│   │   └── volume_controller.py     # 音量控制工具（跨平台音量调节）\n│   └── application.py               # 应用程序主类（核心业务逻辑）\n├── .gitignore                       # Git 忽略文件配置\n├── LICENSE                          # 项目许可证\n├── README.md                        # 项目说明文档\n├── main.py                          # 程序入口点\n├── requirements.txt                 # Python 依赖包列表（通用）\n├── requirements_mac.txt             # macOS 特定依赖包列表\n└── xiaozhi.spec                     # PyInstaller 打包配置文件\n```\n\n## 已实现功能\n\n- [x] **新增 GUI 页面**，无需在控制台一直按空格  \n- [x] **代码模块化**，拆分代码并封装为类，职责分明  \n- [x] **音量调节**，可手动调整音量大小  \n- [x] **自动获取 MAC 地址**，避免 MAC 地址冲突  \n- [x] **支持 WSS 协议**，提升安全性和兼容性  \n- [x] **GUI 新增小智表情与文本显示**，增强交互体验  \n- [x] **新增命令行操控方案**，适用于 Linux 嵌入式设备  \n- [x] **自动对话模式**，实现更自然的交互  \n- [x] **语音唤醒**，支持唤醒词激活交互 (默认关闭需要手动开启)\n- [x] **IoT 设备集成**，实现更多物联网功能  \n- [x] **联网音乐播放**\n- [x] **新增 Volume控制类统一声音改变**\n- [x] **新增 视觉多模态**\n\n## 优化\n\n- [x] 修复 **goodbye 后无法重连** 的问题  \n- [x] 解决 **macOS 和 Linux 运行异常**（原先使用 pycaw 处理音量导致）  \n- [x] **优化“按住说话”按钮**，使其更明显  \n- [x] **修复 Stream not open 错误**（目前 Windows 不再触发，其他系统待确认）  \n- [x] 修复 **没有找到该设备的版本信息，请正确配置 OTA 地址提示**\n- [x] 修复 **cli模式update_volume缺失问题**\n\n## 待实现功能\n\n- [ ] **新 GUI（Electron）**，提供更现代的用户界面\n\n## 贡献\n欢迎提交 Issues 和 Pull Requests！\n\n## 感谢以下开源人员-排名不分前后\n[Xiaoxia](https://github.com/78)\n\n[zhh827](https://github.com/zhh827)\n\n[四博智联-李洪刚](https://github.com/SmartArduino)\n\n[HonestQiao](https://github.com/HonestQiao)\n\n[vonweller](https://github.com/vonweller)\n\n[孙卫公](https://space.bilibili.com/416954647)\n\n[isamu2025](https://github.com/isamu2025)\n\n[Rain120](https://github.com/Rain120)\n\n[kejily](https://github.com/kejily)\n\n\n## Star History\n[![Star History Chart](https://api.star-history.com/svg?repos=Huang-junsen/py-xiaozhi\u0026type=Date)](https://www.star-history.com/#Huang-junsen/py-xiaozhi\u0026Date)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuang-junsen%2Fpy-xiaozhi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhuang-junsen%2Fpy-xiaozhi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhuang-junsen%2Fpy-xiaozhi/lists"}