Fami32 是一套运行在 ESP32-S3 上的 FamiTracker 风格随身 Chiptune 制作固件。
本项目以 FamiTracker Module .ftm 为工程格式，支持 5 个 NES 基础通道：PULSE1、PULSE2、TRIANGLE、NOISE、DPCM。固件会把片内 FAT 分区挂载到 /flash，所有乐曲、配置、导出的 WAV、导入的 DPCM/WAV 样本都围绕这个分区工作。
- 播放、创建、编辑和保存 FamiTracker
.ftm文件。 - 5 通道 Pattern Tracker 编辑：音符、乐器号、音量、效果列。
- Frame 顺序表编辑：增删帧、移动帧、修改每个通道对应的 Pattern 编号。
- 乐器列表与 5 类序列编辑：音量、琶音、音高、高位音高、占空比。
- DPCM 样本导入、重命名、删除、音符映射和参数编辑。
- 音符输入键盘实时演奏，编辑模式下可直接录入音符。
- USB MIDI 输入与可选 MIDI 输出。
- USB MSC 模式，可把设备内
/flash分区作为 U 盘连接电脑管理文件。 - 可视化页面：多通道示波器和音高/音量历史显示。
- 崩溃信息屏幕与 core dump 支持。
源码配置目标为 esp32s3，默认使用 8 MB Flash 和自定义分区表。
关键外设和引脚在 main/include/hardware/fami32_pin.h 中定义：
| 模块 | 引脚 / 配置 |
|---|---|
| OLED | SSD1309/SSD1306 类 128x64 SPI 屏幕，SCL=17、SDA=16、DC=7、RESET=15、CS=6 |
| 音频输出 | PCM5102A I2S，BCK=42、WS=40、DIN=41 |
| 12 键矩阵键盘 | 行：47,18,45,46；列：38,39,48 |
| 音符输入键盘 | 两片 MPR121，I2C SDA=8、SCL=9，地址 0x5A、0x5B |
| USB | TinyUSB MIDI / MSC |
| Flash 分区 | flash FAT 分区挂载为 /flash |
partitions.csv 定义：
| 分区 | 类型 | 地址 | 大小 | 用途 |
|---|---|---|---|---|
app |
factory app | 0x10000 |
0x100000 |
固件程序 |
flash |
FAT data | 0x110000 |
0x6E0000 |
乐曲、配置、样本、导出 WAV |
coredump |
coredump | 0x7F0000 |
0x10000 |
崩溃转储 |
- 设备上电后初始化 OLED、键盘、Flash FAT 分区、USB MIDI 和音频任务。
- 屏幕显示 Fami32 启动画面和版本信息。
- 如果
/flash/FM32CONF.CNF不存在，固件会创建默认配置并自动重启。 - 启动完成后屏幕提示
Press any key to continue...，按任意实体键进入主界面。 - 如果上一次发生 panic，启动时会进入崩溃信息页面，按任意实体键重启。
上电后在启动检查阶段按住 BACK，固件会重启进入 USB MSC 模式。也可以在主选项菜单中选择 USB MSC MODE。
设备有两组输入：12 个实体功能键和 16 个音符/数值键。
| 键名 | 常见作用 |
|---|---|
OK |
播放/停止、确认菜单、执行当前动作、切换序列启用状态 |
BACK |
返回、取消、删除当前编辑项、退出子编辑器 |
MENU |
打开当前页面的选项菜单或功能菜单 |
NAVI |
打开主导航菜单；在序列编辑器内打开序列参数菜单 |
UP / DOWN |
上下移动行、菜单项、帧、样本、乐器等 |
L / R |
左右切换通道、编辑列、序列数据位置或页面 |
S / P |
上一帧/下一帧、数值减/加、Pattern 编号减/加、序列值减/加 |
OCTD / OCTU |
降低/升高音符输入键盘八度；在文字键盘中切换字符页 |
具体页面会复用这些键，下面各页面章节会说明差异。
16 个音符输入键在演奏和编辑中有两类用途：
- 音符输入：默认基于当前八度
g_octv输入半音阶音符；触摸按下发音，释放停止。 - 十六进制输入：在 Channel 编辑页的乐器号、音量、效果命令、效果参数列中，音符输入键输入
0-F。
音符输入键的当前八度由 OCTD / OCTU 改变。开启 MIDI OUT 后，触摸演奏也会发送 USB MIDI Note On / Note Off。
保存、另存为、重命名乐器、重命名样本、重命名文件等场景会进入屏幕键盘。
| 操作 | 说明 |
|---|---|
音符输入键 0-15 |
输入当前字符页中的 16 个字符 |
OCTU |
切到下一组字符 |
OCTD |
切到上一组字符 |
S |
删除最后一个字符 |
OK |
确认并退出文字键盘 |
字符表包含大写字母、小写字母、数字和常见符号。
按 NAVI 打开主导航菜单 MENU。菜单项如下：
| 菜单项 | 页面 |
|---|---|
TRACKER |
总览式 Pattern 编辑页 |
CHANNEL |
单通道详细 Pattern 编辑页 |
FRAMES |
Frame 顺序表编辑页 |
INSTRUMENT |
乐器列表和乐器序列编辑入口 |
DPCM SAMPLES |
DPCM 样本编辑器 |
INFO & SETTING |
歌曲信息和歌曲参数页面 |
OSCILLOSCOPE |
多通道示波器页面 |
VISUALIZATION |
音高/音量历史可视化页面 |
菜单内使用 UP / DOWN 移动，OK 进入，BACK 取消。
Tracker 是默认主页面，用于同时查看 5 个通道的当前 Pattern 内容。屏幕顶部显示行号列 R 和 5 个通道缩写：PU1、PU2、TRI、NOS、DMC。中间高亮行为当前播放/编辑行。
- 左侧显示当前行号。
- 每个通道显示音符和音量。
- 顶部每个通道下方有实时音量条。
- 被静音的通道顶部区域显示棋盘纹理。
- 当前选中的通道顶部显示
>。 - 编辑模式下当前通道标题区域反色。
- 复制模式下，被选中的复制范围会用棋盘纹理标记。
| 操作 | 功能 |
|---|---|
OK |
非复制模式下播放/停止；复制模式下完成复制范围选择 |
UP / DOWN |
当前行上移/下移 |
L / R |
切换当前通道 |
P |
跳到下一帧，并向下移动一行 |
S |
跳到上一帧，并向下移动一行 |
MENU |
打开主选项菜单 OPTION |
NAVI |
打开主导航菜单 |
BACK |
编辑模式下清空当前通道当前行；同时退出复制模式 |
OCTU / OCTD |
改变音符输入键盘八度 |
| 音符输入键 | 实时演奏；编辑模式下把音符写入当前通道当前行 |
在 OPTION 中选择 START EDIT 后进入编辑模式。此时触摸音符会写入当前通道当前行：
- 普通音符会写入音符、八度和当前乐器号。
- 如果当前未播放，写入后行号自动加 1。
BACK会清空当前通道当前行。
在 Tracker、Channel、Oscilloscope、Visualization 等页面按 MENU 可打开主选项菜单。
| 选项 | 作用 |
|---|---|
START EDIT / STOP EDIT |
开启或关闭 Pattern 编辑模式 |
MUTE / UNMUTE |
静音或取消静音当前通道 |
INSTRUMENT |
打开快速乐器选择菜单 |
CLIPBOARD |
打开复制/粘贴菜单 |
CHANNEL |
打开通道设置菜单 |
FILE |
打开文件菜单 |
SETTINGS |
打开系统/音频设置菜单 |
VOLUME |
快速调整主音量 |
USB MSC MODE |
重启进入 USB 大容量存储模式 |
REBOOT |
打开重启/崩溃测试菜单 |
选择 INSTRUMENT 后会列出全部乐器，格式为 编号-名称。用 UP / DOWN 选择，OK 确认。确认后当前乐器号 inst_sel_pos 会被更新。
选择 CLIPBOARD 后有两个选项：
| 选项 | 作用 |
|---|---|
COPY |
从当前行开始进入复制范围选择；移动到结束行后按 OK 完成复制 |
PASTE |
把剪贴板内容粘贴到当前行开始的位置，仅编辑模式下有效 |
复制/粘贴只作用于当前通道、当前 Frame 映射到的 Pattern。
Channel 页面是单通道详细 Pattern 编辑器，适合编辑乐器号、音量和效果列。顶部显示当前通道名称和编号，例如 PULSE1 (CHAN0)。
- 当前通道名称和通道编号。
- 当前通道音量条。
- 当前行附近 9 行 Pattern 数据。
- 每行显示：行号、音符、乐器号、音量、效果列。
- 右侧显示当前通道的波形示波器。
- 静音时右侧显示
MUTE。 - 未启用的扩展效果列区域会显示棋盘纹理。
| 列 | 含义 |
|---|---|
| 音符 | C-4、C#4 等；Noise 通道显示噪声频率形式；^^^ 为 cut；~~~ 为 release/end；... 为空 |
| 乐器 | 两位十六进制乐器编号，空值为 .. |
| 音量 | 一位十六进制音量，空值为 . |
| 效果 | Fxx、Bxx 等命令，空值为 --- |
| 操作 | 功能 |
|---|---|
OK |
播放/停止；复制模式下完成复制 |
UP / DOWN |
当前行上移/下移 |
L / R |
非编辑模式切换通道；编辑模式切换当前编辑列 |
P |
下一帧并向下移动一行 |
S |
上一帧并向下移动一行 |
BACK |
编辑模式下删除当前列内容；非编辑模式下打开通道选择菜单 |
MENU |
一般打开主选项菜单；编辑效果命令列时打开效果帮助菜单 |
NAVI |
打开主导航菜单 |
OCTU / OCTD |
改变音符输入键盘八度 |
进入编辑模式后，L / R 会在以下列之间循环：
- 音符列。
- 乐器号高 4 位。
- 乐器号低 4 位。
- 音量列。
- 每个效果列的命令位、参数高 4 位、参数低 4 位。
音符输入键的作用取决于当前列：
- 音符列：音符输入键输入音符并写入当前乐器号。
- 乐器号列：音符输入键输入十六进制半字节。
- 音量列：音符输入键输入
0-F音量。 - 效果命令列：音符输入键从快速效果表选择命令。
- 效果参数列：音符输入键输入十六进制半字节。
从主选项菜单选择 CHANNEL，或在 Channel 非编辑模式下按 BACK 进入相关菜单。
| 选项 | 作用 |
|---|---|
SELECT CHAN |
选择当前通道：PULSE1、PULSE2、TRIANGLE、NOISE、DPCM |
EXT EFX NUM |
设置当前通道额外效果列数量，范围 0-3 |
注意：实际显示/编辑的效果列数量为基础 1 列加上 EXT EFX NUM。
在编辑模式下，当光标位于效果命令列时按 MENU 打开 EFFECT HELP，选择后会把对应效果命令写入当前效果列。
| 效果 | 含义 |
|---|---|
Fxx |
设置 Speed 或 Tempo；<0x20 设置 Speed，>=0x20 设置 Tempo |
Bxx |
跳转到第 xx 个 Frame |
Dxx |
跳到下一 Frame 的第 xx 行 |
Cxx |
停止歌曲 |
3xx |
自动滑音，xx 为速度 |
0xy |
琶音，x 为第二音，y 为第三音 |
4xy |
Vibrato，x 为速度，y 为深度 |
7xy |
Tremolo，x 为速度，y 为深度 |
Pxx |
以APU period为单位微调音高，范围为 xx - 80 |
Gxx |
行延迟，x 为 tick 数 |
Zxx |
设置 DMC 通道电平值 |
1xx |
上滑音，xx 为速度 |
2xx |
下滑音，xx 为速度 |
V0x |
设置 Duty / 模式，x 为模式值 |
Yxx |
设置 DMC Offset |
Qxy |
Portamento Up，x 为速度，y 为上移音程 |
Rxy |
Portamento Down，x 为速度，y 为下移音程 |
Axy |
音量滑动，x 上升，y 下降 |
Sxx |
延迟切音，x 为 tick 数 |
W0x |
设置 DMC pitch |
Frames 页面编辑歌曲播放顺序表。每个 Frame 包含 5 个通道各自引用的 Pattern 编号。
- 顶部显示
FRAMES (当前帧/最后帧)。 - 左侧显示当前帧附近的 Frame 列表。
- 每行格式为：Frame 编号 + 5 个通道的 Pattern 编号。
- 当前通道对应的 Pattern 编号会被反色标记。
- 右侧显示当前通道当前 Pattern 的 9 行简略预览。
| 操作 | 功能 |
|---|---|
OK |
播放/停止 |
UP / DOWN |
跳到上一帧/下一帧，并向下移动一行 |
L / R |
切换当前通道 |
P |
当前 Frame 的当前通道 Pattern 编号加 1 |
S |
当前 Frame 的当前通道 Pattern 编号减 1 |
MENU |
打开 Frame 操作菜单 |
NAVI |
打开主导航菜单 |
OCTU / OCTD |
改变音符输入键盘八度 |
| 音符输入键 | 实时演奏当前通道 |
按 MENU 打开当前 Frame 的操作菜单。
| 选项 | 作用 |
|---|---|
PUSH NEW |
在末尾追加一个新 Frame |
INSERT NEW |
在当前 Frame 位置插入新 Frame |
MOVE UP |
当前 Frame 上移 |
MOVE DOWN |
当前 Frame 下移 |
REMOVE |
删除当前 Frame |
新 Frame 默认为 5 个通道都引用同一个新的 Pattern 编号。
Instrument 页面管理乐器列表，并进入乐器序列编辑器。
- 顶部显示
INSTRUMENT (当前乐器/最后乐器)。 - 列表显示乐器编号和名称，名称过长会截断。
- 右侧 5 个小图标表示该乐器的 5 类序列启用状态。
- 底部显示当前通道正在使用的乐器名称。
- 底部音高/样本位置指示线会随当前通道播放状态变化。
| 操作 | 功能 |
|---|---|
OK |
进入当前乐器的序列编辑器 |
UP / DOWN |
选择上一个/下一个乐器，循环滚动 |
L / R |
切换当前通道 |
MENU |
打开乐器操作菜单 |
NAVI |
打开主导航菜单 |
OCTU / OCTD |
改变音符输入键盘八度 |
| 音符输入键 | 实时演奏当前通道 |
按 MENU 打开 INSTRUMENT 菜单。
| 选项 | 作用 |
|---|---|
NEW |
新建乐器 |
RENAME |
用文字键盘重命名当前乐器 |
RAND NAME |
从内置随机名称列表给当前乐器命名 |
REMOVE |
删除当前乐器；如果删空，会自动创建一个新乐器 |
在乐器列表按 OK 进入当前乐器的序列编辑器。Fami32 支持 5 类序列：
| 序列 | 作用 |
|---|---|
VOLUME |
音量包络，值通常为 0-15 |
ARPEGGIO |
琶音序列 |
PITCH |
音高偏移序列 |
HI-PITCH |
高位音高偏移序列 |
DUTY |
占空比/波形模式序列，值通常为 0-3 |
屏幕顶部显示乐器名和当前序列图标。如果序列未启用，图标区域会反色。中间以条形/点线方式显示序列数据，底部显示 Loop 和 Release 区间。
| 操作 | 功能 |
|---|---|
OK |
启用/停用当前序列；如果序列不存在，会创建长度为 1 的序列 |
BACK |
返回乐器列表 |
MENU |
选择要编辑的序列类型 |
NAVI |
打开序列参数菜单 |
L / R |
选择上一个/下一个序列数据位置 |
P |
当前序列值加 1 |
S |
当前序列值减 1 |
UP / DOWN |
调整图形显示基准线，便于查看正负值 |
OCTU / OCTD |
改变音符输入键盘八度 |
| 音符输入键 | 实时演奏当前通道 |
在序列编辑器按 NAVI 打开 SEQUENCE 菜单。
| 选项 | 作用 |
|---|---|
LENGTH |
设置当前序列长度，范围 1-255 |
LOOP |
设置循环点，范围 -1 到 长度-1，-1 表示不循环 |
RELEASE |
设置释放点，范围 -1 到 长度-1，-1 表示无释放点 |
SEQU INDEX |
修改乐器引用的序列编号，范围 0-255 |
QUICK GEN. |
快速生成序列数据 |
QUICK GEN. 提供自动生成序列的流程菜单：
| 设置 | 说明 |
|---|---|
MODE |
生成模式：NORMAL、ARPEGGIO、RANDOM |
STYLE |
Normal 模式选择内置数学包络；Arpeggio 模式选择和弦；Random 模式设置随机最大值 |
DIRECTION |
FORWARD 或 REVERSE，Random 模式不使用 |
LENGTH |
生成长度 |
COUNT |
每个生成值重复或采样的步数 |
OK! |
确认生成 |
生成前会自动调整序列长度，然后写入数据。
DPCM Samples 页面管理 DPCM 样本表，并把样本映射到当前乐器的 96 个音符槽。
- 顶部显示
SAMPLE EDITOR和当前样本编号。 - 如果没有样本，显示
NO DPCM SAMPLE和支持格式提示。 - 样本列表显示编号、名称和较长名称样本的字节数。
- 底部提示
OK MAP Ixx MENU EDIT，其中Ixx是当前乐器编号。
| 格式 | 行为 |
|---|---|
.dmc / .dpcm |
直接读取为 DPCM 数据，超过最大长度会截断 |
.wav |
读取 WAV，混合多声道，重采样到 33144 Hz后编码成 DPCM |
限制：
- 最多 64 个 DPCM 样本。
- 单个样本最大约
0x0FF1字节。 - 样本长度会按 FTM/DPCM 需要做对齐填充。
| 操作 | 功能 |
|---|---|
OK |
进入当前样本的音符映射编辑器 |
UP / DOWN |
选择上一个/下一个样本 |
L / R |
切换当前通道 |
MENU |
打开样本操作菜单 |
BACK |
返回上层调用页面 |
NAVI |
打开主导航菜单 |
OCTU / OCTD |
改变音符输入键盘八度 |
| 音符输入键 | 实时演奏当前通道 |
按 MENU 打开 DPCM SAMPLE 菜单。
| 选项 | 作用 |
|---|---|
IMPORT |
从 /flash 文件选择器中选择 .wav、.dmc 或 .dpcm 导入 |
RENAME |
重命名当前样本 |
REMOVE |
删除当前样本，并同步修正所有乐器的样本引用 |
ASSIGN |
进入当前样本的音符映射编辑器 |
映射编辑器针对“当前乐器 + 当前样本”工作。顶部显示 DPCM MAP Ixx Sxx。
屏幕内容：
- 当前音符，例如
C-0。 - 当前音符绑定的样本号
SMP。 - 如果当前音符绑定的是正在编辑的样本，会显示
*。 - 当前音符的
PITCH、LOOP、DELTA参数。 - 底部显示当前样本名称、字节数和简单波形/电平图。
| 操作 | 功能 |
|---|---|
OK |
当前音符未绑定该样本时绑定；已绑定时清除该音符映射 |
BACK |
返回样本列表 |
MENU |
打开当前音符的 DPCM 参数菜单 |
NAVI |
打开主导航菜单并退出映射编辑器 |
L / R |
当前音符向前/向后移动 1 个半音 |
UP / DOWN |
当前音符向上/向下移动 1 个八度 |
P / S |
DPCM pitch 加/减，范围 0-15 |
| 音符输入键 | 直接选择触摸输入对应的音符槽 |
| 选项 | 作用 |
|---|---|
PITCH |
设置当前音符的 DPCM pitch，范围 0-15 |
LOOP |
设置是否循环，0/1 |
DELTA |
设置 Delta counter，范围 -1 到 127，-1 表示不指定 |
CLEAR NOTE |
清除当前音符映射 |
CLEAR INST |
清除当前乐器全部 96 个音符的 DPCM 映射 |
主导航中的 INFO & SETTING 实际进入歌曲信息与歌曲参数页面。系统/音频设置在主选项菜单的 SETTINGS 中。
默认页面标题为 SONG INFO，包含：
| 字段 | 说明 |
|---|---|
TITLE |
歌曲标题 |
AUTHOR |
作者 |
COPYRIGHT |
版权信息 |
按 L 或 R 切换到 SONG SETTING 页面，包含：
| 字段 | 范围 | 说明 |
|---|---|---|
TEMPO |
32-255 |
歌曲 Tempo |
SPEED |
1-31 |
歌曲 Speed |
ROWS |
1-256 |
Pattern 行数 |
修改 ROWS 时，固件会停止播放、把播放行归零，并重设所有通道所有 Pattern 的长度。
| 操作 | 功能 |
|---|---|
UP / DOWN |
选择字段；可选择到无字段状态 |
L / R |
在 SONG INFO 和 SONG SETTING 间切换 |
OK |
编辑选中字段；文本字段进入文字键盘，数值字段进入数值设置框 |
NAVI |
打开主导航菜单 |
| 音符输入键 | 实时演奏当前通道 |
Oscilloscope 页面显示 5 个通道的实时波形，适合观察播放状态和静音状态。
- 顶部布局与 Tracker 类似，显示行号列和 5 个通道缩写。
- 每个通道区域显示实时波形。
- 静音通道以斜线纹理覆盖。
- 顶部仍有每通道音量条和当前通道指示。
Visualization 页面显示每个通道的音高和音量历史轨迹，并在下方显示歌曲信息。
- 每个通道维护一段历史缓冲区，以横线表现音量宽度，以位置表现音高。
- 通道标签为
PU1、PU2、TRI、NOS、DMC。 - 下方显示歌曲
TITLE、AUTHOR、COPYRIGHT。 - 右下角显示当前位置：
(当前行/Pattern长度>当前Frame)。
文件菜单在主选项菜单 OPTION 中选择 FILE 打开。
| 选项 | 作用 |
|---|---|
NEW |
新建空白 .ftm 工程，停止播放并重载播放器 |
OPEN |
从 /flash 选择并读取 .ftm 文件 |
SAVE |
保存到当前文件；如果当前没有文件名，则进入另存为流程 |
SAVE AS |
输入文件名并保存为 /flash/<名称>.ftm |
EXPORT VGM |
把当前歌曲导出为 NES APU .vgm 文件 |
OPEN 会调用文件选择器，从 /flash 开始浏览。选择文件后：
- 固件先检查 FTM 头部是否为
FamiTracker Module。 - 当前只支持 FTM 版本
0x0440。 - 不支持扩展芯片工程。
- 不支持多 Track 工程。
- 读取成功后会重载播放器。
如果失败，会显示错误弹窗并回到新工程状态。
SAVE：如果当前工程来自某个文件，覆盖保存；如果没有当前文件，提示输入名称并保存为.ftm。SAVE AS：使用当前文件名去掉扩展名作为默认名称，输入新名称后保存。- 保存路径固定为
/flash/<名称>.ftm。
文件选择器标题为 FILE SELECTOR/MANAGER。
| 操作 | 功能 |
|---|---|
UP / DOWN |
移动文件/目录选择光标 |
OK |
进入目录或选择文件 |
BACK |
返回上级目录；在起始目录 /flash 时取消选择 |
MENU |
打开文件选项菜单 |
文件选项菜单：
| 选项 | 作用 |
|---|---|
RENAME |
重命名当前文件或目录项 |
DELETE |
删除当前文件或目录项 |
目录会以名称末尾 / 标记。
在主选项菜单 OPTION 中选择 SETTINGS 打开系统设置菜单。
| 选项 | 范围 / 选项 | 说明 |
|---|---|---|
SAMPLE RATE |
10800-192000，步进 6000 |
音频采样率 |
ENGINE SPEED |
1-240 |
音频/播放器引擎速度参数 |
LOW PASS |
1000 到 SAMP_RATE/2 |
低通滤波截止频率 |
HIGH PASS |
0-1000，步进 10 |
高通滤波截止频率 |
FINETUNE |
400-500 |
基准频率，默认围绕 440 Hz |
OVER SAMPLE |
1-8 |
过采样倍率 |
VOLUME |
0-64 |
主音量，播放缓冲会按该值缩放 |
MIDI OUT |
OFF / ON |
是否把触摸演奏发送为 USB MIDI |
DEBUG PRINT |
OFF / ON |
是否输出调试日志 |
RESET CONFIG |
NO / YES |
删除配置文件并重启 |
退出设置菜单后会写入 /flash/FM32CONF.CNF。以下设置修改后会标记需要重启，固件会显示提示并自动重启：
SAMPLE RATEENGINE SPEEDLOW PASSHIGH PASS
VOLUME 快速设置会立即保存。FINETUNE、OVER SAMPLE 等也会写入配置文件。
配置文件路径为 /flash/FM32CONF.CNF，格式由 micro_config 生成，例如：
# micro_config generated file
# format: key = <type>:<value>
# types : i=int, f=float, s=string
SAMPLE_RATE = i:96000
ENGINE_SPEED = i:60
LPF_CUTOFF = i:18000
HPF_CUTOFF = i:32
BASE_FREQ_HZ = i:440
OVER_SAMPLE = i:4
VOLUME = i:16
USB MSC 模式会把片内 FAT 分区作为 U 盘暴露给电脑，用于复制 .ftm、.wav、.dmc、.dpcm 等文件。
进入方式：
- 开机阶段按住
BACK。 - 或在主选项菜单中选择
USB MSC MODE。
进入后屏幕显示 USB MSC MODE... 和动画。按任意实体键退出，设备会显示 REBOOT... 并重启。
正常模式下设备作为 USB MIDI 设备工作。
源码处理的 MIDI 输入行为：
| MIDI 事件 | 行为 |
|---|---|
| Note On | 切换到 MIDI 通道对应的 Fami32 通道，使用当前乐器发音；编辑模式下把音符写入当前行 |
| Note Off | 当前通道停止发音；播放中编辑模式下可写入 Note End |
CC 0x20 |
设置当前乐器编号；如果超出乐器数，会夹到最后一个乐器 |
CC 0x7B |
All Notes Off，切断对应通道声音 |
| Pitch Bend | 改变 BASE_FREQ_HZ 作为实时微调 |
| 其他事件 | 切断当前通道并打印未知事件日志 |
MIDI 通道会用于选择 Fami32 的 channel_sel_pos，实际通道范围会落在 0-4。
在 SETTINGS 中把 MIDI OUT 设置为 ON 后，音符输入键盘演奏会发送：
- Note On：力度
120。 - Note Off：释放时发送。
- MIDI 通道使用当前 Fami32 通道编号。
如果上次重启原因是 panic，启动时会显示 FAMI32 CRASH! 页面。页面内容包括：
- 崩溃任务名。
- PC 地址。
- EXCVADDR。
- 异常原因名称。
- Backtrace 地址列表。
- App ELF SHA 与 Fami32 版本字符串。
按任意实体键后设备显示 REBOOT... 并重启。
主选项菜单的 REBOOT 会进入重启菜单：
| 选项 | 作用 |
|---|---|
NORMAL |
正常软件重启 |
StoreProhibit |
人为触发 StoreProhibited 崩溃，用于测试崩溃页面 |
LoadProhibit |
人为触发 LoadProhibited 崩溃，用于测试崩溃页面 |
当前 FTM 读写实现面向基础 NES 5 通道工程。
支持：
- FamiTracker Module 文件头。
- FTM 版本
0x0440。 - 5 个基础通道。
- INFO、HEADER、INSTRUMENTS、SEQUENCES、FRAMES、PATTERNS、DPCM SAMPLES 等块。
- DPCM 样本和乐器内 96 音符映射。
限制：
- 不支持扩展芯片工程。
- 不支持 Multi-track 工程。
- 打开失败或遇到不支持内容时会回到新工程状态。
- DPCM 样本数量和单样本大小受设备内存与 FTM/DPCM 限制。
- 在任意主编辑页按
MENU打开OPTION。 - 选择
FILE->NEW。 - 选择
INFO & SETTING页面，编辑TITLE、AUTHOR、COPYRIGHT、TEMPO、SPEED、ROWS。 - 进入
INSTRUMENT，创建或命名乐器，按OK设置乐器序列。 - 回到
TRACKER或CHANNEL，在OPTION中选择START EDIT。 - 选择通道和乐器，用音符输入键盘录入音符。
- 用
FRAMES页面组织 Pattern 顺序。 - 用
FILE->SAVE AS保存为.ftm。
- 进入
CHANNEL页面。 - 按
MENU->START EDIT开启编辑模式。 - 用
L/R移动到效果命令列。 - 按
MENU打开EFFECT HELP，选择效果命令，或直接使用音符输入键盘输入效果命令。 - 用
R移到参数高/低位，用音符输入键输入十六进制参数。 - 按
OK播放检查效果。
- 先通过 USB MSC 或其他方式把
.wav、.dmc、.dpcm文件放入/flash。 - 进入
DPCM SAMPLES页面。 - 按
MENU->IMPORT，从文件选择器选中样本文件。 - 导入后按
OK进入映射编辑器。 - 用
L/R或UP/DOWN选择音符，或用音符输入键直接选音符。 - 按
OK把当前样本绑定到该音符。 - 按
MENU调整PITCH、LOOP、DELTA。 - 在 Pattern 中使用 DPCM 通道和对应音符触发样本。
| 路径 | 内容 |
|---|---|
main/src/app |
启动流程、任务创建、启动路由、崩溃检查、版本信息 |
main/src/gui |
所有页面、菜单、输入法和触摸音符处理 |
main/src/core |
Fami32 播放器、通道合成、乐器序列处理 |
main/src/audio |
DPCM 编码/解码、波表、频率换算、音频配置 |
main/src/storage |
FTM 文件读写、Frame/Pattern/Instrument/Sequence/DPCM 数据结构 |
main/src/input |
12 键矩阵键盘、MPR121 音符输入键盘、触摸事件队列 |
main/src/usb |
TinyUSB 初始化、USB MSC 模式、预留 UAC 模式 |
components/USBMIDI |
USB MIDI 封装 |
components/gfx_ssd1306 |
OLED 显示封装 |
components/arduino-esp32-lite |
精简 Arduino ESP32 兼容层 |
| 现象 | 处理 |
|---|---|
| 首次启动后自动重启 | 正常行为；固件在创建默认配置文件 |
打开 .ftm 提示 unsupported version |
当前只支持 FTM 0x0440 |
打开 .ftm 提示 ext-chip not supported |
文件使用了扩展音源芯片，当前不支持 |
打开 .ftm 提示 multi-track not supported |
文件包含多 Track，当前不支持 |
| 设置采样率/滤波后自动重启 | 正常行为；这些设置需要重启生效 |
| USB MSC 退出后重启 | 正常行为；MSC 模式通过重启回到普通模式 |
| DPCM 导入失败 | 检查文件扩展名是否为 .wav、.dmc 或 .dpcm，以及文件是否过大或格式异常 |
屏幕显示 FAMI32 CRASH! |
上次发生 panic；记录异常原因/Backtrace 后按任意键重启 |