SuperSonic：scsynth 兼容合成引擎

项目简介

SuperSonic 是一个与 scsynth 兼容的合成引擎，由 Clockwork 驱动。它最初 fork 自 SuperCollider 的音频合成引擎 scsynth，并在条件允许的范围内保持 scsynth 的 OSC 命令与 SynthDef 继续可用。

它面向希望把 SuperCollider 的合成能力带进自己环境的开发者：既可以作为 AudioWorklet 跑在浏览器里，也可以作为独立原生服务器运行，还能以 NIF 形式作为 BEAM 的原生共享库嵌入 Erlang/Elixir。

目前项目仍处于 Alpha 阶段，API 可能继续演进，但核心合成引擎已相对稳定，适合试验。

主要功能

核心

• scsynth 兼容：沿用 scsynth 的 OSC 命令与 SynthDef，差异记录在文档中。
• 实时指标：两种传输模式下都提供零拷贝遥测，包括 OSC 吞吐、调度器深度与延迟、环形缓冲区占用，以及实时节点树镜像。
• 无 malloc 音频路径：音频线程上不做内存分配、不阻塞。
• 引擎内调度：远期 bundle 由引擎自己保存并按采样时间戳触发，/clearSched 可取消尚未执行的任务。
• Cold swap：可在客户端运行期间重建引擎，用于更换设备或采样率。
• 跟进上游修复：在适用处吸收 SuperCollider scsynth 的修复。

Web

• 双传输模式：追求性能时用 SharedArrayBuffer，零配置 CDN 部署时用 postMessage。
• 移动端容错：支持挂起与恢复，恢复失败时完整重载，之后由客户端恢复 synthdef 与 buffer。
• 可观测：实时提供环形缓冲区使用率、调度器深度、音频健康度和爆音检测。
• 多客户端：每个 Web Worker 都能拥有自己的 OscChannel，日志中带来源 ID。
• 线程安全 node ID：nextNodeId() 在多线程、多 Worker 之间保证唯一。
• 发布在 npm：包名 supersonic-scsynth，core、synthdefs 与 samples 分包提供。

原生

• Ableton Link v4：跨网络 tempo 同步，并支持 Link Audio 输入输出。
• 运行时切换设备与驱动：采样率不匹配时自动 cold swap。
• 无头模式：面向 CI 与容器的高精度定时器驱动处理。
• scsynth 的命令行与 OSC：可像 scsynth 一样通过 TCP、Unix socket、命名管道或共享内存启动与驱动。
• 插件托管：在独立桥接进程中运行 CLAP 与 VST3 插件轨道。
• 会话录制：主输出可录制为 WAV 或 FLAC。

NIF（实验性）

• 干净的 OSC 二进制接口，与 web、native 使用同样的协议边界。
• 永不阻塞调度器：send_osc 是环形写入，start / stop 把慢速启停交给 NIF 自己的线程并回传消息。
• 基于 PID 的通知：任意数量进程可注册，各自收到每条 OSC 回复与调试信息。

安装与使用

在线演示：打开 sonic-pi.net/supersonic/demo.html 即可体验。

Web

可通过 CDN 远程加载、npm 本地安装或自行构建，详见仓库的 docs/INSTALLATION_WEB.md；装好后按 docs/QUICKSTART.md 发出第一个声音，配置项见 docs/API.md。

Native

带上 submodule 克隆后，用 CMake 构建：

git clone --recurse-submodules https://github.com/samaaron/supersonic
cmake -B build/native -DCMAKE_BUILD_TYPE=Release
cmake --build build/native --target SuperSonic

运行方式、设备、传输与日志见 docs/NATIVE.md。若想把引擎链接进自己的进程而不是跑独立服务器，可使用 supersonic_embed 与 supersonic::EmbeddedHost。

NIF

构建时不需要安装 Erlang：

cmake -B build/nif -DCLOCKWORK_NIF=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build/nif --target clockwork_nif --config Release --parallel

产物位于 build/nif/clockwork.so（Windows 上为 clockwork.dll），加载与驱动方式见 docs/NIF.md。

注意事项

• 项目仍在活跃开发中，API 不稳定。
• NIF 属于实验性功能，除自身测试外尚无基于它的实际项目。
• 许可证为 AGPL-3.0-or-later：scsynth 部分为 GPL-3.0-or-later，clockwork 部分为 AGPL-3.0-or-later（或商业授权），两者保持可分离。

---

本作品整理自 GitHub 开源项目 samaaron/supersonic，原作者 @samaaron。中文介绍由 AI 根据项目 README 整理，以原仓库为准。