spessasynth_lib 3.23.11 → 3.23.13

package/index.js

@@ -1,6 +1,13 @@
 // Import modules
 import { loadSoundFont } from "./soundfont/load_soundfont.js";
 import { BasicSoundFont } from "./soundfont/basic_soundfont/basic_soundfont.js";
+import { BasicSample } from "./soundfont/basic_soundfont/basic_sample.js";
+import { BasicInstrumentZone } from "./soundfont/basic_soundfont/basic_zones.js";
+import { BasicInstrument } from "./soundfont/basic_soundfont/basic_instrument.js";
+import { Generator } from "./soundfont/basic_soundfont/generator.js";
+import { Modulator } from "./soundfont/basic_soundfont/modulator.js";
+import { BasicPresetZone } from "./soundfont/basic_soundfont/basic_zones.js";
+import { BasicPreset } from "./soundfont/basic_soundfont/basic_preset.js";
 import { MIDI } from './midi_parser/midi_loader.js';
 import { MIDIticksToSeconds } from './midi_parser/basic_midi.js';
 import { MIDIBuilder } from "./midi_parser/midi_builder.js";
@@ -38,13 +45,20 @@ export {
     Synthetizer,
     DEFAULT_PERCUSSION,
     VOICE_CAP,
-
+    
     // SoundFont
     BasicSoundFont,
+    BasicSample,
+    BasicInstrumentZone,
+    BasicInstrument,
+    BasicPreset,
+    BasicPresetZone,
+    Generator,
+    Modulator,
     loadSoundFont,
     trimSoundfont,
     modulatorSources,
-
+    
     // MIDI
     MIDI,
     MIDIBuilder,
@@ -54,7 +68,7 @@ export {
     applySnapshotToMIDI,
     modifyMIDI,
     MIDIticksToSeconds,
-
+    
     // Utilities
     audioBufferToWav,
     SpessaSynthLogging,

package/midi_parser/basic_midi.js

@@ -1,111 +1,14 @@
 import { messageTypes } from "./midi_message.js";
 import { readBytesAsUintBigEndian } from "../utils/byte_functions/big_endian.js";
+import { MIDISequenceData } from "./midi_sequence.js";
 
-export class BasicMIDI
+/**
+ * BasicMIDI is the base of a complete MIDI file, used by the sequencer internally.
+ * BasicMIDI is not available on the main thread, as it contains the actual track data which can be large.
+ * It can be accessed by calling getMIDI() on the Sequencer.
+ */
+export class BasicMIDI extends MIDISequenceData
 {
-    /**
-     * The time division of the sequence, representing the number of ticks per beat.
-     * @type {number}
-     */
-    timeDivision = 0;
-    
-    /**
-     * The duration of the sequence, in seconds.
-     * @type {number}
-     */
-    duration = 0;
-    
-    /**
-     * The tempo changes in the sequence, ordered from the last change to the first.
-     * Each change is represented by an object with a tick position and a tempo value in beats per minute.
-     * @type {{ticks: number, tempo: number}[]}
-     */
-    tempoChanges = [{ ticks: 0, tempo: 120 }];
-    
-    /**
-     * A string containing the copyright information for the MIDI sequence if detected.
-     * @type {string}
-     */
-    copyright = "";
-    
-    /**
-     * The number of tracks in the MIDI sequence.
-     * @type {number}
-     */
-    tracksAmount = 0;
-    
-    /**
-     * An array containing the lyrics of the sequence, stored as binary chunks (Uint8Array).
-     * @type {Uint8Array[]}
-     */
-    lyrics = [];
-    
-    /**
-     * The tick position of the first note-on event in the MIDI sequence.
-     * @type {number}
-     */
-    firstNoteOn = 0;
-    
-    /**
-     * The MIDI key range used in the sequence, represented by a minimum and maximum note value.
-     * @type {{min: number, max: number}}
-     */
-    keyRange = { min: 0, max: 127 };
-    
-    /**
-     * The tick position of the last voice event (such as note-on, note-off, or control change) in the sequence.
-     * @type {number}
-     */
-    lastVoiceEventTick = 0;
-    
-    /**
-     * An array of MIDI port numbers used by each track in the sequence.
-     * @type {number[]}
-     */
-    midiPorts = [0];
-    
-    /**
-     * An array of channel offsets for each MIDI port, using the SpessaSynth method.
-     * @type {number[]}
-     */
-    midiPortChannelOffsets = [0];
-    
-    /**
-     * A list of sets, where each set contains the MIDI channels used by each track in the sequence.
-     * @type {Set<number>[]}
-     */
-    usedChannelsOnTrack = [];
-    
-    /**
-     * The loop points (in ticks) of the sequence, including both start and end points.
-     * @type {{start: number, end: number}}
-     */
-    loop = { start: 0, end: 0 };
-    
-    /**
-     * The name of the MIDI sequence.
-     * @type {string}
-     */
-    midiName = "";
-    
-    /**
-     * A boolean indicating if the sequence's name is the same as the file name.
-     * @type {boolean}
-     */
-    midiNameUsesFileName = false;
-    
-    /**
-     * The file name of the MIDI sequence, if provided during parsing.
-     * @type {string}
-     */
-    fileName = "";
-    
-    /**
-     * The raw, encoded MIDI name, represented as a Uint8Array.
-     * Useful when the MIDI file uses a different code page.
-     * @type {Uint8Array}
-     */
-    rawMidiName = undefined;
     
     /**
      * The embedded soundfont in the MIDI file, represented as an ArrayBuffer, if available.
@@ -113,26 +16,6 @@ export class BasicMIDI
      */
     embeddedSoundFont = undefined;
     
-    /**
-     * The format of the MIDI file, which can be 0, 1, or 2, indicating the type of the MIDI file.
-     * @type {number}
-     */
-    format = 0;
-    
-    /**
-     * The RMID (Resource Interchangeable MIDI) info data, if the file is RMID formatted.
-     * Otherwise, this field is undefined.
-     * Chunk type (e.g. "INAM"): Chunk data as binary array.
-     * @type {Object<string, IndexedByteArray>}
-     */
-    RMIDInfo = {};
-    
-    /**
-     * The bank offset used for RMID files.
-     * @type {number}
-     */
-    bankOffset = 0;
-    
     /**
      * The actual track data of the MIDI file, represented as an array of tracks.
      * Tracks are arrays of MidiMessage objects.

package/midi_parser/midi_builder.js

@@ -3,6 +3,9 @@ import { messageTypes, MidiMessage } from "./midi_message.js";
 import { IndexedByteArray } from "../utils/indexed_array.js";
 import { SpessaSynthWarn } from "../utils/loggin.js";
 
+/**
+ * A class that helps to build a MIDI file from scratch.
+ */
 export class MIDIBuilder extends BasicMIDI
 {
     /**

package/midi_parser/midi_data.js

@@ -1,111 +1,12 @@
+import { MIDISequenceData } from "./midi_sequence.js";
+
 /**
- * A simplified version of the MIDI, accessible at all times from the Sequencer. use getMIDI() to get the actual sequence
- * This class contains all properties that MIDI does, except for tracks, which is the track data.
+ * A simplified version of the MIDI, accessible at all times from the Sequencer.
+ * Use getMIDI() to get the actual sequence.
+ * This class contains all properties that MIDI does, except for tracks and the embedded soundfont.
  */
-export class MidiData
+export class MidiData extends MIDISequenceData
 {
-    /**
-     * The time division of the sequence, representing the number of ticks per beat.
-     * @type {number}
-     */
-    timeDivision = 0;
-    
-    /**
-     * The duration of the sequence, in seconds.
-     * @type {number}
-     */
-    duration = 0;
-    
-    /**
-     * The tempo changes in the sequence, ordered from the last change to the first.
-     * Each change is represented by an object with a tick position and a tempo value in beats per minute.
-     * @type {{ticks: number, tempo: number}[]}
-     */
-    tempoChanges = [{ ticks: 0, tempo: 120 }];
-    
-    /**
-     * A string containing the copyright information for the MIDI sequence.
-     * @type {string}
-     */
-    copyright = "";
-    
-    /**
-     * The number of tracks in the MIDI sequence.
-     * @type {number}
-     */
-    tracksAmount = 0;
-    
-    /**
-     * An array containing the lyrics of the sequence, stored as binary chunks (Uint8Array).
-     * @type {Uint8Array[]}
-     */
-    lyrics = [];
-    
-    /**
-     * The tick position of the first note-on event in the MIDI sequence.
-     * @type {number}
-     */
-    firstNoteOn = 0;
-    
-    /**
-     * The MIDI key range used in the sequence, represented by a minimum and maximum note value.
-     * @type {{min: number, max: number}}
-     */
-    keyRange = { min: 0, max: 127 };
-    
-    /**
-     * The tick position of the last voice event (such as note-on, note-off, or control change) in the sequence.
-     * @type {number}
-     */
-    lastVoiceEventTick = 0;
-    
-    /**
-     * An array of MIDI port numbers used by each track in the sequence.
-     * @type {number[]}
-     */
-    midiPorts = [0];
-    
-    /**
-     * An array of channel offsets for each MIDI port, using the SpessaSynth method.
-     * @type {number[]}
-     */
-    midiPortChannelOffsets = [0];
-    
-    /**
-     * A list of sets, where each set contains the MIDI channels used by each track in the sequence.
-     * @type {Set<number>[]}
-     */
-    usedChannelsOnTrack = [];
-    
-    /**
-     * The loop points (in ticks) of the sequence, including both start and end points.
-     * @type {{start: number, end: number}}
-     */
-    loop = { start: 0, end: 0 };
-    
-    /**
-     * The name of the MIDI sequence.
-     * @type {string}
-     */
-    midiName = "";
-    
-    /**
-     * A boolean indicating if the sequence's name is the same as the file name.
-     * @type {boolean}
-     */
-    midiNameUsesFileName = false;
-    
-    /**
-     * The file name of the MIDI sequence, if provided by the MIDI class.
-     * @type {string}
-     */
-    fileName = "";
-    
-    /**
-     * The raw, encoded MIDI name, represented as a Uint8Array.
-     * @type {Uint8Array}
-     */
-    rawMidiName = undefined;
     
     /**
      * A boolean indicating if the MIDI file contains an embedded soundfont.
@@ -115,30 +16,12 @@ export class MidiData
     isEmbedded = false;
     
     /**
-     * The MIDI file's format, which can be 0, 1, or 2, indicating the type of the MIDI file.
-     * @type {number}
-     */
-    format = 0;
-    
-    /**
-     * The RMID (Resource Interchangeable MIDI) info data, if the file is RMID formatted.
-     * Otherwise, this field is undefined.
-     * @type {Object<string, IndexedByteArray>}
-     */
-    RMIDInfo = {};
-    
-    /**
-     * The bank offset used for RMID files.
-     * @type {number}
-     */
-    bankOffset = 0;
-    
-    /**
-     * Constructor that copies data from a BasicMIDI instance, except for tracks and embeddedSoundFont.
+     * Constructor that copies data from a BasicMIDI instance.
      * @param {BasicMIDI} midi - The BasicMIDI instance to copy data from.
      */
     constructor(midi)
     {
+        super();
         this.timeDivision = midi.timeDivision;
         this.duration = midi.duration;
         this.tempoChanges = midi.tempoChanges;
@@ -167,7 +50,7 @@ export class MidiData
 
 
 /**
- *
+ * Temporary MIDI data used when the MIDI is not loaded.
  * @type {MidiData}
  */
 export const DUMMY_MIDI_DATA = {
@@ -194,5 +77,6 @@ export const DUMMY_MIDI_DATA = {
     isEmbedded: false,
     RMIDInfo: {},
     bankOffset: 0,
-    midiNameUsesFileName: false
+    midiNameUsesFileName: false,
+    format: 0
 };

package/midi_parser/midi_editor.js

@@ -75,24 +75,38 @@ function getDrumChange(channel, ticks)
 }
 
 /**
- * Allows easy editing of the file
- * @param midi {BasicMIDI}
- * @param desiredProgramChanges {{
- *     channel: number,
- *     program: number,
- *     bank: number,
- *     isDrum: boolean
- * }[]} the programs to set on given channels. Note that the channel may be more than 16, function will adjust midi ports automatically
- * @param desiredControllerChanges {{
- *     channel: number,
- *     controllerNumber: number,
- *     controllerValue: number,
- * }[]} the controllers to set on given channels. Note that the channel may be more than 16, function will adjust midi ports automatically
- * @param desiredChannelsToClear {number[]} the channels to remove from the sequence. Note that the channel may be more than 16, function will adjust midi ports automatically
- * @param desiredChannelsToTranspose {{
- *     channel: number,
- *     keyShift: number
- * }[]} the channels to transpose. if keyShift is float, rpn fine tuning will be applied as well. Note that the channel may be more than 16, function will adjust midi ports automatically
+ * @typedef {Object} DesiredProgramChange
+ * @property {number} channel - The channel number.
+ * @property {number} program - The program number.
+ * @property {number} bank - The bank number.
+ * @property {boolean} isDrum - Indicates if the channel is a drum channel.
+ * If it is, then the bank number is ignored.
+ */
+
+/**
+ * @typedef {Object} DesiredControllerChange
+ * @property {number} channel - The channel number.
+ * @property {number} controllerNumber - The MIDI controller number.
+ * @property {number} controllerValue - The new controller value.
+ */
+
+/**
+ * @typedef {Object} DesiredChanneltranspose
+ * @property {number} channel - The channel number.
+ * @property {number} keyShift - The number of semitones to transpose.
+ * Note that this can use floating point numbers,
+ * which will be used to fine-tune the pitch in cents using RPN.
+ */
+
+/**
+ * Allows easy editing of the file by removing channels, changing programs,
+ * changing controllers and transposing channels. Note that this modifies the MIDI in-place.
+ *
+ * @param {BasicMIDI} midi - The MIDI file to modify.
+ * @param {DesiredProgramChange[]} desiredProgramChanges - The programs to set on given channels.
+ * @param {DesiredControllerChange[]} desiredControllerChanges - The controllers to set on given channels.
+ * @param {number[]} desiredChannelsToClear - The channels to remove from the sequence.
+ * @param {DesiredChanneltranspose[]} desiredChannelsToTranspose - The channels to transpose.
  */
 export function modifyMIDI(
     midi,

package/midi_parser/midi_loader.js

@@ -17,6 +17,11 @@ const GS_TEXT_HEADER = new Uint8Array([0x41, 0x10, 0x45, 0x12, 0x10, 0x00, 0x00]
  * midi_loader.js
  * purpose: parses a midi file for the seqyencer, including things like marker or CC 2/4 loop detection, copyright detection etc.
  */
+
+/**
+ * The MIDI class is a MIDI file parser that reads a MIDI file and extracts all the necessary information from it.
+ * Supported formats are .mid and .rmi files.
+ */
 class MIDI extends BasicMIDI
 {
     /**

package/midi_parser/midi_sequence.js

@@ -0,0 +1,133 @@
+/**
+ * This is the base type for MIDI files. It contains all the "metadata" and information.
+ * It extends to:
+ * - BasicMIDI, which contains the actual track data of the MIDI file. Essentially the MIDI file itself.
+ * - MidiData, which contains all properties that MIDI does, except for tracks and the embedded soundfont.
+ * MidiData is the "shell" of the file which is available on the main thread at all times, containing the metadata.
+ */
+export class MIDISequenceData
+{
+    /**
+     * The time division of the sequence, representing the number of ticks per beat.
+     * @type {number}
+     */
+    timeDivision = 0;
+    
+    /**
+     * The duration of the sequence, in seconds.
+     * @type {number}
+     */
+    duration = 0;
+    
+    /**
+     * The tempo changes in the sequence, ordered from the last change to the first.
+     * Each change is represented by an object with a tick position and a tempo value in beats per minute.
+     * @type {{ticks: number, tempo: number}[]}
+     */
+    tempoChanges = [{ ticks: 0, tempo: 120 }];
+    
+    /**
+     * A string containing the copyright information for the MIDI sequence if detected.
+     * @type {string}
+     */
+    copyright = "";
+    
+    /**
+     * The number of tracks in the MIDI sequence.
+     * @type {number}
+     */
+    tracksAmount = 0;
+    
+    /**
+     * An array containing the lyrics of the sequence, stored as binary chunks (Uint8Array).
+     * @type {Uint8Array[]}
+     */
+    lyrics = [];
+    
+    /**
+     * The tick position of the first note-on event in the MIDI sequence.
+     * @type {number}
+     */
+    firstNoteOn = 0;
+    
+    /**
+     * The MIDI key range used in the sequence, represented by a minimum and maximum note value.
+     * @type {{min: number, max: number}}
+     */
+    keyRange = { min: 0, max: 127 };
+    
+    /**
+     * The tick position of the last voice event (such as note-on, note-off, or control change) in the sequence.
+     * @type {number}
+     */
+    lastVoiceEventTick = 0;
+    
+    /**
+     * An array of MIDI port numbers used by each track in the sequence.
+     * @type {number[]}
+     */
+    midiPorts = [0];
+    
+    /**
+     * An array of channel offsets for each MIDI port, using the SpessaSynth method.
+     * @type {number[]}
+     */
+    midiPortChannelOffsets = [0];
+    
+    /**
+     * A list of sets, where each set contains the MIDI channels used by each track in the sequence.
+     * @type {Set<number>[]}
+     */
+    usedChannelsOnTrack = [];
+    
+    /**
+     * The loop points (in ticks) of the sequence, including both start and end points.
+     * @type {{start: number, end: number}}
+     */
+    loop = { start: 0, end: 0 };
+    
+    /**
+     * The name of the MIDI sequence.
+     * @type {string}
+     */
+    midiName = "";
+    
+    /**
+     * A boolean indicating if the sequence's name is the same as the file name.
+     * @type {boolean}
+     */
+    midiNameUsesFileName = false;
+    
+    /**
+     * The file name of the MIDI sequence, if provided during parsing.
+     * @type {string}
+     */
+    fileName = "";
+    
+    /**
+     * The raw, encoded MIDI name, represented as a Uint8Array.
+     * Useful when the MIDI file uses a different code page.
+     * @type {Uint8Array}
+     */
+    rawMidiName = undefined;
+    
+    /**
+     * The format of the MIDI file, which can be 0, 1, or 2, indicating the type of the MIDI file.
+     * @type {number}
+     */
+    format = 0;
+    
+    /**
+     * The RMID (Resource Interchangeable MIDI) info data, if the file is RMID formatted.
+     * Otherwise, this field is undefined.
+     * Chunk type (e.g. "INAM"): Chunk data as binary array.
+     * @type {Object<string, IndexedByteArray>}
+     */
+    RMIDInfo = {};
+    
+    /**
+     * The bank offset used for RMID files.
+     * @type {number}
+     */
+    bankOffset = 0;
+}

package/midi_parser/midi_writer.js

@@ -4,11 +4,15 @@ import { writeBytesAsUintBigEndian } from "../utils/byte_functions/big_endian.js
 
 /**
  * Exports the midi as a .mid file
- * @param midi {BasicMIDI}
+ * @param midi {BasicMIDI} the midi to export
  * @returns {Uint8Array} the binary .mid file data
  */
 export function writeMIDIFile(midi)
 {
+    if (!midi.tracks)
+    {
+        throw new Error("MIDI has no tracks!");
+    }
     /**
      * @type {Uint8Array[]}
      */

package/midi_parser/rmidi_writer.js

@@ -15,6 +15,7 @@ import { writeLittleEndian } from "../utils/byte_functions/little_endian.js";
 export const RMIDINFOChunks = {
     name: "INAM",
     album: "IPRD",
+    album2: "IALB",
     artist: "IART",
     genre: "IGNR",
     picture: "IPIC",
@@ -371,7 +372,7 @@ export function writeRMIDI(
      */
     const infoContent = [getStringBytes("INFO")];
     const encoder = new TextEncoder();
-    // software
+    // software (SpessaSynth)
     infoContent.push(
         writeRIFFOddSize(RMIDINFOChunks.software, encoder.encode("SpessaSynth"), true)
     );
@@ -430,10 +431,14 @@ export function writeRMIDI(
     // album
     if (metadata.album !== undefined)
     {
+        // note that there are two album chunks: IPRD and IALB
         encoding = FORCED_ENCODING;
         infoContent.push(
             writeRIFFOddSize(RMIDINFOChunks.album, encoder.encode(metadata.album), true)
         );
+        infoContent.push(
+            writeRIFFOddSize(RMIDINFOChunks.album2, encoder.encode(metadata.album), true)
+        );
     }
     // artist
     if (metadata.artist !== undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spessasynth_lib",
-  "version": "3.23.11",
+  "version": "3.23.13",
   "description": "MIDI and SoundFont2/DLS library with no compromises",
   "browser": "index.js",
   "types": "@types/index.d.ts",

package/sequencer/sequencer.js

@@ -61,8 +61,10 @@ export class Sequencer
     onSongChange = {};
     /**
      * Fires on text event
+     * @type {function}
      * @param data {Uint8Array} the data text
      * @param type {number} the status byte of the message (the meta status byte)
+     * @param lyricsIndex {number} if the text is a lyric, the index of the lyric in midiData.lyrics, otherwise -1
      */
     onTextEvent;
     /**
@@ -304,7 +306,6 @@ export class Sequencer
     addOnSongChangeEvent(callback, id)
     {
         this.onSongChange[id] = callback;
-        callback(this.midiData);
     }
     
     /**
@@ -419,13 +420,9 @@ export class Sequencer
                 break;
             
             case WorkletSequencerReturnMessageType.textEvent:
-                /**
-                 * @type {[Uint8Array, number]}
-                 */
-                let textEventData = messageData;
                 if (this.onTextEvent)
                 {
-                    this.onTextEvent(textEventData[0], textEventData[1]);
+                    this.onTextEvent(...(messageData));
                 }
                 break;
             

package/sequencer/worklet_sequencer/process_event.js

@@ -117,7 +117,18 @@ export function _processEvent(event, trackIndex)
         case messageTypes.cuePoint:
         case messageTypes.instrumentName:
         case messageTypes.programName:
-            this.post(WorkletSequencerReturnMessageType.textEvent, [event.messageData, statusByteData.status]);
+            let lyricsIndex = -1;
+            if (statusByteData.status === messageTypes.lyric)
+            {
+                lyricsIndex = Math.min(
+                    this.midiData.lyrics.indexOf(event.messageData) + 1,
+                    this.midiData.lyrics.length - 1
+                );
+            }
+            this.post(
+                WorkletSequencerReturnMessageType.textEvent,
+                [event.messageData, statusByteData.status, lyricsIndex]
+            );
             break;
         
         case messageTypes.midiPort: