120 lines
5.8 KiB
Markdown
120 lines
5.8 KiB
Markdown
# @suaveplan/audio-fx-plugin-spessasynth - SF2/SF3 SoundFont synthesizer plugin for the @suaveplan/audio-fx-plugin-* family.
|
||
|
||
SF2/SF3 SoundFont synthesizer plugin for the `@suaveplan/audio-fx-plugin-*` family. Wraps the MIT-licensed [SpessaSynth](https://github.com/spessasus/SpessaSynth) engine as a standard `AudioFxPlugin`, so it composes inside any `PluginChain`, accepts MIDI from a `MidiPortLike` consumer, and exposes its 16-channel parameter surface through the same automation / snapshot / preset machinery every other plugin uses.
|
||
|
||
`spessasynth_lib` is declared as an `optionalDependencies` entry and pulled in only via lazy `import()` inside the loader, so consumers who never call `init()` pay zero bundle cost.
|
||
|
||
<!-- begin:auto-docs -->
|
||
## Documentation tree
|
||
|
||
- [error-codes](./src/error-codes/error-codes.md) — Defines the stable `SPESSASYNTH.*` error-code namespace used by every other module in `@suaveplan/audio-fx-plugin-spess…
|
||
- [error-codes](./src/error-codes/error-codes.md) — Defines the stable `SPESSASYNTH.*` error-code namespace used by every other module in `@suaveplan/audio-fx-plugin-spess…
|
||
- [loader](./src/loader/soundfont-loader.md) — Lazy entry point for the SF2/SF3/DLS SoundFont pipeline. The loader is the **only** place in the package where `spessas…
|
||
- [soundfont-loader](./src/loader/soundfont-loader.md) — Lazy entry point for the SF2/SF3/DLS SoundFont pipeline. The loader is the **only** place in the package where `spessas…
|
||
- [midi-router](./src/midi-router/midi-router.md) — Routes `MidiMessage` events from a `MidiPortLike` (or a direct `handle()` call) into the upstream `SpessaSynthProcessor…
|
||
- [midi-router](./src/midi-router/midi-router.md) — Routes `MidiMessage` events from a `MidiPortLike` (or a direct `handle()` call) into the upstream `SpessaSynthProcessor…
|
||
- [parameters](./src/parameters/parameters.md) — Declares the parameter surface the `SpessaSynthPlugin` exposes to the host chain: 16 GM channels × 5 controls (`volume`…
|
||
- [parameters](./src/parameters/parameters.md) — Declares the parameter surface the `SpessaSynthPlugin` exposes to the host chain: 16 GM channels × 5 controls (`volume`…
|
||
- [plugin](./src/plugin/spessasynth-plugin.md) — `SpessaSynthPlugin` is the `AudioFxPlugin` implementation that wraps the SpessaSynth SF2/SF3 SoundFont engine. It is a…
|
||
- [spessasynth-plugin](./src/plugin/spessasynth-plugin.md) — `SpessaSynthPlugin` is the `AudioFxPlugin` implementation that wraps the SpessaSynth SF2/SF3 SoundFont engine. It is a…
|
||
- [register](./src/register/register.md) — Provides the one-call helper `registerSpessaSynthPlugin(registry)` that attaches the SpessaSynth plugin factory to a `P…
|
||
- [register](./src/register/register.md) — Provides the one-call helper `registerSpessaSynthPlugin(registry)` that attaches the SpessaSynth plugin factory to a `P…
|
||
- [telemetry](./src/telemetry/telemetry.md) — OpenTelemetry instrument bridge for the SpessaSynth plugin. Exposes three instruments under the meter `@suaveplan/audio…
|
||
- [telemetry](./src/telemetry/telemetry.md) — OpenTelemetry instrument bridge for the SpessaSynth plugin. Exposes three instruments under the meter `@suaveplan/audio…
|
||
- [voice-manager](./src/voice-manager/voice-manager.md) — Owns the polyphony cap and the voice-stealing policy layered on top of the upstream `SpessaSynthProcessor`. The process…
|
||
- [voice-manager](./src/voice-manager/voice-manager.md) — Owns the polyphony cap and the voice-stealing policy layered on top of the upstream `SpessaSynthProcessor`. The process…
|
||
<!-- end:auto-docs -->
|
||
|
||
## Quickstart
|
||
|
||
```ts
|
||
import { SpessaSynthPlugin } from "@suaveplan/audio-fx-plugin-spessasynth";
|
||
|
||
const plugin = new SpessaSynthPlugin();
|
||
await plugin.init({
|
||
soundFontUrl: "/assets/gm.sf2",
|
||
sampleRate: 48_000,
|
||
});
|
||
await plugin.setup(
|
||
{ sampleRate: 48_000, channels: 2, blockSize: 128 },
|
||
chainContext
|
||
);
|
||
|
||
plugin.sendMidi({ type: "noteOn", channel: 0, note: 60, velocity: 100 });
|
||
|
||
const out: Float32Array[] = [
|
||
new Float32Array(128),
|
||
new Float32Array(128),
|
||
];
|
||
plugin.process([], out, {
|
||
blockOffsetSamples: 0,
|
||
sampleRate: 48_000,
|
||
channels: 2,
|
||
opts: {},
|
||
});
|
||
```
|
||
|
||
## SF2 loading
|
||
|
||
```ts
|
||
// From a URL (browser):
|
||
await plugin.init({ soundFontUrl: "/assets/gm.sf2" });
|
||
|
||
// From an in-memory blob (offline render / tests):
|
||
await plugin.init({ soundFontBytes: sf2Bytes });
|
||
|
||
// With an AbortController:
|
||
await plugin.init({ soundFontUrl, signal: ac.signal });
|
||
```
|
||
|
||
## Control-surface integration
|
||
|
||
```ts
|
||
import {
|
||
SpessaSynthPlugin,
|
||
channelParameterId,
|
||
MASTER_GAIN_ID,
|
||
} from "@suaveplan/audio-fx-plugin-spessasynth";
|
||
|
||
// A control-surface knob driving channel-0 volume in real time:
|
||
controlSurface.onKnobMove((value) => {
|
||
plugin.setParameter(channelParameterId(0, "volume"), value);
|
||
});
|
||
|
||
// Automate the master gain over half a second:
|
||
plugin.setParameterCurve(MASTER_GAIN_ID, {
|
||
type: "linear",
|
||
value: 0,
|
||
duration: 0.5,
|
||
});
|
||
```
|
||
|
||
## Registry
|
||
|
||
```ts
|
||
import { PluginRegistry } from "@suaveplan/audio-fx-plugin-base/registry";
|
||
import { registerSpessaSynthPlugin } from "@suaveplan/audio-fx-plugin-spessasynth/register";
|
||
|
||
const registry = new PluginRegistry();
|
||
registerSpessaSynthPlugin(registry);
|
||
|
||
// Now `chain.restore(snapshot, registry)` can rehydrate any snapshot
|
||
// containing a SpessaSynth slot.
|
||
```
|
||
|
||
## Modules
|
||
|
||
- `error-codes` — `SPESSASYNTH.*` codes via `defineCodes`.
|
||
- `loader` — lazy `import("spessasynth_lib")`, SF2/SF3/DLS magic sniff, parse.
|
||
- `midi-router` — channel-voice + program-change + NRPN/RPN reassembly.
|
||
- `parameters` — 16-channel × 5-control + master gain (81 parameters).
|
||
- `voice-manager` — polyphony cap + voice-stealing.
|
||
- `plugin` — `SpessaSynthPlugin` (the `AudioFxPlugin` implementation).
|
||
- `telemetry` — OTel counter + histogram + observable gauge.
|
||
- `register` — registry helper for snapshot-restore.
|
||
|
||
## License
|
||
|
||
MIT.
|
||
|