Quick-Sonic-Worklet Library

Quick-Sonic-Worklet is a TypeScript library designed to streamline the downloading, decoding, and playback of audio files using Web Workers and AudioWorklet. It supports multi-track playback, master volume control, and professional-grade audio effects.

Features

• Worker-based Audio Downloading: Offload audio file downloads to a Web Worker for efficient background processing.
• Main Thread Decoding & Playback: Use decodeAudioData and AudioWorklet for high-performance audio decoding and playback.
• Multi-Track Support: Play multiple audio tracks simultaneously with individual controls.
• Professional Audio Effects: EQ, modulation (chorus/flanger/vibrato), Schroeder reverb, delay, echo, drive, and dynamics.
• Real-time Parameter Control: All effects can be adjusted in real-time during playback.
• Visualizer Integration: Real-time visualizer data handling for audio visualization.
• Master Volume & Low-Pass Filter: Control overall volume and apply global audio filters.

Installation

npm install quick-sonic-worklet

Usage

Importing the Library

import { AudioPreloader } from "./AudioPreloader";
import { AudioLoadWorker } from "./AudioLoader.worker";

Initialization

const fileMap = {
	track1: "audio/track1.mp3",
	track2: "audio/track2.mp3",
};

const preloader = new AudioPreloader(
	"https://example.com/",
	fileMap,
	AudioLoadWorker
);

Loading and Decoding Audio

await preloader.loadAll();
await preloader.decodeAll();
await preloader.initAudioWorklet(workletUrl);

Playing Audio

preloader.playAudio("track1", true, 1.5);  // loop, 1.5x speed
preloader.adjustVolume("track1", 0.8);
preloader.stopAudio("track1");

Audio Effects

EQ (Equalizer)

preloader.adjustEQ("track1", [
	{ frequency: 60, gain: 5 },      // Bass boost (+5dB)
	{ frequency: 1000, gain: -3 },   // Mid cut (-3dB)
	{ frequency: 8000, gain: 2 },    // Treble boost (+2dB)
]);

Modulation Effects

| Type | Description | |------|-------------| | chorus | Rich, layered sound with delayed signal | | flanger | Jet-like sweeping effect | | vibrato | Pitch modulation | | tremolo | Amplitude modulation | | ring | Ring modulation | | square / triangle / sawtooth | Waveform-based modulation |

preloader.adjustModulation("track1", {
	type: "chorus",   // Modulation type
	depth: 0.5,       // 0.0 ~ 1.0
	rate: 2.0         // Hz
});

Reverb (Schroeder Reverb)

Using Presets

| Preset | Decay | Diffusion | Description | |--------|-------|-----------|-------------| | small | 0.70 | 0.40 | Small room | | medium | 0.80 | 0.50 | Medium room | | large | 0.85 | 0.55 | Large room | | hall | 0.90 | 0.60 | Concert hall | | plate | 0.88 | 0.70 | Plate reverb | | cathedral | 0.95 | 0.65 | Cathedral |

preloader.adjustEffects("track1", {
	reverb: 0.5,        // Wet/dry mix (0~1)
	roomSize: "hall"    // Preset
});

Custom Parameters

preloader.adjustEffects("track1", {
	reverb: 0.5,
	reverbDecay: 0.9,      // Decay time (0~1)
	reverbDiffusion: 0.6   // Diffusion (0~1)
});

Delay & Echo

preloader.adjustEffects("track1", {
	delay: 300,   // Delay time in ms (0~2000)
	echo: 200     // Echo time in ms (0~1000, multi-tap)
});

Drive Effects

preloader.adjustDrive("track1", {
	distortion: 0.5,   // Hard clipping (0~1)
	overdrive: 0.3,    // Soft clipping (0~1)
	fuzz: 0.7          // Asymmetric clipping + harmonics (0~1)
});

Dynamics (Compressor)

preloader.adjustDynamics("track1", {
	threshold: -24,   // dB (-60 ~ 0)
	ratio: 4          // Compression ratio (1 ~ 20)
});

Latency Control

preloader.adjustLatency("track1", 50);         // 50ms delay
preloader.adjustLatencySamples("track1", 2400); // 2400 samples delay

Visualizer

preloader.setVisualizerDataHandler((data) => {
	console.log("Band levels:", data);
});

preloader.setVisualizerBands("", [
	{ startFrequency: 20, endFrequency: 200 },
	{ startFrequency: 200, endFrequency: 2000 },
	{ startFrequency: 2000, endFrequency: 20000 },
]);

preloader.setVisualizerBufferSize(256);  // 32~1024

API Reference

Methods

| Method | Description | |--------|-------------| | loadAll() | Download all audio files | | decodeAll() | Decode all downloaded audio | | initAudioWorklet(url) | Initialize AudioWorklet | | playAudio(key, loop?, rate?) | Play a track | | stopAudio(key) | Stop a track | | clearAudio(key) | Remove track from memory | | adjustVolume(key, volume) | Set track volume (0~1) | | adjustEQ(key, bands) | Apply EQ settings | | adjustModulation(key, settings) | Apply modulation | | adjustEffects(key, settings) | Apply delay/reverb/echo | | adjustDrive(key, settings) | Apply drive effects | | adjustDynamics(key, settings) | Apply compression | | adjustLatency(key, ms) | Set latency in ms | | adjustLatencySamples(key, samples) | Set latency in samples | | adjustNormalize(key, flag) | Enable/disable normalization | | setMasterVolume(volume) | Set master volume | | setLowPassFilter(cutoff, Q) | Apply low-pass filter | | setVisualizerDataHandler(callback) | Set visualizer callback | | setVisualizerBands(key, bands) | Configure visualizer bands | | setVisualizerBufferSize(size) | Set FFT buffer size | | resumeContext() | Resume AudioContext | | suspendContext() | Suspend AudioContext | | releaseAllResources() | Release all resources |

Properties

| Property | Description | |----------|-------------| | progress | Loading progress (0~1) | | downloadedCount | Downloaded file count | | downloadedTotal | Total file count | | loaded | All files loaded |

License

MIT License