音乐与音频库

本文引用的文件

modmusic.c
modmusictunes.c
modcodec.c
modxunfeiAI.c
audio.rst
musicbox.rst
audio_play.py
PlayMusic.py

产品概述

本模块面向K12创客教育与嵌入式音频应用，提供三类能力：

music模块（兼容micro:bit）：基于MCPWM输出方波驱动蜂鸣器或简易扬声器，支持音符序列、内置曲库、节拍控制等。
audio模块（ESP32）：基于音频编解码与I2S/Codec的播放与录音能力，支持本地/网络MP3/WAV播放、音量控制、录音到WAV、以及讯飞在线TTS/IAT相关接口。
讯飞语音听写（IAT）：通过WebSocket与HTTP方式对接讯飞开放平台，实现语音转文字与文本转语音。

适用场景包括：课堂互动音效、简单乐器、语音交互原型、离线/在线语音识别与合成等。

核心业务流程

音乐播放流程（music）
- 初始化内部状态与PWM资源
- 解析音符字符串或内置曲目常量
- 按BPM与拍号计算时值，异步逐音播放
- 支持循环、等待完成、停止
音频播放/录音流程（audio）
- 初始化播放器/录音器
- 播放本地或网络音频（MP3/WAV），查询状态，控制暂停/恢复/停止
- 录音为WAV文件，读取响度，释放资源
讯飞IAT/TTS流程
- 配置鉴权参数（app_id/api_key/api_secret）
- WebSocket建立连接并发送音频流（IAT）
- 调用在线服务返回识别结果；TTS将文本转为语音并播放

sequenceDiagram
participant App as "用户程序"
participant Music as "music模块"
participant PWM as "MCPWM硬件"
App->>Music : play(音符列表/内置曲名, wait, loop)
Music->>Music : 解析音符/设置节拍
Music->>PWM : 设置频率/占空比
PWM-->>Music : 播放完成回调
Music-->>App : 完成/继续下一音

图表来源

modmusic.c:46-54
modmusic.c:92-148
modmusic.c:163-273

章节来源

modmusic.c:46-54
modmusic.c:92-148
modmusic.c:163-273

功能模块清单

music模块（兼容micro:bit）
- 播放音符/曲谱：play(tune, pin=16, wait=True, loop=False)
- 播放指定频率音调：pitch(frequency, duration=-1, pin=16, wait=True)
- 停止播放：stop(pin=None)
- 节拍控制：set_tempo(ticks=4, bpm=120)、get_tempo()
- 重置：reset()
- 内置曲库常量：DADADADUM、ENTERTAINER、PRELUDE、ODE、NYAN、RINGTONE、FUNK、BLUES、BIRTHDAY、WEDDING、FUNERAL、PUNCHLINE、PYTHON、BADDY、CHASE、BA_DING、WAWAWAWAA、JUMP_UP、JUMP_DOWN、POWER_UP、POWER_DOWN、GE_CHANG_ZU_GUO、DONG_FANG_HONG、CAI_YUN_ZHUI_YUE、ZOU_JIN_XIN_SHI_DAI、MO_LI_HUA、YI_MENG_SHAN_XIAO_DIAO
audio模块（ESP32）
- 播放：player_init()、play(url)、pause()/resume()/stop()、set_volume(vol)、player_status()、player_deinit()
- 录音：recorder_init()、record(file_name, record_time=5)、loudness()、recorder_deinit()
- 讯飞在线TTS：xunfei_tts_config(config)、xunfei_tts(text)
- 讯飞在线IAT：xunfei_iat_config(config)、xunfei_iat_record(rec_time)、xunfei_iat()
讯飞语音听写（IAT）独立模块
- xunfeiAI.xunfei_iat_init(app_id, api_key, api_secret, text, language="zh_cn")
- xunfeiAI.xunfei_tts()
- xunfeiAI.xunfei_iat(url)

验收要点

music模块可播放单音与多音序列，支持循环与等待模式，能正确解析音符与时值。
audio模块可初始化并播放本地/网络音频，支持暂停/恢复/停止与音量调节；录音生成WAV并可读响度。
IAT/TTS需联网并在讯飞平台完成鉴权配置后，能成功发起请求并获取结果或播放语音。

章节来源

modmusic.c:275-456
modmusic.c:459-522
modmusictunes.c:44-237
modcodec.c:47-128
modcodec.c:131-183
modcodec.c:186-398
modxunfeiAI.c:126-223

数据与状态

music模块
- 运行时状态机：空闲/下一音/发音间隙，用于非阻塞播放与自动切音
- 节拍参数：BPM与每拍ticks，影响音符时长
- 音符解析：支持升降号、八度、时值后缀，默认中音区与四分音符
- 引脚管理：动态申请/释放MCPWM输出引脚，避免冲突
audio模块
- 播放器状态：运行/暂停/空闲，供status查询
- 录音参数：采样率、位深、声道数（WAV）
- 网络播放：URL解析、HTTP下载与解码缓冲
讯飞IAT/TTS
- 鉴权信息：app_id、api_key、api_secret
- 协议：WebSocket握手签名（HMAC-SHA256 + Base64）、时间戳、Host头
- 数据流：音频流上传（IAT）、文本下发（TTS）

flowchart TD
Start(["开始"]) --> Init["初始化music状态<br/>设置BPM/ticks"]
Init --> Parse{"输入是单音还是序列?"}
Parse --> |单音| PlayOne["设置频率/占空比"]
Parse --> |序列| LoopNotes["遍历音符列表"]
PlayOne --> Wait{"wait=True?"}
LoopNotes --> Wait
Wait --> |是| Block["等待播放完成"]
Wait --> |否| Return["立即返回"]
Block --> End(["结束"])
Return --> End

图表来源

modmusic.c:92-148
modmusic.c:163-273
modmusic.c:312-376

章节来源

modmusic.c:62-86
modmusic.c:92-148
modmusic.c:163-273
modcodec.c:47-128
modcodec.c:131-183
modxunfeiAI.c:62-75
modxunfeiAI.c:79-119

关键约束与边界

硬件与平台
- music模块使用ESP32 MCPWM输出，默认引脚16，需确保GPIO有效且未被占用
- audio模块依赖I2S与Codec（如ES8388），需在无DAC构建时传入I2C对象进行初始化
- ESP32-S3固件未包含modcodec与modxunfeiAI，audio与IAT能力以ESP32为主
音频格式与大小
- 播放支持wav/mp3；本地大文件受文件系统与RAM限制，建议小体积音频
- 录音为WAV（8kHz、16bit、单声道），时长受存储容量限制
网络与服务
- 网络播放需先连接WiFi
- 讯飞IAT/TTS需联网并完成鉴权配置；IAT最长约60秒
并发与阻塞
- music.play支持wait/loop控制阻塞行为；pitch支持duration延时停止
- 音频播放状态可通过player_status查询，避免重复操作

最佳实践

使用music.play(..., wait=False)在需要与其他任务并行时使用
播放结束后调用stop或等待自然结束，避免引脚占用
网络播放前检查WiFi连接与URL有效性
讯飞API使用前务必配置鉴权参数，并确保网络可达

章节来源

modmusic.c:312-376
modcodec.c:47-66
modcodec.c:76-128
audio.rst:32-78
audio.rst:83-113
modxunfeiAI.c:126-201

附录：示例与参考路径

音乐盒示例（按键切换内置曲目）
- 参考：musicbox.rst
音频播放示例（本地/网络MP3）
- 参考：audio_play.py
蜂鸣器播放旋律示例
- 参考：PlayMusic.py