react-audio-recorder-hook

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:

• Getting Started Guide
• API Reference
• Examples
• Advanced Usage
• Troubleshooting
• Contributing Guide
• Best Practices
• Auto-publishing Guide

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.