spessasynth_lib 3.27.7 → 4.0.0

package/README.md

@@ -3,9 +3,12 @@
 <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 SF2/DLS/MIDI JavaScript library for the browsers.**
+*A powerful SF2/DLS/MIDI 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.*
+
+**v4.0.0 TypeScript Update is here! The NPM package now contains type declarations for easier developing!**
+[**Read about breaking changes here**](https://spessasus.github.io/spessasynth_lib/extra/4-0-migration-guide)
 
-*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!
@@ -14,20 +17,12 @@ It allows you to:
 - Convert DLS to SF2! (and back!)
 - [and more!](#current-features)
 
-**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
-
 
 > **TIP:**
+> 
 > Looking for a bare JS version that works without WebAudioAPI? Try [spessasynth_core](https://github.com/spessasus/spessasynth_core)!
 
-```shell
-npm install --save spessasynth_lib
-```
+
 
 ### [Project site (consider giving it a star!)](https://github.com/spessasus/spessasynth_lib)
 
@@ -36,64 +31,75 @@ npm install --save spessasynth_lib
 - [SpessaFont - Online SoundFont/DLS Editor](https://spessasus.github.io/SpessaFont)
 
 
-### [Complete documentation](https://github.com/spessasus/spessasynth_lib/wiki/)
+### [Documentation](https://spessasus.github.io/spessasynth_lib)
 
-#### Basic example: play a single note
 
-```js
-import { Synthetizer } from "spessasynth_lib"
 
-const sfont = await (await fetch("soundfont.sf3")).arrayBuffer();
-const ctx = new AudioContext();
-// make sure you copied the worklet processor!
-await ctx.audioWorklet.addModule("./worklet_processor.min.js");
-const synth = new Synthetizer(ctx.destination, sfont);
-document.getElementById("button").onclick = async () =>
-{
-    await ctx.resume();
-    synth.programChange(0, 48); // strings ensemble
-    synth.noteOn(0, 52, 127);
-}
-```
+**SpessaSynth Project index**
 
-*Audio may sometimes sound distorted in Chromium-based browsers: Chrome, Edge, Brave,
-etc. due to a **[Chromium Bug](https://issues.chromium.org/issues/367304685).**
-I can't do anything about it, only hope that it gets fixed.
-Please consider voting for it on the bug tracker to get it fixed!*
+- [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://github.com/spessasus/spessasynth_lib/wiki/Home)** *With [examples!](https://github.com/spessasus/spessasynth_lib/wiki/Getting-Started#examples)*
-- **Easy to Use:** *Basic setup is just [two lines of code!](https://github.com/spessasus/spessasynth_lib/wiki/Getting-Started#minimal-setup)*
+- **[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!*
-- **Reverb and chorus support:** [customizable!](https://github.com/spessasus/spessasynth_lib/wiki/Synthetizer-Class#effects-configuration-object)
-- **Export audio files** using [OfflineAudioContext](https://developer.mozilla.org/en-US/docs/Web/API/OfflineAudioContext)
-- **Written using AudioWorklets:** 
-  - Runs in a **separate thread** for maximum performance
-  - Does not stop playing even when the main thread is frozen
-  - Supported by all modern browsers
+- **Reverb and chorus support:** [customizable](https://spessasus.github.io/spessasynth_lib/synthesizer/#effects-configuration-object) and can be used standalone!
+- **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 ;)*
 
-#### TODO
-- Enhance the built-in chorus and reverb effects (suggestions welcome!)
-
 ### 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 soundfont testing and editing tool
+- [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 © 2025 Spessasus
 Licensed under the Apache-2.0 License.