{"id":13433499,"url":"https://github.com/spessasus/SpessaSynth","last_synced_at":"2025-03-17T12:31:59.303Z","repository":{"id":172871176,"uuid":"643635315","full_name":"spessasus/SpessaSynth","owner":"spessasus","description":"MIDI SoundFont/DLS synthesizer library written in JavaScript.","archived":false,"fork":false,"pushed_at":"2024-11-06T23:01:55.000Z","size":181426,"stargazers_count":88,"open_issues_count":7,"forks_count":10,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-07T09:07:07.207Z","etag":null,"topics":["dls","midi","midi-files","midi-parser","midi-player","midi-sequencer","midi-synth","midi-synthesizer","sf2","sf3","sound-synthesis","soundfont","soundfont-player","soundfont-synthesizers","soundfont2","soundfont2-synthesizer-library","soundfonts","web-midi","web-midi-api","web-midi-synths"],"latest_commit_sha":null,"homepage":"https://spessasus.github.io/SpessaSynth/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spessasus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-21T19:28:41.000Z","updated_at":"2024-11-06T22:13:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"26068732-b9c5-4321-9afa-f391dfbf25f4","html_url":"https://github.com/spessasus/SpessaSynth","commit_stats":null,"previous_names":["spessasus/spessasynth"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spessasus%2FSpessaSynth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spessasus%2FSpessaSynth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spessasus%2FSpessaSynth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spessasus%2FSpessaSynth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spessasus","download_url":"https://codeload.github.com/spessasus/SpessaSynth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244033866,"owners_count":20387015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dls","midi","midi-files","midi-parser","midi-player","midi-sequencer","midi-synth","midi-synthesizer","sf2","sf3","sound-synthesis","soundfont","soundfont-player","soundfont-synthesizers","soundfont2","soundfont2-synthesizer-library","soundfonts","web-midi","web-midi-api","web-midi-synths"],"created_at":"2024-07-31T02:01:27.305Z","updated_at":"2025-03-17T12:31:59.297Z","avatar_url":"https://github.com/spessasus.png","language":"JavaScript","funding_links":[],"categories":["TypeScript","Libraries","MIDI instruments"],"sub_categories":["JavaScript","Sequencers \u0026 Trackers"],"readme":"\u003c!--suppress HtmlDeprecatedAttribute, HtmlRequiredAltAttribute, HtmlExtraClosingTag --\u003e\n\u003cp align='center'\u003e\n\u003cimg src=\"src/website/spessasynth_logo_rounded.png\" width='300' alt='SpessaSynth logo'\u003e\n\u003c/p\u003e\n\n**SpessaSynth** is a SoundFont2-based real-time synthesizer and MIDI library written in vanilla JavaScript.\nIt’s a powerful and versatile library that allows you to:\n- Play MIDI files using SF2/SF3/DLS files\n- Write MIDI files\n- Write SF2/SF3 files\n- Convert DLS to SF2 (and back)\n- [and more!](#easy-integration)\n\nSupported formats list:\n- `.mid` - Standard MIDI File\n- `.kar` - Soft Karaoke MIDI File\n- `.sf2` - SoundFont2 File\n- `.sf3` - SoundFont2 Compressed File\n- `.sfogg` - SF2Pack With Vorbis Compression\n- `.dls` - Downloadable Sounds Levels 1 \u0026 2 (as well as Mobile DLS)\n- `.rmi` - RIFF MIDI File\n- `.rmi` - RIFF MIDI File With Embedded DLS\n- `.rmi` - [RIFF MIDI File With Embedded SF2](https://github.com/spessasus/sf2-rmidi-specification)\n\nWith [an easy way of converting between them!](https://github.com/spessasus/SpessaSynth/wiki/Converting-Between-Formats)\n\n### npm package\n\n```shell\nnpm install --save spessasynth_lib\n```\n\n\u003ch1 align=\"center\"\u003e\u003ca href=\"https://spessasus.github.io/SpessaSynth/\"\u003eLive Demo (no download needed!)\u003c/a\u003e\u003c/h1\u003e\n\n\u003ch2 align=\"center\"\u003eMade with SpessaSynth\u003c/h2\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://www.youtube.com/watch?v=Cu_A1IR65yQ\"\u003e\u003cimg width='500' alt=\"Watch the YouTube video\" src=\"https://github.com/user-attachments/assets/d73c0585-67eb-4490-ad39-839b22ab7577\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**This repository contains both the library and a complete musical web application. See below:**\n\n\u003ch1 align='center'\u003espessasynth_lib\u003c/h1\u003e\n\u003cp align='center'\u003eA flexible, powerful, and feature-packed MIDI SF2/DLS library for the WebAudio API.\u003c/p\u003e\n\n\u003ch3 align='center'\u003e\u003ca href=\"https://github.com/spessasus/SpessaSynth/wiki/Home\"\u003eDocumentation\u003c/a\u003e\u003c/h3\u003e\n\n\u003ch2 align='center'\u003eFull Feature List\u003c/h2\u003e\n\n### Easy Integration\n- **Modular design:** *Easy integration into other projects (load what you need)*\n- **[Detailed documentation:](https://github.com/spessasus/SpessaSynth/wiki/Home)** *With [examples!](https://github.com/spessasus/SpessaSynth/wiki/Usage-As-Library#examples)*\n- **Flexible:** *It's not just a MIDI player!*\n- **Easy to Use:** *Basic setup is just [two lines of code!](https://github.com/spessasus/SpessaSynth/wiki/Usage-As-Library#minimal-setup)*\n- **No dependencies:** *Batteries included!*\n\n### Powerful Synthesizer\n- Suitable for both **real-time** and **offline** synthesis\n- **Excellent SoundFont support:**\n  - **Full Generator Support**\n  - **Full Modulator Support:** *First (to my knowledge) JavaScript SoundFont synth with that feature!*\n  - **GeneralUserGS Compatible:** *[See more here!](https://github.com/mrbumpy409/GeneralUser-GS/blob/main/documentation/README.md)*\n  - **SoundFont3 Support:** Play compressed SoundFonts!\n  - **Experimental SF2Pack Support:** Play soundfonts compressed with BASSMIDI! (*Note: only works with vorbis compression*)\n  - **Can load very large SoundFonts:** up to 4GB! *Note: Only Firefox handles this well; Chromium has a hard-coded memory limit*\n- **Great DLS Support:**\n  - **DLS Level 1 Support**\n  - **DLS Level 2 Support**\n  - **Mobile DLS Support**\n  - **Correct articulator support:** *Converts articulators to both modulators and generators!*\n  - **Tested and working with gm.dls!**\n  - **Correct volume:** *Properly translated to SoundFont volume!*\n  - **A-Law encoding support**\n  - **Both unsigned 8-bit and signed 16-bit sample support (24-bit theoretically supported as well!)**\n  - **Detects special articulator combinations:** *Such as vibratoLfoToPitch*\n- **Soundfont manager:** Stack multiple soundfonts!\n- **Reverb and chorus support:** [customizable!](https://github.com/spessasus/SpessaSynth/wiki/Synthetizer-Class#effects-configuration-object)\n- **Export audio files** using [OfflineAudioContext](https://developer.mozilla.org/en-US/docs/Web/API/OfflineAudioContext)\n- **[Custom modulators for additional controllers](https://github.com/spessasus/SpessaSynth/wiki/Modulator-Class#default-modulators):** *Why not?*\n- **Written using AudioWorklets:** \n  - Runs in a **separate thread** for maximum performance\n  - Supported by all modern browsers\n- **Unlimited channel count:** Your CPU is the limit!\n- **Excellent MIDI Standards Support:**\n  - **MIDI Controller Support:** Default supported controllers [here](https://github.com/spessasus/SpessaSynth/wiki/MIDI-Implementation#supported-controllers)\n  - **MIDI Tuning Standard Support:** [more info here](https://github.com/spessasus/SpessaSynth/wiki/MIDI-Implementation#midi-tuning-standard)\n  - [Full **RPN** and limited **NRPN** support](https://github.com/spessasus/SpessaSynth/wiki/MIDI-Implementation#supported-registered-parameters)\n  - Supports some [**Roland GS** and **Yamaha XG** system exclusives](https://github.com/spessasus/SpessaSynth/wiki/MIDI-Implementation#supported-system-exclusives)\n- **High-performance mode:** Play Rush E! *note: may kill your browser ;)*\n\n### Powerful and Fast MIDI Sequencer\n- **Supports MIDI formats 0, 1, and 2:** *note: format 2 support is experimental as it's very, very rare.*\n- **[Multi-Port MIDI](https://github.com/spessasus/SpessaSynth/wiki/About-Multi-Port) support:** More than 16 channels!\n- **Smart preloading:** Only preloads the samples used in the MIDI file for smooth playback *(down to key and velocity!)*\n- **Lyrics support:** Add karaoke to your program!\n- **Raw lyrics available:** Decode in any encoding! *(Kanji? No problem!)*\n- **Runs in Audio Thread as well:** Never blocks the main thread\n- **Loop points support:** Ensures seamless loops\n\n### Read and Write SoundFont and MIDI Files with Ease\n#### Read and write MIDI files\n  - **Smart name detection:** Handles incorrectly formatted and non-standard track names\n  - **Raw name available:** Decode in any encoding! *(Kanji? No problem!)*\n  - **Port detection during load time:** Manage ports and channels easily!\n  - **Used channels on track:** Quickly determine which channels are used\n  - **Key range detection:** Detect the key range of the MIDI\n  - **Easy MIDI editing:** Use [helper functions](https://github.com/spessasus/SpessaSynth/wiki/Writing-MIDI-Files#modifymidi) to modify the song to your needs!\n  - **Loop detection:** Automatically detects loops in MIDIs (e.g., from *Touhou Project*)\n  - **First note detection:** Skip unnecessary silence at the start by jumping to the first note!\n  - **Lyrics support:** Both regular MIDI and .kar files!\n  - **[Write MIDI files from scratch](https://github.com/spessasus/SpessaSynth/wiki/Creating-MIDI-Files)**\n  - **Easy saving:** Save with just [one function!](https://github.com/spessasus/SpessaSynth/wiki/Writing-MIDI-Files#writemidifile)\n\n#### Read and write [RMID files with embedded SF2 soundfonts](https://github.com/spessasus/sf2-rmidi-specification#readme)\n  - **[Level 4](https://github.com/spessasus/sf2-rmidi-specification#level-4) compliance:** Reads and writes *everything!*\n  - **Compression and trimming support:** Reduce a MIDI file with a 1GB soundfont to **as small as 5MB**!\n  - **DLS Version support:** The original legacy format with bank offset detection!\n  - **Automatic bank shifting and validation:** Every soundfont *just works!*\n  - **Metadata support:** Add title, artist, album name and cover and more! And of course read them too! *(In any encoding!)*\n  - **Compatible with [Falcosoft Midi Player 6!](https://falcosoft.hu/softwares.html#midiplayer)**\n  - **Easy saving:** [As simple as saving a MIDI file!](https://github.com/spessasus/SpessaSynth/wiki/Writing-MIDI-Files#writermidi)\n\n#### Read and write SoundFont2 files\n  - **Easy info access:** Just an [object of strings!](https://github.com/spessasus/SpessaSynth/wiki/SoundFont2-Class#soundfontinfo)\n  - **Smart trimming:** Trim the SoundFont to only include samples used in the MIDI *(down to key and velocity!)*\n  - **sf3 conversion:** Compress SoundFont2 files to SoundFont3 with variable quality!\n  - **Easy saving:** Also just [one function!](https://github.com/spessasus/SpessaSynth/wiki/SoundFont2-Class#write)\n\n#### Read and write SoundFont3 files\n  - Same features as SoundFont2 but with now with **Ogg Vorbis compression!**\n  - **Variable compression quality:** You choose between file size and quality!\n  - **Compression preserving:** Avoid decompressing and recompressing uncompressed samples for minimal quality loss!\n\n#### Read and write DLS Level One or Two files\n  - Read DLS (DownLoadable Sounds) files as SF2 files!\n  - **Works like a normal soundfont:** *Saving it as sf2 is still [just one function!](https://github.com/spessasus/SpessaSynth/wiki/SoundFont2-Class#write)*\n  - Converts articulators to both **modulators** and **generators**!\n  - Works with both unsigned 8-bit samples and signed 16-bit samples!\n  - A-Law encoding support\n  - **Covers special generator cases:** *such as modLfoToPitch*!\n  - **Correct volume:** *looking at you, Viena and gm.sf2!*\n  - Support built right into the synthesizer!\n  - **Convert SF2 to DLS:** [with limitations](https://github.com/spessasus/SpessaSynth/wiki/DLS-Conversion-Problem)\n\n### Export MIDI as WAV\n  - Save the MIDI file as WAV audio!\n  - **Metadata support:** *Embed metadata such as title, artist, album and more!*\n  - **Cue points:** *Write MIDI loop points as cue points!*\n  - **Loop multiple times:** *Render two (or more) loops into the file for seamless transitions!*\n  - *That's right, saving as WAV is also [just one function!](https://github.com/spessasus/SpessaSynth/wiki/Writing-Wave-Files#audiobuffertowav)*\n\n## Limitations\n- Synth's performance may be suboptimal, especially on mobile devices.\n- [SF2 to DLS Conversion](https://github.com/spessasus/SpessaSynth/wiki/DLS-Conversion-Problem)\n- Audio may sometimes sound distorted in Chrome, Edge, Brave,\n  etc. due to a **[Chromium Bug](https://issues.chromium.org/issues/367304685).**\n  I can't do anything about it, only hope that it gets fixed.\n  Please consider voting for it on the bug tracker to get it fixed!\n\n### Installation\n#### Npm package\n```shell\nnpm install --save spessasynth_lib\n```\n#### Or\n1. Clone this repository.\n2. Copy `src/spessasynth_lib` to your project.\n3. [Use the library](https://github.com/spessasus/SpessaSynth/wiki/Home)\n\n\u003e [!TIP]\n\u003e Looking for a Node.js version? Try [spessasynth_core](https://www.npmjs.com/package/spessasynth_core)!\n\n\u003ch1 align='center'\u003eWeb App / Local Edition\u003c/h1\u003e\n\u003cp align='center'\u003eThe complete GUI for spessasynth_lib, allowing remixing, experimenting, and playing MIDIs in the coolest way possible.\u003c/p\u003e\n\n\u003cp align='center'\u003e\n\u003cimg src=\"https://github.com/spessasus/SpessaSynth/assets/95608008/e2e6c4c6-0762-4c11-8887-a2318d431854\" alt=\"SpessaSynth promotional image\" width=\"75%\"\u003e\n\u003c/p\u003e\n\u003ch3 align='center'\u003e\u003ca href='https://github.com/spessasus/SpessaSynth/wiki/How-To-Use-App'\u003eUsage Guide\u003c/a\u003e\u003c/h3\u003e\n\u003ch2 align='center'\u003eFeatures\u003c/h2\u003e\n\n- **Visualization of the played sequence:** with cool effects like visual pitch bend and note-on effects!\n- **Playable keyboard with various sizes:** mobile friendly!\n- **Integrated controller for the synthesizer with numerous options:** Edit instruments, controllers, and more!\n- **MIDI Lyrics support:** Karaoke!\n- **Kar Lyrics support:** Karaoke but fancy!\n- **ASS Subtitle support:** Karaoke but even fancier!\n- **Music player mode:** with support for album covers in .rmi files!\n- Mobile-friendly UI (*synthesizer performance not optimized for mobile... don't tell anyone!*)\n- **Multiple language support:** \n  - English\n  - Polish\n  - Japanese\n  - French (translated by Davy Triponney)\n  - Portuguese (translated by Lucas Gabriel)\n  - Custom locale management system, created specifically for this project\n- **Description of buttons:** Hover over the buttons to see what they do!\n- **`Web MIDI API` support:** Use your physical MIDI devices!\n- [WebMidiLink](https://www.g200kg.com/en/docs/webmidilink/) support\n- **Numerous exporting options:**\n  - Render the MIDI file (modified or unmodified) to .wav\n  - Render each channel as a separate .wav file\n  - Export the modified MIDI file to .mid\n  - Export the trimmed SoundFont to .sf2\n  - Export a DLS file to .sf2\n  - Export an SF2 file to .dls\n  - Or compress it as .sf3!\n  - Bundle both as .rmi with metadata such as album cover!\n- Comes bundled with a compressed [GeneralUser GS](https://schristiancollins.com/generaluser.php) SoundFont to get you started\n- No additional dependencies!\n\n\u003ch3 align='center'\u003eStill not convinced? Check out these screenshots:\u003c/h3\u003e\n\n\u003c!--\nMARKDOWN VERSION\n![image](https://github.com/user-attachments/assets/b0c9a1f3-3278-4208-8d35-f63b0943ae39)\n![image](https://github.com/user-attachments/assets/b7aeef1d-3f9a-4bff-a5cc-cdee700a8a54)\n![image](https://github.com/user-attachments/assets/7499503e-9dec-4f7c-8c58-b4960f63bc39)\n![image](https://github.com/user-attachments/assets/772c1636-26cb-4efd-a9d1-daef5f12c566)\n![image](https://github.com/user-attachments/assets/0c98f317-69d1-499c-968d-0870d9f5bec5)\n![image](https://github.com/user-attachments/assets/c57c4229-92e1-4ab3-81ef-b1162a917220)\n--\u003e\n\u003cp align='center'\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/b0c9a1f3-3278-4208-8d35-f63b0943ae39\" width=\"45%\"\u003e\u003c/img\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/b7aeef1d-3f9a-4bff-a5cc-cdee700a8a54\" width=\"45%\"\u003e\u003c/img\u003e \n\u003cimg src=\"https://github.com/user-attachments/assets/7499503e-9dec-4f7c-8c58-b4960f63bc39\" width=\"45%\"\u003e\u003c/img\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/772c1636-26cb-4efd-a9d1-daef5f12c566\" width=\"45%\"\u003e\u003c/img\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/0c98f317-69d1-499c-968d-0870d9f5bec5\" width=\"45%\"\u003e\u003c/img\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/c57c4229-92e1-4ab3-81ef-b1162a917220\" width=\"45%\"\u003e\u003c/img\u003e \n\u003c/p\u003e\n\n### Installation (Local Edition)\nLocal edition comes with easier soundfont management than the demo version.\n\n\u003e [!IMPORTANT]\n\u003e Firefox is recommended due to Chromium's Web Audio bug and memory limit.\n\u003e A decent computer is also recommended for handling large SoundFonts.\n\n[Recommended high-quality SoundFont (better than the built-in one)](https://musical-artifacts.com/artifacts/1176)\n\n**Local Edition requires Node.js**\n\n#### Windows\n1. Download the code as a ZIP file and extract, or use `git clone https://github.com/spessasus/SpessaSynth`.\n2. Put your SoundFonts into the `soundfonts` folder (you can select SoundFonts in the program).\n3. Double-click `Open SpessaSynth.bat`.\n4. Enjoy!\n\n#### Linux\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/spessasus/SpessaSynth --depth 1\n   cd SpessaSynth\n   npm start\n   ```\n2. Put your SoundFonts into the `soundfonts` folder (you can select SoundFonts in the program).\n3. Enjoy!\n\n[If you would like to help translate SpessaSynth, please read this guide (and thank you!)](src/website/js/locale/locale_files/README.md)\n\n**If you like this project, consider giving it a star. It really helps out!**\n\n#### TODO\n- Improve the performance of the worklet system\n- Potentially port the worklet system to Emscripten\n- Enhance the built-in chorus and reverb effects (suggestions welcome!)\n\n### Special Thanks\n- [FluidSynth](https://github.com/FluidSynth/fluidsynth) - for the source code that helped implement functionality and fixes\n- [Polyphone](https://www.polyphone-soundfonts.com/) - for the soundfont testing and editing tool\n- [Meltysynth](https://github.com/sinshu/meltysynth) - for the initial low-pass filter implementation\n- [RecordingBlogs](https://www.recordingblogs.com/) - for detailed explanations on MIDI messages\n- [stbvorbis.js](https://github.com/hajimehoshi/stbvorbis.js) - for the Vorbis decoder\n- [OggVorbisEncoder](https://github.com/higuma/ogg-vorbis-encoder-js) - for the MIT Vorbis encoder\n- [Composers](https://github.com/spessasus/spessasynth-demo-songs#readme) - for the demo songs\n- [Falcosoft](https://falcosoft.hu) - for help with the RMIDI format\n- [Christian Collins](https://schristiancollins.com) - for the bundled GeneralUserGS soundfont and various bug reports regarding the synthesizer\n- **And You!** - for checking out this project. I hope you like it :)\n\n### Major Releases\n- [0.0.1](https://github.com/spessasus/SpessaSynth/commit/bc5c6516ae7edc94656b5df75d254a29280caa18) - Initial release\n- [1.0.0](https://github.com/spessasus/SpessaSynth/commit/45c23d1c2906b2dec202c0533a9737bd1fa6b3c4) - Removed the 2-sample limit\n- [2.0.0](https://github.com/spessasus/SpessaSynth/commit/350e4db90210375da27e393393df743be2137d59) - Implemented the worklet system and added support for modulators\n- [3.0.0](https://github.com/spessasus/SpessaSynth/commit/b7f9e382a2f62eef462755ac9ebfe603663e4106) - Moved to audioWorkletGlobalScope for offline audio rendering\n\n### License\nCopyright © 2025 Spessasus. Licensed under the MIT License.\n\n\u003e [!IMPORTANT]\n\u003e Please note that the bundled [stbvorbis_sync.js](https://github.com/spessasus/stbvorbis_sync.js) is licensed under the Apache-2.0 license.\n\u003e The license and the file can be found in the `externals` folder in the spessasynth_lib directory.\n\n#### Legal\nThis project is in no way endorsed or otherwise affiliated with the MIDI Manufacturers Association,\nCreative Technology Ltd. or E-mu Systems, Inc., or any other organization mentioned.\nSoundFont® is a registered trademark of Creative Technology Ltd.\nAll other trademarks are the property of their respective owners.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspessasus%2FSpessaSynth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspessasus%2FSpessaSynth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspessasus%2FSpessaSynth/lists"}