#MIDI 乐器、Sampler 与序列器 PRO

MIDI 乐器支持音符开关、控制器、程序/音色库、弯音、声道/复音压力、SysEx、UMP 和原生样本时间排期。发送即时设备 MIDI 前先启动引擎。参数地址和主机时钟用十进制字符串保持精度；定时 MIDI 的 AUEventSampleTimeImmediate 为 -4294967296。线缆编号和消息边界会校验；UMP 使用 Uint32Array 字，不应与字节互换。能否实际渲染某协议/消息取决于插件。

MIDI 命令的 Promise 完成表示已提交给原生接口，不表示远程插件已经渲染出结果。进程外 MIDI 处理器可能异步处理事件，其 MIDI 时钟未必随快速离线渲染的音频图推进；用于离线导出前，应验证所选插件的实际输出。不要假设紧接着的一次渲染必然包含刚提交的事件。实时 MIDI 路由应使用设备渲染的音频图。

AVAudioUnitSampler 可加载音频文件、SoundFont/DLS 或原生乐器。普通采样文件遵循 Sampler 的原生根音/键区映射；需要明确映射时使用音色库/乐器文件。文件操作需要文件访问权限，保留的来源在原生乐器释放前持续拥有。allNotesOff 也清除延音，并始终可用于清理。原生失效后应停止、重建或销毁旧图。

#序列与轨道

独立 AVAudioSequencer 可用于编辑；关联引擎后可驱动乐器。一个引擎只关联一个存活序列器，替换前先 dispose。将目标 Audio Unit attach 到该引擎，再逐轨配置 destination；更改目标前停止序列器。关联序列器启动前先启动引擎。引擎 stop/pause/reset 也停止对应序列器，恢复播放需明确调用。

支持音符、控制、压力/程序/弯音、扩展音符、SysEx、元数据/用户事件、速度、自动化参数和预设事件。参数事件放自动化轨，速度放 tempo track。可清除、剪切、移动、复制、合并、反转，配置静音、独奏、循环、长度和偏移。拍与秒不同，转换应使用序列器的速度图。timeResolution 表示文件 PPQN，从所属 tempo track 读取，而不是读取普通轨道。

getEvents(range) 返回复制后的原生元信息。Sysex/User 公开 sizeInBytes，Meta 公开 metaType；这类不可变 opaque 数据没有公开的枚举 getter。observeUserEvents 在播放时异步提供完整用户事件字节、精确字符串序号、轨道句柄和 discontinuity。队列暂无事件时 read 返回 null；close 解除观察。getStatistics 提供接纳/交付/排队/丢弃的事件数量，不是音频渲染回调。

load/loadData 会替换轨道句柄，之后需重新获取轨道并绑定目标；已移除、销毁或替换的旧轨道拒绝继续操作。复制/合并直接使用原生事件内容，保留 opaque 数据，不绕经 JS 字节副本。大型列表请按有界范围查询。部分编辑可能保留保守的原生事件内存信用，直到轨道清空或被替换。

#MIDI 文件与精度

exportData/write 按所选原生 MIDI 文件分辨率导出，往返可能量化小数拍点；自定义用户事件也可能不保留在标准 MIDI 文件中（已在 iOS26.5 验证）。文件导出不等于精确原生事件快照。自定义播放消息使用用户事件观察；需要可编辑工程格式时保留脚本的源事件数据。write 默认保护已有文件，覆盖需明确 overwrite，文件工作在 worker 执行。

#完整 index.tsx

示例生成自有短 CAF 采样，每个音符有可访问的 On/Off 按钮，并提供延音、四拍旋律、速度/循环、可选音色库/MIDI 文件选择和 MIDI 导出。无需下载或麦克风。切换速度从第0拍重启。示例激活共享播放会话，关闭时仅删除其自有临时目录；需要保留的导出请先复制到其它位置。

点击文档的示例入口即可运行，完整代码见同级 index.tsx。