做音乐软件的人迟早要面对一个问题：怎么在前端 Electron 里做高性能的二进制文件解析和音频处理？
这篇文章记一下 GT Maker（gtmaker.cn）踩过的坑。Electron + Rust + TypeScript，吉他谱解析引擎从纯 JS 迁移到 Rust 后的性能提升和架构设计。
## 架构选择：为什么是 Electron + Rust
最初用纯 TypeScript 写的，解析 GP 文件够用，但批量导入几百首歌时卡得明显。JS 的单线程 + 无原生二进制操作，处理大文件时瓶颈明显。
选了 napi-rs 做桥接，Rust 负责核心计算，Electron 负责 UI。分工明确：
| 模块 | 职责 | 技术 |
|------|------|------|
| core | 格式解析 + 音频处理 | Rust |
| main | 进程管理 + 文件 IO | Electron (Node) |
| renderer | UI + 播放控制 | TypeScript + Web Audio |
## Rust 核心层设计
**统一格式解析层**
GP3 到 GP8 的格式差异很大。MusicXML 是 XML，alphaTex 是纯文本。没有选择每个格式各自适配，而是抽象了一层统一的音符模型：
```rust
// packages/core/src/models.rs
pub struct Note {
pub pitch: u8, // MIDI 音高
pub duration: f64, // 时值（拍）
pub velocity: u8, // 力度 0-127
pub track_id: u16, // 轨道号
pub string: Option<u8>, // 弦号
pub fret: Option<u8>, // 品位
}
pub struct Track {
pub name: String,
pub instrument: u8,
pub channel: u8,
pub notes: Vec<Note>,
}
pub struct Score {
pub title: String,
pub artist: String,
pub tempo: u32,
pub tracks: Vec<Track>,
pub measures: Vec<Measure>,
}
```
所有解析器（GP3/GP5/GP7/GP8/MusicXML/alphaTex）输出统一的 `Score` 结构，渲染层只认这个结构。加新格式只需写一个新解析器，不影响其他模块。
**GP 文件解析的坑**
GP3/GP5/GP7/GP8 是二进制格式，每个版本的差异比想象中大：
```rust
// packages/core/src/parsers/gp5.rs
pub fn parse_gp5(data: &[u8]) -> Result<Score> {
let mut cursor = Cursor::new(data);
// 版本标识（31 bytes）
let version = read_string(&mut cursor, 31)?;
// 标题信息（UTF-16 编码，GP5 开始）
let title = read_utf16_string(&mut cursor)?;
let artist = read_utf16_string(&mut cursor)?;
// 临时记号
let tempo = cursor.read_u32::<LittleEndian>()?;
// 轨道信息（GP5 支持最多 8 轨道）
let track_count = cursor.read_u8()?;
let mut tracks = Vec::new();
for _ in 0..track_count {
tracks.push(parse_track(&mut cursor)?);
}
// ... 后续解析音符数据
}
```
主要差异点：
| 差异 | GP3 | GP5 | GP7 | GP8 |
|------|-----|-----|-----|-----|
| 编码 | ASCII | UTF-16 | UTF-16 | UTF-16 |
| 轨道上限 | 4 | 8 | 64 | 64 |
| 音色系统 | MIDI Program | RSE + MIDI | RSE + MIDI | RSE + MIDI |
| 力度 | 固定 | 逐音符 | 逐音符 | 逐音符 |
| 图形符号 | 基础 | 丰富 | 最全 | 最全 |
## napi-rs 桥接
Rust 写好核心逻辑后，通过 napi-rs 暴露给 Node/Electron：
```rust
// packages/core/src/lib.rs
#[napi]
pub fn parse_score(file_path: String) -> Result<Score> {
let data = std::fs::read(&file_path)?;
let ext = Path::new(&file_path)
.extension()
.and_then(|e| e.to_str())
.unwrap_or("");
match ext {
"gp3" => parsers::gp3::parse_gp3(&data),
"gp5" => parsers::gp5::parse_gp5(&data),
"gp7" | "gp8" => parsers::gp7::parse_gp7(&data),
"musicxml" => parsers::musicxml::parse_musicxml(&data),
_ => Err("Unsupported format".into()),
}
}
#[napi]
pub fn tempo_shift(audio: Vec<f32>, ratio: f32) -> Vec<f32> {
// WSOLA + 相位声码器双引擎
audio_processor::tempo_shift(&audio, ratio)
}
```
TypeScript 端直接调用：
```typescript
// packages/renderer/src/audio/engine.ts
import { parseScore, tempoShift } from '@gtmaker/core';
export class AudioEngine {
async loadFile(path: string) {
const score = await parseScore(path);
this.tracks = score.tracks;
this.renderScore(score);
}
setTempo(ratio: number) {
this.playbackRate = ratio;
// Rust 端处理，不阻塞 UI
tempoShift(this.audioBuffer, ratio);
}
}
```
## 变速引擎：WSOLA + 相位声码器
变速播放是核心功能，要求：0.25x~3x 变速，音高不变，延迟低。
试了几个方案：
| 方案 | 优点 | 缺点 |
|------|------|------|
| SoundTouch | 成熟稳定 | 依赖大，配置复杂 |
| Rubber Band | 质量高 | 计算量大，实时性差 |
| WSOLA | 快，延迟低 | 瞬态处理差 |
| 相位声码器 | 音质好 | 实现复杂 |
最终选了双引擎：
```rust
pub fn tempo_shift(audio: &[f32], ratio: f32) -> Vec<f32> {
if ratio >= 0.8 {
// 高速：WSOLA，快
wsola_shift(audio, ratio)
} else {
// 低速：相位声码器，音质好
phase_vocoder_shift(audio, ratio)
}
}
```
## 批量导入优化
扫目录看起来简单，实际要考虑：
```typescript
// packages/renderer/src/import/scanner.ts
export async function scanDirectory(dir: string): Promise<ScoreMeta[]> {
const results: ScoreMeta[] = [];
// 异步递归扫描
const files = await fs.readdir(dir, { recursive: true });
for (const file of files) {
if (!SUPPORTED_FORMATS.includes(path.extname(file))) continue;
// 重复文件去重（基于内容 hash）
const hash = await fileHash(file);
if (seen.has(hash)) continue;
seen.add(hash);
// 推断歌手（从目录层级）
const artist = inferArtist(file, dir);
// 解析元数据（不加载完整音符）
const meta = await parseMetadata(file);
results.push({ ...meta, artist, path: file });
}
return results;
}
```
做了个缓存索引，第一次扫描慢点，后面秒开。用户反馈："几百首歌几分钟搞定，整理谱比我还勤快。"
## 练习模式设计
A-B 循环、变速、节拍器三件套。关键是让这三个功能可以同时工作：
```typescript
// packages/renderer/src/player/practice.ts
export class PracticeMode {
private abLoop: { start: number; end: number } | null = null;
private tempo: number = 1.0;
private metronome: Metronome;
setABLoop(start: number, end: number) {
this.abLoop = { start, end };
}
setTempo(ratio: number) {
this.tempo = ratio;
this.metronome.setTempo(this.baseTempo * ratio);
// Rust 端处理变速，不阻塞 UI
this.audioEngine.setTempo(ratio);
}
onTimeUpdate(time: number) {
// A-B 循环 + 变速 + 节拍器同时工作
if (this.abLoop && time >= this.abLoop.end) {
this.audioEngine.seek(this.abLoop.start);
}
}
}
```
## 性能对比
迁移到 Rust 后的性能提升：
| 操作 | 纯 TS | Rust | 提升 |
|------|-------|------|------|
| 解析 GP7 文件 | 420ms | 9ms | 47x |
| 批量导入 500 首 | 12s | 0.8s | 15x |
| 变速处理（1分钟音频） | 380ms | 12ms | 32x |
## 总结
Electron + Rust 的组合适合这种"重计算 + 重 UI"的场景。Rust 做核心计算，Electron 做界面，napi-rs 桥接，分工明确。
GT Maker 免费下载，弹吉他的朋友可以试试：gtmaker.cn
欢迎技术交流。