# soundfont-loader

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Lazy entry point for the SF2/SF3/DLS SoundFont pipeline. The loader is the **only** place in the package where `spessasynth_lib` is referenced — the import is a dynamic `import("spessasynth_lib")` so consumers who instantiate the plugin but never call `init()` pay zero bundle cost. The loader also accepts an injectable `moduleLoader` so tests can swap in a deterministic stub without touching the real upstream library.

The loader is responsible for three things: (1) lazy-resolving the optional upstream module and surfacing `SPESSASYNTH.MODULE_UNAVAILABLE` if it isn't installed; (2) fetching the SoundFont bytes from a URL or accepting them inline; (3) sniffing the RIFF magic to reject obviously-wrong inputs before handing them to `SoundBankLoader.fromArrayBuffer`. Parse failures from the upstream parser are caught and re-raised as `SPESSASYNTH.SOUNDFONT_PARSE_FAILED` with the underlying error on `cause` so log aggregation can correlate.

## Features

- Dynamic `import("spessasynth_lib")` — the only static reference in the codebase, ring-fenced inside `defaultModuleLoader`.
- Injectable `moduleLoader` and `fetchImpl` for hermetic tests.
- Magic-byte sniff (`RIFF…sfbk` or `RIFF…DLS `) — rejects non-SoundFont inputs with `UNSUPPORTED_FORMAT` before invoking the parser.
- `AbortSignal` propagation to the fetch.
- Returns parsed `SoundBankLike` + resolved `SpessaSynthModuleLike` + raw bytes so callers can construct the processor and (optionally) persist the bytes.
- Strict typed error surface: `SOUNDFONT_LOAD_FAILED`, `UNSUPPORTED_FORMAT`, `SOUNDFONT_PARSE_FAILED`, `MODULE_UNAVAILABLE`.

## Usage: Basic

```ts
import { loadSoundFont } from "@suaveplan/audio-fx-plugin-spessasynth/loader";

const { bank, module } = await loadSoundFont({
    soundFontUrl: "/assets/gm.sf2",
});
const processor = new module.SpessaSynthProcessor(48_000);
processor.soundBankManager.addSoundBank(bank, "main", 0);
```

## Usage: Advanced

```ts
import { loadSoundFont } from "@suaveplan/audio-fx-plugin-spessasynth/loader";

const ac = new AbortController();
setTimeout(() => ac.abort(), 5_000);

const { bank, bytes, module } = await loadSoundFont({
    soundFontUrl: "https://cdn.example.com/orchestra.sf3",
    signal: ac.signal,
    fetchImpl: customFetcher,
    moduleLoader: async () => upstreamStubModule,
});

// Persist bytes for offline reuse.
await driveStore.put("orchestra.sf3", bytes);
```

## API Reference

- `loadSoundFont(opts: LoadSoundFontOptions): Promise<LoadedSoundFont>`.
- `LoadSoundFontOptions = { soundFontUrl?, soundFontBytes?, signal?, fetchImpl?, moduleLoader? }`. Exactly one of `soundFontUrl` / `soundFontBytes` is required.
- `LoadedSoundFont = { bank, module, bytes }`.
- `SpessaSynthModuleLike`, `SpessaSynthProcessorLike`, `SoundBankLike` — structural views of the upstream surface used elsewhere in the package.

## Implementation Notes

The structural module / processor / bank types are declared inside the package rather than imported from `spessasynth_lib` so the optional dependency does not leak into the static type graph — the only place the upstream is named is inside `defaultModuleLoader`'s dynamic `import()`. The magic sniff is intentionally cheap (12 bytes) and runs before the parser, so consumers that hand the loader random Uint8Arrays (e.g. a corrupt cache entry) get a fast, specific error rather than a deep stack from the parser. The `ArrayBuffer` is sliced from the supplied `Uint8Array.buffer` using the `byteOffset`/`byteLength` window so callers can pass a `Uint8Array` view of a larger buffer without leaking the surrounding bytes into the parser.