useAudio

React hook to manage an audio.

Add the hook via the CLI:

npmyarnpnpm

npx @novajslabs/cli add useAudio

npx @novajslabs/cli add useAudio

pnpm dlx @novajslabs/cli add useAudio

Or copy and paste the code into your project:

TypeScriptJavaScript

import { useEffect, useState, RefObject } from "react";

export const useAudio = (ref: RefObject<HTMLAudioElement>) => {
  const audio = ref.current;

  const [audioState, setAudioState] = useState({
    isPaused: audio ? audio?.paused : true,
    isMuted: audio ? audio?.muted : false,
    currentVolume: audio ? audio?.volume : 100,
    currentTime: audio ? audio?.currentTime : 0,
  });

  const play = () => {
    audio?.play();
    setAudioState((prev) => {
      return {
        ...prev,
        isPaused: false,
        isMuted: audio ? audio.muted : prev.isMuted,
      };
    });
  };

  const pause = () => {
    audio?.pause();
    setAudioState((prev) => {
      return {
        ...prev,
        isPaused: true,
      };
    });
  };

  const handlePlayPauseControl = (e: Event) => {
    setAudioState((prev) => {
      return {
        ...prev,
        isPaused: (e.target as HTMLAudioElement).paused,
      };
    });
  };

  const togglePause = () => (audio?.paused ? play() : pause());

  const handleVolume = (delta: number) => {
    const deltaDecimal = delta / 100;

    if (audio) {
      let newVolume = audio?.volume + deltaDecimal;

      if (newVolume >= 1) {
        newVolume = 1;
      } else if (newVolume <= 0) {
        newVolume = 0;
      }

      audio.volume = newVolume;
      setAudioState((prev) => {
        return {
          ...prev,
          currentVolume: newVolume * 100,
        };
      });
    }
  };

  const handleVolumeControl = (e: Event) => {
    if (e.target && audio) {
      const newVolume = (e.target as HTMLAudioElement).volume * 100;

      handleMute(audio.muted);
      setAudioState((prev) => ({
        ...prev,
        currentVolume: newVolume,
      }));
    }
  };

  const handleMute = (mute: boolean) => {
    if (audio) {
      audio.muted = mute;
      setAudioState((prev) => {
        return {
          ...prev,
          isMuted: mute,
        };
      });
    }
  };

  const handleTime = (delta: number = 5) => {
    if (audio) {
      let newTime = audio.currentTime + delta;

      if (newTime >= audio.duration) {
        newTime = audio.duration;
      } else if (newTime <= 0) {
        newTime = 0;
      }

      audio.currentTime = newTime;
      setAudioState((prev) => {
        return {
          ...prev,
          currentTime: newTime,
        };
      });
    }
  };

  const handleTimeControl = (e: Event) => {
    setAudioState((prev) => {
      return {
        ...prev,
        currentTime: (e.target as HTMLAudioElement).currentTime,
      };
    });
  };

  useEffect(() => {
    return () => {
      pause();
    };
  }, []);

  useEffect(() => {
    if (audio) {
      audio.addEventListener("volumechange", handleVolumeControl);
      audio.addEventListener("play", handlePlayPauseControl);
      audio.addEventListener("pause", handlePlayPauseControl);
      audio.addEventListener("timeupdate", handleTimeControl);

      return () => {
        audio.removeEventListener("volumechange", handleVolumeControl);
        audio.removeEventListener("play", handlePlayPauseControl);
        audio.removeEventListener("pause", handlePlayPauseControl);
        audio.removeEventListener("timeupdate", handleTimeControl);
      };
    }
  }, [audio]);

  return {
    ...audioState,
    play,
    pause,
    togglePause,
    increaseVolume: (increase: number = 5) => handleVolume(increase),
    decreaseVolume: (decrease: number = 5) => handleVolume(decrease * -1),
    mute: () => handleMute(true),
    unmute: () => handleMute(false),
    toggleMute: () => handleMute(!audio?.muted),
    forward: (increase: number = 5) => handleTime(increase),
    back: (decrease: number = 5) => handleTime(decrease * -1),
  };
};

import { useEffect, useState } from "react";

export const useAudio = (ref) => {
  const audio = ref.current;

  const [audioState, setAudioState] = useState({
    isPaused: audio ? audio?.paused : true,
    isMuted: audio ? audio?.muted : false,
    currentVolume: audio ? audio?.volume : 100,
    currentTime: audio ? audio?.currentTime : 0,
  });

  const play = () => {
    audio?.play();
    setAudioState((prev) => {
      return {
        ...prev,
        isPaused: false,
        isMuted: audio ? audio.muted : prev.isMuted,
      };
    });
  };

  const pause = () => {
    audio?.pause();
    setAudioState((prev) => {
      return {
        ...prev,
        isPaused: true,
      };
    });
  };

  const handlePlayPauseControl = (e) => {
    setAudioState((prev) => {
      return {
        ...prev,
        isPaused: e.target.paused,
      };
    });
  };

  const togglePause = () => (audio?.paused ? play() : pause());

  const handleVolume = (delta) => {
    const deltaDecimal = delta / 100;

    if (audio) {
      let newVolume = audio?.volume + deltaDecimal;

      if (newVolume >= 1) {
        newVolume = 1;
      } else if (newVolume <= 0) {
        newVolume = 0;
      }

      audio.volume = newVolume;
      setAudioState((prev) => {
        return {
          ...prev,
          currentVolume: newVolume * 100,
        };
      });
    }
  };

  const handleVolumeControl = (e) => {
    if (e.target && audio) {
      const newVolume = e.target.volume * 100;

      handleMute(audio.muted);
      setAudioState((prev) => ({
        ...prev,
        currentVolume: newVolume,
      }));
    }
  };

  const handleMute = (mute) => {
    if (audio) {
      audio.muted = mute;
      setAudioState((prev) => {
        return {
          ...prev,
          isMuted: mute,
        };
      });
    }
  };

  const handleTime = (delta = 5) => {
    if (audio) {
      let newTime = audio.currentTime + delta;

      if (newTime >= audio.duration) {
        newTime = audio.duration;
      } else if (newTime <= 0) {
        newTime = 0;
      }

      audio.currentTime = newTime;
      setAudioState((prev) => {
        return {
          ...prev,
          currentTime: newTime,
        };
      });
    }
  };

  const handleTimeControl = (e) => {
    setAudioState((prev) => {
      return {
        ...prev,
        currentTime: e.target.currentTime,
      };
    });
  };

  useEffect(() => {
    return () => {
      pause();
    };
  }, []);

  useEffect(() => {
    if (audio) {
      audio.addEventListener("volumechange", handleVolumeControl);
      audio.addEventListener("play", handlePlayPauseControl);
      audio.addEventListener("pause", handlePlayPauseControl);
      audio.addEventListener("timeupdate", handleTimeControl);

      return () => {
        audio.removeEventListener("volumechange", handleVolumeControl);
        audio.removeEventListener("play", handlePlayPauseControl);
        audio.removeEventListener("pause", handlePlayPauseControl);
        audio.removeEventListener("timeupdate", handleTimeControl);
      };
    }
  }, [audio]);

  return {
    ...audioState,
    play,
    pause,
    togglePause,
    increaseVolume: (increase = 5) => handleVolume(increase),
    decreaseVolume: (decrease = 5) => handleVolume(decrease * -1),
    mute: () => handleMute(true),
    unmute: () => handleMute(false),
    toggleMute: () => handleMute(!audio?.muted),
    forward: (increase = 5) => handleTime(increase),
    back: (decrease = 5) => handleTime(decrease * -1),
  };
};

Requirements

React 16.8 or higher

Parameters

ref required

Type: HTMLAudioElement

The HTML audio element to be manage.

Return values

isPaused

Type: boolean

Indicates whether the audio is currently paused (true) or playing (false).

isMuted

Type: boolean

Indicates whether the audio is currently muted (true) or unmuted (false).

currentVolume

Type: number

The current volume level of the audio, ranging from 0 to 100.

currentTime

Type: number

The current playback position (in seconds) of the audio.

play

Type: function

Play the audio.

pause

Type: function

Pause the audio.

togglePause

Type: function

Toggle between playing and pausing the audio.

increaseVolume

Type: function

Increase the volume by a specified amount.

decreaseVolume

Type: function

Decrease the volume by a specified amount.

mute

Type: function

Mute the audio.

unmute

Type: function

Unmute the audio.

toggleMute

Type: function

Toggle between muting and unmuting the audio.

forward

Type: function

Fast forward the audio by a specified number of seconds.

back

Type: function

Rewind the audio by a specified number of seconds.

Example

tsx

import { useRef } from "react";
import { useAudio } from "./hooks/useAudio";

const App = () => {
  const audioRef = useRef<HTMLAudioElement>(null);
  const {
    isPaused,
    isMuted,
    currentVolume,
    currentTime,
    play,
    pause,
    togglePause,
    increaseVolume,
    decreaseVolume,
    mute,
    unmute,
    toggleMute,
    forward,
    back,
  } = useAudio(audioRef);

  return (
    <div>
      <audio ref={audioRef} src="audio.mp3" />
      <div>
        <button onClick={togglePause}>{isPaused ? "Play" : "Pause"}</button>
        <button onClick={toggleMute}>{isMuted ? "Unmute" : "Mute"}</button>
        <input
          type="range"
          min={0}
          max={100}
          value={currentVolume}
          onChange={(e) => increaseVolume(Number(e.target.value))}
        />
        <input
          type="range"
          min={0}
          max={videoRef.current?.duration || 0}
          value={currentTime}
          onChange={(e) =>
            videoRef.current &&
            (videoRef.current.currentTime = Number(e.target.value))
          }
        />
        <button onClick={() => forward(10)}>Forward</button>
        <button onClick={() => back(10)}>Back</button>
      </div>
    </div>
  );
};

export default App;

Use cases

Here are some use cases where this React hook is useful:

Controlling audio playback in a custom media player
Implementing a podcast player with seek functionality
Building a music streaming app with volume control
Creating an audio preview component for an e-commerce site
Developing an educational platform with audio lectures

useAudio ​

Requirements ​

Parameters ​

ref required ​

Return values ​

isPaused ​

isMuted ​

currentVolume ​

currentTime ​

play ​

pause ​

togglePause ​

increaseVolume ​

decreaseVolume ​

mute ​

unmute ​

toggleMute ​

forward ​

back ​

Example ​

Use cases ​

useAudio

Requirements

Parameters

ref required

Return values

isPaused

isMuted

currentVolume

currentTime

play

pause

togglePause

increaseVolume

decreaseVolume

mute

unmute

toggleMute

forward

back

Example

Use cases