/**
 * AudioTypes.ts
 *
 * Core type definitions for the HoloScript audio system.
 * Provides interfaces for audio sources, listeners, effects,
 * spatial audio, and music sequencing.
 *
 * @module audio
 */
/**
 * 3D vector for audio positioning — tuple form avoids coupling to @holoscript/core object-style Vector3.
 */
export type IVector3 = [number, number, number];
/**
 * Orientation for audio listener (forward and up vectors)
 */
export interface IAudioOrientation {
    forward: IVector3;
    up: IVector3;
}
/**
 * Audio source types
 */
export type AudioSourceType = 'buffer' | 'stream' | 'oscillator' | 'noise';
/**
 * Oscillator waveform types
 */
export type OscillatorType = 'sine' | 'square' | 'sawtooth' | 'triangle' | 'custom';
/**
 * Noise types for procedural audio
 */
export type NoiseType = 'white' | 'pink' | 'brown' | 'blue' | 'violet';
/**
 * Spatial audio model
 */
export type SpatialModel = 'HRTF' | 'panning' | 'equalpower';
/**
 * Distance rolloff types for spatial audio
 */
export type RolloffType = 'linear' | 'inverse' | 'exponential';
/**
 * Loop mode for sequencer
 */
export type LoopMode = 'none' | 'pattern' | 'sequence' | 'all';
/**
 * Sequencer state enum
 */
export type SequencerState = 'stopped' | 'playing' | 'paused' | 'recording';
/**
 * Playback state of an audio source
 */
export type PlaybackState = 'stopped' | 'playing' | 'paused' | 'scheduled';
/**
 * Audio source configuration
 */
export interface IAudioSourceConfig {
    id: string;
    type: AudioSourceType;
    url?: string;
    buffer?: ArrayBuffer;
    oscillatorType?: OscillatorType;
    frequency?: number;
    noiseType?: NoiseType;
    volume?: number;
    pitch?: number;
    loop?: boolean;
    loopStart?: number;
    loopEnd?: number;
    spatial?: boolean;
    position?: IVector3;
    maxDistance?: number;
    refDistance?: number;
    rolloffFactor?: number;
    coneInnerAngle?: number;
    coneOuterAngle?: number;
    coneOuterGain?: number;
    orientation?: IVector3;
    startTime?: number;
    duration?: number;
    fadeInTime?: number;
    fadeOutTime?: number;
    effects?: string[];
    group?: string;
}
/**
 * Audio source runtime state
 */
export interface IAudioSourceState {
    id: string;
    type: AudioSourceType;
    state: PlaybackState;
    volume: number;
    pitch: number;
    loop: boolean;
    position: IVector3;
    currentTime: number;
    duration: number;
    spatial: boolean;
}
/**
 * Audio listener configuration (usually follows camera)
 */
export interface IAudioListenerConfig {
    position: IVector3;
    orientation: IAudioOrientation;
    velocity?: IVector3;
}
/**
 * Effect types
 */
export type EffectType = 'gain' | 'filter' | 'reverb' | 'delay' | 'distortion' | 'compressor' | 'eq' | 'equalizer' | 'spatial' | 'chorus' | 'flanger' | 'phaser' | 'tremolo' | 'pan';
/**
 * Filter types for EQ and filter effects
 */
export type FilterType = 'lowpass' | 'highpass' | 'bandpass' | 'lowshelf' | 'highshelf' | 'peaking' | 'notch' | 'allpass';
/**
 * Base effect configuration
 */
export interface IEffectConfig {
    id: string;
    type: EffectType;
    bypass?: boolean;
    wet?: number;
}
/**
 * Gain effect
 */
export interface IGainEffect extends IEffectConfig {
    type: 'gain';
    gain: number;
}
/**
 * Filter effect
 */
export interface IFilterEffect extends IEffectConfig {
    type: 'filter';
    filterType: FilterType;
    frequency: number;
    Q?: number;
    gain?: number;
}
/**
 * Reverb effect
 */
export interface IReverbEffect extends IEffectConfig {
    type: 'reverb';
    roomSize?: number;
    decay?: number;
    damping?: number;
    preDelay?: number;
    impulseUrl?: string;
}
/**
 * Delay effect
 */
export interface IDelayEffect extends IEffectConfig {
    type: 'delay';
    delayTime: number;
    /** Alias for delayTime */
    time?: number;
    feedback?: number;
    maxDelay?: number;
}
/**
 * Distortion effect
 */
export interface IDistortionEffect extends IEffectConfig {
    type: 'distortion';
    amount: number;
    oversample?: 'none' | '2x' | '4x';
}
/**
 * Compressor effect
 */
export interface ICompressorEffect extends IEffectConfig {
    type: 'compressor';
    threshold: number;
    knee?: number;
    ratio: number;
    attack?: number;
    release?: number;
    makeupGain?: number;
}
/**
 * EQ band
 */
export interface IEQBand {
    frequency: number;
    gain: number;
    Q?: number;
    type?: FilterType;
}
/**
 * Equalizer effect
 */
export interface IEQEffect extends IEffectConfig {
    type: 'eq';
    bands: IEQBand[];
}
/**
 * Panner effect
 */
export interface IPanEffect extends IEffectConfig {
    type: 'pan';
    pan: number;
}
/**
 * Union type for all effects
 */
export type AudioEffect = IGainEffect | IFilterEffect | IReverbEffect | IDelayEffect | IDistortionEffect | ICompressorEffect | IEQEffect | IPanEffect | ISpatialEffect;
/**
 * Alias for EQ band (API compatibility)
 */
export type IEqualizerBand = IEQBand;
/**
 * Equalizer effect interface (extends EQ with 'equalizer' type)
 */
export interface IEqualizerEffect extends IEffectConfig {
    type: 'equalizer';
    bands: IEQBand[];
}
/**
 * Spatial audio effect
 */
export interface ISpatialEffect extends IEffectConfig {
    type: 'spatial';
    model: SpatialModel;
    refDistance: number;
    maxDistance: number;
    rolloff: RolloffType;
    coneInnerAngle?: number;
    coneOuterAngle?: number;
    coneOuterGain?: number;
}
/**
 * Audio bus interface
 */
export interface IAudioBus {
    id: string;
    name: string;
    volume: number;
    muted: boolean;
    solo: boolean;
    effects: string[];
    inputs: string[];
    output?: string;
}
/**
 * Sequencer configuration
 */
export interface ISequencerConfig {
    bpm: number;
    beatsPerBar: number;
    swingAmount?: number;
    lookAheadTime?: number;
    scheduleAheadTime?: number;
}
/**
 * Pattern reference in track
 */
export interface IPatternRef {
    patternId: string;
    startBeat: number;
    loop?: boolean;
    loopCount?: number;
}
/**
 * Audio group (bus) for managing multiple sources
 */
export interface IAudioGroup {
    id: string;
    name: string;
    volume: number;
    muted: boolean;
    solo: boolean;
    effects: string[];
    parent?: string;
}
/**
 * Musical note
 */
export interface INote {
    pitch: number | string;
    velocity: number;
    duration: number;
    startBeat: number;
    /** Alias for startBeat (for compatibility) */
    start?: number;
}
/**
 * Pattern of notes
 */
export interface IPattern {
    id: string;
    name?: string;
    notes: INote[];
    lengthBeats?: number;
    /** Alias for lengthBeats */
    length?: number;
    loop?: boolean;
    /** Number of bars in pattern */
    bars?: number;
    /** Beats per bar */
    beatsPerBar?: number;
    /** Subdivision (notes per beat) */
    subdivision?: number;
}
/**
 * Track in a sequence
 */
export interface ITrack {
    id: string;
    name?: string;
    instrument?: string;
    patterns: IPatternRef[];
    volume?: number;
    pan?: number;
    muted?: boolean;
    solo?: boolean;
    /** Source ID for this track */
    sourceId?: string;
    /** Effect chain IDs */
    effects?: string[];
    /** Output source ID */
    outputSource?: string;
}
/**
 * Music sequence configuration
 */
export interface ISequence {
    id: string;
    name?: string;
    bpm?: number;
    beatsPerBar?: number;
    bars?: number;
    tracks: ITrack[];
    patterns?: IPattern[];
    /** Order of patterns to play */
    patternOrder?: string[];
    /** Time signature [beats, noteValue] */
    timeSignature?: [number, number];
    /** Loop the sequence */
    loop?: boolean;
}
/**
 * Sequencer state
 */
export interface ISequencerState {
    isPlaying: boolean;
    isPaused: boolean;
    currentBeat: number;
    currentBar: number;
    bpm: number;
    looping: boolean;
    loopStart: number;
    loopEnd: number;
}
/**
 * Audio event types
 */
export type AudioEventType = 'sourceStarted' | 'sourceStopped' | 'sourceEnded' | 'sourcePaused' | 'sourceResumed' | 'sourceLooped' | 'bufferLoaded' | 'bufferError' | 'beatTick' | 'barTick' | 'beat' | 'bar' | 'sequenceEnd' | 'sequencerStarted' | 'sequencerStopped' | 'sequencerPaused' | 'sequencerSeeked' | 'sequenceLooped' | 'noteTriggered' | 'noteReleased' | 'metronomeClick' | 'bpmChanged';
/**
 * Audio event
 */
export interface IAudioEvent {
    type: AudioEventType;
    sourceId?: string;
    timestamp: number;
    data?: Record<string, unknown>;
}
/**
 * Audio event callback
 */
export type AudioEventCallback = (event: IAudioEvent) => void;
/**
 * Audio system configuration
 */
export interface IAudioSystemConfig {
    sampleRate?: number;
    maxSources?: number;
    masterVolume?: number;
    spatialEnabled?: boolean;
    defaultRolloff?: 'linear' | 'inverse' | 'exponential';
    defaultRefDistance?: number;
    defaultMaxDistance?: number;
    doppler?: boolean;
    dopplerFactor?: number;
    speedOfSound?: number;
}
/**
 * Audio system defaults
 */
export declare const AUDIO_DEFAULTS: Required<IAudioSystemConfig>;
/**
 * Main audio context interface
 */
export interface IAudioContext {
    initialize(): Promise<void>;
    suspend(): Promise<void>;
    resume(): Promise<void>;
    dispose(): void;
    readonly state: 'suspended' | 'running' | 'closed';
    readonly currentTime: number;
    readonly sampleRate: number;
    setMasterVolume(volume: number): void;
    getMasterVolume(): number;
    mute(): void;
    unmute(): void;
    readonly isMuted: boolean;
    setListenerPosition(position: IVector3): void;
    setListenerOrientation(orientation: IAudioOrientation): void;
    setListenerVelocity(velocity: IVector3): void;
    getListenerConfig(): IAudioListenerConfig;
    createSource(config: IAudioSourceConfig): Promise<string>;
    getSource(id: string): IAudioSourceState | undefined;
    getAllSources(): IAudioSourceState[];
    removeSource(id: string): boolean;
    play(sourceId: string, when?: number): void;
    stop(sourceId: string): void;
    pause(sourceId: string): void;
    resumeSource(sourceId: string): void;
    setVolume(sourceId: string, volume: number): void;
    setPitch(sourceId: string, pitch: number): void;
    setLoop(sourceId: string, loop: boolean, start?: number, end?: number): void;
    setPosition(sourceId: string, position: IVector3): void;
    setOrientation(sourceId: string, orientation: IVector3): void;
    createEffect(config: AudioEffect): string;
    getEffect(id: string): AudioEffect | undefined;
    removeEffect(id: string): boolean;
    connectSourceToEffect(sourceId: string, effectId: string): void;
    disconnectSourceFromEffect(sourceId: string, effectId: string): void;
    createGroup(config: IAudioGroup): string;
    getGroup(id: string): IAudioGroup | undefined;
    setGroupVolume(groupId: string, volume: number): void;
    setGroupMuted(groupId: string, muted: boolean): void;
    setGroupSolo(groupId: string, solo: boolean): void;
    loadBuffer(url: string): Promise<ArrayBuffer>;
    decodeBuffer(buffer: ArrayBuffer): Promise<AudioBuffer>;
    getCachedBuffer(url: string): ArrayBuffer | undefined;
    clearBufferCache(): void;
    on(event: AudioEventType, callback: AudioEventCallback): void;
    off(event: AudioEventType, callback: AudioEventCallback): void;
    emit(event: IAudioEvent): void;
    getAnalyzerData(sourceId: string): Float32Array | undefined;
    getFrequencyData(sourceId: string): Uint8Array | undefined;
}
/**
 * Music sequencer interface
 */
export interface ISequencer {
    load(sequence: ISequence): void;
    unload(): void;
    play(): void;
    pause(): void;
    stop(): void;
    seek(beat: number): void;
    getState(): ISequencerState;
    readonly isPlaying: boolean;
    readonly currentBeat: number;
    setBPM(bpm: number): void;
    getBPM(): number;
    setLoop(enabled: boolean, startBeat?: number, endBeat?: number): void;
    setTrackVolume(trackId: string, volume: number): void;
    setTrackMuted(trackId: string, muted: boolean): void;
    setTrackSolo(trackId: string, solo: boolean): void;
    on(event: 'beatTick' | 'barTick' | 'sequenceEnd', callback: AudioEventCallback): void;
    off(event: 'beatTick' | 'barTick' | 'sequenceEnd', callback: AudioEventCallback): void;
    addPattern(pattern: IPattern): void;
    removePattern(patternId: string): boolean;
    getPattern(patternId: string): IPattern | undefined;
    scheduleNote(trackId: string, note: INote): void;
    quantize(beat: number, grid: number): number;
}
/**
 * Create a zero vector
 */
export declare function zeroVector(): IVector3;
/**
 * Create default listener orientation
 */
export declare function defaultOrientation(): IAudioOrientation;
/**
 * Create a buffer source config
 */
export declare function bufferSource(id: string, url: string, options?: Partial<IAudioSourceConfig>): IAudioSourceConfig;
/**
 * Create an oscillator source config
 */
export declare function oscillatorSource(id: string, waveform: OscillatorType, frequency: number, options?: Partial<IAudioSourceConfig>): IAudioSourceConfig;
/**
 * Create a stream source config
 */
export declare function streamSource(id: string, url: string, options?: Partial<IAudioSourceConfig>): IAudioSourceConfig;
/**
 * Create a noise source config
 */
export declare function noiseSource(id: string, noiseType: NoiseType, options?: Partial<IAudioSourceConfig>): IAudioSourceConfig;
/**
 * Add spatial properties to an existing source config (decorator pattern)
 */
export declare function spatialSource(config: IAudioSourceConfig, position: IVector3, options?: Partial<IAudioSourceConfig>): IAudioSourceConfig;
/**
 * Create a gain effect config
 */
export declare function gainEffect(id: string, gain?: number): IGainEffect;
/**
 * Create a reverb effect config
 */
export declare function reverbEffect(id: string, decay?: number, wet?: number, options?: Partial<IReverbEffect>): IReverbEffect;
/**
 * Create a delay effect config
 */
export declare function delayEffect(id: string, time?: number, feedback?: number, options?: Partial<IDelayEffect>): IDelayEffect;
/**
 * Create a filter effect config
 */
export declare function filterEffect(id: string, filterType: FilterType, frequency: number, options?: Partial<IFilterEffect>): IFilterEffect;
/**
 * Create a compressor effect config
 */
export declare function compressorEffect(id: string, threshold?: number, ratio?: number, options?: Partial<ICompressorEffect>): ICompressorEffect;
/**
 * Convert MIDI note number to frequency
 */
export declare function midiToFrequency(note: number): number;
/**
 * Convert frequency to MIDI note number (rounded to nearest integer)
 */
export declare function frequencyToMidi(frequency: number): number;
/**
 * Convert note name to MIDI number
 * e.g., 'C4' -> 60, 'A4' -> 69
 */
export declare function noteNameToMidi(name: string): number;
/**
 * Convert MIDI number to note name
 */
export declare function midiToNoteName(midi: number): string;
/**
 * Validate audio source config
 */
export declare function validateSourceConfig(config: IAudioSourceConfig): {
    valid: boolean;
    errors: string[];
};
/**
 * Create a lowpass filter effect
 */
export declare function lowpassFilter(id: string, frequency: number, Q?: number): IFilterEffect;
/**
 * Create a highpass filter effect
 */
export declare function highpassFilter(id: string, frequency: number, Q?: number): IFilterEffect;
/**
 * Create a bandpass filter effect
 */
export declare function bandpassFilter(id: string, frequency: number, Q?: number): IFilterEffect;
/**
 * Create a distortion effect config
 */
export declare function distortionEffect(id: string, amount?: number, options?: Partial<IDistortionEffect>): IDistortionEffect;
/**
 * Create a pan effect config
 */
export declare function panEffect(id: string, pan?: number): IPanEffect;
/**
 * Create an EQ band config
 */
export declare function eqBand(frequency: number, Q?: number, gain?: number): IEQBand;
/**
 * Create an equalizer effect config
 */
export declare function equalizerEffect(id: string, bands: IEQBand[], options?: Partial<IEqualizerEffect>): IEqualizerEffect;
/**
 * Create a note config for sequencer
 */
export declare function createNote(pitch: number | string, start: number, duration: number, velocity?: number): INote;
/**
 * Create a pattern config for sequencer
 */
export declare function createPattern(id: string, notes: INote[], options?: Partial<IPattern>): IPattern;
/**
 * Create a track config for sequencer
 */
export declare function createTrack(id: string, patterns: IPatternRef[], options?: Partial<ITrack>): ITrack;
/**
 * Create a sequence config for sequencer
 */
export declare function createSequence(id: string, patternOrder: string[], tracks: ITrack[], options?: Partial<ISequence>): ISequence;
//# sourceMappingURL=AudioTypes.d.ts.map