Component Props & Events

import AudioPlayer from 'react-h5-audio-player';
import { ReactNode, CSSProperties } from 'react';

interface CoreAudioProps {
  /** HTML5 Audio tag src property */
  src?: string;
  /** HTML5 Audio tag autoPlay property */
  autoPlay?: boolean;
  /** HTML5 Audio tag loop property */
  loop?: boolean;
  /** HTML5 Audio tag muted property */  
  muted?: boolean;
  /** Volume level from 0 to 1 (won't work on most mobile devices) */
  volume?: number;
  /** HTML5 Audio tag preload property */
  preload?: AUDIO_PRELOAD_ATTRIBUTE;
  /** CORS attribute for cross-origin requests */
  crossOrigin?: React.AudioHTMLAttributes<HTMLAudioElement>['crossOrigin'];
  /** Media group for synchronized playback */
  mediaGroup?: string;
}

interface BehaviorProps {
  /** Whether to play audio after src prop is changed */
  autoPlayAfterSrcChange?: boolean;
  /** Enable/disable default keyboard shortcuts */
  hasDefaultKeyBindings?: boolean;
  /** Time interval in milliseconds to trigger onListen event */
  listenInterval?: number;
  /** Progress indicator refresh interval in milliseconds */
  progressUpdateInterval?: number;
  /** Default jump step for rewind/forward in milliseconds */
  progressJumpStep?: number;
  /** Separate backward/forward jump steps in milliseconds */
  progressJumpSteps?: {
    backward?: number;
    forward?: number;
  };
  /** Volume increment for up/down arrow keys */
  volumeJumpStep?: number;
}

interface UIDisplayProps {
  /** Custom CSS classes */
  className?: string;
  /** Inline CSS styles */
  style?: CSSProperties;
  /** Layout orientation */
  layout?: MAIN_LAYOUT;
  /** Show rewind/forward buttons */
  showJumpControls?: boolean;
  /** Show previous/next buttons */
  showSkipControls?: boolean;
  /** Show download progress indicator */
  showDownloadProgress?: boolean;
  /** Show filled progress indicator */
  showFilledProgress?: boolean;
  /** Show filled volume indicator */
  showFilledVolume?: boolean;
  /** Time display format */
  timeFormat?: TIME_FORMAT;
}

interface CustomContentProps {
  /** Custom header content above the player */
  header?: ReactNode;
  /** Custom footer content below the player */
  footer?: ReactNode;
  /** Default current time display when audio not loaded */
  defaultCurrentTime?: ReactNode;
  /** Default duration display when audio not loaded */
  defaultDuration?: ReactNode;
  /** Child elements (e.g., <track> elements for captions) */
  children?: ReactNode;
}

interface HTML5AudioEvents {
  /** Fired when playback is aborted */
  onAbort?: (e: Event) => void;
  /** Fired when enough data is available to start playing */
  onCanPlay?: (e: Event) => void;
  /** Fired when enough data is available to play through without buffering */
  onCanPlayThrough?: (e: Event) => void;
  /** Fired when playback reaches the end */
  onEnded?: (e: Event) => void;
  /** Fired when playback starts after being paused or delayed */
  onPlaying?: (e: Event) => void;
  /** Fired when a seek operation begins */
  onSeeking?: (e: Event) => void;
  /** Fired when a seek operation completes */
  onSeeked?: (e: Event) => void;
  /** Fired when data loading is stalled */
  onStalled?: (e: Event) => void;
  /** Fired when data loading is suspended */
  onSuspend?: (e: Event) => void;
  /** Fired when loading begins */
  onLoadStart?: (e: Event) => void;
  /** Fired when metadata has finished loading */
  onLoadedMetaData?: (e: Event) => void;
  /** Fired when the first frame has finished loading */
  onLoadedData?: (e: Event) => void;
  /** Fired when playback is waiting for more data */
  onWaiting?: (e: Event) => void;
  /** Fired when the media element is reset to its initial state */
  onEmptied?: (e: Event) => void;
  /** Fired when an error occurs during loading or playback */
  onError?: (e: Event) => void;
  /** Fired during playback at intervals specified by listenInterval */
  onListen?: (e: Event) => void;
  /** Fired when volume changes */
  onVolumeChange?: (e: Event) => void;
  /** Fired when playback is paused */
  onPause?: (e: Event) => void;
  /** Fired when playback starts */
  onPlay?: (e: Event) => void;
}

interface CustomControlEvents {
  /** Called when previous button is clicked */
  onClickPrevious?: (e: React.SyntheticEvent) => void;
  /** Called when next button is clicked */
  onClickNext?: (e: React.SyntheticEvent) => void;
  /** Called when play() promise is rejected */
  onPlayError?: (err: Error) => void;
  /** Called when currentTime change fails */
  onChangeCurrentTimeError?: (err: Error) => void;
}

interface PlayerProps extends 
  CoreAudioProps,
  BehaviorProps, 
  UIDisplayProps,
  CustomContentProps,
  HTML5AudioEvents,
  CustomControlEvents {
  
  // UI Customization (see UI Customization & Layout doc)
  customIcons?: CustomIcons;
  customProgressBarSection?: CustomUIModules;
  customControlsSection?: CustomUIModules;
  customAdditionalControls?: CustomUIModules;
  customVolumeControls?: CustomUIModules;
  i18nAriaLabels?: I18nAriaLabels;
  
  // Advanced Features (see Advanced Features & MSE doc)
  mse?: MSEPropsObject;
}

<AudioPlayer
  src="audio.mp3"
  autoPlay={false}
  loop={false}
  volume={0.8}
  onPlay={e => console.log('Started playing')}
  onPause={e => console.log('Paused')}
  onEnded={e => console.log('Finished playing')}
/>

<AudioPlayer
  src="podcast.mp3"
  listenInterval={500}
  onListen={e => {
    const audio = e.target as HTMLAudioElement;
    console.log('Current time:', audio.currentTime);
    // Update progress, save position, etc.
  }}
  onLoadedMetaData={e => {
    const audio = e.target as HTMLAudioElement;
    console.log('Duration:', audio.duration);
  }}
  onError={e => {
    console.error('Audio error:', e);
    // Handle error, show message, etc.
  }}
/>

const [currentTrack, setCurrentTrack] = useState(0);
const playlist = ['song1.mp3', 'song2.mp3', 'song3.mp3'];

<AudioPlayer
  src={playlist[currentTrack]}
  showSkipControls={true}
  onClickPrevious={() => {
    setCurrentTrack(prev => Math.max(0, prev - 1));
  }}
  onClickNext={() => {
    setCurrentTrack(prev => Math.min(playlist.length - 1, prev + 1));
  }}
  onEnded={() => {
    // Auto-advance to next track
    if (currentTrack < playlist.length - 1) {
      setCurrentTrack(prev => prev + 1);
    }
  }}
/>