@fluex/fluexgl-dsp 0.1.2

package/lib/src/index.ts

@@ -0,0 +1,93 @@
+/**
+ * FluexGL Audio
+ * A javascript digital audio processor library.
+ */
+
+import { FluexGLAudioDescriptor } from "./typings";
+
+export const FluexGLAudio: FluexGLAudioDescriptor = {
+    name: "FluexGL Audio",
+    author: "Rohan Kanhaisingh",
+    version: "0.0.2",
+    license: "MIT",
+    repository: "https://github.com/rohankanhaisingh/FluexGL-Audio",
+    options: {
+        maxMasterChannels: 8,
+        maxTotalChannels: 128,
+        sampleRate: 44000,
+        spatialization: "stereo",
+        debugger: {
+            showErrors: true,
+            showInfo: true,
+            showWarnings: true,
+            breakOnError: true
+        }
+    }
+}
+
+export {
+    Chorus,
+    Distortion,
+    Equalizer,
+    Filter,
+    Limiter,
+    Saturation,
+    StereoPanner,
+    Compressor,
+    MultibandCompressor,
+    AdvancedDelay,
+    MonoDelay,
+    PingPongDelay,
+    StereoDelay,
+    ChamberReverb,
+    ConvolverReverb,
+    GenericReverb,
+    HallReverb,
+    RoomReverb,
+    SoftClip
+} from "./effects/exports";
+
+export {
+    AudioDevice,
+    Channel,
+    Effector,
+    Master,
+    AudioClip,
+    DspPipeline
+} from "./core/exports";
+
+export {
+    InitializeDspPipeline,
+    ResolveAudioOutputDevices,
+    ResolveAudioInputDevices,
+    ResolveDefaultAudioInputDevice,
+    ResolveDefaultAudioOutputDevice,
+    LoadAudioSource,
+    LoadWorkletOnMasterChannel,
+} from "./utilities/helpers";
+
+export {
+    SUPPORTED_FILE_TYPES
+} from "./utilities/constants";
+
+export {
+    hasInitializedWasm,
+} from "./utilities/web-assembly";
+
+export type {
+    FluexGLAudioDescriptor,
+    FluexGLAudioDebuggerOptions,
+    FluexGLAudioOptions,
+    LoadAudioSourceOptions,
+    AudioSourceData,
+    ChannelOptions,
+    ChannelSpatialization,
+    AudioClipEventMap,
+    AudioClipEvents,
+    AudioClipOnProgressEvent,
+    AudioClipAnalyserProperty,
+    AudioClipAnalyserType,
+    DspPipelineInitializationOptions,
+    DspPipelineInitializationState,
+    ChorusEffectOptions
+} from "./typings";

package/lib/src/typings.ts

@@ -0,0 +1,79 @@
+export type ChannelSpatialization = "mono" | "stereo" | "surround";
+
+export type AudioClipAnalyserType = "pre" | "post";
+export type AudioClipAnalyserProperty = "fftSize" | "minDecibels" | "maxDecibels" | "smoothingTimeConstant";
+
+export type AudioClipEvents  = {
+    [K in keyof AudioClipEventMap]: AudioClipEventMap[K][];
+}
+
+export interface FluexGLAudioDebuggerOptions {
+    breakOnError: boolean;
+    showInfo: boolean;
+    showErrors: boolean;
+    showWarnings: boolean;
+}
+
+export interface FluexGLAudioOptions {
+    maxMasterChannels: number;
+    maxTotalChannels: number;
+    sampleRate: number;
+    spatialization: ChannelSpatialization;
+    debugger: FluexGLAudioDebuggerOptions;
+}
+
+export interface FluexGLAudioDescriptor {
+    name: string;
+    author: string;
+    version: string;
+    license: string;
+    repository: string;
+    options: FluexGLAudioOptions;
+}
+
+export interface LoadAudioSourceOptions {
+    allowForeignFileTypes: boolean;
+}
+
+export interface AudioSourceData {
+    arrayBuffer: ArrayBuffer;
+    audioBuffer: AudioBuffer;
+    id: string;
+    timestamp: number;
+}
+
+export interface ChannelOptions {
+    label: string | null;
+    maxAudioNodes: number;
+    maxEffects: number;
+}
+
+export interface AudioClipOnProgressEvent {
+    startTime: number;
+    offset: number;
+    current: number;
+    contextTimestamp: number;
+    formatted: string;
+}
+
+export interface AudioClipEventMap {
+    "progress": (event: AudioClipOnProgressEvent) => void;
+}
+
+export interface DspPipelineInitializationOptions {
+    pathToWasm: string;
+    pathToWorklet: string;
+}
+
+export interface DspPipelineInitializationState {
+    success: boolean;
+    workletBlobUrl: string;
+}
+
+export interface ChorusEffectOptions {
+    baseDelayMs?: number;
+    depthMs?: number;
+    rateHz?: number;
+    mix?: number;
+    feedback?: number;  
+}

package/lib/src/utilities/constants.ts

@@ -0,0 +1,9 @@
+export const SUPPORTED_FILE_TYPES: string[] = [
+    "audio/aac",
+    "audio/mp3",
+    "audio/mpeg",
+    "audio/ogg",
+    "audio/wav",
+    "audio/wave",
+    "audio/webm"
+];

package/lib/src/utilities/debugger.ts

@@ -0,0 +1,66 @@
+import { ErrorCodes, WarningCodes } from "../console-codes";
+
+import { FluexGLAudio } from "../index";
+
+export namespace Debug {
+
+    export function Log(message: string, additionalDetails?: string[]) {
+
+        if (!FluexGLAudio.options.debugger.showInfo) return;
+
+        let outputString: string = `%c[INFO]: %c${message} %c`;
+
+        additionalDetails && additionalDetails.forEach(function (detail: string) {
+            outputString += `\n\u0009  > ${detail}`
+        });
+
+        return console.log(outputString, "color: white;", "color: gray", "color: gray");
+    }
+
+    export function Success(message: string, additionalDetails?: string[]) {
+
+        if (!FluexGLAudio.options.debugger.showInfo) return;
+
+        let outputString: string = `%c[SUCCESS]: %c${message} %c`;
+
+        additionalDetails && additionalDetails.forEach(function (detail: string) {
+            outputString += `\n\u0009  > ${detail}`
+        });
+
+        return console.log(outputString, "color: lime;", "color: white", "color: gray");
+    }
+
+    export function Warn(message: string, additionalDetails?: string[], warningCode?: WarningCodes) {
+
+        if (!FluexGLAudio.options.debugger.showWarnings) return;
+
+        let outputString: string = `%c(${warningCode ? warningCode : "Unknown".toUpperCase()}) %c[WARNING]: %c${message} %c`;
+
+        (additionalDetails && additionalDetails !== null) && additionalDetails.forEach(function (detail: string) {
+            outputString += `\n\u0009  > ${detail}`
+        });
+
+        return console.log(outputString, "color: gray", "color: yellow;", "color: white", "color: white; font-style: italic;");
+    }
+
+    export function Error(message: string, additionalDetails?: string[], errorCode?: ErrorCodes) {
+
+        if (!FluexGLAudio.options.debugger.showErrors) return;
+
+        let outputString: string = `%c(${errorCode ? errorCode : "Unknown".toUpperCase()}) %c[ERROR]: %c${message} %c`;
+
+        (additionalDetails && additionalDetails !== null) && additionalDetails.forEach(function (detail: string) {
+            outputString += `\n\u0009  > ${detail}`
+        });
+
+        console.log(outputString, "color: red", "color: red;", "color: white", "color: white; font-style: italic;");
+
+        if (FluexGLAudio.options.debugger.breakOnError) {
+
+            for (let char of message)
+                outputString = outputString.replace("%c", "");
+
+            throw new window.Error(outputString);
+        }
+    }
+}

package/lib/src/utilities/helpers.ts

@@ -0,0 +1,215 @@
+import mime from "mime";
+import { v4 } from "uuid";
+
+import { AudioDevice } from "../core/classes/AudioDevice";
+import { Master } from "../core/classes/Master";
+
+import { Debug } from "./debugger";
+import { SUPPORTED_FILE_TYPES } from "./constants";
+
+import { LoadWebAssemblyModule } from "./web-assembly";
+import { ErrorCodes, WarningCodes } from "../console-codes";
+
+import { LoadAudioSourceOptions, AudioSourceData, DspPipelineInitializationOptions, DspPipelineInitializationState } from "../typings";
+
+/**
+ * Initializes the DSP pipeline by requesting audio permissions and initializing the WASM module.
+ * Very important to call this function and wait for it to complete before using any audio features.
+ * 
+ * FluexGL DSP cannot be used without calling this function first.
+ * @returns 
+ */
+export async function InitializeDspPipeline(options: DspPipelineInitializationOptions): Promise<DspPipelineInitializationState | null> {
+    Debug.Log("Attempting to initialize DSP pipeline...");
+
+    const start: number = Date.now();
+    let initialized: boolean = true;
+
+    try {
+
+        const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+
+        Debug.Log(`Found ${stream.getTracks().length} media stream tracks.`);
+
+        stream.getTracks().forEach(function (track: MediaStreamTrack) {
+            track.stop();
+        });
+    } catch (err) {
+
+        initialized = false;
+
+        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)
+    }
+
+    await LoadWebAssemblyModule(options.pathToWasm);
+
+    const workletFileRequest = await fetch(options.pathToWorklet);
+    const textContent: string = await workletFileRequest.text();
+
+    const blobUrl: string = ConstructProcessorWorklet(textContent);
+
+    const end: number = Date.now(),
+        difference: number = end - start;
+
+    Debug.Success(`Succesfully initialized DSP pipeline within ${difference}ms.`);
+
+    return {
+        success: true,
+        workletBlobUrl: blobUrl
+    };
+}
+
+/**
+ * Resolves a list of available audio output devices.
+ * @returns 
+ */
+export async function ResolveAudioOutputDevices(): Promise<AudioDevice[]> {
+
+    const devices = await navigator.mediaDevices.enumerateDevices();
+
+    const audioDevices: AudioDevice[] = [];
+
+    for (let device of devices)
+        device.kind === "audiooutput" && audioDevices.push(new AudioDevice(device));
+
+    return audioDevices;
+}
+
+/**
+ * Resolves a list of available audio input devices.
+ * @returns 
+ */
+export async function ResolveAudioInputDevices(): Promise<AudioDevice[]> {
+
+    const devices = await navigator.mediaDevices.enumerateDevices();
+
+    const audioDevices: AudioDevice[] = [];
+
+    for (let device of devices)
+        device.kind === "audioinput" && audioDevices.push(new AudioDevice(device));
+
+    return audioDevices;
+}
+
+/**
+ * Resolves the default audio output device.
+ * @returns 
+ */
+export async function ResolveDefaultAudioOutputDevice(init: DspPipelineInitializationState): Promise<AudioDevice | null> {
+    Debug.Log("Attempting to resolve default audio output device...");
+    
+    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, init.workletBlobUrl);
+
+    return defaultAudioDevice;
+}
+
+/**
+ * Resolves the default audio input device.
+ * @returns 
+ */
+export async function ResolveDefaultAudioInputDevice(init: DspPipelineInitializationState): Promise<AudioDevice | null> {
+    Debug.Log("Attempting to resolve default audio output device...");
+    
+    const audioDeviceInfos: MediaDeviceInfo[] = [];
+    const devices = await navigator.mediaDevices.enumerateDevices();
+
+    for (let device of devices)
+        (device.kind === "audioinput" && 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, init.workletBlobUrl);
+
+    return defaultAudioDevice;
+}
+
+/**
+ * Loads an audio source from a specified path.
+ * @param path 
+ * @param options 
+ * @returns 
+ */
+export async function LoadAudioSource(path: string, options: Partial<LoadAudioSourceOptions> = { allowForeignFileTypes: false }): Promise<AudioSourceData | null> {
+
+    const extension: string | null = mime.getType(path);
+
+    if (!extension && !options.allowForeignFileTypes) {
+
+        Debug.Error("The file type of the specified file could not be identified.", [
+            `Set allowForeignFileTypes to true in the properties to allow foreign or unknown file types.`
+        ], ErrorCodes.NO_FILE_TYPE_FOUND);
+        return null;
+    }
+
+    if (!SUPPORTED_FILE_TYPES.includes(extension as string)) Debug.Warn("The file type of the specified file is unknown and possibly unknown, but will be used anyways.");
+
+    const file = await fetch(path, { method: "get" });
+
+    if (file.status !== 200) {
+
+        Debug.Error("The specified file could not be loaded.", [
+            `Received status code: ${file.status}.`
+        ], ErrorCodes.PATH_TO_FILE_NOT_FOUND);
+        return null;
+    }
+
+    const tempContext = new AudioContext(),
+        arrayBuffer = await file.arrayBuffer(),
+        audioBuffer = await tempContext.decodeAudioData(arrayBuffer);
+
+    // IMPORTANT!
+    tempContext.close();
+
+    return {
+        arrayBuffer, audioBuffer,
+        id: v4(),
+        timestamp: Date.now()
+    }
+}
+
+export function ConstructProcessorWorklet(code: string): string {
+
+    const blob = new Blob([code], {
+        type: "application/javascript"
+    });
+
+    return URL.createObjectURL(blob);
+}
+
+export async function LoadWorkletOnMasterChannel(master: Master, workletBlobUrl: string) {
+    Debug.Log("Loading worklet modules on master channel...", [ `Channel ID: ${master.id}` ]);
+
+    const context: AudioContext = master.context,
+        start: number = Date.now();
+
+    await context.audioWorklet.addModule(workletBlobUrl);
+
+    const end: number = Date.now(),
+        difference: number = end - start;
+
+    Debug.Success("Succesfully loaded audio processor worklets into master channel.", [
+        `Executed in ${difference}ms.`,
+    ]);
+
+    return true;
+}

package/lib/src/utilities/web-assembly.ts

@@ -0,0 +1,14 @@
+export let hasInitializedWasm: boolean = false;
+export let compiledWebAssemblyModule: WebAssembly.Module | null = null;
+
+export async function LoadWebAssemblyModule(path: string): Promise<WebAssembly.Module> {
+
+    return new Promise(function(resolve, reject) {
+        WebAssembly.compileStreaming(fetch(path)).then(function(module: WebAssembly.Module) {
+            compiledWebAssemblyModule = module;
+            resolve(module);
+        }).catch(function(error: Error) {
+            reject(error);
+        });
+    })
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@fluex/fluexgl-dsp",
+    "version": "0.1.2",
+    "description": "An open-source, web-based DSP library developed alongside FluexGL, designed for creating and manipulating sounds in various contexts.",
+    "main": "lib/dist/index.js",
+    "types": "lib/dist/index.d.ts",
+    "scripts": {
+        "typecheck": "tsc -p lib/tsconfig.json --noEmit",
+        "build": "tsc --build"
+    },
+    "keywords": [
+        "Audio",
+        "WebAudio",
+        "Advanced",
+        "audio",
+        "processing",
+        "DSP"
+    ],
+    "files": [
+        "lib",
+        "README.md",
+        "LICENSE"
+    ],
+    "author": "Rohan Kanhaisingh",
+    "license": "MIT",
+    "dependencies": {
+        "@types/uuid": "^10.0.0",
+        "date-fns": "^4.1.0",
+        "mime": "^4.1.0",
+        "terser": "^5.44.0",
+        "truncate": "^3.0.0",
+        "uuid": "^13.0.0"
+    },
+    "devDependencies": {
+        "@types/node": "^24.9.2",
+        "concurrently": "^9.2.1"
+    },
+    "directories": {
+        "doc": "docs",
+        "lib": "lib"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/rohankanhaisingh/FluexGL-DSP.git"
+    },
+    "bugs": {
+        "url": "https://github.com/rohankanhaisingh/FluexGL-DSP/issues"
+    },
+    "homepage": "https://github.com/rohankanhaisingh/FluexGL-DSP#readme"
+}