useAudio
About
A comprehensive hook to control and manage audio elements in your React application with advanced features like volume control, playback rate adjustment, seeking, and error handling.
Examples
Basic example
Advanced audio player with controls
Audio player with playlist
Arguments
Argument value | Type | Description | Default |
---|---|---|---|
options | Object | See table below | |
callbacks | Object | See table below |
Options
Options value | Type | Description | Default |
---|---|---|---|
autoPlay | Boolean | Indicates if the audio should start playing automatically | false |
isMuted | Boolean | Indicates if the audio should be muted by default | false |
volume | Number | Initial volume level (0-1) | 1 |
playbackRate | Number | Initial playback speed (0.25-4) | 1 |
loop | Boolean | Whether the audio should loop | false |
preload | String | How much of the audio to preload ("none", "metadata", "auto") | "metadata" |
Callbacks
Callbacks value | Type | Description | Default |
---|---|---|---|
onPlay | Function | Called when audio starts playing | undefined |
onPause | Function | Called when audio is paused | undefined |
onEnded | Function | Called when audio playback ends | undefined |
onMute | Function | Called when audio is muted | undefined |
onUnmute | Function | Called when audio is unmuted | undefined |
onLoadedMetadata | Function | Called when audio metadata is loaded | undefined |
onTimeUpdate | Function | Called when current time changes (currentTime) | undefined |
onDurationChange | Function | Called when duration changes (duration) | undefined |
onVolumeChange | Function | Called when volume changes (volume) | undefined |
onRateChange | Function | Called when playback rate changes (rate) | undefined |
onError | Function | Called when an error occurs (error) | undefined |
onLoadStart | Function | Called when loading starts | undefined |
onCanPlay | Function | Called when audio can start playing | undefined |
onWaiting | Function | Called when audio is buffering | undefined |
Returns
Returns an array with three elements:
Return value | Type | Description | Default |
---|---|---|---|
ref | Callback Ref | A ref that should be used on the audio element you want to control | undefined |
state | Object | An object containing isPlaying and isMuted properties | |
controls | Object | An object containing audio control methods |
State Properties
Property | Type | Description |
---|---|---|
isPlaying | Boolean | Whether the audio is playing |
isMuted | Boolean | Whether the audio is muted |
volume | Number | Current volume level (0-1) |
currentTime | Number | Current playback position in seconds |
duration | Number | Total duration of audio in seconds |
playbackRate | Number | Current playback speed (0.25-4) |
isLoading | Boolean | Whether the audio is loading |
isBuffering | Boolean | Whether the audio is buffering |
loop | Boolean | Whether the audio is set to loop |
hasError | Boolean | Whether an error has occurred |
error | String | Error message (only present when hasError is true) |
Control Methods
Method | Type | Description |
---|---|---|
play | Function | Start playing the audio (returns Promise) |
pause | Function | Pause the audio |
togglePlay | Function | Toggle play/pause state (returns Promise) |
mute | Function | Mute the audio |
unmute | Function | Unmute the audio |
toggleMute | Function | Toggle mute/unmute state |
setVolume | Function | Set volume level (0-1) |
setCurrentTime | Function | Set current playback position in seconds |
setPlaybackRate | Function | Set playback speed (0.25-4) |
seek | Function | Seek forward/backward by specified seconds |
fastForward | Function | Fast forward by 10 seconds (or custom amount) |
rewind | Function | Rewind by 10 seconds (or custom amount) |
setLoop | Function | Enable/disable looping |