useAudioRecorder

sensors

Installation

npx usehooks-cli@latest add use-audio-recorder

Description

A comprehensive hook for audio recording with real-time analysis using getUserMedia, MediaRecorder, and Web Audio APIs. Provides full control over audio recording including pause/resume, duration tracking, and optional real-time frequency analysis.

Parameters

Name	Type	Default	Description
options?	UseAudioRecorderOptions	-	Configuration options for the audio recorder

Parameter Properties

options properties:

Name	Type	Description
audioBitsPerSecond?	number	Audio bitrate in bits per second (default: 128000)
mimeType?	string	MIME type for the recording (default: 'audio/webm')
timeslice?	number	Time interval for data chunks in milliseconds
enableAnalysis?	boolean	Enable real-time audio analysis (default: false)
fftSize?	number	FFT size for audio analysis (default: 2048)

Return Type

UseAudioRecorderReturn

Property	Type	Description
isSupported	boolean	Whether audio recording is supported in the current browser
isRecording	boolean	Whether audio is currently being recorded
isPaused	boolean	Whether recording is currently paused
stream	MediaStream \| null	The current media stream from getUserMedia
mediaRecorder	MediaRecorder \| null	The MediaRecorder instance
audioBlob	Blob \| null	The recorded audio as a Blob
audioUrl	string \| null	Object URL for the recorded audio
duration	number	Recording duration in seconds
error	string \| null	Error message if any operation failed
analysisData	AudioAnalysisData \| null	Real-time audio analysis data (frequency, time domain, volume)
startRecording	() => Promise<void>	Start audio recording
stopRecording	() => void	Stop audio recording
pauseRecording	() => void	Pause audio recording
resumeRecording	() => void	Resume paused recording
clearRecording	() => void	Clear the current recording data
downloadRecording	(filename?: string) => void	Download the recorded audio file

Examples

Basic Audio Recording

Simple audio recording with start/stop functionality

import { useAudioRecorder } from '@usehooks/use-audio-recorder';

function AudioRecorder() {
  const {
    isSupported,
    isRecording,
    audioUrl,
    duration,
    startRecording,
    stopRecording,
    downloadRecording
  } = useAudioRecorder();

  if (!isSupported) {
    return <div>Audio recording not supported</div>;
  }

  return (
    <div>
      <button onClick={startRecording} disabled={isRecording}>
        Start Recording
      </button>
      <button onClick={stopRecording} disabled={!isRecording}>
        Stop Recording
      </button>
      <p>Duration: {duration}s</p>
      {audioUrl && (
        <div>
          <audio src={audioUrl} controls />
          <button onClick={() => downloadRecording('my-recording.webm')}>
            Download
          </button>
        </div>
      )}
    </div>
  );
}

Recording with Pause/Resume

Audio recording with pause and resume functionality

import { useAudioRecorder } from '@usehooks/use-audio-recorder';

function AdvancedRecorder() {
  const {
    isRecording,
    isPaused,
    duration,
    startRecording,
    stopRecording,
    pauseRecording,
    resumeRecording,
    clearRecording
  } = useAudioRecorder();

  return (
    <div>
      <button onClick={startRecording} disabled={isRecording}>
        Start
      </button>
      <button onClick={pauseRecording} disabled={!isRecording || isPaused}>
        Pause
      </button>
      <button onClick={resumeRecording} disabled={!isPaused}>
        Resume
      </button>
      <button onClick={stopRecording} disabled={!isRecording}>
        Stop
      </button>
      <button onClick={clearRecording}>
        Clear
      </button>
      <p>Status: {isRecording ? (isPaused ? 'Paused' : 'Recording') : 'Stopped'}</p>
      <p>Duration: {duration}s</p>
    </div>
  );
}

Real-time Audio Analysis

Recording with real-time frequency analysis and volume monitoring

import { useAudioRecorder } from '@usehooks/use-audio-recorder';

function AudioAnalyzer() {
  const {
    isRecording,
    analysisData,
    startRecording,
    stopRecording
  } = useAudioRecorder({
    enableAnalysis: true,
    fftSize: 1024
  });

  return (
    <div>
      <button onClick={startRecording} disabled={isRecording}>
        Start Analysis
      </button>
      <button onClick={stopRecording} disabled={!isRecording}>
        Stop
      </button>
      
      {analysisData && (
        <div>
          <p>Volume: {(analysisData.volume * 100).toFixed(1)}%</p>
          <div>
            Frequency Data: {analysisData.frequencyData.length} bins
          </div>
          <div>
            Time Domain: {analysisData.timeData.length} samples
          </div>
        </div>
      )}
    </div>
  );
}

Dependencies

react

Notes

•Requires user permission to access microphone
•Browser support varies for different MIME types
•Real-time analysis may impact performance on lower-end devices
•Audio context is automatically cleaned up on component unmount
•Recording automatically stops when component unmounts

Implementation

"use client";

import { useState, useEffect, useRef, useCallback } from "react";

interface UseAudioRecorderOptions {
  audioBitsPerSecond?: number;
  mimeType?: string;
  timeslice?: number;
  enableAnalysis?: boolean;
  fftSize?: number;
}

interface AudioAnalysisData {
  frequencyData: Uint8Array;
  timeData: Uint8Array;
  volume: number;
}

interface UseAudioRecorderReturn {
  isSupported: boolean;
  isRecording: boolean;
  isPaused: boolean;
  stream: MediaStream | null;
  mediaRecorder: MediaRecorder | null;
  audioBlob: Blob | null;
  audioUrl: string | null;
  duration: number;
  error: string | null;
  analysisData: AudioAnalysisData | null;
  startRecording: () => Promise<void>;
  stopRecording: () => void;
  pauseRecording: () => void;
  resumeRecording: () => void;
  clearRecording: () => void;
  downloadRecording: (filename?: string) => void;
}

const useAudioRecorder = (
  options: UseAudioRecorderOptions = {}
): UseAudioRecorderReturn => {
  const {
    audioBitsPerSecond = 128000,
    mimeType = "audio/webm",
    timeslice,
    enableAnalysis = false,
    fftSize = 2048,
  } = options;

  const [isRecording, setIsRecording] = useState(false);
  const [isPaused, setIsPaused] = useState(false);
  const [stream, setStream] = useState<MediaStream | null>(null);
  const [mediaRecorder, setMediaRecorder] = useState<MediaRecorder | null>(
    null
  );
  const [audioBlob, setAudioBlob] = useState<Blob | null>(null);
  const [audioUrl, setAudioUrl] = useState<string | null>(null);
  const [duration, setDuration] = useState(0);
  const [error, setError] = useState<string | null>(null);
  const [analysisData, setAnalysisData] = useState<AudioAnalysisData | null>(
    null
  );

  const chunksRef = useRef<Blob[]>([]);
  const startTimeRef = useRef<number>(0);
  const pausedTimeRef = useRef<number>(0);
  const intervalRef = useRef<number | null>(null);
  const audioContextRef = useRef<AudioContext | null>(null);
  const analyserRef = useRef<AnalyserNode | null>(null);
  const sourceRef = useRef<MediaStreamAudioSourceNode | null>(null);
  const animationFrameRef = useRef<number | null>(null);

  const isSupported =
    typeof navigator !== "undefined" &&
    !!navigator.mediaDevices &&
    !!navigator.mediaDevices.getUserMedia &&
    !!window.MediaRecorder;

  const updateDuration = useCallback(() => {
    if (startTimeRef.current) {
      const elapsed = Date.now() - startTimeRef.current - pausedTimeRef.current;
      setDuration(Math.floor(elapsed / 1000));
    }
  }, []);

  const analyzeAudio = useCallback(() => {
    if (!analyserRef.current || !enableAnalysis) return;

    const frequencyData = new Uint8Array(analyserRef.current.frequencyBinCount);
    const timeData = new Uint8Array(analyserRef.current.fftSize);

    analyserRef.current.getByteFrequencyData(frequencyData);
    analyserRef.current.getByteTimeDomainData(timeData);

    // Calculate volume (RMS)
    let sum = 0;
    for (let i = 0; i < timeData.length; i++) {
      const sample = ((timeData[i] ?? 0) - 128) / 128;
      sum += sample * sample;
    }
    const volume = Math.sqrt(sum / timeData.length);

    setAnalysisData({
      frequencyData: frequencyData.slice(),
      timeData: timeData.slice(),
      volume,
    });

    if (isRecording && !isPaused) {
      animationFrameRef.current = requestAnimationFrame(analyzeAudio);
    }
  }, [isRecording, isPaused, enableAnalysis]);

  const setupAudioAnalysis = useCallback(
    (mediaStream: MediaStream) => {
      if (!enableAnalysis) return;

      try {
        audioContextRef.current = new (window.AudioContext ||
          (window as any).webkitAudioContext)();
        analyserRef.current = audioContextRef.current.createAnalyser();
        sourceRef.current =
          audioContextRef.current.createMediaStreamSource(mediaStream);

        analyserRef.current.fftSize = fftSize;
        analyserRef.current.smoothingTimeConstant = 0.8;

        sourceRef.current.connect(analyserRef.current);

        analyzeAudio();
      } catch (err) {
        console.warn("Failed to setup audio analysis:", err);
      }
    },
    [enableAnalysis, fftSize, analyzeAudio]
  );

  const startRecording = useCallback(async () => {
    if (!isSupported) {
      setError("Audio recording is not supported in this browser");
      return;
    }

    try {
      setError(null);
      const mediaStream = await navigator.mediaDevices.getUserMedia({
        audio: {
          echoCancellation: true,
          noiseSuppression: true,
          autoGainControl: true,
        },
      });

      setStream(mediaStream);
      setupAudioAnalysis(mediaStream);

      const recorder = new MediaRecorder(mediaStream, {
        audioBitsPerSecond,
        mimeType: MediaRecorder.isTypeSupported(mimeType)
          ? mimeType
          : "audio/webm",
      });

      chunksRef.current = [];

      recorder.ondataavailable = (event) => {
        if (event.data.size > 0) {
          chunksRef.current.push(event.data);
        }
      };

      recorder.onstop = () => {
        const blob = new Blob(chunksRef.current, { type: recorder.mimeType });
        setAudioBlob(blob);
        setAudioUrl(URL.createObjectURL(blob));
        setIsRecording(false);
        setIsPaused(false);

        if (intervalRef.current) {
          clearInterval(intervalRef.current);
          intervalRef.current = null;
        }

        if (animationFrameRef.current) {
          cancelAnimationFrame(animationFrameRef.current);
          animationFrameRef.current = null;
        }
      };

      recorder.onpause = () => {
        setIsPaused(true);
        pausedTimeRef.current += Date.now() - startTimeRef.current;
        if (animationFrameRef.current) {
          cancelAnimationFrame(animationFrameRef.current);
          animationFrameRef.current = null;
        }
      };

      recorder.onresume = () => {
        setIsPaused(false);
        startTimeRef.current = Date.now();
        if (enableAnalysis) {
          analyzeAudio();
        }
      };

      recorder.onerror = (event) => {
        setError(`Recording error: ${event.error?.message || "Unknown error"}`);
        setIsRecording(false);
        setIsPaused(false);
      };

      setMediaRecorder(recorder);
      recorder.start(timeslice);
      setIsRecording(true);
      startTimeRef.current = Date.now();
      pausedTimeRef.current = 0;
      setDuration(0);

      intervalRef.current = setInterval(updateDuration, 1000);
    } catch (err) {
      const errorMessage =
        err instanceof Error ? err.message : "Failed to start recording";
      setError(errorMessage);
    }
  }, [
    isSupported,
    audioBitsPerSecond,
    mimeType,
    timeslice,
    setupAudioAnalysis,
    updateDuration,
    enableAnalysis,
    analyzeAudio,
  ]);

  const stopRecording = useCallback(() => {
    if (mediaRecorder && mediaRecorder.state !== "inactive") {
      mediaRecorder.stop();
    }

    if (stream) {
      stream.getTracks().forEach((track) => track.stop());
      setStream(null);
    }

    if (audioContextRef.current) {
      audioContextRef.current.close();
      audioContextRef.current = null;
    }
  }, [mediaRecorder, stream]);

  const pauseRecording = useCallback(() => {
    if (mediaRecorder && mediaRecorder.state === "recording") {
      mediaRecorder.pause();
    }
  }, [mediaRecorder]);

  const resumeRecording = useCallback(() => {
    if (mediaRecorder && mediaRecorder.state === "paused") {
      mediaRecorder.resume();
    }
  }, [mediaRecorder]);

  const clearRecording = useCallback(() => {
    if (audioUrl) {
      URL.revokeObjectURL(audioUrl);
    }
    setAudioBlob(null);
    setAudioUrl(null);
    setDuration(0);
    setAnalysisData(null);
    setError(null);
  }, [audioUrl]);

  const downloadRecording = useCallback(
    (filename = "recording.webm") => {
      if (!audioUrl) return;

      const link = document.createElement("a");
      link.href = audioUrl;
      link.download = filename;
      document.body.appendChild(link);
      link.click();
      document.body.removeChild(link);
    },
    [audioUrl]
  );

  // Cleanup on unmount
  useEffect(() => {
    return () => {
      if (intervalRef.current) {
        clearInterval(intervalRef.current);
      }
      if (animationFrameRef.current) {
        cancelAnimationFrame(animationFrameRef.current);
      }
      if (stream) {
        stream.getTracks().forEach((track) => track.stop());
      }
      if (audioContextRef.current) {
        audioContextRef.current.close();
      }
      if (audioUrl) {
        URL.revokeObjectURL(audioUrl);
      }
    };
  }, [stream, audioUrl]);

  return {
    isSupported,
    isRecording,
    isPaused,
    stream,
    mediaRecorder,
    audioBlob,
    audioUrl,
    duration,
    error,
    analysisData,
    startRecording,
    stopRecording,
    pauseRecording,
    resumeRecording,
    clearRecording,
    downloadRecording,
  };
};

export { useAudioRecorder };
export type {
  UseAudioRecorderOptions,
  AudioAnalysisData,
  UseAudioRecorderReturn,
};

useToggle

CLI Docs All Hooks

useBarcodeDetector