Xiaozhi Esp32 Music Wechat

小智开源音乐固件

（中文 | [English](READMEen.md) | [日本語](READMEja.md)）

视频

👉 【开源】虾哥ai小智机器音乐播放器纯固件带歌词显示

👉 【开源】虾哥小智音乐播放器纯固件

介绍

这是一个由虾哥开源的ESP32项目，以 MIT 许可证发布，允许任何人免费使用，或用于商业用途。

本项目基于 Maggotxy/xiaozhi-esp32-music 进行二次开发，新增了微信留言推送功能，并修复了 ML307 4G 网络下的兼容性问题。

开发时间: 2025年11月6日

我们希望通过这个项目，让大家的小智都能播放歌曲。

如果你有任何想法或建议，请随时提出 Issues 或加入 QQ 群：826072986

项目主要贡献者：空白泡泡糖果（B站UP），硅灵造物科技（B站UP）

音乐服务器提供者（为爱发电）：一撒

💡注意事项

1. 如果小智说找不到歌曲怎么办？

进入小智后台，找到对应设备，修改角色配置

• 选择 DeepSeekV3 大语言模型
• 在人物介绍中填入
• 收到音乐相关的需求时，只使用 MPC tool self.music.play_song 工具，同时禁止使用 search_music 功能。

2. 如何启用微信留言推送功能？

默认情况下，留言推送功能是关闭的。需要：

• 在 sdkconfig 中启用 CONFIG_ENABLE_MESSAGE_PUSHER=y
• 配置 WxPusher 的 AppToken 和 UID
• 详细配置步骤请参考 [微信留言推送配置](#微信留言推送配置) 章节

3. 暂不支持的开发板

• ESP32C3芯片的开发板

项目改动范围

新增

• main\boards\common\music.h
• main\boards\common\esp32_music.cc
• main\boards\common\esp32_music.h
• main\message_pusher.cc
• main\message_pusher.h

修改

• main\mcp_server.cc
• main\boards\common\board.cc
• main\boards\common\board.h
• main\application.cc
• main\application.h
• main\display\display.cc
• main\display\display.h
• main\audio\audio_service.cc
• main\audio\audio_service.h
• main\idf_component.yml

基于 MCP 控制万物

小智 AI 聊天机器人作为一个语音交互入口，利用 Qwen / DeepSeek 等大模型的 AI 能力，通过 MCP 协议实现多端控制。

已实现功能

• 🎭 丰富的角色定制系统：支持台湾女友、土豆子、English Tutor 等多种预设角色
• 🎨 个性化配置：自定义助手昵称、对话语言、角色音色和性格介绍
• 🎵 智能音乐控制：支持 self.music.play_song 工具进行音乐播放控制
• 💬 微信留言推送：支持 self.message.send_to_wechat 工具，通过语音指令发送留言到微信
• 📡 Wi-Fi / ML307 Cat.1 4G 网络连接
• 🗣️ 离线语音唤醒 ESP-SR
• 🔗 支持两种通信协议（[Websocket](docs/websocket.md) 或 MQTT+UDP）
• 🎧 采用 OPUS 音频编解码
• 🤖 基于流式 ASR + LLM + TTS 架构的语音交互
• 👤 声纹识别，识别当前说话人的身份 3D Speaker
• 📺 OLED / LCD 显示屏，支持表情显示
• 🔋 电量显示与电源管理
• 🌍 支持多语言（中文、英文、日文）
• 💻 支持 ESP32-C3、ESP32-S3、ESP32-P4 芯片平台
• 🏠 通过设备端 MCP 实现设备控制（音量、灯光、电机、GPIO 等）
• ☁️ 通过云端 MCP 扩展大模型能力（智能家居控制、PC桌面操作、知识搜索、邮件收发等）

硬件

面包板手工制作实践

详见飞书文档教程：

👉 《小智 AI 聊天机器人百科全书》

面包板效果图如下：

支持 70 多个开源硬件（仅展示部分）

• 立创·实战派 ESP32-S3 开发板
• 乐鑫 ESP32-S3-BOX3
• M5Stack CoreS3
• M5Stack AtomS3R + Echo Base
• 神奇按钮 2.4
• 微雪电子 ESP32-S3-Touch-AMOLED-1.8
• LILYGO T-Circle-S3
• 虾哥 Mini C3
• 璀璨·AI 吊坠
• 无名科技 Nologo-星智-1.54TFT
• SenseCAP Watcher
• ESP-HI 超低成本机器狗

软件

固件烧录

新手第一次操作建议先不要搭建开发环境，直接使用免开发环境烧录的固件。

固件默认接入 xiaozhi.me 官方服务器，个人用户注册账号可以免费使用 Qwen 实时模型。

👉 新手烧录固件教程

开发环境

• Cursor 或 VSCode
• 安装 ESP-IDF 插件，选择 SDK 版本 5.4 或以上
• Linux 比 Windows 更好，编译速度快，也免去驱动问题的困扰
• 本项目使用 Google C++ 代码风格，提交代码时请确保符合规范

开发者文档

• [自定义开发板指南](main/boards/README.md) - 学习如何为小智 AI 创建自定义开发板
• [MCP 协议物联网控制用法说明](docs/mcp-usage.md) - 了解如何通过 MCP 协议控制物联网设备
• [MCP 协议交互流程](docs/mcp-protocol.md) - 设备端 MCP 协议的实现方式
• [一份详细的 WebSocket 通信协议文档](docs/websocket.md)

大模型配置

如果你已经拥有一个的小智 AI 聊天机器人设备，并且已接入官方服务器，可以登录 xiaozhi.me 控制台进行配置。

🎭 角色配置指南

在 xiaozhi.me 控制台中，您可以：

1. 选择角色模板：从台湾女友、土豆子、English Tutor、好奇小男孩、汪汪队队长等预设角色中选择
2. 设置助手昵称：为您的 AI 伴侣起一个专属的名字（默认：小智）
3. 配置对话语言：支持普通话、英语、日语等多种语言
4. 选择角色音色：清澈小何等多种音色可供选择
5. 自定义角色介绍：详细描述角色的性格特点和背景设定

💡 特别功能：收到音乐相关需求时，小智会优先使用 self.music.play_song 工具，确保音乐播放体验的流畅性。

👉 后台操作视频教程（旧版界面）

微信留言推送配置

小智支持通过语音指令发送留言到微信，使用 WxPusher 消息推送服务实现。

📱 配置步骤

1. 注册 WxPusher 账号

• 访问 WxPusher 官网
• 使用微信扫码注册并登录

1. 创建应用并获取 AppToken

• 在控制台创建新应用
• 复制应用的 AppToken

1. 获取用户 UID

• 在"我的"页面找到您的 UID
• 或使用微信关注"WxPusher"公众号后，在对话中获取 UID

1. 修改配置文件

• 打开项目根目录下的 sdkconfig 文件
• 找到以下配置项并修改：

`` # CONFIG_ENABLE_MESSAGE_PUSHER is not set ` 修改为： ` CONFIG_ENABLE_MESSAGE_PUSHER=y CONFIG_MESSAGE_PUSHER_APP_TOKEN="你的AppToken" CONFIG_MESSAGE_PUSHER_UID="你的UID" ``

• 或者使用 idf.py menuconfig 命令，在 Xiaozhi Assistant 菜单中配置

🎯 使用方法

配置完成后，您可以通过以下语音指令使用留言功能：

"给小杰说，今天晚上不回家了"
"留言我在公司加班"
"告诉小明我想你了"
"跟妈妈说，我会晚点回去"

小智会自动识别留言意图，提取留言内容，并通过微信推送到配置的账号。

🔧 技术特性

• ✅ 支持 WiFi 和 ML307 4G 网络
• ✅ 自动 URL 编码，支持中文内容
• ✅ 基于 MCP 协议的 self.message.send_to_wechat 工具
• ✅ 实时推送，秒级送达

相关开源项目

🎵 音乐服务器

• xiaojieyahuhu/MeowEmbeddedMusicServer - Meow 为嵌入式设备制作的音乐串流服务
• 🎵 在线听音乐，支持多个音乐源（酷我、网易云、咪咕、百度等）
• 📱 为嵌入式设备提供音乐串流服务
• 📚 管理音乐库，智能缓存机制
• 🔍 搜索和缓存音乐
• ⬇️ 支持通过 url=true 参数直接下载音频文件
• 🎼 自动获取歌词和封面
• 💾 基于 Go 语言开发，性能优异
• 使用示例：

``` # 搜索并获取音乐信息 http://localhost:2233/stream_pcm?song=歌曲名&artist=歌手名

# 直接下载音频文件（适用于4G网络） http://localhost:2233/stream_pcm?song=歌曲名&artist=歌手名&url=true ```

小智服务器

在个人电脑上部署服务器，可以参考以下第三方开源的项目：

• xinnan-tech/xiaozhi-esp32-server Python 服务器
• joey-zhou/xiaozhi-esp32-server-java Java 服务器
• AnimeAIChat/xiaozhi-server-go Golang 服务器

使用小智通信协议的第三方客户端项目：

• huangjunsen0406/py-xiaozhi Python 客户端
• TOM88812/xiaozhi-android-client Android 客户端
• 100askTeam/xiaozhi-linux 百问科技提供的 Linux 客户端
• 78/xiaozhi-sf32 思澈科技的蓝牙芯片固件
• QuecPython/solution-xiaozhiAI 移远提供的 QuecPython 固件

贡献者

感谢以下所有为本项目做出贡献的开发者！

主要贡献者

小杰呀呼呼

项目维护者

Maggotxy

原始音乐功能开发者

空白泡泡糖果

B站UP主 · 核心开发

硅灵造物科技

B站UP主 · 核心开发

特别鸣谢

• 一撒 - 音乐服务器提供者（为爱发电）🎵
• 虾哥 (@78) - xiaozhi-esp32 原始项目作者

所有代码贡献者

[](https://github.com/xiaojieyahuhu/xiaozhi-esp32-music/graphs/contributors)

---

💖 如果这个项目对你有帮助，欢迎 Star ⭐ 支持一下！

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: xiaojie-yahu
• Source: xiaojie-yahu/xiaozhi-esp32-music-wechat
• License: MIT

Install and usage instructions live in the source repository linked above.