API

Audio

The <Audio /> component provides the core functionality.

Props

	Type	Default	Required
playlist	AudioTrack[]	---	✔️
defaultMuted	boolean	false	❌
defaultRepeat	RepeatMode	'playlist'	❌
defaultShuffle	boolean	false	❌
defaultVolume	number	100	❌
defaultPlaybackRate	number	1	❌
defaultTrackIndex	number	0	❌
startMargin	number | boolean	true	❌
children	AudioChildren	---	❌

Default Repeat

Specifies the default repeat behavior of the audio player.

Repeat Behavior

There are two repeat behaviors available :

1. 'track' - Repeats the currently playing track
2. 'playlist' - Repeats the entire playlist

If not specified, the default behavior is 'playlist'.

The repeat behavior can be controlled using the setRepeat method.

Start Margin

In many audio players, when a certain amount of time has passed since the track began, clicking the "previous track" button restarts the current track. However, if less time has passed, clicking the button skips to the previous track.

The startMargin prop controls this behavior. It accepts both boolean and number values:

• Setting it to false disables this functionality.
• Setting it to true defaults the margin to 5 seconds.
• Providing a number will override the default, specifying the number of seconds to use as the margin.

AudioContext

const audioContext = useAudio();

const AudioPlayer = () => <Audio>{audioContext => (...)}</Audio>;

AudioContext Type

• audioRef - audio element's ref
• playlist
• playing
• loading - true when loading track's data chunks
• duration
• timeLeft
• currentTime
• muted
• shuffle
• repeat
• volume
• playbackRate
• trackIndex
• currentTrack
• play
• pause
• togglePlay - play/pause
• toggleMuted - mute/unmute
• toggleShuffle - shuffle/unshuffle playlist
• setVolume
• setRepeat
• setCurrentTime
• forwardTrack
• rewindTrack
• nextTrack
• prevTrack
• playTrack
• setPlaybackRate

useAudio

a hook that provides the audioContext within the scope of the <Audio /> component

import { useAudio } from 're-audio';

const PlayerControls = () => {
  const audioContext = useAudio();

  return (...);
};

export default PlayerControls;

Utils

• formatTime - used to format :
  • duration
  • timeLeft
  • currentTime

import { useAudio, formatTime } from 're-audio';

const TimeDisplay = () => {
  const { duration } = useAudio();

  return <span>{formatTime(duration)}</span>;
};

export default TimeDisplay;

Types

• RepeatMode

type RepeatMode = 'track' | 'playlist';

• AudioChildren

type AudioChildren = React.ReactNode | ((audioContext: AudioContext) => React.ReactNode);

• AudioTrack

type AudioTrack = {
  id: string | number;
  src: string;
  type?: string;
  fallbacks?: Pick<AudioTrack, 'src' | 'type'>[];
} & Record<string, unknown>;

• AudioState

type AudioState = {
  playing: boolean;
  loading: boolean;
  duration: number;
  timeLeft: number;
  currentTime: number;
  muted: boolean;
  shuffle: boolean;
  repeat: RepeatMode;
  volume: number;
  playbackRate: number;
  trackIndex: number;
  currentTrack: AudioTrack;
};

• AudioContext

type AudioContext = {
  audioRef: React.RefObject<HTMLAudioElement>;
  playlist: AudioTrack[];
  playing: boolean;
  loading: boolean;
  duration: number;
  timeLeft: number;
  currentTime: number;
  muted: boolean;
  shuffle: boolean;
  repeat: RepeatMode;
  volume: number;
  playbackRate: number;
  trackIndex: number;
  currentTrack: AudioTrack;
  play: () => void;
  pause: () => void;
  togglePlay: () => void;
  toggleMuted: () => void;
  toggleShuffle: () => void;
  setVolume: (newVolume: number) => void;
  setRepeat: (repeat: RepeatMode) => void;
  setCurrentTime: (newCurrentTime: number) => void;
  forwardTrack: (step?: number) => void;
  rewindTrack: (step?: number) => void;
  nextTrack: () => void;
  prevTrack: () => void;
  playTrack: (trackIndex: number) => void;
  setPlaybackRate: (newPlaybackRate: number) => void;
};