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.*
+
+**v3.28 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/3-28-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,30 +31,16 @@ 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
 
@@ -88,17 +64,43 @@ Please consider voting for it on the bug tracker to get it fixed!*
 
 ### 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"
+
+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 WorkletSynthesizer(ctx.destination);
+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);
+}
+```
+
+*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!*
+
 # 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,39 @@
+import path from "path";
+import { NPM_DIST_DIR } from "./util.ts";
+import { runCommandSync } from "./run_command.ts";
+import esbuild from "esbuild";
+
+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,
+    "worklet_processor.min.js"
+);
+// main bundle
+runCommandSync("tsup src/index.ts --clean --sourcemap --dts --format esm");
+
+// worklet
+// esbuild src/worklet_processor/ts
+// --bundle
+// --tree-shaking=true
+// --minify
+// --sourcemap=linked
+// --format=esm
+// --outfile=dist/worklet_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.");

build_scripts/build_pages.ts

@@ -0,0 +1,7 @@
+import { buildDocs } from "./build_docs.ts";
+import { buildExamples } from "../examples/build_examples.ts";
+
+console.log("Building for GitHub Pages...");
+buildDocs();
+buildExamples();
+console.log("Pages built successfully.");

build_scripts/debug_disable.js → build_scripts/debug_disable.ts

@@ -1,9 +1,9 @@
-import { runCommandSync } from "./run_command.js";
+import { runCommandSync } from "./run_command.ts";
 
 runCommandSync("npm uninstall spessasynth_core");
 runCommandSync("npm install spessasynth_core");
 runCommandSync("npm pkg set dependencies.spessasynth_core=latest");
 runCommandSync("npm update");
 runCommandSync("npm run build");
 
-console.log("All commands completed successfully.");
+console.log("All commands completed successfully.");

build_scripts/debug_enable.js → build_scripts/debug_enable.ts

@@ -1,4 +1,4 @@
-import { runCommandSync } from "./run_command.js";
+import { runCommandSync } from "./run_command.ts";
 
 runCommandSync("npm uninstall spessasynth_core");
 runCommandSync("npm install ../spessasynth_core");