spessasynth_lib 3.26.0 → 3.26.2

package/sequencer/sequencer_message.js

@@ -0,0 +1,53 @@
+export const SongChangeType = {
+    backwards: 0,   // no additional data
+    forwards: 1,    // no additional data
+    shuffleOn: 2,   // no additional data
+    shuffleOff: 3,  // no additional data
+    index: 4        // songIndex<number>
+};
+
+/**
+ * @enum {number}
+ * @property {number} loadNewSongList          - 0 -> [...song<MIDI>]
+ * @property {number} pause                    - 1 -> isFinished<boolean>
+ * @property {number} stop                     - 2 -> (no data)
+ * @property {number} play                     - 3 -> resetTime<boolean>
+ * @property {number} setTime                  - 4 -> time<number>
+ * @property {number} changeMIDIMessageSending - 5 -> sendMIDIMessages<boolean>
+ * @property {number} setPlaybackRate          - 6 -> playbackRate<number>
+ * @property {number} setLoop                  - 7 -> [loop<boolean>, count<number>]
+ * @property {number} changeSong               - 8 -> [changeType<SongChangeType>, data<number>]
+ * @property {number} getMIDI                  - 9 -> (no data)
+ * @property {number} setSkipToFirstNote       -10 -> skipToFirstNoteOn<boolean>
+ * @property {number} setPreservePlaybackState -11 -> preservePlaybackState<boolean>
+ */
+export const SpessaSynthSequencerMessageType = {
+    loadNewSongList: 0,
+    pause: 1,
+    stop: 2,
+    play: 3,
+    setTime: 4,
+    changeMIDIMessageSending: 5,
+    setPlaybackRate: 6,
+    setLoop: 7,
+    changeSong: 8,
+    getMIDI: 9,
+    setSkipToFirstNote: 10,
+    setPreservePlaybackState: 11
+};
+
+/**
+ *
+ * @enum {number}
+ */
+export const SpessaSynthSequencerReturnMessageType = {
+    midiEvent: 0,               // [...midiEventBytes<number>]
+    songChange: 1,              // [songIndex<number>, isAutoPlayed<boolean>]
+    timeChange: 2,              // newTime<number>
+    pause: 3,                   // no data
+    getMIDI: 4,                 // midiData<MIDI>
+    midiError: 5,               // errorMSG<string>
+    metaEvent: 6,               // [event<MIDIMessage>, trackNum<number>]
+    loopCountChange: 7,         // newLoopCount<number>
+    songListChange: 8          // songListData<MIDIData[]>
+};

package/synthetizer/README.md

@@ -0,0 +1,38 @@
+## 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.
+- `worklet_wrapper` - the wrapper for the core synthesis engine using audio worklets.
+
+`worklet_processor.min.js` - the minified worklet processor code to import.
+
+# About the message protocol
+Since spessasynth_lib runs in the audioWorklet thread, here is an explanation of how it works:
+
+There's one processor per synthesizer, with a `MessagePort` for communication.
+Each processor has a single `SpessaSynthequencer` instance that is idle by default.
+
+The `Synthetizer`, 
+`Sequencer` and `SoundFontManager` classes are all interfaces 
+that do not do anything except sending the commands to te processor.
+
+The synthesizer sends the commands (note on, off, etc.) directly to the processor where they are processed and executed.
+
+The sequencer sends the commands through the connected synthesizer's messagePort, which then get processed as sequencer messages and routed properly.
+
+
+## How it works in spessasynth_lib
+Both `Synthetizer` and `Sequencer` are essentially "remote control"
+for the actual sequencer and synthesizer in the audio worklet thread (here)
+These core components are wrapped in the AudioWorkletProcessor, which is receiving both commands and data (MIDIs, sound banks)
+through the message port, and sends data back (events, time changes, status changes, etc.).
+
+For example,
+the playback to WebMIDIAPI is actually the sequencer in the worklet thread
+playing back the sequence and then postMessaging the commands through the synthesizer to the sequencer
+which actually sends them to the specified output.
+
+The wonders of separate audio thread...

package/synthetizer/audio_effects/effects_config.js

@@ -0,0 +1,25 @@
+import { DEFAULT_CHORUS_CONFIG } from "./fancy_chorus.js";
+
+/**
+ * @typedef {Object} SynthConfig
+ * @property {boolean?} chorusEnabled - indicates if the chorus effect is enabled.
+ * @property {ChorusConfig?} chorusConfig - the configuration for chorus. Pass undefined to use defaults
+ * @property {boolean?} reverbEnabled - indicates if the reverb effect is enabled.
+ * @property {AudioBuffer?} reverbImpulseResponse - the impulse response for the reverb. Pass undefined to use defaults
+ * @property {{
+ *      worklet: function(context: object, name: string, options?: Object)
+ * }?} audioNodeCreators - custom audio node creation functions for Web Audio wrappers.
+ */
+
+
+/**
+ * @type {SynthConfig}
+ */
+export const DEFAULT_SYNTH_CONFIG = {
+    chorusEnabled: true,
+    chorusConfig: DEFAULT_CHORUS_CONFIG,
+    
+    reverbEnabled: true,
+    reverbImpulseResponse: undefined, // will load the integrated one
+    audioNodeCreators: undefined
+};

package/synthetizer/audio_effects/fancy_chorus.js

@@ -0,0 +1,162 @@
+/**
+ * fancy_chorus.js
+ * purpose: creates a simple chorus effect node
+ */
+
+/**
+ * @typedef {{
+ *     oscillator: OscillatorNode,
+ *     oscillatorGain: GainNode,
+ *     delay: DelayNode
+ * }} ChorusNode
+ */
+
+/**
+ * @typedef {Object} ChorusConfig
+ * @property {number?} nodesAmount - the amount of delay nodes (for each channel) and the corresponding oscillators
+ * @property {number?} defaultDelay - the initial delay, in seconds
+ * @property {number?} delayVariation - the difference between delays in the delay nodes
+ * @property {number?} stereoDifference - the difference of delays between two channels (added to the left channel and subtracted from the right)
+ * @property {number?} oscillatorFrequency - the initial delay time oscillator frequency, in Hz.
+ * @property {number?} oscillatorFrequencyVariation - the difference between frequencies of oscillators, in Hz
+ * @property {number?} oscillatorGain - how much will oscillator alter the delay in delay nodes, in seconds
+ */
+
+const NODES_AMOUNT = 4;
+const DEFAULT_DELAY = 0.03;
+const DELAY_VARIATION = 0.01;
+const STEREO_DIFF = 0.02;
+
+const OSC_FREQ = 0.2;
+const OSC_FREQ_VARIATION = 0.05;
+const OSC_GAIN = 0.003;
+
+export const DEFAULT_CHORUS_CONFIG = {
+    nodesAmount: NODES_AMOUNT,
+    defaultDelay: DEFAULT_DELAY,
+    delayVariation: DELAY_VARIATION,
+    stereoDifference: STEREO_DIFF,
+    oscillatorFrequency: OSC_FREQ,
+    oscillatorFrequencyVariation: OSC_FREQ_VARIATION,
+    oscillatorGain: OSC_GAIN
+};
+
+export class FancyChorus
+{
+    /**
+     * Creates a fancy chorus effect
+     * @param output {AudioNode}
+     * @param config {ChorusConfig}
+     */
+    constructor(output, config = DEFAULT_CHORUS_CONFIG)
+    {
+        const context = output.context;
+        
+        this.input = context.createChannelSplitter(2);
+        
+        const merger = context.createChannelMerger(2);
+        
+        /**
+         * @type {ChorusNode[]}
+         */
+        const chorusNodesLeft = [];
+        /**
+         * @type {ChorusNode[]}
+         */
+        const chorusNodesRight = [];
+        let freq = config.oscillatorFrequency;
+        let delay = config.defaultDelay;
+        for (let i = 0; i < config.nodesAmount; i++)
+        {
+            // left node
+            this.createChorusNode(
+                freq,
+                delay - config.stereoDifference,
+                chorusNodesLeft,
+                0,
+                merger,
+                0,
+                context,
+                config
+            );
+            // right node
+            this.createChorusNode(
+                freq,
+                delay + config.stereoDifference,
+                chorusNodesRight,
+                1,
+                merger,
+                1,
+                context,
+                config
+            );
+            freq += config.oscillatorFrequencyVariation;
+            delay += config.delayVariation;
+        }
+        
+        merger.connect(output);
+        this.merger = merger;
+        this.chorusLeft = chorusNodesLeft;
+        this.chorusRight = chorusNodesRight;
+    }
+    
+    delete()
+    {
+        this.input.disconnect();
+        delete this.input;
+        this.merger.disconnect();
+        delete this.merger;
+        for (const chorusLeftElement of this.chorusLeft)
+        {
+            chorusLeftElement.delay.disconnect();
+            chorusLeftElement.oscillator.disconnect();
+            chorusLeftElement.oscillatorGain.disconnect();
+            delete chorusLeftElement.delay;
+            delete chorusLeftElement.oscillatorGain;
+            delete chorusLeftElement.oscillatorGain;
+        }
+        for (const chorusRightElement of this.chorusRight)
+        {
+            chorusRightElement.delay.disconnect();
+            chorusRightElement.oscillator.disconnect();
+            chorusRightElement.oscillatorGain.disconnect();
+            delete chorusRightElement.delay;
+            delete chorusRightElement.oscillatorGain;
+            delete chorusRightElement.oscillatorGain;
+        }
+    }
+    
+    /**
+     * @param freq {number}
+     * @param delay {number}
+     * @param list {ChorusNode[]}
+     * @param input {number}
+     * @param output {AudioNode}
+     * @param outputNum {number}
+     * @param context {BaseAudioContext}
+     * @param config {ChorusConfig}
+     */
+    createChorusNode(freq, delay, list, input, output, outputNum, context, config)
+    {
+        const oscillator = context.createOscillator();
+        oscillator.type = "sine";
+        oscillator.frequency.value = freq;
+        const gainNode = context.createGain();
+        gainNode.gain.value = config.oscillatorGain;
+        const delayNode = context.createDelay();
+        delayNode.delayTime.value = delay;
+        
+        oscillator.connect(gainNode);
+        gainNode.connect(delayNode.delayTime);
+        oscillator.start(context.currentTime /*+ delay*/);
+        
+        this.input.connect(delayNode, input);
+        delayNode.connect(output, 0, outputNum);
+        
+        list.push({
+            oscillator: oscillator,
+            oscillatorGain: gainNode,
+            delay: delayNode
+        });
+    }
+}