掌上音乐盒 从 TF 卡到扬声器

你好，我是吴老师。

这份是给你自己读的——不用等我讲，你一段一段往下看，看到要动手的地方就真去动手。

这一课的重点不是"听懂"，是"做出来"。 你要亲手把一个只会响的板子，一步一步变成一台能放歌、能选歌、能调音量的音乐盒。

读完之后，你应该能：让板子放 TF 卡里的歌；给音乐盒加上"显示歌名、调音量、上一首下一首、随机播放"；说清一首歌是怎么从卡里跑到扬声器的。

用时：90 分钟（大部分时间在动手）。准备：板子、TF 卡（FAT32）、数据线、Skill 已接入的 WorkBuddy。

一、今天做一个"掌上音乐盒"

先看成品——这台音乐盒做完是这样用的：

屏幕上列着一排歌名
    ↓
手指点哪首     → 就放哪首
底部一排按钮   → 音量− / 上一首 / 播放暂停 / 下一首 / 音量+
播放时         → 顶部显示歌名 + 进度条，RGB 灯跟着音乐呼吸

先别急着做。第一步是把歌准备好。

第一步：把歌拷进 TF 卡

我给你准备了 5 首示例歌曲，都是用代码合成的，没有版权问题，随便用、随便改：

⬇ 点这里下载示例歌曲包（5 首，约 1.4 MB）

（格式：44.1kHz 立体声 16 位 MP3 —— 和板子的配置一致，拷进去就能放）

怎么放进去：把 TF 卡插到电脑（或读卡器），把这 5 个 .mp3 拷到卡的根目录， 拔下来插回板子。

为什么要自己准备歌，不能上网找？

网上的流行歌都是商业版权音乐——你能自己听，但不能交给别人、更不能放进公开的课程仓库。 所以我干脆用代码合成了一批：旋律就是一张"音符表"，你想改哪首就改哪首。

想自己造歌？看 assets/music/README.md——跑一个脚本就能生成， 用的是你第 11 课就学过的「旋律 = 一串频率 + 时长」。

准备好之后，回答一个问题（做的时候留意）：

一首歌是怎么从卡里跑到扬声器的？中间经过了几个地方？ （先猜一猜，第二节你就会看到答案。）

二、第一步：先让它能放歌

请使用课程的 esp32s3-touchboard-hardware-dev Skill，
烧录 assets/codes/demo01_play_song，让板子上电自动播放 TF 卡里的歌。
播放前先检查声卡（ES8311）和功放初始化方式。

烧进去之后，上电先别动，观察 30 秒，然后边玩边记：

能放歌了。恭喜——最难的一步已经过去了。

顺便搞清楚：这首歌是怎么跑到扬声器里的

现在回头看第一节那个问题。一首歌要走 4 步：

四步里有三步你早就学过了，只有第②步"解码"是新的。

为什么要"解码"？

因为 MP3 是"压缩"过的——体积可能只有原始声音的 1/10。

打个比方：一箱苹果要寄外地，直接寄又大又贵；聪明做法是榨成汁寄一小瓶，到了兑水还原。

• 卡里的 MP3 = "浓缩汁"（小）
• 解码 = "兑水还原"（还原成声音点）
• 还原后走 I2S 送到扬声器

⚠️ 但要说清楚：MP3 是有损压缩——压缩时把一部分声音信息直接扔掉了 （专挑人耳听不出来的扔：被大声音盖住的小声音、20kHz 以上的高频……）。 扔掉的部分是加不回来的，所以"还原"出来不等于和原版一模一样。 大多数情况下听不太出来，但反复压缩、或者用好音响听，就能听出差别。

三、第二步：把歌名显示出来

现在能放歌了，但你根本不知道在放哪首。

第二步：让屏幕上显示歌名。

别急着问 AI——先自己写一版提示词。

想一想，要让 AI 帮你做这件事，你得交代清楚哪几件事？ （比如：显示什么？显示在哪？用什么字体？歌名太长怎么办？）

在下面写一版：

写完了，再点开看看我写的版本——对比一下，你想漏了什么？

请在播放器上加：屏幕上显示当前歌曲的文件名（不要扩展名），
再加一个播放进度条。
用课程的中文字库，中英文都要能显示。

烧进去看看——看到歌名了吗？

这里有个小坑，提前告诉你：歌名太长会超出屏幕。 屏幕只有 240 像素宽，一个汉字 16 像素、一个字母 6 像素—— 算一算，一行最多放得下几个字？

所以程序里要把太长的名字截断，末尾加个"…"。 如果显示成一团乱或者跑到屏幕外，就是这个没处理。

做完这一步，你的音乐盒已经"看得见"了。

顺便说个"必须一直转"的东西

你可能在代码里看到一个奇怪的函数：audio.loop()，它在主循环里一遍一遍地转。

主循环里有一句 audio.loop()，每转一圈都要跑一次，一次都不能少。

为什么？ 因为一首歌几十 MB，板子内存装不下，不可能一次解完。 audio.loop() 每转一圈只解一小段、送一小段——边解码边播放。

就像水龙头：一边进水（解码）、一边出水（播放）， 而不是"先把缸接满、再倒出去"。

它一停，歌就卡住——传送带的电机不能停。

四、第三步：加上音量调节

歌在放了，名字也看到了。但声音太大/太小怎么办？——现在只能改代码重烧。

第三步：加上音量调节。

先自己写提示词。 这次要想的是：

• 用什么来调？（BOOT 键？屏幕上的按钮？两个都要？）
• 调大调小分几档？屏幕上要不要显示当前音量？
• 调完之后，歌是继续放还是重头开始？

在下面写一版，再点开对照：

请给播放器加上音量调节：用 BOOT 键或者屏幕上的按钮，
把音量调大/调小，屏幕上显示当前音量。

它背后其实只做了一件事：告诉声卡"现在音量调到几档"。

🔍 想一想：改音量的时候，歌会不会停一下？

你调音量时歌是继续放的——因为音量是"配置"， 走的是第 13 课学的 I2C，而声音数据在 I2S 上照常跑，两条路互不干扰。

这就是第 13 课那句"I2C 管事儿，I2S 送货"在真实作品里的样子。

五、第四步：加上"上一首 / 下一首 / 暂停"

一首放完了会自己跳下一首。但放到一半想换歌呢？

第四步：加上一排按钮。

先自己写。 这一步要交代的事情比较多，想一想：

• 要哪几个按钮？分别叫什么？
• 屏幕只有 240×320，按钮要多大才好点？（想想第 8 课：手指尖接触面积约 8~10 像素）
• 按钮排在哪？横排还是竖排？
• 点下去有没有反馈（变色）？

请在屏幕底部加一排按钮：音量−、上一首、播放暂停、下一首、音量+
（屏幕分辨率 240×320 竖屏，按钮要够大，手指点得准）。
手指点哪个就做哪个。

屏幕上点一下、歌就换——这就是第 8 课学的"按钮是判断出来的"： 程序判断你手指的坐标落在哪个按钮的格子里，就执行对应的动作。

做完这一步，它已经真的像一台音乐盒了。

六、第五步：加上"随机播放"（新增，不是替换）

现在是按顺序一首首放。想要随机呢？

⚠️ 注意这一步的要求：是新增一个模式，不是把原来的顺序播放换掉。

也就是说，做完之后你的音乐盒应该有两种模式： 顺序播放和随机播放，而且能在两种之间切换。

第五步：新增一个"播放模式"按钮。

先自己写。 这一步最容易写漏——想清楚两件事：

1. 是"加一个新功能"还是"把旧的换掉"？这两句话 AI 理解得完全不一样；
2. 随机挑的时候，会不会挑到正在放的这首？

请给播放器【新增】一个"播放模式"功能，不要改掉原来的顺序播放：
1. 在屏幕上加一个"模式"按钮，点一下在【顺序播放】和【随机播放】之间切换；
2. 按钮上要显示当前是哪一种模式（比如写"顺序"或"随机"）；
3. 顺序模式 = 原来那样往下放；
   随机模式 = 下一首随机挑，但别挑到正在放的那一首；
4. 其余功能（音量、上一首下一首、进度条）都不动。

做法：让程序多记一件事——"现在是什么模式"。

程序里新增一个标记：现在到底是【顺序】还是【随机】

选下一首的时候，看这个标记：
    如果是【随机】 → 随便挑一首（别挑到正在放的那首）
    如果是【顺序】 → 还按原来那样，往下走一首

"模式"按钮要做的，就是把那个标记翻个面（顺序 ↔ 随机）。

💡 注意你刚才做了什么： 你没有动"怎么把歌放出来"（解码、I2S、音量、进度条全没碰）， 只是多了两条"选哪首歌"的路。

这就是好代码的样子——一个功能一小块： "放歌"和"选歌"是两件独立的事，加新功能不用拆老功能。

七、你还能加什么

上面五步做完，你的音乐盒已经能听、能看、能点了。 下面这些都是你能自己加的（挑一个，照着同样的套路做）：

做任何一个之前，先问自己两个问题：

1. 这件事属于哪一小块？（选歌？显示？交互？）
2. 我能不能只改那一小块，别的不动？

这两个问题问顺了，你就能改任何程序。

八、故障排查：没声音怎么办

排查的顺序：先看屏幕上的提示（它在告诉你哪一步失败了），再看文件，最后才怀疑代码。

九、自检小测

先自己想，再点开对答案。

① 读文件   SD_MMC 把 MP3 文件读出来
② 解 码    解码库把它还原成声音点（PCM）
③ 送声音   audio.loop() 一小段一小段送进 I2S
④ 出 声    I2S → ES8311 声卡 → 扬声器

每一圈：
    loop() 里的解码       ← 每圈都做，一次不能少
    每隔 250 毫秒才画一次屏 ← 攒着做，几百圈才轮到一次

原来：下一首 = 当前这首 + 1
现在：下一首 = 随便挑一首

十、最后

这一课你亲手做出了一台音乐盒——从"能放歌"到"能点、能调、能随机"， 每一步都是你自己加上去的。

第 3 章（声音与存储）到这里就结束了。 从第 11 课的"让板子响一声"，到现在这台音乐盒，你已经会用： 扬声器、麦克风、I2S 总线、TF 卡、WAV、MP3——

下一章（第 17 课起），板子要出门上网了。