BasicSoundBank

This module handles parsing and writing SoundFont2 (.sf2, .sf3 and .sfogg) files.

It also contains support for .dls files.

Tip

If you encounter any errors in this documentation, please open an issue!

Specifications

• SoundFont2 Specification
• SoundFont3 Description
• DLS Level 2 Specification

Initialization

const soundBank = SoundBankLoader.fromArrayBuffer(buffer);

• buffer - An ArrayBuffer representing the binary file data either DLS level 1/2 or SoundFont2.

The returned value is the parsed BasicSoundBank, described below.

Properties

isSF3DecoderReady

A Promise object indicating if the SF3/SF2Pack decoder is ready. Make sure to await it if you are loading SF3/SF2Pack files. It only needs to be awaited once, globally. Then all banks can be loaded synchronously.

Note

this property is static.

soundBankInfo

The metadata of this sound bank, described below

name

The sound bank’s name.

version

The sound bank’s version, stored as an object: - major - the major revision, number. - minor - the minor revision, number.

creationDate

The creation date of this sound bank, a Date object.

Note

Note that if the date text is invalid, the current date will be used instead. If you have a valid date in your sound bank, and it still fails to parse, please open an issue!

soundEngine

The sound engine name

Note

The other properties of soundBankInfo listed below are all optional!

engineer

The engineer (creator) of the sound bank

product

The product information.

copyright

The copyright information.

comment

The comment, usually the description.

subject

The subject of the file. This only appears in DLS files.

romInfo

ROM Bank information.

romVersion

A tag that only applies to SF2 and will usually be undefined.

Stored like the version field.

software

Software used to edit the file.

presets

An array of all presets in the bank, ordered by bank and preset number. An array of BasicPresets.

instruments

An array of all instruments in the bank. An array of BasicInstruments.

samples

An array of all samples in the bank. An array of BasicSamples.

defaultModulators

All the default modulators for this bank. A list of Modulators

customDefaultModulators

A boolean, indicating if the bank uses the DMOD chunk.

isXGBank

Checks for XG drum sets and considers if this sound bank is XG-compatible.

Methods

mergeSoundBanks

Merges multiple sound banks, adding (not replacing) presets on top of the previous ones, and returns a new soundBank.

BasicSoundBank.mergeSoundBanks(soundbank1, soundbank2, soundbank3, /* more here... */);

• parameters - BasicSoundBank instances. The first is used as a base, and the rest are added on top.

The return value is a new BasicSoundBank.

The INFO data is taken from the first sound bank.

Note

This method is static.

getDummySoundBankFile

Creates a simple sound bank with a single saw wave preset.

const sfBinary = await BasicSoundBank.getDummySoundBankFile();

The returned value is an ArrayBuffer - the binary representation of an .sf2 file.

Note

This method is static and asynchronous

copyFrom

Copies a given sound bank.

BasicSoundBank.copyFrom(bank);

• bank - the bank to copy.

addCompletePresets

Adds complete presets along with their instruments and samples.

bank.addCompletePresets(presets);

• presets - an array of BasicPresets to add.

writeDLS

Writes out a DLS Level 2 sound bank. The returned value is an ArrayBuffer - the binary of the file.

const dls = await soundBank.writeDLS(options);

• options - An optional object:
  • progressFunction - See this for a detailed explanation

Danger

This method is limited. See this for more info.

Important

This method is asynchronous.

Warning

This method is memory and CPU intensive with large sound banks.

writeSF2

Write out an SF2 or SF3 file. The return value is an ArrayBuffer - the binary of the file.

const binary = await soundBank.writeSF2(options);

• options - An optional object:
  • writeDefaultModulators - a boolean indicating if the DMOD chunk should be written. Defaults to true.
  • writeExtendedLimits - if the xdta chunk should be written to allow virtually infinite parameters. Defaults to true.
  • compress - A boolean indicating if any uncompressed samples should be compressed using the lossy Ogg Vorbis codec. This significantly reduces file size. Defaults to false.
  • decompress - A boolean indicating if any compressed samples should be decompressed. If false, the compressed samples are preserved which results in faster write time and no quality loss. Defaults to false and not recommended.
  • progressFunction - See this for a detailed explanation
  • compressionFunction - See this for a detailed explanation

Important

This method is asynchronous.

Note

If the sound bank was already compressed, it will not be decompressed to avoid losing quality.

Warning

This method is memory and CPU intensive with large sound banks, especially if compression is enabled.

addPresets

Adds presets to the sound bank.

addInstruments

Adds instruments to the sound bank.

addSamples

Adds samples to the sound bank.

cloneSample

Clones the sample into this sound bank.

• sample - the sample to copy.

Returns the copied sample, if a sample exists with that name, it is returned instead.

cloneInstrument

Recursively clones an instrument into this sound bank, as well as its samples.

• instrument - the instrument to copy.

Returns the copied instrument, if an instrument exists with that name, it is returned instead.

clonePreset

Recursively clones a preset into this sound bank, as well as its instruments and samples.

• preset - the preset to copy.

Returns the copied preset, if a preset exists with that name, it is returned instead.

flush

Updates internal values. Call after updating the preset list.

trimSoundBank

Trims a sound bank to only contain samples in a given MIDI file.

soundBank.trimSoundBank(midi);

• midi - BasicMIDI - The MIDI file for which to trim the soundBank.

removeUnusedElements

Removes all unused elements (samples and instruments)

deleteInstrument

Deletes a given instrument from the sound bank.

deletePreset

Deletes a given preset from the sound bank.

deleteSample

Deletes a given sample from the sound bank.

getPreset

Returns the matching BasicPreset class instance.

soundBank.getPreset(patch, system);

• patch - the MIDI Patch to select.
• system - the MIDI system to select for (gm, gs, xg, gm2). If you’re unsure, pick gs.

destroySoundBank

Deletes everything irreversibly.

Extra info

progressFunction

This optional function gets called after every sample has been written. It can be useful for displaying progress for long writing operations.

It takes the following arguments:

• name - string - sample’s name.
• writtenCount - number - the count of written samples so far.
• totalSampleCount - number - the total number of samples.

Please note that it’s usually only effective when writing with compression, as raw writing is inlined for speed.

compressionFunction

This function must be provided if compress is enabled.

The function takes the following arguments:

• audioData: a Float32Array with the sample data.
• sampleRate: in Hertz.

The function is recommended to be asynchronous. It must return an Uint8Array instance containing the compressed bitstream.

Note

Note that using a custom function allows for using any type of compression for the SF3 soundBank. This is allowed by the RFC describing SF3 spec, but SpessaSynth can only read Ogg Vorbis compression.

Import your function:

import {encodeVorbis} from './libvorbis/encode_vorbis.js'; // adjust the path if necessary

Then pass it to the write method:

const file = await soundBank.writeSF2({
    compress: true,
    compressionFunction: encodeVorbis
});

Why is it not bundled?

Importing it into the package would increase the size with the entire 1.1MB encoder, which would be unnecessary if the functionality is not used. This approach ensures that only software that uses this functionality can rely on this large file.