更新记录

1.0.0（2026-07-19）

首发：自研（SoundFont 引擎 自研 SoundFont/SF2 + MIDI 合成 + 内置 WAV 编解码 写 wav）编写软件合成器核心，经 原生绑定层 生成

平台兼容性

uni-app x(5.14)

nex-synth —— 原生 SoundFont 软件合成器

自研软件合成器核心（SoundFont/SF2 + MIDI 合成 + 内置 WAV 编解码），提供 uni-app 可调的 JS 对象 API。 仅支持 App 端（Android / iOS），H5 / 小程序加载不了原生库。自研、无额外系统依赖。

同一份 utssdk 插件同时支持 uni-app x（uvue） 与 经典 uni-app（vue3），无需分叉。 本插件是对象型（同 wordfilter 范式）：SoundFont 是有状态对象——用 .sf2 路径加载一次（解析音色库）， 之后反复渲染单音符 / 和弦 / 标准 MIDI 文件到 wav 文件（路径出，不把 PCM buffer 跨语言边界）。

你需要自备一个 .sf2 音色库

本插件是软件合成器，自身不含音色——你需要提供一个标准 SoundFont 2（.sf2）文件，例如：

• GeneralUser GS（约 30 MB，通用 GM 音色，免费）
• FluidR3_GM（约 140 MB，音质更佳，免费）

把 .sf2 随 App 资源打包或下载到本地，把其文件路径传给 new SoundFont(sf2Path) 即可。

⚠️ 延迟说明：这是离线软件合成（渲染到 wav 文件），不保证实时低延迟。用于「生成音频片段」场景 （音符/和弦/MIDI → wav），不适合做需要按键即响的实时演奏引擎。

API（对象型 + 路径出）

• 参数（均 number）：preset = MIDI 程序号 0..127（选音色，库里没有的合法程序号回退默认音色）； key = MIDI 音高 0..127（60 = 中央 C）；velocity = 力度 0..127；durationMs = 时长 1..300000。越界 → InvalidParam（不 panic）。
• keysJson：音高数组 JSON 字符串，形如 "[60,64,67]"（C 大三和弦）。空和弦 / 含越界 key / 超 128 音 / 非法 JSON → InvalidParam。
• 输出 wav：双声道 16-bit PCM，采样率 44100。SynthResult.sampleCount 为每声道帧数（≈ sampleRate × durationMs / 1000），durationMs 为实际时长。
• renderMidiFile：渲染至序列结束 + 释放尾巴，受时长硬上限（5 分钟）保护，避免畸形 MIDI 撑爆内存。

用法

import { SoundFont } from "@/uni_modules/nex-synth";

// 1. 用 .sf2 路径加载一次（App 首次用到时建好，复用这个实例）
const sf = new SoundFont("/sdcard/Android/data/<app>/files/GeneralUser.sf2");

// 2. 反复渲染
const r1 = sf.renderNote(0, 60, 100, 1000, "/.../note.wav");   // 钢琴中央 C，1 秒
console.log(r1.sampleCount);                                    // ≈ 44100

sf.renderChord(0, "[60,64,67]", 100, 2000, "/.../chord.wav");  // C 大三和弦，2 秒
sf.renderMidiFile("/.../song.mid", "/.../song.wav");           // 标准 MIDI 文件 → wav

console.log(sf.listPresets());                                  // [{"bank":0,"patch":0,"name":"..."}]
console.log(sf.sampleRate());                                   // 44100

错误以异常向 JS 透传，调用方应 try/catch：构造（坏 .sf2）、渲染（越界参数 / 坏 MIDI）都可能 throw。

平台与调试边界

• 仅 app-android / app-ios；H5、各家小程序不支持。
• Android 本地真机调试 原生库 需 HBuilderX ≥ 4.26（自定义调试基座），云打包不受此限。
• iOS 因 原生扩展库 含 Swift，宿主原生工程需开启「支持 Swift」。
• 最终 App 打包由 HBuilderX / @dcloudio CLI 完成。