@clxrity/react-audio/dist/index.d.ts

An interactive audio package for React

import * as react from 'react';
import { JSX, ComponentProps, RefObject } from 'react';
import * as react_jsx_runtime from 'react/jsx-runtime';

interface CustomProps {
    [key: string]: {
        value: unknown;
        description?: string;
        required: boolean;
        default?: unknown;
    };
}
interface Component<T extends keyof JSX.IntrinsicElements> {
    title: string;
    url: string;
    description: string;
    props: CustomProps & Partial<ComponentProps<T>>;
}
interface BaseProps {
    src: string;
    autoplay?: boolean;
    loop?: boolean;
    color?: string;
    showProgress?: boolean;
    showVolume?: boolean;
}
type FFTSize = 32 | 64 | 128 | 256 | 512 | 1024 | 2048 | 4096 | 8192 | 16384 | 32768;

interface PlayerProps extends ComponentProps<"audio"> {
    onNext?: () => void;
    onPrev?: () => void;
    src: BaseProps["src"];
    autoplay?: BaseProps["autoplay"];
    loop?: BaseProps["loop"];
    showProgress?: BaseProps["showProgress"];
    showVolume?: BaseProps["showVolume"];
    color?: BaseProps["color"];
    showNextPrevControls?: boolean;
    size?: number;
}
/**
 * Audio player component for playing audio files.
 * - Supports playback controls (play, pause, next, previous)
 * - Displays current playback time and duration
 * - Allows volume control
 */
declare const Player: react.ForwardRefExoticComponent<Omit<PlayerProps, "ref"> & react.RefAttributes<HTMLAudioElement>>;

interface AudioRecorderProps {
    className?: string;
    waveColor?: string;
    width?: number;
    height?: number;
    /** Called with the Blob whenever a fresh recording is finalized */
    onRecordingComplete?: (blob: Blob) => void;
}
/**
 * AudioRecorder component
 * - Start / stop microphone recording
 * - Preview playback of the recorded clip
 * - Simple realtime waveform while recording (time domain)
 * - Download button to save the recorded audio (webm)
 */
declare function AudioRecorder({ className, waveColor, width, height, onRecordingComplete, }: AudioRecorderProps): react_jsx_runtime.JSX.Element;

interface AudioLooperProps {
    className?: string;
    maxTracks?: number;
    defaultLoopDuration?: number;
    color?: string;
}
/**
 * AudioLooper component
 * - Multi-track loop recording and playback
 * - Configurable loop duration
 * - Individual track controls (record, play, volume, clear)
 * - Master controls for all tracks
 * - Visual progress indicators
 */
declare function AudioLooper({ className, maxTracks, defaultLoopDuration, color, }: AudioLooperProps): react_jsx_runtime.JSX.Element;

interface ShufflePlayerProps extends ComponentProps<"audio"> {
    srcs: string[];
    autoplay?: BaseProps["autoplay"];
    color?: BaseProps["color"];
    showNextPrevControls?: boolean;
    showProgress?: BaseProps["showProgress"];
    showVolume?: BaseProps["showVolume"];
    shuffle?: boolean;
    onNext?: () => void;
    onPrev?: () => void;
}
/**
 * ShufflePlayer component for playing audio files in a shuffled order.
 * - Supports playback controls (play, pause, next, previous)
 * - Displays current playback time and duration
 * - Allows volume control
 */
declare function ShufflePlayer({ srcs, autoplay, color, showNextPrevControls, showProgress, showVolume, shuffle, onNext, onPrev, ...props }: ShufflePlayerProps): react_jsx_runtime.JSX.Element;

interface WaveformProps extends ComponentProps<"div"> {
    src: BaseProps["src"];
    size?: number;
    color?: BaseProps["color"];
    autoplay?: BaseProps["autoplay"];
    loop?: BaseProps["loop"];
    showProgress?: BaseProps["showProgress"];
    showVolume?: BaseProps["showVolume"];
    fftSize?: FFTSize;
    onLoad?: () => void;
}
/**
 * Waveform component renders an audio player and a real-time waveform visualization.
 * - Supports playback controls (play, pause, next, previous)
 * - Displays current playback time and duration
 * - Allows volume control
 */
declare function Waveform({ src, size, color, autoplay, loop, showProgress, showVolume, fftSize, onLoad, ...props }: WaveformProps): react_jsx_runtime.JSX.Element;

interface OscillatorProps extends ComponentProps<"div"> {
    type?: OscillatorType;
    frequency?: number;
    gain?: number;
    isPlaying?: boolean;
    onPlayChange?: (playing: boolean) => void;
    showControls?: boolean;
    onFrequencyChange?: (frequency: number) => void;
    onGainChange?: (gain: number) => void;
}
/**
 * Oscillator component for generating audio signals.
 * - Supports various waveforms (sine, square, etc.)
 * - Allows control over frequency and gain
 * - Provides play/pause functionality
 */
declare function Oscillator({ type, frequency, gain, isPlaying, onPlayChange, showControls, onFrequencyChange, onGainChange, ...props }: OscillatorProps): react_jsx_runtime.JSX.Element;

interface SpectroGramDisplayProps extends ComponentProps<"canvas"> {
    audioRef: RefObject<HTMLAudioElement>;
    fftSize?: FFTSize;
    width?: number | string;
    height?: number | string;
    minDecibels?: number;
    maxDecibels?: number;
    smoothingTimeConstant?: number;
    colorMap?: string[];
    onFrameUpdate?: (data: Uint8Array) => void;
    fillStyle?: string;
    loop?: boolean;
}
/**
 * Spectrogram display component for visualizing audio frequency data.
 * - Supports real-time audio visualization
 * - Displays frequency data as a color map
 * - Allows customization of appearance and behavior
 */
declare function SpectroGramDisplay({ audioRef, fftSize, width, height, minDecibels, maxDecibels, colorMap, onFrameUpdate, fillStyle, loop, smoothingTimeConstant, ...props }: SpectroGramDisplayProps): react_jsx_runtime.JSX.Element;
interface SpectrogramProps extends ComponentProps<"div"> {
    src: BaseProps["src"];
    fftSize?: FFTSize;
    width?: number | string;
    height?: number | string;
    minDecibels?: number;
    maxDecibels?: number;
    colorMap?: string[];
    smoothingTimeConstant?: number;
    onFrameUpdate?: (data: Uint8Array) => void;
    loop?: BaseProps["loop"];
    fillStyle?: string;
}
declare function Spectrogram({ src, fftSize, width, height, minDecibels, maxDecibels, colorMap, smoothingTimeConstant, onFrameUpdate, loop, fillStyle, ...props }: SpectrogramProps): react_jsx_runtime.JSX.Element;

declare const components: {
    readonly Player: Component<"audio">;
    readonly ShufflePlayer: Component<"audio">;
    readonly Waveform: Component<"canvas">;
    readonly Oscillator: Component<"div">;
    readonly Spectrogram: Component<"div">;
    readonly AudioRecorder: Component<"div">;
    readonly AudioLooper: {
        name: string;
        category: string;
        description: string;
        features: string[];
        props: {
            className: {
                type: string;
                description: string;
                required: boolean;
                default: undefined;
            };
            maxTracks: {
                type: string;
                description: string;
                required: boolean;
                default: number;
            };
            defaultLoopDuration: {
                type: string;
                description: string;
                required: boolean;
                default: number;
            };
            color: {
                type: string;
                description: string;
                required: boolean;
                default: string;
            };
        };
        usage: string;
        examples: {
            title: string;
            code: string;
        }[];
    };
};

/**
 * Hook to create and manage an AnalyserNode for a given audio element and context.
 * Ensures nodes are not created or connected after the context is closed.
 */
declare function useAudioAnalyser(audioElement: HTMLAudioElement | null, audioContext: AudioContext | null, sourceNodeRef: RefObject<MediaElementAudioSourceNode | null>, fftSize: FFTSize): {
    analyser: AnalyserNode;
    getFrequencyData: () => Uint8Array<ArrayBuffer>;
} | null;

interface LoopTrack {
    id: string;
    audioUrl: string | null;
    isPlaying: boolean;
    isRecording: boolean;
    volume: number;
    duration: number;
}
interface UseAudioLooperReturn {
    tracks: LoopTrack[];
    isRecording: boolean;
    masterVolume: number;
    loopDuration: number;
    currentTime: number;
    addTrack: () => string;
    removeTrack: (trackId: string) => void;
    startRecording: (trackId: string) => void;
    stopRecording: (trackId: string) => void;
    togglePlayback: (trackId: string) => void;
    clearTrack: (trackId: string) => void;
    setTrackVolume: (trackId: string, volume: number) => void;
    setMasterVolume: (volume: number) => void;
    setLoopDuration: (duration: number) => void;
    startAllTracks: () => void;
    stopAllTracks: () => void;
    clearAllTracks: () => void;
}
declare function useAudioLooper(): UseAudioLooperReturn;

declare function useAudioRecorder(): {
    recording: boolean;
    audioUrl: string | null;
    startRecording: () => Promise<void>;
    stopRecording: () => void;
    getWaveformData: () => number[];
};

export { AudioLooper, type AudioLooperProps, AudioRecorder, type AudioRecorderProps, type BaseProps, type FFTSize, Oscillator, type OscillatorProps, Player, type PlayerProps, ShufflePlayer, type ShufflePlayerProps, SpectroGramDisplay, type SpectroGramDisplayProps, Spectrogram, type SpectrogramProps, Waveform, type WaveformProps, components, useAudioAnalyser, useAudioLooper, useAudioRecorder };