React Audio Recorder Hook

A powerful, TypeScript-based React hook for recording, managing, and processing audio in web applications with minimal setup and maximum flexibility.

Features

Simple Integration: Add professional audio recording capabilities to your React app with just a few lines of code
Full Recording Control: Start, stop, pause, resume, and cancel recordings with ease
Customizable Audio Settings: Configure audio constraints, chunk intervals, and MIME types
Recording Management: Track recording duration and state (recording/paused) automatically
Audio Processing: Save recordings as blobs with URLs for immediate playback or download
TypeScript Support: Fully typed API with comprehensive interfaces for type safety
Modern Browser Support: Works across all major browsers that support the MediaRecorder API
Zero Dependencies: Lightweight implementation built only on React hooks
Responsive Design: Perfect for both desktop and mobile web applications
Audio Visualization: Example component demonstrates how to add audio waveform visualization
Comprehensive Tests: Complete test suite ensures reliability

Support

If you find this package helpful, you can support its development by buying me a coffee:

Installation

npm install react-audio-recorder-hook
# or
yarn add react-audio-recorder-hook

Documentation

For comprehensive documentation, see the following resources:

Basic Usage

import React from 'react';
import useAudioRecorder from 'react-audio-recorder-hook';

function AudioRecorderComponent() {
  const {
    startRecording,
    stopRecording,
    cancelRecording,
    pauseRecording,
    resumeRecording,
    playRecording,
    saveRecording,
    isRecording,
    isPaused,
    recordingDuration,
  } = useAudioRecorder({
    audioConstraints: { echoCancellation: true },
  });

  const handlePlay = async () => {
    const audioUrl = await playRecording();
    if (audioUrl) {
      const audio = new Audio(audioUrl);
      audio.play();
    }
  };

  const handleSave = async () => {
    const recording = await saveRecording();
    if (recording) {
      console.log('Recording saved:', recording.blob);
      // You can upload the blob or use it as needed
    }
  };

  return (
    <div>
      <div>
        Recording: {isRecording ? 'Yes' : 'No'}
        {isPaused && ' (Paused)'}
      </div>
      <div>Duration: {recordingDuration}s</div>

      <div>
        {!isRecording && <button onClick={startRecording}>Start Recording</button>}

        {isRecording && !isPaused && <button onClick={pauseRecording}>Pause</button>}

        {isRecording && isPaused && <button onClick={resumeRecording}>Resume</button>}

        {isRecording && <button onClick={stopRecording}>Stop</button>}

        {isRecording && <button onClick={cancelRecording}>Cancel</button>}

        <button onClick={handlePlay}>Play</button>
        <button onClick={handleSave}>Save</button>
      </div>
    </div>
  );
}

API Overview

useAudioRecorder(options)

Options

audioConstraints: MediaTrackConstraints - Audio constraints to pass to getUserMedia
chunkInterval: number - Recording data chunk interval in milliseconds (default: 500)
preferredMimeType: string - Custom MIME type to use if supported
onNotSupported: () => void - Called when recording is unsupported on the browser

Returns

An object with the following properties:

startRecording: () => Promise - Starts recording audio
stopRecording: () => Promise - Stops the current recording
cancelRecording: () => void - Cancels the current recording
pauseRecording: () => void - Pauses the current recording
resumeRecording: () => Promise - Resumes a paused recording
saveRecording: () => Promise<{ blob: Blob; url: string } | null> - Creates a blob and URL for the recording
playRecording: () => Promise<string | null> - Creates a URL for the recording that can be used with Audio
isRecording: boolean - Whether recording is in progress
isPaused: boolean - Whether recording is paused
recordingDuration: number - Current recording duration in seconds
mediaStream: MediaStream | null - The current media stream

Advanced Usage Examples

Audio Recorder with Visualization

This package includes an example component that demonstrates how to implement audio waveform visualization with the hook:

import { AudioRecorderWithVisualization } from 'react-audio-recorder-hook/examples';

function App() {
  return (
    <div className="app">
      <h1>Audio Recorder with Visualization</h1>
      <AudioRecorderWithVisualization
        width={500}
        height={100}
        backgroundColor="#f0f0f0"
        barColor="#3a86ff"
      />
    </div>
  );
}

Testing

The package includes a comprehensive test suite that ensures all functionality works as expected. All tests are now passing.

# Run the test suite
pnpm test

# Generate test coverage report
pnpm test:coverage

Contributing

We welcome contributions! Please see our Contributing Guide for details on how to submit pull requests, report issues, and suggest enhancements.

Roadmap

See our improvements document for planned enhancements and future features.

License

MIT

Troubleshooting

iOS Compatibility

Version 1.0.5 and later includes improved compatibility with iOS devices by automatically detecting iOS browsers and using compatible audio formats (mp4/aac). If you experience issues with audio recording on iOS:

Ensure you're using the latest version of the package
You can explicitly set a compatible MIME type using the preferredMimeType option:
```
useAudioRecorder({
  preferredMimeType: 'audio/mp4',
});
```
For iOS Safari, ensure your app has proper microphone permissions and is served over HTTPS

If you still encounter issues on iOS devices, please report them on our GitHub issues page.