react-use-audio-player

react-use-audio-player

A custom React hook for controlling browser audio playback

Install

yarn add react-use-audio-player

TypeScript

For convenience, the library's type definitions are included in the package under index.d.ts.

Usage

This library exports a context Provider and two hooks for controlling the audio source.

AudioPlayerProvider

This Provider is required for the hooks to function. The Provider contains a single audio source and exposes an interface for manipulating it via the useAudioPlayer hook. The benefit of having a single, shared audio source is that it allows the developer to compose together multiple components that share knowledge about the audio. For example, you may have separate components PlayPauseButton, SeekBar and VolumeControls all working together on the same audio source.

import React from "react"
import { AudioPlayerProvider } from "react-use-audio-player"

const App = () => {
    return (
        <AudioPlayerProvider>
            <AudioPlayer file="meow.mp3" />
        </AudioPlayerProvider>
    )
}

useAudioPlayer

This is the main hook for controlling your audio instance.

Example:

import React from "react"
import { useAudioPlayer } from "react-use-audio-player"

const AudioPlayer = ({ file }) => {
    const { play, pause, playbackReady, loading, isPlaying } = useAudioPlayer(
        file
    )

    const togglePlay = () => {
        if (isPlaying()) {
            pause()
        } else {
            play()
        }
    }

    if (!playbackReady && !loading) return <div>No audio to play</div>
    if (loading) return <div>Loading audio</div>

    return (
        <div>
            <button onClick={togglePlay}>
                {isPlaying() ? "Pause" : "Play"}
            </button>
        </div>
    )
}

API

loading: boolean

true if audio is being fetched

playbackReady: boolean

true if the audio has been loaded and can be played

error: Error

set when audio has failed to load

play: function

plays the loaded audio

pause: function

pauses audio

stop: function

stops the audio, returning the position to 0

loadAudio: function(url: string)

loads an audio file

isPlaying: function: boolean

true is the audio is currently playing

seek: function(position: number)

sets the position of the audio to position (seconds)

mute: function

mutes the audio

useAudioPosition

This hooks exposes the current position and duration of the audio instance as its playing in real time (60 fps via requestAnimationFrame). This data may be useful when animating a visualization for your audio like a seek bar. A separate hook was created to manage this state in order to avoid many rerenders of components that don't need the live data feed. For example a component that renders a play/pause button may use useAudioPlayer but does not need to rerender every time the position of the playing audio changes.

import React from "react"
import { useAudioPosition } from "react-use-audio-player"

const PlayBar = () => {
    const { position, duration } = useAudioPosition()
    const [percent, setPercent] = React.useState(0)

    React.useEffect(() => {
        setPercent((position / duration) * 100 || 0)
    }, [position, duration])

    return <ProgressBar percentComplete={percent} />
}

API

position: number

the current playback position of the audio in seconds

duration: number

the total length of the audio in seconds

Examples

To run the example applications follow the following steps:

1. git clone the repository
2. cd useAudioPlayer/examples
3. yarn install
4. yarn start
5. follow the local README for further assistance

Development Tools

Eslint

A basic eslint configuration has been set up but should be expanded with more rules.

Prettier

Code style and formatting is handled by Prettier. The formatter will run pre-commit to ensure consistent style between contributers.