import type { SoundOptions } from "./core.ts";
import { type AudioEngine, type Sound, type Voice } from "./core.ts";
/**
 * Extended SoundOptions with spatial audio properties.
 * Use this interface when creating a Sound instance with spatial audio capabilities.
 * @example
 * ```typescript
 * const sound = new Sound({
 *   src: ['sound.mp3'],
 *   pos: [10, 20, 30],
 *   stereo: 0.5,
 *   distanceModel: 'inverse'
 * } as SpatialSoundOptions);
 * ```
 */
/** Panner attributes a spatial sound can be configured with. */
export interface PannerAttrOptions {
    /** Inner angle of the sound cone in degrees. */
    coneInnerAngle: number;
    /** Outer angle of the sound cone in degrees. */
    coneOuterAngle: number;
    /** Gain value outside the outer cone (0.0 to 1.0). */
    coneOuterGain: number;
    /** Distance model algorithm. */
    distanceModel: "linear" | "inverse" | "exponential";
    /** Maximum distance for the distance model. */
    maxDistance: number;
    /** Panning model algorithm. */
    panningModel: "equalpower" | "HRTF";
    /** Reference distance for the distance model. */
    refDistance: number;
    /** Rolloff factor for the distance model. */
    rolloffFactor: number;
}
export interface SpatialSoundOptions extends SoundOptions {
    /** 3D position of the sound source [x, y, z]. */
    pos?: [number, number, number];
    /** Orientation vector of the sound source [x, y, z]. */
    orientation?: [number, number, number];
    /** Stereo panning value from -1.0 (left) to 1.0 (right). */
    stereo?: number;
    /** Inner angle of the sound cone in degrees. Default: `360` */
    coneInnerAngle?: number;
    /** Outer angle of the sound cone in degrees. Default: `360` */
    coneOuterAngle?: number;
    /** Gain value outside the outer cone. Range: 0.0 to 1.0. Default: `0` */
    coneOuterGain?: number;
    /** Distance model algorithm: 'linear', 'inverse', or 'exponential'. Default: `'inverse'` */
    distanceModel?: "linear" | "inverse" | "exponential";
    /** Maximum distance for the distance model. Default: `10000` */
    maxDistance?: number;
    /** Panning model: 'equalpower' or 'HRTF'. Default: `'HRTF'` */
    panningModel?: "equalpower" | "HRTF";
    /** Reference distance for the distance model. Default: `1` */
    refDistance?: number;
    /** Rolloff factor for the distance model. Default: `1` */
    rolloffFactor?: number;
    /** Fires when the stereo panning changes. */
    onstereo?: () => void;
    /** Fires when the 3D position changes. */
    onpos?: () => void;
    /** Fires when the orientation changes. */
    onorientation?: () => void;
}
/**
 * audioEngine instance with spatial audio capabilities.
 * Use this type when the spatial plugin is registered to get full type safety for spatial audio methods.
 * @example
 * ```typescript
 * import { audioEngine } from 'engine';
 * import { SpatialAudioPlugin, type SpatialAudioEngine } from 'engine/plugins/spatial';
 *
 * audioEngine.addPlugin(new SpatialAudioPlugin());
 *
 * const engine: SpatialAudioEngine = audioEngine as SpatialAudioEngine;
 * engine.pos(10, 20, 30); // Set listener position
 * engine.orientation(0, 0, -1, 0, 1, 0); // Set listener orientation
 * engine.stereo(0.5); // Set stereo panning
 * ```
 */
export type SpatialAudioEngine = AudioEngine & SpatialAudioState & {
    /**
     * Set or get the listener's 3D position.
     * @param x - X coordinate (optional)
     * @param y - Y coordinate (optional)
     * @param z - Z coordinate (optional)
     * @returns If called with no arguments, returns the current position [x, y, z]. Otherwise, returns the audioEngine instance for chaining.
     */
    pos(x?: number, y?: number, z?: number): SpatialAudioEngine | [number, number, number];
    /**
     * Set or get the listener's orientation.
     * @param x - Forward X component (optional)
     * @param y - Forward Y component (optional)
     * @param z - Forward Z component (optional)
     * @param xUp - Up X component (optional)
     * @param yUp - Up Y component (optional)
     * @param zUp - Up Z component (optional)
     * @returns If called with no arguments, returns the current orientation [forwardX, forwardY, forwardZ, upX, upY, upZ]. Otherwise, returns the audioEngine instance for chaining.
     */
    orientation(x?: number, y?: number, z?: number, xUp?: number, yUp?: number, zUp?: number): SpatialAudioEngine | [number, number, number, number, number, number];
    /**
     * Set or get the stereo panning value.
     * @param pan - Panning value from -1.0 (left) to 1.0 (right) (optional)
     * @returns If called with no arguments, returns the current panning value. Otherwise, returns the audioEngine instance for chaining.
     */
    stereo(pan?: number): SpatialAudioEngine;
};
/**
 * Sound instance with spatial audio capabilities.
 * Use this type when the spatial plugin is registered to get full type safety for spatial audio methods.
 * @example
 * ```typescript
 * import { Sound } from 'engine';
 * import { SpatialAudioPlugin, type SpatialSound, type SpatialSoundOptions } from 'engine/plugins/spatial';
 *
 * audioEngine.addPlugin(new SpatialAudioPlugin());
 *
 * const sound: SpatialSound = new Sound({
 *   src: ['sound.mp3'],
 *   pos: [10, 20, 30]
 * } as SpatialSoundOptions) as SpatialSound;
 *
 * sound.pos(5, 10, 15); // Set sound position
 * sound.stereo(0.5); // Set stereo panning
 * sound.orientation(0, 1, 0); // Set sound orientation
 * ```
 */
export type SpatialSound = Sound & SpatialSoundState & {
    /**
     * Set or get the sound's 3D position.
     * @param x - X coordinate (optional)
     * @param y - Y coordinate (optional)
     * @param z - Z coordinate (optional)
     * @param id - Voice ID to target a specific sound instance (optional)
     * @returns If called with no arguments, returns the current position [x, y, z]. Otherwise, returns the Sound instance for chaining.
     */
    pos(x?: number, y?: number, z?: number, id?: number): SpatialSound | [number, number, number] | null;
    /**
     * Set or get the sound's orientation vector.
     * @param x - X component (optional)
     * @param y - Y component (optional)
     * @param z - Z component (optional)
     * @param id - Voice ID to target a specific sound instance (optional)
     * @returns If called with no arguments, returns the current orientation [x, y, z]. Otherwise, returns the Sound instance for chaining.
     */
    orientation(x?: number, y?: number, z?: number, id?: number): SpatialSound | [number, number, number] | null;
    /**
     * Set or get the stereo panning value.
     * @param pan - Panning value from -1.0 (left) to 1.0 (right) (optional)
     * @param id - Voice ID to target a specific sound instance (optional)
     * @returns If called with no arguments, returns the current panning value. Otherwise, returns the Sound instance for chaining.
     */
    stereo(pan?: number, id?: number): SpatialSound | number | null;
    /**
     * Set or get panner node attributes.
     * @param o - Panner attributes object (optional)
     * @param id - Voice ID to target a specific sound instance (optional)
     * @returns If called with no arguments, returns the current panner attributes. Otherwise, returns the Sound instance for chaining.
     */
    pannerAttr(o?: PannerAttrOptions | number, id?: number): SpatialSound | PannerAttrOptions;
};
/**
 * Spatial Audio Plugin
 * Adds 3D spatial audio and stereo panning capabilities to audioEngine and Sound instances
 */
/**
 * Initialize spatial audio when audioEngine is initialized
 * This is called either:
 * - When audioEngine initializes (if plugin was registered before)
 * - Immediately during registration (if audioEngine is already initialized)
 * @param engine - the audio engine singleton
 */
export declare function installSpatialOnEngine(engine: AudioEngine): void;
/**
 * Extend Sound instances with spatial audio methods
 * @param sound - the sound the hook fires for
 * @param options - the options the sound was constructed with
 */
export declare function installSpatialOnSound(sound: Sound, options: SoundOptions): void;
/**
 * Extend Voice instances with spatial audio properties
 * @param voice - the individual playing instance
 * @param parent - the sound the voice belongs to
 */
export declare function installSpatialOnVoice(voice: Voice, parent: Sound): void;
/**
 * Handle load queue for spatial audio
 * @param sound - the sound the hook fires for
 */
export declare function applySpatialAfterLoad(sound: Sound): void;
//# sourceMappingURL=spatial.d.ts.map