audio-hooks/dist/react/index.d.ts

A React hooks library for managing audio playback with advanced controls and features.

export { AudioProvider } from 'web-audio-hooks/react';

/**
 * Represents the playback mode for audio tracks
 * @typedef {('Shuffle' | 'SingleOnce' | 'SingleLoop' | 'SequentialOnce' | 'SequentialLoop')} PlayMode
 * - 'Shuffle' - Shuffle playback mode
 * - 'SingleLoop' - Repeat One playback mode
 * - 'SingleOnce' - Play current track once then stop
 * - 'SequentialOnce' - Play all tracks once then stop
 * - 'SequentialLoop' - Repeat All playback mode
 */
declare const MODE: Record<PlayMode, PlayMode>;
declare const MODES: readonly ["Shuffle", "SingleOnce", "SingleLoop", "SequentialOnce", "SequentialLoop"];
type PlayMode = (typeof MODES)[number];
/**
 * AudioControls interface for audio playback functionality
 */
interface AudioControls {
    /** Start playing the current audio track */
    play: () => void;
    /** Pause the current audio track */
    pause: () => void;
    /** Toggle play between play and pause */
    togglePlay: () => void;
    /** Skip to next track based on current play mode */
    next: () => void;
    /** Go to previous track based on current play mode */
    prev: () => void;
    /**
     * Seek to specific time in current track
     * @param time - Target time in seconds
     */
    seek: (time: number) => void;
    /**
     * Fast forward by specified milliseconds
     * @param ms - Number of milliseconds to fast forward (default: 5000)
     */
    fastForward: (ms?: number) => void;
    /**
     * Rewind by specified milliseconds
     * @param ms - Number of milliseconds to rewind (default: 5000)
     */
    rewind: (ms?: number) => void;
    /**
     * Set audio volume
     * @param volume - Volume level between 0 and 1
     */
    setVolume: (volume: number) => void;
    /**
     * Change playback mode
     * @param mode - Optional specific play mode to set, cycles through modes if not provided
     */
    nextPlayMode: (mode?: PlayMode) => void;
    /**
     * Play specific track by index
     * @param index - Index of track in playlist
     */
    playTrack: (index: number) => void;
    /**
     * Set playback speed
     * @param rate - Playback rate between 0.5 and 3.0
     */
    setPlaybackRate: (rate: number) => void;
    /**
     * Set the list of audio URLs
     * @param urls - Array of URLs for audio tracks
     */
    setAudioList: (urls: string[]) => void;
    /**
     * Switch to a specific track in the playlist without playing it
     * @param index - Index of track to switch to
     */
    switchAudio: (index: number) => void;
}
/**
 * State interface for audio playback functionality
 */
interface AudioState {
    audios: string[];
    /** Whether audio is currently playing */
    playing: boolean;
    /** Index of currently playing track in playlist */
    playingIndex: number;
    /** Current playback position in seconds */
    currentTime: number;
    /** Total duration of current track in seconds */
    duration: number;
    /** Current volume level between 0 and 1 */
    volume: number;
    /** Current playback speed between 0.5 and 3.0 */
    playbackRate: number;
    /** Current playback mode (sequential/shuffle/loop) */
    playMode: PlayMode;
}
interface AudioEvents {
    onEnded?: () => void;
}
type AudioOptions = AudioEvents;
/**
 * Return type for useAudioList hook
 * @property state - Current state of audio playback including playing status, time, volume etc
 * @property controls - Methods to control audio playback like play, pause, seek etc
 * @property setAudioList - Function to update the list of audio URLs
 */
type UseAudioListReturn = {
    state: AudioState;
    controls: AudioControls;
};
/**
 * React hook for managing a list of audio tracks with playback controls
 * @param urls - Array of URLs for audio tracks to be played
 * @returns Object containing playback state, controls, and URL setter
 * @example
 * ```tsx
 * const { state, controls, setAudioList } = useAudioList([
 *   'audio1.mp3',
 *   'audio2.mp3'
 * ])
 * ```
 */
declare const useAudioList: (urls: string[], { onEnded, }?: AudioOptions) => UseAudioListReturn;

export { type AudioControls, type AudioOptions, type AudioState, MODE, type UseAudioListReturn, useAudioList };