当我把K10做成音乐播放器，再加入小智后是这样！

一、项目简介

我想让行空板 K10 不只是播放一段固定音频，而是成为一台可以显示封面、切换电台，并能通过语音点播 TF 卡歌曲的小播放器。于是手动封装了一个netAudio的积木库，实现功能的复用。

这个项目由两部分组成：netAudio 负责网络音频、TF 卡 MP3、电台和播放器界面；小智 MCP 负责理解用户的点播意图，并调用 K10 上的控制工具。比如说“看看卡里有什么歌”，设备返回当前 TF 卡歌单；说“播放第三首”，设备就按列表序号播放。

项目使用 Mind+ V2 和行空板 K10。歌曲名单来自 TF 卡扫描结果，不需要在程序中逐首手填。

二、功能特性

TF 卡歌曲播放：扫描 /mp3 目录中的 MP3、WAV，生成带序号的播放列表，支持指定歌曲、上一曲、下一曲和自动续播。
网络电台：提供内置电台列表，支持按序号点播和切换电台。
小智语音控制：通过一个 net_audio MCP 工具查询歌曲或电台列表，再按序号执行点播；也支持调音量和重新扫描歌单。
播放器界面：显示歌曲信息、内嵌封面、进度、音量和频谱。没有封面时使用耳机占位图。
横竖屏皮肤：可从 TF 卡加载对应方向的 BMP 皮肤。屏幕方向在初始化时确定，修改方向后需要重新启动程序。

小智调用的是同一个工具，而不是为“查询歌曲”“播放第 N 首”“切换电台”各做一个孤立接口。例如，查询歌单使用 action=songs，点播歌曲使用 action=play_song 和 index=3。列表从 1 开始编号，查询结果支持分页，适合逐页发送给小智。

三、硬件与准备

项目	用途
行空板 K10	运行程序、显示界面、播放音频
TF 卡	存放歌曲和可选的界面皮肤
esp32-s3 AI Camera	烧录“小智”，我改名为“美惠”了！！

把歌曲放入 TF 卡的 /mp3 目录。若要使用自定义皮肤，可把 mp3skin-portrait.bmp 和 mp3skin-landscape.bmp 放在 TF 卡根目录；播放器会根据屏幕方向选择。

四、积木封装与小智交互

netAudio 的积木保持通用：扫描 TF 卡歌曲、获取歌曲列表、获取电台列表、按序号播放、设置音量、显示播放器界面都可以单独用于普通 Mind+ 项目。小智只是调用这些能力的一种方式。

netAudio 封装积木：

程序启动时完成屏幕、TF 卡、播放器和网络初始化，然后扫描 /mp3。MCP 侧只注册一个 net_audio 工具，由 action 决定操作：

`action`	作用
`songs` / `radios`	分页获取歌曲或电台列表
`play_song` / `play_radio`	根据 `index` 按序号播放
`next_song` / `next_radio`	切换下一首或下一台
`volume`	设置音量
`rescan`	重新扫描 TF 卡歌单

一个典型的交互过程是：用户问“小智，卡里有什么歌？”→ 小智查询歌曲列表 → 用户说“播放第三首”→ 小智提交序号 3 → K10 开始播放。这样，更换 TF 卡内容后只需重新扫描，不必修改歌曲名称对应的积木逻辑。

五、调试实录

这个项目最费时间的地方，其实不是让声音“响起来”，而是让声音、语音识别和界面同时稳定运行。

早期版本在识别命令或按键切歌后出现过重启。排查后发现，语音识别和播放会同时使用 K10 的音频资源：歌曲直接切到 44.1/48 kHz 输出时，会干扰识别侧使用的时钟；在按键回调里直接执行切歌，也增加了并发冲突。现在把按键和识别结果先记为待处理指令，由主循环统一执行；启用语音识别时，播放输出也按其音频时钟要求处理。

另一个明显问题是卡顿。K10 的音频 DMA 缓冲时间很短，如果解码时直接等待网络数据或整屏刷新，就可能听到断续。netAudio 把拉流、解码和界面绘制分开，用环形缓冲吸收网络及 TF 卡读取的波动；封面解析也放在后台。项目记录中的一次实机测试里，横屏底部频谱相邻帧约 134 ms，单帧绘制平均约 8 ms。这些是该测试条件下的结果，实际表现仍会受歌曲、皮肤和网络影响。

界面也经历了多次返工：横屏没有真正切换、文字遮住控件、出现两条进度条、封面加载后频谱消失。最终按屏幕实际宽高布局，将动态文字、进度和频谱分区绘制；横屏皮肤的频谱固定在底部，避免压住人物图片和歌曲信息。