@kidlib/web-audio 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -12,9 +12,9 @@ declare const AudioRecorderState: {
 
 declare type AudioRecorderState = (typeof AudioRecorderState)[keyof typeof AudioRecorderState];
 
-declare type BaseNodeType = 'instrument' | 'voice' | 'fx' | 'param' | 'container' | 'recorder' | 'audiograph';
+declare type BaseNodeType = "instrument" | "voice" | "fx" | "param" | "container" | "recorder" | "audiograph";
 
-declare type BusNodeName = 'input' | 'output' | 'dryMix' | 'wetMix' | 'hpf' | 'lpf' | 'distortion' | 'feedback' | 'reverb' | 'compressor' | 'limiter' | 'delay';
+declare type BusNodeName = "input" | "output" | "dryMix" | "wetMix" | "hpf" | "lpf" | "distortion" | "feedback" | "reverb" | "compressor" | "limiter" | "delay";
 
 declare type BusNodeTypeMap = {
     input: ILibAudioNode<GainNode>;
@@ -36,7 +36,7 @@ declare type BusSendName = `${BusNodeName}_send`;
 /** False in Safari — AudioContext.setSinkId is Chromium/Firefox only */
 export declare function canSetOutputDevice(): boolean;
 
-declare type ContainerType = 'pool' | 'chain' | 'audiolib';
+declare type ContainerType = "pool" | "chain" | "audiolib";
 
 /**
  * Creates and initializes a new audio recorder
@@ -144,7 +144,7 @@ export declare class CustomEnvelope implements LibNode {
     dispose(): void;
 }
 
-declare type CustomFxType = 'feedback-delay' | 'harmonic-feedback' | 'distortion' | 'dattorro-reverb';
+declare type CustomFxType = "feedback-delay" | "harmonic-feedback" | "distortion" | "dattorro-reverb";
 
 declare type CustomLibWaveform = (typeof CUSTOM_WAVEFORMS)[number];
 
@@ -222,7 +222,7 @@ declare class DattorroReverb implements ILibAudioNode {
     setParam(name: string, value: number, time?: number): void;
     getAudioParam(name: string): AudioParam | null;
     setAmountMacro(amount: number): void;
-    setPreset(preset?: 'room' | 'church' | 'freeze' | 'ether' | 'default', rampTime?: number): void;
+    setPreset(preset?: "room" | "church" | "freeze" | "ether" | "default", rampTime?: number): void;
     /**
      DIFFUSION PARAMETER (0.0 - 1.0, default: 0.7)
      Controls reverb density and scatter. Higher = more complex tail.
@@ -273,7 +273,7 @@ declare interface DefaultWorkletConfig extends WorkletConfig {
     message: WorkletMessage;
 }
 
-declare type DelayCharacter = 'clean' | 'bitCrushed' | 'filtered';
+declare type DelayCharacter = "clean" | "bitCrushed" | "filtered";
 
 declare type DelayConfig = {
     params: DelayParams;
@@ -297,8 +297,8 @@ declare type DistortionConfig = {
 };
 
 declare type DistortionMsg = {
-    type: 'setLimitingMode';
-    mode: 'soft-clipping' | 'hard-clipping';
+    type: "setLimitingMode";
+    mode: "soft-clipping" | "hard-clipping";
 };
 
 declare type DistortionParams = {
@@ -315,7 +315,7 @@ export declare class EnvelopeData {
     #private;
     points: EnvelopePoint[];
     constructor(points: EnvelopePoint[] | undefined, valueRange: [number, number] | undefined, durationSeconds: number, sustainIdx?: number, releaseIdx?: number);
-    addPoint(time: number, value: number, curve?: 'linear' | 'exponential'): void;
+    addPoint(time: number, value: number, curve?: "linear" | "exponential"): void;
     updatePoint(index: number, time?: number, value?: number): void;
     updateStartPoint: (time?: number, value?: number) => void;
     updateEndPoint: (time?: number, value?: number) => void;
@@ -339,10 +339,10 @@ export declare class EnvelopeData {
 export declare type EnvelopePoint = {
     time: number;
     value: number;
-    curve?: 'linear' | 'exponential';
+    curve?: "linear" | "exponential";
 };
 
-export declare type EnvelopeType = 'amp-env' | 'pitch-env' | 'filter-env' | 'loop-env' | 'default-env';
+export declare type EnvelopeType = "amp-env" | "pitch-env" | "filter-env" | "loop-env" | "default-env";
 
 declare type FbDelayConfig = {
     params: FbDelayParams;
@@ -350,14 +350,14 @@ declare type FbDelayConfig = {
 };
 
 declare type FbDelayMsg = {
-    type: 'setAutoGain';
+    type: "setAutoGain";
     enabled: boolean;
     amount: number;
 } | {
-    type: 'triggerDecay';
+    type: "triggerDecay";
     baseFeedbackAmount: number;
 } | {
-    type: 'stopDecay';
+    type: "stopDecay";
 };
 
 declare type FbDelayParams = {
@@ -495,13 +495,13 @@ declare class InstrumentBus implements ILibAudioNode {
     /**
      * Set the character modes for the delay processor, in the order in which to process (e.g. ['filtered', 'bitCrushed'])
      */
-    setDelayCharacter(modes: Array<'clean' | 'bitCrushed' | 'filtered'>): this;
+    setDelayCharacter(modes: Array<"clean" | "bitCrushed" | "filtered">): this;
     setReverbSize(amount: number): this;
     setReverbDecay(decay: number): this;
     setDistortionMacro(amount: number): void;
     setDrive(amount: number): this;
     setClippingMacro(amount: number): this;
-    setClippingMode(mode: 'soft-clipping' | 'hard-clipping'): void;
+    setClippingMode(mode: "soft-clipping" | "hard-clipping"): void;
     setFeedbackAmount(amount: number): this;
     setFeedbackPitchScale(value: number): this;
     setFeedbackDecay(amount: number): this;
@@ -551,11 +551,11 @@ declare class InstrumentBus implements ILibAudioNode {
     onMessage(type: string, handler: MessageHandler<Message>): () => void;
 }
 
-declare type InstrumentType = 'sample-player' | 'synth';
+declare type InstrumentType = "sample-player" | "synth";
 
 export declare type KeyMap = Record<string, number>;
 
-export declare type KeymapKey = 'piano' | 'major' | 'minor' | 'pentatonic' | 'chromatic';
+export declare type KeymapKey = "piano" | "major" | "minor" | "pentatonic" | "chromatic";
 
 export declare const keymaps: Record<KeymapKey, KeyMap>;
 
@@ -629,7 +629,7 @@ declare class MacroParam {
     init(): Promise<void>;
     addTarget(targetParam: AudioParam, paramType: string, scaleFactor?: number): this;
     ramp(targetValue: number, duration: number, constant: number, options?: {
-        method?: 'exponential' | 'linear';
+        method?: "exponential" | "linear";
         debounceMs?: number;
         onComplete?: () => void;
         onCompleteDelayMs?: number;
@@ -678,7 +678,7 @@ declare interface Message {
 
 declare type MessageHandler<T> = (data: T) => void;
 
-declare type NativeAudioNode = 'AudioWorkletNode' | 'GainNode' | 'BiquadFilterNode' | 'AudioBufferSourceNode' | 'DynamicsCompressorNode';
+declare type NativeAudioNode = "AudioWorkletNode" | "GainNode" | "BiquadFilterNode" | "AudioBufferSourceNode" | "DynamicsCompressorNode";
 
 declare type NodeID_2 = string;
 
@@ -772,12 +772,12 @@ export declare class Recorder implements LibNode {
 }
 
 export declare type RecorderInput = {
-    type: 'microphone';
+    type: "microphone";
     deviceId?: string;
 } | {
-    type: 'display';
+    type: "display";
 } | {
-    type: 'audio-node';
+    type: "audio-node";
     node: AudioNode;
 };
 
@@ -788,8 +788,6 @@ declare type RecorderOptions = {
     autoStop: boolean;
     stopThreshold: number;
     silenceTimeoutMs: number;
-    preprocess: boolean;
-    preprocessOptions: object;
 };
 
 export declare type RecorderStartOptions = Partial<RecorderOptions> & {
@@ -798,20 +796,20 @@ export declare type RecorderStartOptions = Partial<RecorderOptions> & {
 
 declare const ROOT_NOTES: {
     readonly C: 0;
-    readonly 'C#': 1;
+    readonly "C#": 1;
     readonly Db: 1;
     readonly D: 2;
-    readonly 'D#': 3;
+    readonly "D#": 3;
     readonly Eb: 3;
     readonly E: 4;
     readonly F: 5;
-    readonly 'F#': 6;
+    readonly "F#": 6;
     readonly Gb: 6;
     readonly G: 7;
-    readonly 'G#': 8;
+    readonly "G#": 8;
     readonly Ab: 8;
     readonly A: 9;
-    readonly 'A#': 10;
+    readonly "A#": 10;
     readonly Bb: 10;
     readonly B: 11;
 };
@@ -825,6 +823,7 @@ export declare class SamplePlayer implements ILibInstrumentNode {
     readonly nodeId: NodeID_2;
     readonly nodeType: "sample-player";
     readonly context: AudioContext;
+    static readonly MAX_LAYERS = 4;
     randomizeVelocity: boolean;
     voicePool: SampleVoicePool;
     outBus: InstrumentBus;
@@ -845,13 +844,24 @@ export declare class SamplePlayer implements ILibInstrumentNode {
     get output(): GainNode;
     get now(): number;
     get initialized(): boolean;
-    getMacrosAudioParam(paramName: 'loopStart' | 'loopEnd'): AudioParam;
-    getMacro(paramName: 'loopStart' | 'loopEnd'): MacroParam;
+    getMacrosAudioParam(paramName: "loopStart" | "loopEnd"): AudioParam;
+    getMacro(paramName: "loopStart" | "loopEnd"): MacroParam;
     setModulationAmount: (modType: "AM" | "FM", amount: number) => void;
-    setModulationWaveform(modType?: 'AM' | 'FM', waveform?: CustomLibWaveform | OscillatorType | PeriodicWave, customWaveOptions?: WaveformOptions): void;
-    syncLFOsToNoteFreq(lfoId: 'gain-lfo' | 'pitch-lfo', enabled: boolean): void;
+    setModulationWaveform(modType?: "AM" | "FM", waveform?: CustomLibWaveform | OscillatorType | PeriodicWave, customWaveOptions?: WaveformOptions): void;
+    syncLFOsToNoteFreq(lfoId: "gain-lfo" | "pitch-lfo", enabled: boolean): void;
     freezeActiveVoices(freeze: boolean): this;
+    /**
+     * Load a single sample. Equivalent to `loadLayers([buffer])`: any previously
+     * loaded extra layers are cleared.
+     */
     loadSample(buffer: AudioBuffer | ArrayBuffer, modSampleRate?: number, preprocessOptions?: Partial<PreProcessOptions>): Promise<AudioBuffer | null>;
+    /**
+     * Replace the whole layer set. Layers are summed inside the voice worklet at
+     * one shared playhead, so they play in unison and layer 0 is the authority
+     * for duration, loop points, start/end and zero crossings. Layers shorter
+     * than layer 0 fall silent at their own end; longer ones are truncated.
+     */
+    loadLayers(buffers: (AudioBuffer | ArrayBuffer)[], modSampleRate?: number, preprocessOptions?: Partial<PreProcessOptions>): Promise<AudioBuffer[] | null>;
     cropSample(startSeconds?: number, endSeconds?: number, fadeMs?: number): Promise<AudioBuffer | null>;
     detectPitch(buffer: AudioBuffer): Promise<{
         frequency: number;
@@ -888,7 +898,7 @@ export declare class SamplePlayer implements ILibInstrumentNode {
     setSustainPedal(pressed: boolean): this;
     sustainPedalOn: () => this;
     sustainPedalOff: () => this;
-    setPlaybackDirection(direction: 'forward' | 'reverse'): this;
+    setPlaybackDirection(direction: "forward" | "reverse"): this;
     setLoopDurationDriftAmount(amount: number): this;
     setPanDriftEnabled: (enabled: boolean) => this;
     setTimestretchEnabled: (enabled: boolean) => this;
@@ -903,7 +913,7 @@ export declare class SamplePlayer implements ILibInstrumentNode {
     setKeytrackLoopAmount(amount: number): this;
     getKeytrackLoopAmount: () => number;
     get tempo(): number;
-    setLoopPoint(loopPoint: 'start' | 'end', loopStartSeconds: number, loopEndSeconds: number, rampDuration?: number): this;
+    setLoopPoint(loopPoint: "start" | "end", loopStartSeconds: number, loopEndSeconds: number, rampDuration?: number): this;
     scrollLoopPoints(loopStart: number, loopEnd: number): this;
     setParam(name: string, value: number): this;
     applyParams(params: SamplerParamPatch): this;
@@ -941,7 +951,7 @@ export declare class SamplePlayer implements ILibInstrumentNode {
     setFeedbackDecay(value: number): void;
     setFeedbackLowpassCutoff(freqHz: number): void;
     setFeedbackAmount: (amount: number) => void;
-    setFeedbackMode(mode: 'monophonic' | 'polyphonic' | 'double-trouble'): void;
+    setFeedbackMode(mode: "monophonic" | "polyphonic" | "double-trouble"): void;
     setFeedbackPitchScale(value: number): void;
     get mainOut(): GainNode;
     get outputBus(): InstrumentBus;
@@ -956,6 +966,8 @@ export declare class SamplePlayer implements ILibInstrumentNode {
     get loopEnd(): number;
     get isLoaded(): boolean;
     get audiobuffer(): AudioBuffer | null;
+    /** All loaded layers. Index 0 is the authority layer (=== `audiobuffer`). */
+    get layers(): readonly AudioBuffer[];
     dispose(): void;
 }
 
@@ -1035,6 +1047,13 @@ declare class SampleVoice {
     });
     init(): Promise<void>;
     loadBuffer(buffer: AudioBuffer, zeroCrossings?: number[]): Promise<boolean>;
+    /**
+     * Replace the whole layer set. Layers are summed at one shared playhead, so
+     * layer 0 is the authority for duration and all range math; the rest only
+     * add samples. A layer at the wrong sample rate is dropped on its own,
+     * leaving the others playable, except layer 0: losing it fails the load.
+     */
+    loadLayers(buffers: AudioBuffer[], zeroCrossings?: number[]): Promise<boolean>;
     freeze(freeze: boolean): this;
     setGlideTime(seconds: number): void;
     trigger(options: {
@@ -1052,8 +1071,8 @@ declare class SampleVoice {
         secondsFromNow?: number | undefined;
     }): this;
     stop(timestamp?: number): this;
-    setModulationAmount(modType: 'AM' | 'FM', amount: number): this;
-    setModulationWaveform(modType?: 'AM' | 'FM', waveform?: CustomLibWaveform | OscillatorType | PeriodicWave, customWaveOptions?: WaveformOptions): this;
+    setModulationAmount(modType: "AM" | "FM", amount: number): this;
+    setModulationWaveform(modType?: "AM" | "FM", waveform?: CustomLibWaveform | OscillatorType | PeriodicWave, customWaveOptions?: WaveformOptions): this;
     enableEnvelope: (envType: EnvelopeType) => void;
     disableEnvelope: (envType: EnvelopeType) => void;
     setEnvelopeTimeScale: (envType: EnvelopeType, timeScale: number) => void;
@@ -1125,7 +1144,7 @@ declare class SampleVoice {
         glideTime?: number;
         cancelPrevious?: boolean;
     }): this;
-    setPlaybackDirection(direction: 'forward' | 'reverse'): this;
+    setPlaybackDirection(direction: "forward" | "reverse"): this;
     setLoopDurationDriftAmount(amount: number): this;
     setPanDriftEnabled: (enabled: boolean) => this;
     setTimestretchEnabled: (enabled: boolean) => this;
@@ -1144,7 +1163,7 @@ declare class SampleVoicePool implements LibNode {
     disconnect(): void;
     onMessage(type: string, handler: MessageHandler<Message>): () => void;
     sendUpstreamMessage(type: string, data: any): this;
-    setBuffer(buffer: AudioBuffer, zeroCrossings?: number[]): this;
+    setLayers(buffers: AudioBuffer[], zeroCrossings?: number[]): this;
     allocate(available?: Set<SampleVoice>, releasing?: Set<SampleVoice>): SampleVoice | undefined;
     prevMidiNote: number;
     noteOn(midiNote: MidiValue, velocity?: MidiValue, secondsFromNow?: number, glideTime?: number): MidiValue | null;
@@ -1190,7 +1209,7 @@ declare const SCALE_PATTERNS: {
 export declare function setAudioOutputDevice(deviceId: string): Promise<void>;
 
 declare type SetDelayCharacterMsg = {
-    type: 'setCharacter';
+    type: "setCharacter";
     modes: DelayCharacter[];
 };
 
@@ -1198,10 +1217,10 @@ declare type SetDelayCharacterMsg = {
 export declare const SUPPORTED_WAVEFORMS: readonly SupportedWaveform[];
 
 /** Union type of all supported waveforms */
-export declare type SupportedWaveform = 'sine' | 'sawtooth' | 'square' | 'triangle' | CustomLibWaveform;
+export declare type SupportedWaveform = "sine" | "sawtooth" | "square" | "triangle" | CustomLibWaveform;
 
 declare type TriggerDelayMsg = {
-    type: 'trigger';
+    type: "trigger";
 };
 
 declare class ValueSnapper {
@@ -1210,8 +1229,8 @@ declare class ValueSnapper {
     setScale(rootNote: keyof typeof ROOT_NOTES, scalePattern: readonly number[] | number[], tuningOffset: number | undefined, // in semitones
     lowestOctave: number | undefined, highestOctave: number | undefined, normalize: NormalizeOptions | false, snapToZeroCrossings?: number[] | false): number[];
     setRootNote(rootNote: keyof typeof ROOT_NOTES): void;
-    setAllowedPeriods(periods: number[], normalize: NormalizeOptions | false, snapToZeroCrossings?: number[] | false, direction?: 'left' | 'right' | 'any'): number[];
-    snapToValue(target: number, allowedValues?: number[], tolerance?: number, preferDirection?: 'left' | 'right' | 'any'): number;
+    setAllowedPeriods(periods: number[], normalize: NormalizeOptions | false, snapToZeroCrossings?: number[] | false, direction?: "left" | "right" | "any"): number[];
+    snapToValue(target: number, allowedValues?: number[], tolerance?: number, preferDirection?: "left" | "right" | "any"): number;
     snapToMusicalPeriod(targetPeriod: number, allowedPeriods?: number[]): number;
     setAllowedValues(values: number[], normalize: NormalizeOptions | false): number[];
     get rootNote(): "C" | "C#" | "Db" | "D" | "D#" | "Eb" | "E" | "F" | "F#" | "Gb" | "G" | "G#" | "Ab" | "A" | "A#" | "Bb" | "B";
@@ -1234,7 +1253,7 @@ declare const VoiceState: {
 
 declare type VoiceState = (typeof VoiceState)[keyof typeof VoiceState];
 
-declare type VoiceType = 'sample-voice' | 'karplus-strong-voice' | 'osc-voice' | 'noise-voice';
+declare type VoiceType = "sample-voice" | "karplus-strong-voice" | "osc-voice" | "noise-voice";
 
 /**
  * Generic options interface that can be used with any CustomLibWaveform type
@@ -1268,11 +1287,11 @@ declare class WorkletNode<TConfig extends WorkletConfig = DefaultWorkletConfig>
     private _processorReady;
     private _messageQueue;
     constructor(audioContext: AudioContext, processorName: string, options?: AudioWorkletNodeOptions);
-    setParam<K extends keyof TConfig['params']>(name: K, value: TConfig['params'][K]): this;
-    getParam<K extends keyof TConfig['params']>(name: K): AudioParam | undefined;
-    sendProcessorMessage(message: TConfig['message']): this;
+    setParam<K extends keyof TConfig["params"]>(name: K, value: TConfig["params"][K]): this;
+    getParam<K extends keyof TConfig["params"]>(name: K): AudioParam | undefined;
+    sendProcessorMessage(message: TConfig["message"]): this;
     private _onProcessorMessage?;
-    onProcessorMessage(callback: (event: MessageEvent<TConfig['message']>) => void): this;
+    onProcessorMessage(callback: (event: MessageEvent<TConfig["message"]>) => void): this;
     dispose(): void;
 }