171 lines
5.4 KiB
Markdown
171 lines
5.4 KiB
Markdown
# 🎹 MIDI Editor - 网页端歌声 MIDI 编辑器
|
||
|
||
[English](README.md) | [简体中文](README_CN.md)
|
||
|
||
一个功能完整的网页端歌声 MIDI 文件编辑器。支持实时拖拽调整 MIDI 音符、歌词编辑、音频波形对齐，以及导入导出含歌词的 MIDI 文件。
|
||
|
||
  
|
||
|
||
## ✨ 功能特性
|
||
|
||
### 🎼 钢琴卷帘编辑
|
||
|
||
- **可视化音符编辑**：支持 C1-C8 全音域显示，直观的钢琴键布局
|
||
- **拖拽操作**：
|
||
- 移动音符：拖拽音符块调整位置和音高
|
||
- 调整音头：拖拽音符左边缘调整开始时间
|
||
- 调整音尾：拖拽音符右边缘调整结束时间
|
||
- **快捷音高调整**：
|
||
- Command/Ctrl + 上/下键调整选中音符的音高
|
||
- 通过功能区的移调功能来整体移动音高
|
||
- **双击添加**：在钢琴卷帘空白处双击快速添加新音符
|
||
- **钢琴键试听**：点击左侧钢琴键可试听对应音高
|
||
|
||
### 🔍 缩放与导航
|
||
|
||
- **水平缩放**
|
||
- **垂直缩放**
|
||
- **动态精度**：缩放越大，音符调整的 snap 粒度越精细（最小 0.01 秒）
|
||
- **自动滚动**：播放时播放头自动保持可见
|
||
|
||
### 📝 歌词编辑
|
||
|
||
- **实时编辑**：右侧列表直接编辑每个音符的歌词
|
||
- **批量填充**：输入一段歌词，按字顺序自动填充到音符
|
||
- **从选中开始**：批量填充可从当前选中的音符开始
|
||
- **精确调整**：可直接编辑 PITCH（音高）、START（开始时间）、END（结束时间）
|
||
- **确认机制**：修改数值后按 Enter 或点击 ✓ 确认，避免误操作
|
||
|
||
### 🎵 音频对齐
|
||
|
||
- **波形显示**：导入音频后显示波形，与 MIDI 同步滚动
|
||
- **格式支持**：MP3、WAV、OGG、FLAC、M4A、AAC
|
||
- **同步播放**：音频与 MIDI 同步播放，可分别调整音量大小
|
||
- **点击定位**：点击波形或时间尺可快速定位播放位置
|
||
|
||
### ⚠️ 重叠检测
|
||
|
||
- **可视化标注**：时间重叠的音符显示为红色并闪烁
|
||
- **一键修复**：点击消除重叠按钮自动修复所有重叠
|
||
|
||
### 📥 导入导出
|
||
|
||
- **MIDI 导入**：支持标准 MIDI 文件，自动解析歌词元数据
|
||
- **MIDI 导出**：导出包含歌词信息的 MIDI 文件
|
||
|
||
### 🎨 界面特性
|
||
|
||
- **主题切换**：支持浅色/深色主题
|
||
- **响应式布局**：自适应窗口大小
|
||
- **SVG 网格**：跨浏览器兼容的网格渲染
|
||
- **状态提示**：实时显示操作状态和错误信息
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Node.js 18+
|
||
- npm 或 yarn
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
|
||
# 启动开发服务器
|
||
npm run dev
|
||
|
||
# 在局域网启动
|
||
npm run dev -- --host 0.0.0.0
|
||
```
|
||
|
||
### 构建
|
||
|
||
```bash
|
||
# 构建生产版本
|
||
npm run build
|
||
|
||
# 预览构建结果
|
||
npm run preview
|
||
```
|
||
|
||
## 📖 使用指南
|
||
|
||
### 基本工作流
|
||
|
||
1. **导入 MIDI**：点击导入 MIDI 按钮选择 .mid 文件
|
||
2. **编辑音符**：在钢琴卷帘中拖拽调整音符位置和时长
|
||
3. **添加歌词**：在右侧列表中输入句级别的歌词或单字编辑
|
||
4. **对齐音频**（可选）：导入参考音频进行对照编辑
|
||
5. **导出文件**：点击导出含歌词 MIDI 保存文件
|
||
|
||
### 快捷操作
|
||
|
||
| 操作 | 说明 |
|
||
|------|------|
|
||
| 双击钢琴卷帘 | 添加新音符 |
|
||
| 双击音符 | 修改歌词 |
|
||
| 拖拽音符 | 移动音符位置/音高 |
|
||
| 拖拽音符边缘 | 调整音符时长 |
|
||
| Backspace / Delete | 删除选中音符 |
|
||
| Enter | 确认数值修改 |
|
||
| Escape | 取消数值修改 |
|
||
| Ctrl(Command) + 滚轮 | 水平缩放 |
|
||
| Ctrl(Command) + Shift(Option) + 滚轮 | 垂直缩放 |
|
||
|
||
### 播放控制
|
||
|
||
| 按钮 | 功能 |
|
||
|------|------|
|
||
| ⏮ | 回到开头 |
|
||
| ⏪ | 后退 2 秒 |
|
||
| ▶ / ⏸ | 播放 / 暂停 |
|
||
| ⏩ | 前进 2 秒 |
|
||
| ⏭ | 跳到结尾 |
|
||
| 选定区域 | 播放选定区域 |
|
||
|
||
## 🛠 技术栈
|
||
|
||
- **前端框架**：React 19 + TypeScript
|
||
- **构建工具**：Vite 7
|
||
- **状态管理**：Zustand
|
||
- **音频引擎**：Tone.js
|
||
- **波形显示**：WaveSurfer.js
|
||
- **MIDI 解析**：@tonejs/midi
|
||
- **样式**：CSS（自定义变量主题）
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
.
|
||
├── eslint.config.js
|
||
├── index.html
|
||
├── package.json
|
||
├── postcss.config.js
|
||
├── README.md
|
||
├── README_CN.md
|
||
├── tailwind.config.js
|
||
├── tsconfig.app.json
|
||
├── tsconfig.json
|
||
├── tsconfig.node.json
|
||
├── vite.config.ts
|
||
├── public/
|
||
└── src/
|
||
├── App.css # 主样式（含主题变量、布局、组件样式）
|
||
├── App.tsx # 主应用组件（走带、导入导出、移调等）
|
||
├── constants.ts # 常量定义（网格宽度、行高、音域范围）
|
||
├── i18n.ts # 国际化（中英文翻译、歌词智能分词器）
|
||
├── index.css # 全局样式（Tailwind、根字体、主题渐变）
|
||
├── main.tsx # React 入口
|
||
├── types.ts # 类型定义（NoteEvent、TimeSignature 等）
|
||
├── components/
|
||
│ ├── AudioTrack.tsx # 音频波形显示组件
|
||
│ ├── LyricTable.tsx # 歌词编辑表格组件
|
||
│ └── PianoRoll.tsx # 钢琴卷帘编辑器组件
|
||
├── lib/
|
||
│ └── midi.ts # MIDI 导入导出工具（含 UTF-8 歌词编解码）
|
||
└── store/
|
||
└── useMidiStore.ts # Zustand 状态管理
|
||
```
|