spessasynth_core 1.1.3 → 1.1.4

package/{spessasynth_core/soundfont/chunk → src/soundfont/read_sf2}/zones.js

@@ -1,102 +1,96 @@
-import {readBytesAsUintLittleEndian} from "../../utils/byte_functions.js";
-import {ShiftableByteArray} from "../../utils/shiftable_array.js";
-import {RiffChunk} from "./riff_chunk.js";
-import {Generator, generatorTypes} from "./generators.js";
-import {Sample} from "./samples.js";
-import {Instrument} from "./instruments.js";
-import {Modulator} from "./modulators.js";
+import { readLittleEndian } from "../../utils/byte_functions/little_endian.js";
+import { IndexedByteArray } from "../../utils/indexed_array.js";
+import { RiffChunk } from "../basic_soundfont/riff_chunk.js";
+import { BasicInstrumentZone, BasicPresetZone } from "../basic_soundfont/basic_zones.js";
+import { Generator, generatorTypes } from "../basic_soundfont/generator.js";
+import { Modulator } from "../basic_soundfont/modulator.js";
 
 /**
  * zones.js
  * purpose: reads instrumend and preset zones from soundfont and gets their respective samples and generators and modulators
  */
 
-export class InstrumentZone {
+export class InstrumentZone extends BasicInstrumentZone
+{
     /**
      * Creates a zone (instrument)
-     * @param dataArray {ShiftableByteArray}
+     * @param dataArray {IndexedByteArray}
      */
-    constructor(dataArray) {
-        this.generatorZoneStartIndex = readBytesAsUintLittleEndian(dataArray, 2);
-        this.modulatorZoneStartIndex = readBytesAsUintLittleEndian(dataArray, 2);
+    constructor(dataArray)
+    {
+        super();
+        this.generatorZoneStartIndex = readLittleEndian(dataArray, 2);
+        this.modulatorZoneStartIndex = readLittleEndian(dataArray, 2);
         this.modulatorZoneSize = 0;
         this.generatorZoneSize = 0;
-        this.keyRange = {min: 0, max: 127};
-        this.velRange = {min: 0, max: 127}
         this.isGlobal = true;
-        /**
-         * @type {Generator[]}
-         */
-        this.generators = [];
-        /**
-         * @type {Modulator[]}
-         */
-        this.modulators = [];
     }
-
+    
     setZoneSize(modulatorZoneSize, generatorZoneSize)
     {
         this.modulatorZoneSize = modulatorZoneSize;
         this.generatorZoneSize = generatorZoneSize;
     }
-
+    
     /**
      * grab the generators
      * @param generators {Generator[]}
      */
     getGenerators(generators)
     {
-        for(let i = this.generatorZoneStartIndex; i < this.generatorZoneStartIndex + this.generatorZoneSize; i++)
+        for (let i = this.generatorZoneStartIndex; i < this.generatorZoneStartIndex + this.generatorZoneSize; i++)
         {
             this.generators.push(generators[i]);
         }
     }
-
+    
     /**
      * grab the modulators
      * @param modulators {Modulator[]}
      */
     getModulators(modulators)
     {
-        for(let i = this.modulatorZoneStartIndex; i < this.modulatorZoneStartIndex + this.modulatorZoneSize; i++)
+        for (let i = this.modulatorZoneStartIndex; i < this.modulatorZoneStartIndex + this.modulatorZoneSize; i++)
         {
             this.modulators.push(modulators[i]);
         }
     }
-
+    
     /**
      * Loads the zone's sample
-     * @param samples {Sample[]}
+     * @param samples {BasicSample[]}
      */
-    getSample(samples) {
+    getSample(samples)
+    {
         let sampleID = this.generators.find(g => g.generatorType === generatorTypes.sampleID);
         if (sampleID)
         {
             this.sample = samples[sampleID.generatorValue];
             this.isGlobal = false;
+            this.sample.useCount++;
         }
     }
-
+    
     /**
      * Reads the keyRange of the zone
      */
     getKeyRange()
     {
         let range = this.generators.find(g => g.generatorType === generatorTypes.keyRange);
-        if(range)
+        if (range)
         {
             this.keyRange.min = range.generatorValue & 0x7F;
             this.keyRange.max = (range.generatorValue >> 8) & 0x7F;
         }
     }
-
+    
     /**
      * reads the velolicty range of the zone
      */
     getVelRange()
     {
         let range = this.generators.find(g => g.generatorType === generatorTypes.velRange);
-        if(range)
+        if (range)
         {
             this.velRange.min = range.generatorValue & 0x7F;
             this.velRange.max = (range.generatorValue >> 8) & 0x7F;
@@ -105,11 +99,11 @@ export class InstrumentZone {
 }
 
 /**
- * Reads the given instrument zone chunk
+ * Reads the given instrument zone read
  * @param zonesChunk {RiffChunk}
  * @param instrumentGenerators {Generator[]}
  * @param instrumentModulators {Modulator[]}
- * @param instrumentSamples {Sample[]}
+ * @param instrumentSamples {BasicSample[]}
  * @returns {InstrumentZone[]}
  */
 export function readInstrumentZones(zonesChunk, instrumentGenerators, instrumentModulators, instrumentSamples)
@@ -118,10 +112,10 @@ export function readInstrumentZones(zonesChunk, instrumentGenerators, instrument
      * @type {InstrumentZone[]}
      */
     let zones = [];
-    while(zonesChunk.chunkData.length > zonesChunk.chunkData.currentIndex)
+    while (zonesChunk.chunkData.length > zonesChunk.chunkData.currentIndex)
     {
         let zone = new InstrumentZone(zonesChunk.chunkData);
-        if(zones.length > 0)
+        if (zones.length > 0)
         {
             let modulatorZoneSize = zone.modulatorZoneStartIndex - zones[zones.length - 1].modulatorZoneStartIndex;
             let generatorZoneSize = zone.generatorZoneStartIndex - zones[zones.length - 1].generatorZoneStartIndex;
@@ -134,95 +128,95 @@ export function readInstrumentZones(zonesChunk, instrumentGenerators, instrument
         }
         zones.push(zone);
     }
+    if (zones.length > 1)
+    {
+        // remove terminal
+        zones.pop();
+    }
     return zones;
 }
 
-export class PresetZone {
+export class PresetZone extends BasicPresetZone
+{
     /**
      * Creates a zone (preset)
-     * @param dataArray {ShiftableByteArray}
+     * @param dataArray {IndexedByteArray}
      */
-    constructor(dataArray) {
-        this.generatorZoneStartIndex = readBytesAsUintLittleEndian(dataArray, 2);
-        this.modulatorZoneStartIndex = readBytesAsUintLittleEndian(dataArray, 2);
+    constructor(dataArray)
+    {
+        super();
+        this.generatorZoneStartIndex = readLittleEndian(dataArray, 2);
+        this.modulatorZoneStartIndex = readLittleEndian(dataArray, 2);
         this.modulatorZoneSize = 0;
         this.generatorZoneSize = 0;
-        this.keyRange = {min: 0, max: 127};
-        this.velRange = {min: 0, max: 127}
         this.isGlobal = true;
-        /**
-         * @type {Generator[]}
-         */
-        this.generators = [];
-        /**
-         * @type {Modulator[]}
-         */
-        this.modulators = [];
     }
-
+    
     setZoneSize(modulatorZoneSize, generatorZoneSize)
     {
         this.modulatorZoneSize = modulatorZoneSize;
         this.generatorZoneSize = generatorZoneSize;
     }
-
+    
     /**
      * grab the generators
      * @param generators {Generator[]}
      */
     getGenerators(generators)
     {
-        for(let i = this.generatorZoneStartIndex; i < this.generatorZoneStartIndex + this.generatorZoneSize; i++)
+        for (let i = this.generatorZoneStartIndex; i < this.generatorZoneStartIndex + this.generatorZoneSize; i++)
         {
             this.generators.push(generators[i]);
         }
     }
-
+    
     /**
      * grab the modulators
      * @param modulators {Modulator[]}
      */
     getModulators(modulators)
     {
-        for(let i = this.modulatorZoneStartIndex; i < this.modulatorZoneStartIndex + this.modulatorZoneSize; i++)
+        for (let i = this.modulatorZoneStartIndex; i < this.modulatorZoneStartIndex + this.modulatorZoneSize; i++)
         {
             this.modulators.push(modulators[i]);
         }
     }
-
+    
     /**
      * grab the instrument
-     * @param instruments {Instrument[]}
+     * @param instruments {BasicInstrument[]}
      */
     getInstrument(instruments)
     {
         let instrumentID = this.generators.find(g => g.generatorType === generatorTypes.instrument);
-        if(instrumentID) {
+        if (instrumentID)
+        {
             this.instrument = instruments[instrumentID.generatorValue];
+            this.instrument.addUseCount();
             this.isGlobal = false;
         }
     }
-
+    
     /**
      * Reads the keyRange of the zone
      */
     getKeyRange()
     {
         let range = this.generators.find(g => g.generatorType === generatorTypes.keyRange);
-        if(range)
+        if (range)
         {
             this.keyRange.min = range.generatorValue & 0x7F;
             this.keyRange.max = (range.generatorValue >> 8) & 0x7F;
         }
     }
-
+    
     /**
      * reads the velolicty range of the zone
      */
     getVelRange()
     {
         let range = this.generators.find(g => g.generatorType === generatorTypes.velRange);
-        if(range)
+        if (range)
         {
             this.velRange.min = range.generatorValue & 0x7F;
             this.velRange.max = (range.generatorValue >> 8) & 0x7F;
@@ -231,10 +225,10 @@ export class PresetZone {
 }
 
 /**
- * Reads the given preset zone chunk
+ * Reads the given preset zone read
  * @param zonesChunk {RiffChunk}
  * @param presetGenerators {Generator[]}
- * @param instruments {Instrument[]}
+ * @param instruments {BasicInstrument[]}
  * @param presetModulators {Modulator[]}
  * @returns {PresetZone[]}
  */
@@ -244,10 +238,10 @@ export function readPresetZones(zonesChunk, presetGenerators, presetModulators,
      * @type {PresetZone[]}
      */
     let zones = [];
-    while(zonesChunk.chunkData.length > zonesChunk.chunkData.currentIndex)
+    while (zonesChunk.chunkData.length > zonesChunk.chunkData.currentIndex)
     {
         let zone = new PresetZone(zonesChunk.chunkData);
-        if(zones.length > 0)
+        if (zones.length > 0)
         {
             let modulatorZoneSize = zone.modulatorZoneStartIndex - zones[zones.length - 1].modulatorZoneStartIndex;
             let generatorZoneSize = zone.generatorZoneStartIndex - zones[zones.length - 1].generatorZoneStartIndex;
@@ -260,5 +254,10 @@ export function readPresetZones(zonesChunk, presetGenerators, presetModulators,
         }
         zones.push(zone);
     }
+    if (zones.length > 1)
+    {
+        // remove terminal
+        zones.pop();
+    }
     return zones;
 }

package/src/synthetizer/README.md

@@ -0,0 +1,7 @@
+## This is the main synthesizer folder.
+
+The code here is responsible for making the actual sound.
+This is the heart of the SpessaSynth library.
+
+- `audio_engine` - the core synthesis engine, it theoretically can run on non-browser environments.
+- `audio_effects` - the WebAudioAPI audio effects.

package/src/synthetizer/audio_engine/README.md

@@ -0,0 +1,9 @@
+## This is the synthesis engine folder.
+
+The code here is responsible for a single midi channel, synthesizing the sound to it.
+
+- `engine_methods` contains the methods for the `main_processor.js`
+- `engine_components` contains the various digital signal processing functions such as the wavetable oscillator, low
+  pass filter, etc.
+
+For those interested, `render_voice.js` file contains the actual DSP synthesis code.

package/src/synthetizer/audio_engine/engine_components/compute_modulator.js

@@ -0,0 +1,266 @@
+import { getModulatorCurveValue, MOD_PRECOMPUTED_LENGTH } from "./modulator_curves.js";
+import { VolumeEnvelope } from "./volume_envelope.js";
+import { ModulationEnvelope } from "./modulation_envelope.js";
+import { generatorLimits, generatorTypes } from "../../../soundfont/basic_soundfont/generator.js";
+import { Modulator, modulatorSources } from "../../../soundfont/basic_soundfont/modulator.js";
+import { NON_CC_INDEX_OFFSET } from "./controller_tables.js";
+
+/**
+ * compute_modulator.js
+ * purpose: precomputes all curve types and computes modulators
+ */
+
+const EFFECT_MODULATOR_TRANSFORM_MULTIPLIER = 1000 / 200;
+
+/**
+ * Computes a given modulator
+ * @param controllerTable {Int16Array} all midi controllers as 14bit values + the non-controller indexes, starting at 128
+ * @param modulator {Modulator} the modulator to compute
+ * @param voice {Voice} the voice belonging to the modulator
+ * @returns {number} the computed value
+ */
+export function computeModulator(controllerTable, modulator, voice)
+{
+    if (modulator.transformAmount === 0)
+    {
+        modulator.currentValue = 0;
+        return 0;
+    }
+    // mapped to 0-16384
+    let rawSourceValue;
+    if (modulator.sourceUsesCC)
+    {
+        rawSourceValue = controllerTable[modulator.sourceIndex];
+    }
+    else
+    {
+        const index = modulator.sourceIndex + NON_CC_INDEX_OFFSET;
+        switch (modulator.sourceIndex)
+        {
+            case modulatorSources.noController:
+                rawSourceValue = 16383; // equals to 1
+                break;
+            
+            case modulatorSources.noteOnKeyNum:
+                rawSourceValue = voice.midiNote << 7;
+                break;
+            
+            case modulatorSources.noteOnVelocity:
+                rawSourceValue = voice.velocity << 7;
+                break;
+            
+            case modulatorSources.polyPressure:
+                rawSourceValue = voice.pressure << 7;
+                break;
+            
+            default:
+                rawSourceValue = controllerTable[index]; // pitch bend and range are stored in the cc table
+                break;
+        }
+        
+    }
+    
+    const sourceValue = transforms[modulator.sourceCurveType][modulator.sourcePolarity][modulator.sourceDirection][rawSourceValue];
+    
+    // mapped to 0-127
+    let rawSecondSrcValue;
+    if (modulator.secSrcUsesCC)
+    {
+        rawSecondSrcValue = controllerTable[modulator.secSrcIndex];
+    }
+    else
+    {
+        const index = modulator.secSrcIndex + NON_CC_INDEX_OFFSET;
+        switch (modulator.secSrcIndex)
+        {
+            case modulatorSources.noController:
+                rawSecondSrcValue = 16383; // equals to 1
+                break;
+            
+            case modulatorSources.noteOnKeyNum:
+                rawSecondSrcValue = voice.midiNote << 7;
+                break;
+            
+            case modulatorSources.noteOnVelocity:
+                rawSecondSrcValue = voice.velocity << 7;
+                break;
+            
+            case modulatorSources.polyPressure:
+                rawSecondSrcValue = voice.pressure << 7;
+                break;
+            
+            default:
+                rawSecondSrcValue = controllerTable[index]; // pitch bend and range are stored in the cc table
+        }
+        
+    }
+    const secondSrcValue = transforms[modulator.secSrcCurveType][modulator.secSrcPolarity][modulator.secSrcDirection][rawSecondSrcValue];
+    
+    // see the comment for isEffectModulator (modulator.js in basic_soundfont) for explanation
+    let transformAmount = modulator.transformAmount;
+    if (modulator.isEffectModulator && transformAmount <= 1000)
+    {
+        transformAmount *= EFFECT_MODULATOR_TRANSFORM_MULTIPLIER;
+        transformAmount = Math.min(transformAmount, 1000);
+    }
+    
+    // compute the modulator
+    let computedValue = sourceValue * secondSrcValue * transformAmount;
+    
+    if (modulator.transformType === 2)
+    {
+        // abs value
+        computedValue = Math.abs(computedValue);
+    }
+    
+    modulator.currentValue = computedValue;
+    return computedValue;
+}
+
+/**
+ * Computes modulators of a given voice. Source and index indicate what modulators shall be computed
+ * @param voice {Voice} the voice to compute modulators for
+ * @param controllerTable {Int16Array} all midi controllers as 14bit values + the non-controller indexes, starting at 128
+ * @param sourceUsesCC {number} what modulators should be computed, -1 means all, 0 means modulator source enum 1 means midi controller
+ * @param sourceIndex {number} enum for the source
+ */
+export function computeModulators(voice, controllerTable, sourceUsesCC = -1, sourceIndex = 0)
+{
+    const modulators = voice.modulators;
+    const generators = voice.generators;
+    const modulatedGenerators = voice.modulatedGenerators;
+    
+    if (sourceUsesCC === -1)
+    {
+        // All modulators mode: compute all modulators
+        modulatedGenerators.set(generators);
+        modulators.forEach(mod =>
+        {
+            const limits = generatorLimits[mod.modulatorDestination];
+            const newValue = modulatedGenerators[mod.modulatorDestination] + computeModulator(
+                controllerTable,
+                mod,
+                voice
+            );
+            modulatedGenerators[mod.modulatorDestination] = Math.max(
+                limits.min,
+                Math.min(newValue, limits.max)
+            );
+        });
+        VolumeEnvelope.recalculate(voice);
+        ModulationEnvelope.recalculate(voice);
+        return;
+    }
+    
+    // Optimized mode: calculate only modulators that use the given source
+    const volenvNeedsRecalculation = new Set([
+        generatorTypes.initialAttenuation,
+        generatorTypes.delayVolEnv,
+        generatorTypes.attackVolEnv,
+        generatorTypes.holdVolEnv,
+        generatorTypes.decayVolEnv,
+        generatorTypes.sustainVolEnv,
+        generatorTypes.releaseVolEnv,
+        generatorTypes.keyNumToVolEnvHold,
+        generatorTypes.keyNumToVolEnvDecay
+    ]);
+    
+    const computedDestinations = new Set();
+    
+    modulators.forEach(mod =>
+    {
+        if (
+            (mod.sourceUsesCC === sourceUsesCC && mod.sourceIndex === sourceIndex) ||
+            (mod.secSrcUsesCC === sourceUsesCC && mod.secSrcIndex === sourceIndex)
+        )
+        {
+            const destination = mod.modulatorDestination;
+            if (!computedDestinations.has(destination))
+            {
+                // Reset this destination
+                modulatedGenerators[destination] = generators[destination];
+                // compute our modulator
+                computeModulator(controllerTable, mod, voice);
+                // sum the values of all modulators for this destination
+                modulators.forEach(m =>
+                {
+                    if (m.modulatorDestination === destination)
+                    {
+                        const limits = generatorLimits[mod.modulatorDestination];
+                        const newValue = modulatedGenerators[mod.modulatorDestination] + m.currentValue;
+                        modulatedGenerators[mod.modulatorDestination] = Math.max(
+                            limits.min,
+                            Math.min(newValue, limits.max)
+                        );
+                    }
+                });
+                computedDestinations.add(destination);
+            }
+        }
+    });
+    
+    // Recalculate volume envelope if necessary
+    if ([...computedDestinations].some(dest => volenvNeedsRecalculation.has(dest)))
+    {
+        VolumeEnvelope.recalculate(voice);
+    }
+    
+    ModulationEnvelope.recalculate(voice);
+}
+
+
+/**
+ * as follows: transforms[curveType][polarity][direction] is an array
+ * @type {Float32Array[][][]}
+ */
+const transforms = [];
+
+for (let curve = 0; curve < 4; curve++)
+{
+    transforms[curve] =
+        [
+            [
+                new Float32Array(MOD_PRECOMPUTED_LENGTH),
+                new Float32Array(MOD_PRECOMPUTED_LENGTH)
+            ],
+            [
+                new Float32Array(MOD_PRECOMPUTED_LENGTH),
+                new Float32Array(MOD_PRECOMPUTED_LENGTH)
+            ]
+        ];
+    for (let i = 0; i < MOD_PRECOMPUTED_LENGTH; i++)
+    {
+        
+        // polarity 0 dir 0
+        transforms[curve][0][0][i] = getModulatorCurveValue(
+            0,
+            curve,
+            i / MOD_PRECOMPUTED_LENGTH,
+            0
+        );
+        
+        // polarity 1 dir 0
+        transforms[curve][1][0][i] = getModulatorCurveValue(
+            0,
+            curve,
+            i / MOD_PRECOMPUTED_LENGTH,
+            1
+        );
+        
+        // polarity 0 dir 1
+        transforms[curve][0][1][i] = getModulatorCurveValue(
+            1,
+            curve,
+            i / MOD_PRECOMPUTED_LENGTH,
+            0
+        );
+        
+        // polarity 1 dir 1
+        transforms[curve][1][1][i] = getModulatorCurveValue(
+            1,
+            curve,
+            i / MOD_PRECOMPUTED_LENGTH,
+            1
+        );
+    }
+}

package/src/synthetizer/audio_engine/engine_components/controller_tables.js

@@ -0,0 +1,88 @@
+import { midiControllers } from "../../../midi/midi_message.js";
+import { modulatorSources } from "../../../soundfont/basic_soundfont/modulator.js";
+
+/*
+ * A bit of explanation:
+ * The controller table is stored as an int16 array, it stores 14-bit values.
+ * This controller table is then extended with the modulatorSources section,
+ * for example, pitch range and pitch range depth.
+ * This allows us for precise control range and supports full pitch-wheel resolution.
+ */
+export const NON_CC_INDEX_OFFSET = 128;
+export const CONTROLLER_TABLE_SIZE = 147;
+
+
+// an array with preset default values, so we can quickly use set() to reset the controllers
+export const resetArray = new Int16Array(CONTROLLER_TABLE_SIZE).fill(0);
+export const setResetValue = (i, v) => resetArray[i] = v << 7;
+
+// values come from Falcosoft MidiPlayer 6
+setResetValue(midiControllers.mainVolume, 100);
+setResetValue(midiControllers.balance, 64);
+setResetValue(midiControllers.expressionController, 127);
+setResetValue(midiControllers.pan, 64);
+
+setResetValue(midiControllers.portamentoOnOff, 127);
+
+setResetValue(midiControllers.filterResonance, 64);
+setResetValue(midiControllers.releaseTime, 64);
+setResetValue(midiControllers.attackTime, 64);
+setResetValue(midiControllers.brightness, 64);
+
+setResetValue(midiControllers.decayTime, 64);
+setResetValue(midiControllers.vibratoRate, 64);
+setResetValue(midiControllers.vibratoDepth, 64);
+setResetValue(midiControllers.vibratoDelay, 64);
+setResetValue(midiControllers.generalPurposeController6, 64);
+setResetValue(midiControllers.generalPurposeController8, 64);
+
+setResetValue(midiControllers.RPNLsb, 127);
+setResetValue(midiControllers.RPNMsb, 127);
+setResetValue(midiControllers.NRPNLsb, 127);
+setResetValue(midiControllers.NRPNMsb, 127);
+
+
+export const PORTAMENTO_CONTROL_UNSET = 1;
+// special case: portamento control
+// since it is only 7-bit, only the values at multiple of 128 are allowed.
+// a value of just 1 indicates no key set, hence no portamento.
+// this is the "initial unset portamento key" flag.
+resetArray[midiControllers.portamentoControl] = PORTAMENTO_CONTROL_UNSET;
+
+// pitch wheel
+setResetValue(NON_CC_INDEX_OFFSET + modulatorSources.pitchWheel, 64);
+setResetValue(NON_CC_INDEX_OFFSET + modulatorSources.pitchWheelRange, 2);
+
+/**
+ * @enum {number}
+ */
+export const customControllers = {
+    channelTuning: 0,           // cents, RPN for fine tuning
+    channelTransposeFine: 1,    // cents, only the decimal tuning, (e.g., transpose is 4.5,
+    // then shift by 4 keys + tune by 50 cents)
+    modulationMultiplier: 2,    // cents, set by modulation depth RPN
+    masterTuning: 3,            // cents, set by system exclusive
+    channelTuningSemitones: 4   // semitones, for RPN coarse tuning
+};
+export const CUSTOM_CONTROLLER_TABLE_SIZE = Object.keys(customControllers).length;
+export const customResetArray = new Float32Array(CUSTOM_CONTROLLER_TABLE_SIZE);
+customResetArray[customControllers.modulationMultiplier] = 1;
+/**
+ * @enum {number}
+ */
+export const dataEntryStates = {
+    Idle: 0,
+    RPCoarse: 1,
+    RPFine: 2,
+    NRPCoarse: 3,
+    NRPFine: 4,
+    DataCoarse: 5,
+    DataFine: 6
+};
+/**
+ * This is a channel configuration enum, it is internally sent from Synthetizer via controller change
+ * @enum {number}
+ */
+export const channelConfiguration = {
+    velocityOverride: 128 // overrides velocity for the given channel
+};