KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #codex #claude-code #mcp #rust #deepseek-harness #typescript #ai-agent #cli

Fami32

★ 46 Open GitHub ↗

FamiTracker on ESP32

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Fami32

## Desktop port

Build the Linux version with Clang (SDL2 development files are required):

```sh
make linux
./build/linux/fami32
```

Cross-compile the Windows version with MinGW-w64. It uses Win32 GDI and
waveOut directly, so the generated executable does not need SDL:

```sh
make windows
```

Desktop songs, exports, samples, and `FM32CONF.CNF` are stored in
`./fami32_data` relative to the directory where Fami32 is launched.

Keyboard controls:

| Fami32 control | PC keyboard |
| --- | --- |
| Up / Down / L / R | Arrow keys |
| OK / Back | Enter / Escape |
| Menu / Navi | Tab / Home |
| S / P | Backspace / Space |
| Octave up / down | Page Up / Page Down |
| 16-key note pad | `Z S X D C V G B H N J M , L . ;` |

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` | 崩溃转储 |

## 第一次启动

1. 设备上电后初始化 OLED、键盘、Flash FAT 分区、USB MIDI 和音频任务。
2. 屏幕显示 Fami32 启动画面和版本信息。
3. 如果 `/flash/FM32CONF.CNF` 不存在，固件会创建默认配置并自动重启。
4. 启动完成后屏幕提示 `Press any key to continue...`，按任意实体键进入主界面。
5. 如果上一次发生 panic，启动时会进入崩溃信息页面，按任意实体键重启。

### 开机进入 USB MSC

上电后在启动检查阶段按住 `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

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` 会清空当前通道当前行。

### 主选项菜单 `OPTION`

在 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

Channel 页面是单通道详细 Pattern 编辑器，适合编辑乐器号、音量和效果列。顶部显示当前通道名称和编号，例如 `PULSE1 (CHAN0)`。

### 屏幕内容

- 当前通道名称和通道编号。
- 当前通道音量条。
- 当前行附近 9 行 Pattern 数据。
- 每行显示：行号、音符、乐器号、音量、效果列。
- 右侧显示当前通道的波形示波器。
- 静音时右侧显示 `MUTE`。
- 未启用的扩展效果列区域会显示棋盘纹理。

### Pattern 列格式

| 列 | 含义 |
| --- | --- |
| 音符 | `C-4`、`C#4` 等；Noise 通道显示噪声频率形式；`^^^` 为 cut；`~~~` 为 release/end；`...` 为空 |
| 乐器 | 两位十六进制乐器编号，空值为 `..` |
| 音量 | 一位十六进制音量，空值为 `.` |
| 效果 | `Fxx`、`Bxx` 等命令，空值为 `---` |

### 操作

| 操作 | 功能 |
| --- | --- |
| `OK` | 播放/停止；复制模式下完成复制 |
| `UP` / `DOWN` | 当前行上移/下移 |
| `L` / `R` | 非编辑模式切换通道；编辑模式切换当前编辑列 |
| `P` | 下一帧并向下移动一行 |
| `S` | 上一帧并向下移动一行 |
| `BACK` | 编辑模式下删除当前列内容；非编辑模式下打开通道选择菜单 |
| `MENU` | 一般打开主选项菜单；编辑效果命令列时打开效果帮助菜单 |
| `NAVI` | 打开主导航菜单 |
| `OCTU` / `OCTD` | 改变音符输入键盘八度 |

### 编辑列

进入编辑模式后，`L` / `R` 会在以下列之间循环：

1. 音符列。
2. 乐器号高 4 位。
3. 乐器号低 4 位。
4. 音量列。
5. 每个效果列的命令位、参数高 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

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` | 改变音符输入键盘八度 |
| 音符输入键 | 实时演奏当前通道 |

### Frame 操作菜单

按 `MENU` 打开当前 Frame 的操作菜单。

| 选项 | 作用 |
| --- | --- |
| `PUSH NEW` | 在末尾追加一个新 Frame |
| `INSERT NEW` | 在当前 Frame 位置插入新 Frame |
| `MOVE UP` | 当前 Frame 上移 |
| `MOVE DOWN` | 当前 Frame 下移 |
| `REMOVE` | 删除当前 Frame |

新 Frame 默认为 5 个通道都引用同一个新的 Pattern 编号。

## 页面四：Instrument

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 序列生成

`QUICK GEN.` 提供自动生成序列的流程菜单：

| 设置 | 说明 |
| --- | --- |
| `MODE` | 生成模式：`NORMAL`、`ARPEGGIO`、`RANDOM` |
| `STYLE` | Normal 模式选择内置数学包络；Arpeggio 模式选择和弦；Random 模式设置随机最大值 |
| `DIRECTION` | `FORWARD` 或 `REVERSE`，Random 模式不使用 |
| `LENGTH` | 生成长度 |
| `COUNT` | 每个生成值重复或采样的步数 |
| `OK!` | 确认生成 |

生成前会自动调整序列长度，然后写入数据。

## 页面五：DPCM Samples

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 音符映射编辑器

映射编辑器针对“当前乐器 + 当前样本”工作。顶部显示 `DPCM MAP Ixx Sxx`。

屏幕内容：

- 当前音符，例如 `C-0`。
- 当前音符绑定的样本号 `SMP`。
- 如果当前音符绑定的是正在编辑的样本，会显示 `*`。
- 当前音符的 `PITCH`、`LOOP`、`DELTA` 参数。
- 底部显示当前样本名称、字节数和简单波形/电平图。

### DPCM 映射操作

| 操作 | 功能 |
| --- | --- |
| `OK` | 当前音符未绑定该样本时绑定；已绑定时清除该音符映射 |
| `BACK` | 返回样本列表 |
| `MENU` | 打开当前音符的 DPCM 参数菜单 |
| `NAVI` | 打开主导航菜单并退出映射编辑器 |
| `L` / `R` | 当前音符向前/向后移动 1 个半音 |
| `UP` / `DOWN` | 当前音符向上/向下移动 1 个八度 |
| `P` / `S` | DPCM pitch 加/减，范围 `0-15` |
| 音符输入键 | 直接选择触摸输入对应的音符槽 |

### DPCM 参数菜单

| 选项 | 作用 |
| --- | --- |
| `PITCH` | 设置当前音符的 DPCM pitch，范围 `0-15` |
| `LOOP` | 设置是否循环，`0/1` |
| `DELTA` | 设置 Delta counter，范围 `-1` 到 `127`，`-1` 表示不指定 |
| `CLEAR NOTE` | 清除当前音符映射 |
| `CLEAR INST` | 清除当前乐器全部 96 个音符的 DPCM 映射 |

## 页面六：Info & Setting

主导航中的 `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

Oscilloscope 页面显示 5 个通道的实时波形，适合观察播放状态和静音状态。

### 屏幕内容

- 顶部布局与 Tracker 类似，显示行号列和 5 个通道缩写。
- 每个通道区域显示实时波形。
- 静音通道以斜线纹理覆盖。
- 顶部仍有每通道音量条和当前通道指示。

### 操作

同 [Tracker 操作](#操作)

## 页面八：Visualization

Visualization 页面显示每个通道的音高和音量历史轨迹，并在下方显示歌曲信息。

### 屏幕内容

- 每个通道维护一段历史缓冲区，以横线表现音量宽度，以位置表现音高。
- 通道标签为 `PU1`、`PU2`、`TRI`、`NOS`、`DMC`。
- 下方显示歌曲 `TITLE`、`AUTHOR`、`COPYRIGHT`。
- 右下角显示当前位置：`(当前行/Pattern长度>当前Frame)`。

### 操作

同 [Tracker 操作](#操作)

## 文件菜单与文件选择器

文件菜单在主选项菜单 `OPTION` 中选择 `FILE` 打开。

### 文件菜单

| 选项 | 作用 |
| --- | --- |
| `NEW` | 新建空白 `.ftm` 工程，停止播放并重载播放器 |
| `OPEN` | 从 `/flash` 选择并读取 `.ftm` 文件 |
| `SAVE` | 保存到当前文件；如果当前没有文件名，则进入另存为流程 |
| `SAVE AS` | 输入文件名并保存为 `/flash/<名称>.ftm` |
| `EXPORT VGM` | 把当前歌曲导出为 NES APU `.vgm` 文件 |

### 打开文件

`OPEN` 会调用文件选择器，从 `/flash` 开始浏览。选择文件后：

- 固件先检查 FTM 头部是否为 `FamiTracker Module`。
- 当前只支持 FTM 版本 `0x0440`。
- 支持 2A03、VRC6、VRC7、FDS、MMC5、N163 工程；其他扩展芯片暂不支持。
- 不支持多 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 RATE`
- `ENGINE SPEED`
- `LOW PASS`
- `HIGH PASS`

`VOLUME` 快速设置会立即保存。`FINETUNE`、`OVER SAMPLE` 等也会写入配置文件。

### 配置文件格式

配置文件路径为 `/flash/FM32CONF.CNF`，格式由 `micro_config` 生成，例如：

```text
# 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 模式

USB MSC 模式会把片内 FAT 分区作为 U 盘暴露给电脑，用于复制 `.ftm`、`.wav`、`.dmc`、`.dpcm` 等文件。

进入方式：

- 开机阶段按住 `BACK`。
- 或在主选项菜单中选择 `USB MSC MODE`。

进入后屏幕显示 `USB MSC MODE...` 和动画。按任意实体键退出，设备会显示 `REBOOT...` 并重启。

## USB MIDI

正常模式下设备作为 USB MIDI 设备工作。

### 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。

### MIDI 输出

在 `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 基础通道与已接入扩展芯片工程。

支持：

- FamiTracker Module 文件头。
- FTM 版本 `0x0440`。
- 5 个基础通道。
- VRC6、VRC7、FDS、MMC5、N163 扩展通道。
- INFO、HEADER、INSTRUMENTS、SEQUENCES、FRAMES、PATTERNS、DPCM SAMPLES 等块。
- N163 乐器波形、独立 N163 sequences 和 1-8 个 N163 通道数。
- DPCM 样本和乐器内 96 音符映射。

限制：

- 不支持 S5B 等其他扩展芯片工程。
- `EXPORT VGM` 当前仍面向 NES APU 导出，不包含扩展芯片音频。
- 不支持 Multi-track 工程。
- 打开失败或遇到不支持内容时会留在文件选择器，可继续选择；当前工程会回到新工程状态。
- DPCM 样本数量和单样本大小受设备内存与 FTM/DPCM 限制。

## 常用工作流

### 新建一首歌

1. 在任意主编辑页按 `MENU` 打开 `OPTION`。
2. 选择 `FILE` -> `NEW`。
3. 选择 `INFO & SETTING` 页面，编辑 `TITLE`、`AUTHOR`、`COPYRIGHT`、`TEMPO`、`SPEED`、`ROWS`。
4. 进入 `INSTRUMENT`，创建或命名乐器，按 `OK` 设置乐器序列。
5. 回到 `TRACKER` 或 `CHANNEL`，在 `OPTION` 中选择 `START EDIT`。
6. 选择通道和乐器，用音符输入键盘录入音符。
7. 用 `FRAMES` 页面组织 Pattern 顺序。
8. 用 `FILE` -> `SAVE AS` 保存为 `.ftm`。

### 编辑单通道效果

1. 进入 `CHANNEL` 页面。
2. 按 `MENU` -> `START EDIT` 开启编辑模式。
3. 用 `L` / `R` 移动到效果命令列。
4. 按 `MENU` 打开 `EFFECT HELP`，选择效果命令，或直接使用音符输入键盘输入效果命令。
5. 用 `R` 移到参数高/低位，用音符输入键输入十六进制参数。
6. 按 `OK` 播放检查效果。

### 导入并映射 DPCM 样本

1. 先通过 USB MSC 或其他方式把 `.wav`、`.dmc`、`.dpcm` 文件放入 `/flash`。
2. 进入 `DPCM SAMPLES` 页面。
3. 按 `MENU` -> `IMPORT`，从文件选择器选中样本文件。
4. 导入后按 `OK` 进入映射编辑器。
5. 用 `L` / `R` 或 `UP` / `DOWN` 选择音符，或用音符输入键直接选音符。
6. 按 `OK` 把当前样本绑定到该音符。
7. 按 `MENU` 调整 `PITCH`、`LOOP`、`DELTA`。
8. 在 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 | 文件使用了 N163、S5B 等尚未支持的扩展音源芯片 |
| 打开 `.ftm` 提示 multi-track not supported | 文件包含多 Track，当前不支持 |
| 设置采样率/滤波后自动重启 | 正常行为；这些设置需要重启生效 |
| USB MSC 退出后重启 | 正常行为；MSC 模式通过重启回到普通模式 |
| DPCM 导入失败 | 检查文件扩展名是否为 `.wav`、`.dmc` 或 `.dpcm`，以及文件是否过大或格式异常 |
| 屏幕显示 `FAMI32 CRASH!` | 上次发生 panic；记录异常原因/Backtrace 后按任意键重启 |

Fami32

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README