Add TypeScript

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -42,7 +42,7 @@ body:
       description: Steps to reproduce the behavior.
       placeholder: |
         1. Load this MIDI...
-        2. Load this soundfont
+        2. Load this sf2/dls file
         3. Play '...'
         4. See error...
     validations:
@@ -62,6 +62,6 @@ body:
   - type: textarea
     attributes:
       label: Additional info
-      description: Any additional info and attachments (screenshots, MIDIs, soundfonts, other environments) go here.
+      description: Any additional info and attachments (screenshots, MIDIs, sf2/dls files, other environments) go here.
     validations:
       required: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -27,6 +27,6 @@ body:
   - type: textarea
     attributes:
       label: Additional info
-      description: Any additional info and attachments (screenshots, MIDIs, soundfonts, other environments) go here.
+      description: Any additional info and attachments (screenshots, MIDIs, sf2/dls files, other environments) go here.
     validations:
       required: false

.github/workflows/deploy.yaml

@@ -36,15 +36,17 @@ jobs:
           python-version: '3.13'
       - name: Install Node dependencies
         run: npm ci
+      - name: Install Python dependencies
+        run: pip install -r docs/requirements.txt
       - name: Build Pages
         run: npm run build
       - name: Setup Pages
         uses: actions/configure-pages@v5
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          # Upload dist folder
-          path: './dist'
+          # Upload docs folder
+          path: './docs'
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4

.gitignore

@@ -64,9 +64,8 @@ $RECYCLE.BIN/
 
 # Windows shortcuts
 *.lnk
-/synthetizer/worklet_processor.min.js.map
+*.tgz
+/synthetizer/
 /spessasynth_lib.wiki/
 dist/
-synthetizer/
-*.tgz
-gh-pages/
+/gh-pages/

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "tabWidth": 4,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "none",
+  "endOfLine": "lf"
+}

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,25 +17,12 @@ It allows you to:
 - Convert DLS to SF2! (and back!)
 - [and more!](#current-features)
 
-**The next major update (4.0) will include many breaking changes. 
-The documentation will be updated when the update releases.
-[The migration guide will be published here.](https://github.com/spessasus/spessasynth_lib/pull/10)**
-
-
-**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)
 
@@ -41,64 +31,75 @@ npm install --save spessasynth_lib
 - [SpessaFont - Online SoundFont/DLS Editor](https://spessasus.github.io/SpessaFont)
 
 
-### [Complete documentation](https://spessasus.github.io/spessasynth_lib/)
+### [Documentation](https://github.com/spessasus/spessasynth_lib/wiki/)
 
-#### 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://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://spessasus.github.io/spessasynth_lib/synthesizer/#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.

build_scripts/build.ts

@@ -0,0 +1,6 @@
+import { runCommandSync } from "./run_command.ts";
+
+console.log("Building spessasynth_lib...");
+runCommandSync("npm run build:npm");
+runCommandSync("npm run build:pages");
+console.log("spessasynth_lib built successfully.");

build_scripts/build_docs.ts

@@ -0,0 +1,8 @@
+import { runCommandSync } from "./run_command.ts";
+import { GH_PAGES_DIR } from "./util.ts";
+
+export const buildDocs = () => {
+    console.log("Building MkDocs...");
+    runCommandSync(`mkdocs build -c -s -d ${GH_PAGES_DIR}`);
+    console.log("MkDocs built successfully.");
+};

build_scripts/build_npm.ts

@@ -0,0 +1,52 @@
+import path from "path";
+import { NPM_DIST_DIR } from "./util.ts";
+import esbuild from "esbuild";
+import * as tsup from "tsup";
+
+console.log("Building NPM package...");
+const dirname = import.meta.dirname;
+const INPUT_PATH = path.join(dirname, "..", "src", "worklet_processor.ts");
+const OUTPUT_PATH = path.join(
+    dirname,
+    "..",
+    NPM_DIST_DIR,
+    "spessasynth_processor.min.js"
+);
+try 
+{
+// Main bundle
+await tsup.build({
+    entry: ["src/index.ts"],
+    format: "esm",
+    dts: true,
+    sourcemap: true,
+    outDir: "dist"
+})
+
+// Worklet
+// Esbuild src/worklet_processor/ts
+// --bundle
+// --tree-shaking=true
+// --minify
+// --sourcemap=linked
+// --format=esm
+// --outfile=dist/spessasynth_processor.min.js
+// --platform=browser
+esbuild.buildSync({
+    entryPoints: [INPUT_PATH],
+    bundle: true,
+    treeShaking: true,
+    minify: true,
+    format: "esm",
+    platform: "browser",
+    sourcemap: "linked",
+    outfile: OUTPUT_PATH,
+    logLevel: "info",
+    target: "esnext"
+});
+console.log("NPM package built successfully.");
+}
+catch(e)
+{
+    console.error(e, "\nFailed to build the NPM package.")
+}

build_scripts/build_pages.ts

@@ -0,0 +1,13 @@
+import { buildDocs } from "./build_docs.ts";
+import { buildExamples } from "../examples/build_examples.ts";
+
+console.log("Building for GitHub Pages...");
+try {
+buildDocs();
+buildExamples();
+console.log("Pages built successfully.");
+}
+catch(e)
+{
+    console.error(e, "\n\nFailed to build GitHub pages. Did you install MkDocs?")
+}