BasicSoundBank¶

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

It also contains support for .dls files and experimental read support for 64-bit SFE

Specifications¶

• SoundFont2 Specification
• SoundFont3 Description
• DLS Level 2 Specification

Initialization¶

1

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.

type¶

The type of the sound bank that was loaded, either sf2 or dls.

soundBankInfo¶

The metadata of this sound bank as an object with properties 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.

soundEngine¶

The sound engine name.

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. (SF2 only)

romVersion¶

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

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.

1
2
3
4
5

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.

getSampleSoundBankFile¶

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

1

const sfBinary = BasicSoundBank.getSampleSoundBankFile();

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

copyFrom¶

Copies a given sound bank.

1

BasicSoundBank.copyFrom(bank);

• bank - the bank to copy.

addCompletePresets¶

Adds complete presets along with their instruments and samples.

1

bank.addCompletePresets(presets);

• presets - an array of BasicPresets to add.

setSampleFormat¶

Sets the sound bank's sample format in place.

1

await soundBank.setSampleFormat(options);

• options - An optional object (all properties are optional):
  • format - The sample format to use:
    • pcm - decompresses the sound bank and changes its version to 2.04 (SF2)
    • compressed - compresses the sound bank with a given function and changes its version to 3.0 (SF3)
  • compressionFunction - See this for a detailed explanation. It can be undefined if the format is pcm.
  • progressFunction - See this for a detailed explanation

writeDLS¶

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

1

const dls = soundBank.writeDLS(options);

• options - An optional object (all properties are optional):
  • progressFunction - See this for a detailed explanation
  • software - A string, the ISFT field to set when writing. If unset, "SpessaSynth" is written. This field indicates the last software that was used to edit this sound bank.

writeSF2¶

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

1

const binary = soundBank.writeSF2(options);

• options - An optional object (all properties are optional):
  • 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.
  • progressFunction - See this for a detailed explanation
  • software - A string, the ISFT field to set when writing. If unset, "SpessaSynth" is written. This field indicates the last software that was used to edit this sound bank.

writeSFE¶

Writes the sound bank as an SFE 4 file. This enables features such as bank LSB and RIFF64.

1

const binary = soundBank.writeSFE(options);

• options - An optional object (all properties are optional):
  • progressFunction - See this for a detailed explanation
  • software - A string, the ISFT field to set when writing. If unset, "SpessaSynth" is written. This field indicates the last software that was used to edit this sound bank.
  • rf64 - If the RIFS (64-bit RIFF chunks) should be used. Increases maximum size from 4GB to effectively infinite. Recommended, since SFE 4 is effectively incompatible with SF2.

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.

trim¶

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

1

soundBank.trim(presetData);

• presetData - PresetWithKeyCombinations which is Map<BasicPreset, Map<number, Set<number>>. Absent presets will be removed from the sound bank, and samples that don't get activated in the remaining presets will be removed as well.

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.

1

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 for operations that take a long time (for example sample writing). It can be useful for displaying progress for long writing operations.

It takes the following arguments:

• progress - number - the estimated progress of writing.

Please note that it's usually only effective when writing with compression, as raw writing is inlined for speed. If you are writing from a separate thread (e.g. a worker thread), then even inlined writing should show progress.

compressionFunction¶

This function must be provided if compressed format is chosen.

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.

Import your function:

1
2

// Example name, yours will be different
import { encodeVorbis } from "./libvorbis/encode_vorbis.js";

Then pass it to the compressing method:

1
2
3
4

await soundBank.setSampleFormat({
    format: "compressed",
    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.