spessasynth_lib/README.md

MIDI and SoundFont2/DLS library for the browsers with no compromises

<!--suppress HtmlDeprecatedAttribute, HtmlRequiredAltAttribute, HtmlExtraClosingTag -->
<p align='center'>
<img src='https://raw.githubusercontent.com/spessasus/SpessaSynth/refs/heads/master/src/website/spessasynth_logo_rounded.png' width='300' alt='SpessaSynth logo'>
</p>

_A powerful multipurpose SF2/DLS/MIDI TypeScript/JavaScript library for the browsers, based on spessasynth_core.
This is a WebAudioAPI wrapper for the [spessasynth_core](https://github.com/spessasus/spessasynth_core) library._

It allows you to:

- Play MIDI files using SF2/SF3/DLS files!
- Read and write MIDI files!
- Write SF2/SF3 files!
- Convert DLS to SF2! (and back!)
- [and more!](#current-features)

> **TIP:**
>
> Looking for a bare JS version that works without WebAudioAPI? Try [spessasynth_core](https://github.com/spessasus/spessasynth_core)!

### v4.3.0 The General Update is here!

Featuring robust MIDI analysis and editing, broadened MIDI exclusive support,
and reworked, more powerful API!

### [Project site (consider giving it a star!)](https://github.com/spessasus/spessasynth_lib)

### Made with spessasynth_lib

- [SpessaSynth - Online SF2/DLS MIDI Player](https://spessasus.github.io/SpessaSynth)
- [signal - Online MIDI Editor](https://signalmidi.app/)

### [Documentation](https://spessasus.github.io/spessasynth_lib)

**SpessaSynth Project index**

- [spessasynth_core](https://github.com/spessasus/spessasynth_core) - SF2/DLS/MIDI library
- [spessasynth_lib](https://github.com/spessasus/spessasynth_lib) (you are here) - spessasynth_core wrapper optimized for browsers and WebAudioAPI
- [SpessaSynth](https://github.com/spessasus/SpessaSynth) - online/local MIDI player/editor application
- [SpessaFont](https://github.com/spessasus/SpessaFont) - online SF2/DLS editor

## Current Features

### [All the features of spessasynth_core!](https://github.com/spessasus/spessasynth_core?#current-features)

### On top of that...

- **Fully typed:** _Faster development and IDE auto-completion!_
- **Modular design:** _Easy integration into other projects (load what you need)_
- **[Detailed documentation:](https://spessasus.github.io/spessasynth_lib/)** _With [examples!](https://spessasus.github.io/spessasynth_lib/getting-started/#examples)_
- **Easy to Use:** _Basic setup is just [two lines of code!](https://spessasus.github.io/spessasynth_lib/getting-started/#minimal-setup)_
- **No external dependencies:** _Just spessasynth_core!_
- **Export audio files** using [OfflineAudioContext](https://developer.mozilla.org/en-US/docs/Web/API/OfflineAudioContext)!
- **AudioWorklet synthesizer:**
    - Runs in a **separate thread** for maximum performance!
    - Does not stop playing even when the main thread is frozen!
    - Supported by all modern browsers!
- **Web Worker synthesizer:**
    - Synthesize directly in the Web Worker!
    - Direct audio engine access!
    - Export audio automatically in the worker!
    - Avoids [Chromium Audio Bugs](https://issues.chromium.org/issues/367304685)!
- **High-performance mode:** Play Rush E! _note: may kill your browser ;)_

### Special Thanks

- [FluidSynth](https://github.com/FluidSynth/fluidsynth) - for the source code that helped implement functionality and fixes
- [Polyphone](https://www.polyphone-soundfonts.com/) - for the sound bank testing and editing tool
- [Meltysynth](https://github.com/sinshu/meltysynth) - for the initial low-pass filter implementation
- [RecordingBlogs](https://www.recordingblogs.com/) - for detailed explanations on MIDI messages
- [stbvorbis.js](https://github.com/hajimehoshi/stbvorbis.js) - for the Vorbis decoder
- [fflate](https://github.com/101arrowz/fflate) - for the MIT DEFLATE implementation
- [tsup](https://github.com/egoist/tsup) - for the TypeScript bundler
- [foo_midi](https://github.com/stuerp/foo_midi) - for useful resources on XMF file format
- [Falcosoft](https://falcosoft.hu) - for help with the RMIDI format
- [Christian Collins](https://schristiancollins.com) - for various bug reports regarding the synthesizer
- **And You!** - for checking out this project. I hope you like it :)

### Basic example: play a single note

```js
import { WorkletSynthesizer } from "spessasynth_lib";

// SF2, SF3, SFOGG and DLS files are all supported!
const sfont = await (await fetch("soundfont.sf3")).arrayBuffer();
const ctx = new AudioContext();
// make sure you copied the worklet processor!
await ctx.audioWorklet.addModule("./spessasynth_processor.min.js");
const synth = new WorkletSynthesizer(ctx);
await synth.soundBankManager.addSoundBank(sfont, "main");
await synth.isReady;
document.getElementById("button").onclick = async () => {
    await ctx.resume();
    synth.programChange(0, 48); // strings ensemble
    synth.noteOn(0, 52, 127);
};
```

## License

Copyright © 2026 Spessasus
Licensed under the Apache-2.0 License.

#### Legal

This project is in no way endorsed or otherwise affiliated with the MIDI Manufacturers Association,
Roland Corporation, Yamaha Corporation, Creative Technology Ltd. or E-mu Systems, Inc.,
or any other organization mentioned.
SoundFont® is a registered trademark of Creative Technology Ltd.
All other trademarks are the property of their respective owners.