headless-react-audio-recorder v1.0.2

Headless React Audio Recorder and Player (Headless Recorder)

Overview

Headless Recorder is an open-source project for a React-based audio recorder and player. It provides a headless implementation that allows developers to easily integrate audio recording and playback functionalities into their applications without dealing with UI components.

Ideally fit for design branding solutions.

Features

• Audio Recording: Capture high-quality audio from the user's microphone.
• Audio Playback: Play recorded audio with customizable controls.
• Headless Implementation: Allows for full control over the UI, providing only the essential functionality.
• Easy Integration: Simple and intuitive API for seamless integration into any React project.
• Customizable: Flexible architecture that supports extensions and customizations.
• Save Record on Finish: Automatically saves the recorded audio file when the recording process is completed.
• Recording Process Visualization: Provides visual feedback and indicators during the recording process to help users understand the status and duration of the recording.
• Screen Wake: Keeps the screen awake during the recording process to prevent interruptions and ensure continuous recording.

Installation

To install Headless Recorder, run the following command in your project directory:

npm i headless-react-audio-recorder

Idea

Creating headless UI Recorder components allows developers to easily integrate audio recording and playback functionalities while maintaining complete control over the design and branding. It offers flexibility in customizing the user interface, ensuring that the components can match any design system or brand identity seamlessly. By separating the functionality from the presentation layer, it simplifies maintenance, enhances reusability, and ensures a consistent user experience across different projects and contexts. This approach is especially beneficial for projects that require unique and tailored user interfaces.

Inspired of the idea of Shadcn, headlessui, and others.

Usage

Use single useRecorder hook for all actions:

import { useRecorder } from "headless-react-audio-recorder";

function App() {
  // use single hook for all actions
  const {
    startRecording,
    stopRecording,
    togglePauseResume,
    recordingBlob,
    isRecording,
    isPaused,
    recordingTime,
    lastRecordingTime,
    recordTimeLimit,
    downloadingBlob,
    showVisualizer,
    visualizer,
    audio,
    player,
    playerRef,
    isPlayingPlayer,
    onPlayPausePlayer,
  } = useRecorder({
    onRecordingComplete: (blob: Blob) => {
      console.log("recording complete", blob);
    },
    recordTimeLimit: 180,
    downloadOnFinish: false,
    showVisualizer: true,
    wakeLock: true,
    wakeLockOptions: {
      onError: (error) => {
        console.error("Wake Lock request failed", error);
      },
      onRequest: () => {
        console.log("Wake Lock is active");
      },
      onRelease: () => {
        console.log("Wake Lock is released");
      },
    },
    player: true,
    playerOptions: {
      waveColor: "#570df8",
      progressColor: "#00126e",
    },
  });

  // user defined function to format time
  const formatTime = (seconds: number) =>
    [seconds / 60, seconds % 60]
      .map((v) => `0${Math.floor(v)}`.slice(-2))
      .join(":");

  return (
    <div>
      {/* Record Action  */}
      {!isRecording && (
        <button onClick={() => startRecording()}>
          {lastRecordingTime ? `Start over` : `Record`}
        </button>
      )}

      {/* resume/pause Action  */}
      {(isRecording || isPaused) && (
        <button onClick={togglePauseResume}>
          {isPaused ? "resume" : "pause"}
        </button>
      )}

      {(isRecording || isPaused) && (
        <button onClick={stopRecording}>Finish</button>
      )}

      {/* possible range indicator  */}
      <div>
        {!recordingBlob && !!recordTimeLimit && (isRecording || isPaused) && (
          <input
            type="range"
            min={0}
            max={recordTimeLimit}
            value={recordingTime}
          />
        )}
      </div>

      {/* Recording Time parsed */}
      {(isRecording || isPaused || recordingBlob) && (
        <p className="text-sm font-thin">{`${formatTime(
          isRecording ? recordingTime : lastRecordingTime
        )} ${!!recordTimeLimit ? ` / ${formatTime(recordTimeLimit)}` : ""}`}</p>
      )}

      {/* Recording Time Blob */}
      <p>recording Time: {recordingTime}</p>

      {/* last Recording Blob */}
      <p>last recording Time: {lastRecordingTime}</p>

      {/* Record Blob */}
      {downloadingBlob && <p>record is downloading...</p>}

      {/* Optional visualizer */}
      {showVisualizer && isRecording ? <div>{visualizer}</div> : null}

      {/* Optional Built-In player */}
      {audio && player && !isRecording && (
        <div>
          <div ref={playerRef} />

          <button onClick={onPlayPausePlayer} disabled={!audio}>
            {isPlayingPlayer ? "Pause" : "Play"}
          </button>
        </div>
      )}

      {/* Optional HTML5 player */}
      {audio && player && !isRecording && (
        <div>
          <audio controls src={audio} />
        </div>
      )}
    </div>
  );
}

export default App;

Under the hood implementation

• limited hooks taken from react-audio-voice-recorder, without ui
• optional visualizer during recording react-audio-visualize
• optional saving record on finish provided by @ffmpeg
• optional Screen Wake Lock API, limited hooks taken from react-screen-wake-lock
• optional player of recorded voice (as a replacement of html5 built-in player), hooks of @wavesurfer/react with all listed options

Props

Contributing

We welcome contributions from the community! If you would like to contribute, please follow these steps:

• Fork the repository.

• Create a new branch for your feature or bug fix.

• Make your changes and commit them.

• Push your changes to your forked repository.

• Create a pull request to the main repository.

License

This project is licensed under the MIT License. See the LICENSE file for more information.

Feel free to customize this template to fit the specifics of your project. If you need any help with additional details or sections, just let me know! 😊