@fluex/fluexgl-dsp 0.1.2

package/lib/src/core/classes/Channel.ts

@@ -0,0 +1,199 @@
+import { v4 } from "uuid";
+
+import { Effector } from "./Effector";
+import { AudioClip } from "./AudioClip";
+import { Master } from "./Master";
+
+import { ChannelOptions } from "../../typings";
+import { Debug } from "../../utilities/debugger";
+
+export class Channel {
+
+    public id: string = v4();
+    public effects: Effector[] = [];
+    public label: string | null;
+
+    public parentialContext: AudioContext | null = null;
+    public parentialMasterChannel: Master | null = null;
+
+    public audioClips: AudioClip[] = [];
+
+    public gainNode: GainNode | null = null;
+    public stereoPannerNode: StereoPannerNode | null = null;
+
+    public audioClipsInputGainNode: GainNode | null = null;
+
+    constructor(public options: Partial<ChannelOptions> = { maxAudioNodes: 8, maxEffects: 8 }) {
+
+        this.label = options.label ?? null;
+    }
+
+    private rebuildEffectChain() {
+        Debug.Log("Attempting to rebuild effect chain.");
+
+        if (!this.audioClipsInputGainNode || !this.gainNode) return Debug.Error("Could not rebuild effect chain, because one or more gain nodes on this channel are undefined.", [
+            `Channel id: ${this.id}.`,
+            `Current amount of effects: ${this.effects.length}.`
+        ]);
+
+        this.audioClipsInputGainNode.disconnect();
+
+        for (const effect of this.effects) {
+            effect.audioWorkletNode?.disconnect();
+        }
+
+        const activeEffects = this.effects.filter(e => !!e.audioWorkletNode /* && e.enabled !== false */);
+
+        if (activeEffects.length === 0) {
+
+            this.audioClipsInputGainNode.connect(this.gainNode);
+        } else {
+
+            const firstEffectGain = activeEffects[0].audioWorkletNode!;
+            this.audioClipsInputGainNode.connect(firstEffectGain);
+
+            for (let i = 0; i < activeEffects.length - 1; i++) {
+                
+                const current = activeEffects[i].audioWorkletNode!;
+                const next = activeEffects[i + 1].audioWorkletNode!;
+
+                current.connect(next);
+            }
+
+            const lastEffectGain = activeEffects[activeEffects.length - 1].audioWorkletNode!;
+
+            lastEffectGain.connect(this.gainNode);
+        }
+
+        Debug.Success("Successfully rebuilt effect chain.", [
+            `Channel id: ${this.id}.`,
+            `Current amount of effects: ${this.effects.length}`
+        ]);
+    }
+
+    public InitializeChannelOnMasterAttachment(master: Master) {
+
+        this.parentialMasterChannel = master;
+        this.parentialContext = master.context;
+
+        this.gainNode = new GainNode(this.parentialContext);
+        this.stereoPannerNode = new StereoPannerNode(this.parentialContext);
+
+        this.audioClipsInputGainNode = new GainNode(this.parentialContext);
+
+        this.audioClipsInputGainNode.connect(this.stereoPannerNode);
+        this.stereoPannerNode.connect(this.gainNode);
+        this.gainNode.connect(this.parentialMasterChannel.gainNode);
+    }
+
+    public SetLabel(label: string): void {
+
+        this.options.label = label;
+        this.label = label;
+    }
+
+    public ClearLabel(): void {
+
+        this.options.label = "";
+        this.label = null;
+    }
+
+    public AttachAudioClip(clip: AudioClip) {
+
+        if (this.audioClips.includes(clip)) return Debug.Error("Could not attach audio clip because it is already part of this channel", [
+            "Call .DetachAudioClip([clip AudioClip]) before attaching audio clip."
+        ]);
+
+        clip.InitializeAudioClipOnAttaching(this);
+        this.audioClips.push(clip);
+    }
+
+    public DetachAudioClip(clip: AudioClip) {
+
+        if (!this.audioClips.includes(clip)) return Debug.Error("Could not detach audio clip, because it is not part of this channel.", [
+            "Call .AttachAudioClip([clip AudioClip]) before deattaching audio clip."
+        ]);
+
+        const self: Channel = this;
+
+        clip.parentialAudioContext = null;
+        clip.parentialChannel = null;
+        clip.hasAttachedToChannel = false;
+
+        clip.stereoPannerNode?.disconnect();
+        clip.gainNode?.disconnect();
+
+        clip.DisconnectAllAudioBufferSourceNodes();
+
+        this.audioClips.forEach(function (_clip: AudioClip, index: number) {
+            if (clip.id === _clip.id)
+                return self.audioClips.splice(index, 1);
+        });
+    }
+
+    public SetVolume(volume: number): void {
+
+        if (!this.gainNode) return Debug.Error("Could not set channel volume because the channel is not attached to a master channel.", [
+            "Attach the channel to a master channel before setting the volume."
+        ]);
+
+        this.gainNode.gain.setValueAtTime(volume, this.parentialContext!.currentTime);
+    }
+
+    public SetPanLevel(pan: number): void {
+
+        if (!this.stereoPannerNode) return Debug.Error("Could not set channel pan level because the channel is not attached to a master channel.", [
+            "Attach the channel to a master channel before setting the pan level."
+        ]);
+
+        this.stereoPannerNode.pan.setValueAtTime(pan, this.parentialContext!.currentTime);
+    }
+
+    public AddEffect(effect: Effector): void {
+
+        if (!this.parentialContext) return Debug.Error("Could not add effect on channel, because the parential context is undefined.", [
+            `Channel ID: ${this.id}`,
+            `Effect ID: ${effect.id}`,
+            `Effect name: ${effect.constructor.name}`
+        ])
+
+        if (this.effects.includes(effect)) return Debug.Error("Could not add effect because it is already part of this channel", [
+            "Call .RemoveEffect([effect Effector]) before adding effect."
+        ]);
+
+        effect.InitializeOnAttachment(this.parentialContext);
+
+        this.effects.push(effect);
+        this.rebuildEffectChain();
+    }
+
+    public RemoveEffect(effect: Effector): void {
+
+        if (!this.effects.includes(effect)) return Debug.Error("Could not remove effect, because it is not part of this channel.", [
+            "Call .AddEffect([effect Effector]) before removing effect."
+        ]);
+
+        const self: Channel = this;
+
+        this.effects.forEach(function (_effect: Effector, index: number) {
+            if (effect.id === _effect.id)
+                return self.effects.splice(index, 1);
+        });
+
+        this.rebuildEffectChain();
+    }
+
+    // Public getters and setters
+
+    public get volume(): number | null {
+
+        if (!this.gainNode) return null;
+        return this.gainNode.gain.value;
+    }
+
+    public get panLevel(): number | null {
+
+        if (!this.stereoPannerNode) return null;
+        return this.stereoPannerNode.pan.value;
+    }
+}

package/lib/src/core/classes/DpsPipeline.ts

@@ -0,0 +1,153 @@
+import { v4 } from "uuid";
+
+import { AudioDevice } from "./AudioDevice";
+import { Debug } from "../../utilities/debugger";
+import { LoadWebAssemblyModule } from "../../utilities/web-assembly";
+import { ConstructProcessorWorklet, LoadWorkletOnMasterChannel } from "../../utilities/helpers";
+
+import { ErrorCodes, WarningCodes } from "../../console-codes";
+import { DspPipelineInitializationOptions } from "../../typings";
+
+/**
+ * Represents the digital signal processing (DSP) pipeline responsible for initializing
+ * WebAssembly modules, AudioWorklet processors, and resolving audio output devices.
+ */
+export class DspPipeline {
+
+    /**
+     * The path to the WebAssembly module file.
+     */
+    public pathToWasm: string | null = null;
+
+    /**
+     * The path to the AudioWorklet processor script.
+     */
+    public pathToWorklet: string | null = null;
+
+    /**
+     * Unique identifier of this DSP pipeline instance.
+     */
+    public id: string = v4();
+
+    /**
+     * Indicates whether the DSP pipeline has been successfully initialized.
+     */
+    public hasInitialized: boolean = false;
+
+    /**
+     * The generated blob URL containing the AudioWorklet processor code.
+     */
+    private blobUrl: string | null = null;
+
+    /**
+     * Creates a new instance of the {@link DspPipeline} class.
+     *
+     * @param options - Initialization options for the DSP pipeline.
+     * Must include valid paths to the WebAssembly and AudioWorklet files.
+     */
+    constructor(options: DspPipelineInitializationOptions) {
+        this.pathToWasm = options.pathToWasm;
+        this.pathToWorklet = options.pathToWorklet;
+    }
+
+    /**
+     * Initializes the DSP pipeline.
+     * This is a convenience wrapper around {@link InitializeDpsPipeline}.
+     *
+     * @returns A promise resolving to `true` if the initialization succeeded, otherwise `false`.
+     */
+    public async Init(): Promise<boolean> {
+        return await this.InitializeDpsPipeline();
+    }
+
+    /**
+     * Performs the full initialization of the DSP pipeline.
+     * Loads the WebAssembly module, constructs the AudioWorklet blob URL,
+     * and ensures audio access permissions are granted.
+     *
+     * @returns A promise resolving to `true` when initialization completes successfully, otherwise `false`.
+     */
+    public async InitializeDpsPipeline(): Promise<boolean> {
+        Debug.Log("Attempting to initialize DSP pipeline...");
+
+        const start: number = Date.now();
+
+        if (!this.pathToWasm || !this.pathToWorklet) {
+            Debug.Error("Could not initialize DSP pipeline, because the path to the WASM, or the worklet file has not been defined.");
+            return false;
+        }
+
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+            Debug.Log(`Found ${stream.getTracks().length} media stream tracks.`);
+
+            // Stop all tracks immediately after verification
+            stream.getTracks().forEach((track: MediaStreamTrack) => {
+                track.stop();
+            });
+        } catch (err) {
+            Debug.Error(
+                "Permission to access media devices has not been granted.",
+                ["Make sure the user has granted FluentGL permission to access media devices."],
+                ErrorCodes.NO_CONTEXT_PERMISSION
+            );
+            return false;
+        }
+
+        await LoadWebAssemblyModule(this.pathToWasm);
+
+        const workletFileRequest = await fetch(this.pathToWorklet);
+        const textContent: string = await workletFileRequest.text();
+
+        this.blobUrl = ConstructProcessorWorklet(textContent);
+
+        const end: number = Date.now();
+        const difference: number = end - start;
+
+        Debug.Success(`Successfully initialized DSP pipeline within ${difference}ms.`);
+
+        return (this.hasInitialized = true);
+    }
+
+    /**
+     * Resolves and initializes the system’s default audio output device.
+     * This method can only be called after the DSP pipeline has been initialized.
+     *
+     * @returns A promise that resolves with the default {@link AudioDevice} instance,
+     * or `null` if no default device was found or initialization failed.
+     */
+    public async ResolveDefaultAudioOutputDevice() {
+        Debug.Log("Attempting to resolve default audio output device...");
+
+        if (!this.hasInitialized || !this.blobUrl) {
+            Debug.Error(
+                "Could not resolve default audio output device, because the required blob URL has not been created.",
+                ["Call await .InitializeDpsPipeline() before resolving default audio output device."]
+            );
+            return null;
+        }
+
+        const audioDeviceInfos: MediaDeviceInfo[] = [];
+        const devices = await navigator.mediaDevices.enumerateDevices();
+
+        for (let device of devices)
+            (device.kind === "audiooutput" && device.deviceId === "default") &&
+                audioDeviceInfos.push(device);
+
+        devices.length === 0 &&
+            Debug.Warn("No default audio device found.", [], WarningCodes.NO_DEFAULT_AUDIO_DEVICE_FOUND);
+
+        const defaultAudioDevice =
+            devices.length === 0 ? null : new AudioDevice(audioDeviceInfos[0]);
+
+        if (!defaultAudioDevice) return null;
+
+        await LoadWorkletOnMasterChannel(defaultAudioDevice.masterChannel, this.blobUrl);
+
+        return defaultAudioDevice;
+    }
+
+    public TellMeWhatTheFuckThisWholeLibraryActuallyDoes() {
+        return `I wanted to create a web based game and implement advanced audio, but javascript is slow so that's why this library uses Web Assembly. You dont have to use it, unless you know what the fuck you're doing. If you do, god bless you.`
+    }
+}

package/lib/src/core/classes/Effector.ts

@@ -0,0 +1,11 @@
+import { v4 } from "uuid";
+
+export abstract class Effector {
+    
+    public id: string = v4();
+    public label: string | null = null;
+    public audioWorkletNode: AudioWorkletNode | null = null;
+    public parentialContext: AudioContext | null = null;
+
+    public abstract InitializeOnAttachment(parentialContext: AudioContext): Promise<void>;
+}

package/lib/src/core/classes/Master.ts

@@ -0,0 +1,50 @@
+import { v4 } from "uuid";
+
+import { Channel } from "./Channel";
+
+import { Debug } from "../../utilities/debugger";
+
+export class Master {
+
+    public id: string = v4();
+    public channels: Channel[] = [];
+    public context: AudioContext = new AudioContext();
+
+    public gainNode: GainNode = this.context.createGain();
+    public analyserNode: AnalyserNode = this.context.createAnalyser();
+
+    constructor() {
+     
+        this.gainNode.connect(this.analyserNode);
+        this.analyserNode.connect(this.context.destination);
+    }
+
+    public AttachChannel(channel: Channel): void {
+
+        if(this.channels.includes(channel)) return Debug.Error("Could not attach the channel because it is already part of this master channel.",[
+            "Call .DetachChannel([channel Channel]) before attaching the channel."
+        ]);
+
+        channel.InitializeChannelOnMasterAttachment(this);
+
+        this.channels.push(channel);
+        return;
+    }
+
+    public DetachChannel(channel: Channel): void {
+
+        if(!this.channels.includes(channel)) return Debug.Error("Could not detach the channel because it is not part of this master channel.", [
+            "Call .AttachChannel([channel Channel]) before detaching the channel."
+        ]);
+
+        const self = this;
+
+        this.channels.forEach(function(_channel: Channel, index: number) {
+            if(channel.id === _channel.id) {
+
+                self.channels.splice(index, 1);
+                return;
+            }
+        });
+    }
+}

package/lib/src/core/exports.ts

@@ -0,0 +1,6 @@
+export { AudioDevice } from "./classes/AudioDevice";
+export { Channel } from "./classes/Channel";
+export { Effector } from "./classes/Effector";
+export { Master } from "./classes/Master";
+export { AudioClip } from "./classes/AudioClip";
+export { DspPipeline } from "./classes/DpsPipeline";

package/lib/src/effects/classes/Chorus.ts

@@ -0,0 +1,109 @@
+import { compiledWebAssemblyModule } from "../../utilities/web-assembly";
+import { Effector } from "../../core/classes/Effector";
+import { Debug } from "../../utilities/debugger";
+import { ChorusEffectOptions } from "../../typings";
+
+export class Chorus extends Effector {
+
+    public baseDelayMs: number = 15;
+    public depthMs: number = 8;
+    public rateHz: number = 1.5;
+    public mix: number = 0.5;
+    public feedback: number = 0.2;
+
+    public options: ChorusEffectOptions = {};
+
+    private sampleRate: number = 0;
+
+    constructor(options?: ChorusEffectOptions) {
+        super();
+
+        this.options = {
+            baseDelayMs: this.baseDelayMs,
+            depthMs: this.depthMs,
+            rateHz: this.rateHz,
+            mix: this.mix,
+            feedback: this.mix,
+            ...options
+        }
+    }
+
+    public async InitializeOnAttachment(parentialContext: AudioContext): Promise<void> {
+
+        if (!compiledWebAssemblyModule) return Debug.Error("Could not initialize effector because the nessecary WASM file has not been specified.", [
+            `Effector type: Chorus`
+        ]);
+
+        this.sampleRate = parentialContext.sampleRate;
+
+        this.audioWorkletNode = new AudioWorkletNode(parentialContext, "ChorusProcessor", {
+            numberOfInputs: 1,
+            numberOfOutputs: 1,
+            outputChannelCount: [2],
+            parameterData: {
+                ...this.options,
+                sampleRate: this.sampleRate
+            },
+            processorOptions: {
+                module: compiledWebAssemblyModule
+            }
+        });
+
+        this.parentialContext = parentialContext;
+    }
+
+    public SetBaseDelayMs(value: number) {
+
+        this.baseDelayMs = value;
+        this.options.baseDelayMs = value;
+
+        this.audioWorkletNode?.port.postMessage({
+            type: "set-base-delay-ms",
+            value
+        });
+    }
+
+    public SetDepthMs(value: number) {
+
+        this.depthMs = value;
+        this.options.depthMs = value;
+
+        this.audioWorkletNode?.port.postMessage({
+            type: "set-depth-ms",
+            value
+        });
+    }
+
+    public SetRateHz(value: number) {
+
+        this.rateHz = value;
+        this.options.rateHz = value;
+
+        this.audioWorkletNode?.port.postMessage({
+            type: "set-rate-hz",
+            value
+        });
+    }
+
+    public SetMix(value: number) {
+
+        this.mix = value;
+        this.options.mix = value;
+
+        this.audioWorkletNode?.port.postMessage({
+            type: "set-mix",
+            value
+        });
+    }
+
+    public SetFeedback(value: number) {
+
+        this.feedback = value;
+        this.options.feedback = value;
+
+        this.audioWorkletNode?.port.postMessage({
+            type: "set-mix",
+            value
+        });
+    }
+}

package/lib/src/effects/classes/Distortion.ts

@@ -0,0 +1 @@
+export class Distortion {}

package/lib/src/effects/classes/Equalizer.ts

@@ -0,0 +1 @@
+export class Equalizer {}

package/lib/src/effects/classes/Filter.ts

@@ -0,0 +1 @@
+export class Filter {}

package/lib/src/effects/classes/Limiter.ts

@@ -0,0 +1 @@
+export class Limiter {}

package/lib/src/effects/classes/Saturation.ts

@@ -0,0 +1 @@
+export class Saturation {}

package/lib/src/effects/classes/SoftClip.ts

@@ -0,0 +1,42 @@
+import { compiledWebAssemblyModule } from "../../utilities/web-assembly";
+import { Effector } from "../../core/classes/Effector";
+import { Debug } from "../../utilities/debugger";
+
+export class SoftClip extends Effector {
+
+    constructor(public drive: number = 1) {
+        super();
+    }
+
+    public async InitializeOnAttachment(parentialContext: AudioContext): Promise<void> {
+
+        if(!compiledWebAssemblyModule) return Debug.Error("Could not initialize effector because the nessecary WASM file has not been specified.", [
+            `Effector type: SoftClip`
+        ]);
+
+        this.audioWorkletNode = new AudioWorkletNode(parentialContext, "SoftClipProcessor", {
+            numberOfInputs: 1,
+            numberOfOutputs: 1,
+            outputChannelCount: [2],
+            parameterData: {
+                drive: this.drive
+            },
+            processorOptions: {
+                module: compiledWebAssemblyModule
+            }
+        });
+
+        this.parentialContext = parentialContext;
+    }
+
+    public SetDrive(drive: number): SoftClip {
+
+        if(this.audioWorkletNode) this.audioWorkletNode.port.postMessage({
+            type: "set-drive",
+            value: drive
+        });
+
+        this.drive = drive;
+        return this;
+    }
+}

package/lib/src/effects/classes/StereoPanner.ts

@@ -0,0 +1 @@
+export class StereoPanner {}

package/lib/src/effects/classes/compressors/Compressor.ts

@@ -0,0 +1 @@
+export class Compressor {}

package/lib/src/effects/classes/compressors/MultibandCompressor.ts

@@ -0,0 +1 @@
+export class MultibandCompressor {}

package/lib/src/effects/classes/delays/AdvancedDelay.ts

@@ -0,0 +1 @@
+export class AdvancedDelay {}

package/lib/src/effects/classes/delays/MonoDelay.ts

@@ -0,0 +1 @@
+export class MonoDelay {}

package/lib/src/effects/classes/delays/PingPongDelay.ts

@@ -0,0 +1 @@
+export class PingPongDelay {}

package/lib/src/effects/classes/delays/StereoDelay.ts

@@ -0,0 +1 @@
+export class StereoDelay {}

package/lib/src/effects/classes/reverbs/ChamberReverb.ts

@@ -0,0 +1 @@
+export class ChamberReverb {}

package/lib/src/effects/classes/reverbs/ConvolverReverb.ts

@@ -0,0 +1 @@
+export class ConvolverReverb {}

package/lib/src/effects/classes/reverbs/GenericReverb.ts

@@ -0,0 +1 @@
+export class GenericReverb {}

package/lib/src/effects/classes/reverbs/HallReverb.ts

@@ -0,0 +1 @@
+export class HallReverb {}

package/lib/src/effects/classes/reverbs/RoomReverb.ts

@@ -0,0 +1 @@
+export class RoomReverb {}

package/lib/src/effects/exports.ts

@@ -0,0 +1,22 @@
+export { Chorus } from "./classes/Chorus";
+export { Distortion } from "./classes/Distortion";
+export { Equalizer } from "./classes/Equalizer";
+export { Filter } from "./classes/Filter";
+export { Limiter } from "./classes/Limiter";
+export { Saturation } from "./classes/Saturation";
+export { StereoPanner } from "./classes/StereoPanner";
+export { SoftClip } from "./classes/SoftClip";
+
+export { Compressor } from "./classes/compressors/Compressor";
+export { MultibandCompressor } from "./classes/compressors/MultibandCompressor";
+
+export { AdvancedDelay } from "./classes/delays/AdvancedDelay";
+export { MonoDelay } from "./classes/delays/MonoDelay";
+export { PingPongDelay } from "./classes/delays/PingPongDelay";
+export { StereoDelay } from "./classes/delays/StereoDelay";
+
+export { ChamberReverb } from "./classes/reverbs/ChamberReverb";
+export { ConvolverReverb } from "./classes/reverbs/ConvolverReverb";
+export { GenericReverb } from "./classes/reverbs/GenericReverb";
+export { HallReverb } from "./classes/reverbs/HallReverb";
+export { RoomReverb } from "./classes/reverbs/RoomReverb";