react-voice-visualizer

react-voice-visualizer Demo App

Overview

The react-voice-visualizer library offers a comprehensive and highly customizable solution for capturing, visualizing, and manipulating audio recordings within your web applications. Built with React hook and component, this library simplifies the process of integrating audio recording and visualization functionalities using the Web Audio API.

Experience the Demo App: Click here to explore the react-voice-visualizer. Try it out and see it in action!

Key Features:

• Audio Recording: Easily capture audio recordings with minimal setup using React hook and component.

• Visualization: Visualize audio data in real-time, making it suitable for applications such as voice recognition, sound analysis, and more.

• Customization: The library is absolutely customizable, allowing you to tailor the audio recording and visualization components to fit your project's unique requirements.

• Responsiveness: Create audio applications that adapt seamlessly to various screen sizes and devices, ensuring a consistent user experience across platforms.

This README provides a comprehensive guide to effectively utilizing the library's features.

Installation

To integrate the React Voice Visualizer library into your project, simply install it via npm or yarn:

npm install react-voice-visualizer

or

yarn add react-voice-visualizer

Demo App

For a live demonstration of the React Voice Visualizer library, you can check out the Demo Voice Visualizer App. This app showcases various features and functionalities of the library in action.

Feel free to explore the demo app to see how the React Voice Visualizer can be used in different scenarios. You can refer to the source code of the demo app for additional examples and inspiration for using the library effectively.

Usage

To start using the VoiceVisualizer component, you will need to import the necessary hook and component from the library. Here's an example of how to use this library in your App component:

import { useEffect } from "react";
import { useVoiceVisualizer, VoiceVisualizer } from "react-voice-visualizer";

const App = () => {
    // Initialize the recorder controls using the hook
    const recorderControls = useVoiceVisualizer();
    const {
        // ... (Extracted controls and states, if necessary)
        recordedBlob,
        error,
        audioRef,
    } = recorderControls;

    // Get the recorded audio blob
    useEffect(() => {
        if (!recordedBlob) return;

        console.log(recordedBlob);
    }, [recordedBlob, error]);

    // Get the error when it occurs
    useEffect(() => {
        if (!error) return;

        console.error(error);
    }, [error]);

    return (
        <VoiceVisualizer ref={audioRef} controls={recorderControls} />
    );
};

export default App;

Additionally, you can use the setPreloadedAudioBlob function to load any audio data. Pass your audio data in a Blob format to this function:

setPreloadedAudioBlob(audioBlob);

Example:

import { useEffect } from 'react';
import { useVoiceVisualizer, VoiceVisualizer } from 'react-voice-visualizer';

const App = ({audioBlob}) => {
    const recorderControls = useVoiceVisualizer();
    const {
        // ... (Extracted controls and states, if necessary)
        setPreloadedAudioBlob,
        togglePauseResume,
        isAvailableRecordedAudio,
        isPreloadedBlob,
        error,
        audioRef
    } = recorderControls;

    useEffect(() => {
        // Set the preloaded audioBlob when the component mounts
        if (audioBlob) {
            setPreloadedAudioBlob(audioBlob);
        }
    }, [audioBlob]);

    // Get and log any error when it occurs
    useEffect(() => {
        if (!error) return;

        console.error(error);
    }, [error]);


    // Function to handle audio playback
    const handleUserClickToPlayAudio = () => {
        if (isAvailableRecordedAudio) {
            togglePauseResume();
        }
    };
    
    return (
        <div>
            {/* Button to initiate audio playback */}
            <button onClick={handleUserClickToPlayAudio}>Click to Toggle Play Audio</button>

            <VoiceVisualizer
                ref={audioRef}
                controls={recorderControls}
                isControlPanelShown={false} // Set to 'false' in most cases. You should use your own UI.
                isDefaultUIShown={false} // Set to 'false' in most cases, but should be determined based on the specific user's use case.
            />
        </div>
    );
};

export default App;

Autoplay Audio on Load

If you want the audio to autoplay as soon as it becomes available upon a user's click, please refer to the following example.

This example illustrates how to utilize the onClickAutoplayAudioOnLoad and setPreloadedAudioBlob functions to enable audio playback only when a user initiates it by clicking a button; otherwise, it may cause error during the execution of audio.play() that can be handled using the onErrorPlayingAudio callback, which you can pass as a parameter to useVoiceVisualizer hook.

By clicking the "Click to Play Audio" button, audio data is fetched and prepared for playback, ensuring compliance with autoplay policies. This approach guarantees that audio begins playing in response to a user's interaction, providing a seamless and policy-compliant audio experience.

Example:

import { useEffect } from 'react';
import { useVoiceVisualizer, VoiceVisualizer } from 'react-voice-visualizer';

const App = ({audioUrl}) => {
    const recorderControls = useVoiceVisualizer();
    const {
        // ... (Extracted controls and states, if necessary)
        setPreloadedAudioBlob,
        onClickAutoplayAudioOnLoad, // Import the onClickAutoplayAudioOnLoad function
        togglePauseResume,
        isAvailableRecordedAudio,
        isPreloadedBlob,
        error,
        audioRef,
    } = recorderControls;

    // Get and log any error when it occurs
    useEffect(() => {
        if (!error) return;

        console.error(error);
    }, [error]);

    // Function to handle user click event for audio autoplay
    const handleUserClickToAutoplayAudio = () => {
        if (isAvailableRecordedAudio) {
            togglePauseResume();
        } else {
        // Fetch the audio data and trigger autoplay upon user interaction
        onClickAutoplayAudioOnLoad(); // Call the onClickAutoplayAudioOnLoad function
        fetch(audioUrl)
            .then((response) => {
                if (!response.ok) {
                    throw new Error('The network response was not successful');
                }

                return response.blob()
            })
            .then((blob) => {
                setPreloadedAudioBlob(blob); // Set blob
            })
            .catch((err) => {
                // Handle errors, both network-related and those that occur during blob retrieval
                console.error(err);
            });
        }
    };

    return (
        <div>
            {/* Button to initiate audio playback */}
            <button onClick={handleUserClickToAutoplayAudio}>Click to Play Audio</button>
            
            <VoiceVisualizer
                ref={audioRef}
                controls={recorderControls}
                isControlPanelShown={false} // Set to 'false'. You should use your own UI.
                isDefaultUIShown={false} // Set to 'false' in most cases, but should be determined based on the specific user's use case.
            />
        </div>
    );
};
export default App;

Getting started

• Import the required components and hooks from the library.
• Initialize the recorder controls using the useVoiceVisualizer hook.
• Use the provided state and functions to manage audio recording and playback.
• Render the VoiceVisualizer component to display the real-time audio visualization.
• Use the provided buttons to start, pause, stop, and save the audio recording.

Remember to include necessary CSS styles to customize the components and buttons according to your design preferences.

API Reference

useVoiceVisualizer() Hook

A hook that provides recorder controls and state for audio visualization.

Usage

const recorderControls = useVoiceVisualizer();

Parameters (All parameters are optional)

Parameter	Type	Description
onStartRecording	() => void	Callback function triggered when recording starts.
onStopRecording	() => void	Callback function triggered when recording stops.
onPausedRecording	() => void	Callback function triggered when recording is paused.
onResumedRecording	() => void	Callback function triggered when recording is resumed.
onClearCanvas	() => void	Callback function triggered when the canvas is cleared.
onEndAudioPlayback	() => void	Callback function triggered when audio playback ends.
onStartAudioPlayback	() => void	Callback function triggered when audio playback starts.
onPausedAudioPlayback	() => void	Callback function triggered when audio playback is paused.
onResumedAudioPlayback	() => void	Callback function triggered when audio playback is resumed.
onErrorPlayingAudio	(error: Error) => void	Callback function is invoked when an error occurs during the execution of audio.play(). It provides an opportunity to handle and respond to such error.

Returns

Returns	Type	Description
audioRef	MutableRefObject <HTMLAudioElement | null>	Reference to the audio element used for playback.
isRecordingInProgress	boolean	Indicates if audio recording is currently in progress.
isPausedRecording	boolean	Indicates if audio recording is currently paused.
audioData	Uint8Array	Audio data for real-time visualization.
recordingTime	number	Elapsed time during recording in milliseconds.
mediaRecorder	MediaRecorder | null	MediaRecorder instance used for recording audio.
duration	number	Duration of the recorded audio in seconds.
currentAudioTime	number	Current playback time of the recorded audio in seconds.
audioSrc	string	Source URL of the recorded audio file for playback.
isPausedRecordedAudio	boolean	Indicates if recorded audio playback is paused.
isProcessingRecordedAudio	boolean	Indicates if the recorded audio is being processed and 'Processing Audio...' text shown.
isCleared	boolean	Indicates if the canvas has been cleared.
isPreloadedBlob	boolean	Indicates whether a blob of recorded audio data has been preloaded.
isAvailableRecordedAudio	boolean	Indicates whether recorded audi is available and not currently being processed. This return value can be used to check if it's an appropriate time to work with recorded audio data in your application.
recordedBlob	Blob | null	Recorded audio data in Blob format.
bufferFromRecordedBlob	AudioBuffer | null	Audio buffer from the recorded Blob.
formattedDuration	string	Formatted duration time in format 09:51m.
formattedRecordingTime	string	Formatted recording current time in format 09:51.
formattedRecordedAudioCurrentTime	string	Formatted recorded audio current time in format 09:51:1.
setPreloadedAudioBlob	(audioBlob: Blob) => void	This function allows you to load an existing audio blob for further processing, playback and visualization. The audioBlob parameter represents the recorded audio data stored in a Blob format.
onClickAutoplayAudioOnLoad	() => void	This function should be used in conjunction with the setPreloadedAudioBlob function when you load a completed audio blob. To start playing audio as soon as it becomes available, call this function but only in response to a user's click event. It ensures compliance with autoplay policies.
startRecording	() => void	Function to start audio recording.
togglePauseResume	() => void	Function to toggle pause/resume during recording and playback of recorded audio.
stopRecording	() => void	Function to stop audio recording.
saveAudioFile	() => void	This function allows you to save the recorded audio as a webm file format. Please note that it supports saving audio only in the webm format. If you need to save the audio in a different format, you can use external libraries like FFmpeg to convert the Blob to your desired format. This flexibility allows you to tailor the output format according to your specific needs.
clearCanvas	() => void	Function to clear the visualization canvas.
isAutoplayPreloadedBlob	boolean	State that indicates whether an onClickAutoplayAudioOnLoad function has been called. It is set to false once the audio data becomes available.
setIsAutoplayPreloadedBlob	Dispatch<SetStateAction<boolean>>	This function can handle the isAutoplayPreloadedBlob state and can be used to abort autoplay preloaded blob.
setCurrentAudioTime	Dispatch<SetStateAction<number>>	Internal function to handle current audio time updates during playback.
error	Error | null	Error object if any error occurred during recording or playback.
_setIsProcessingAudioOnComplete	Dispatch<SetStateAction<boolean>>	Internal function to set isProcessingAudioOnComplete state.
_setIsProcessingOnResize	Dispatch<SetStateAction<boolean>>	Internal function to set isProcessingOnResize state.
_handleAudioPlaybackOnLoad	() => void	(Do not use) Internal function to handle autoplay.

Load and visualize any Audio

You can use the setPreloadedAudioBlob function to load any audio data. Pass your audio data as a Blob to this function:

setPreloadedAudioBlob(audioBlob);

VoiceVisualizer Component

A component that visualizes the real-time audio wave during recording.

Props for AudioVisualizer Component

Props	Description	Default	Type
ref	A reference to the audio element - audioRef from the useVoiceVisualizer hook.	-	React.RefObject (Required)
controls	Provides the audio recording controls and states required for visualization.	-	Controls (Required)
height	The height of the visualization canvas.	200	string | number (Optional)
width	The width of the visualization canvas.	100%	string | number (Optional)
backgroundColor	The background color of the visualization canvas.	transparent	string (Optional)
mainBarColor	The color of the main audio wave line.	#FFFFFF	string (Optional)
secondaryBarColor	The secondary color of the audio wave line.	#5e5e5e	string (Optional)
speed	The speed of the audio visualization animation (Integer from 1 to 6, higher number is slower).	3	number (Optional)
barWidth	The width of each audio wave bar.	2	number (Optional)
gap	The gap between each audio wave bar.	1	number (Optional)
rounded	The border radius of the audio wave bars.	5	number (Optional)
isControlPanelShown	Whether to display the audio control panel, including features such as recorded audio duration, current recording time, and control buttons. If you want to create your own UI, set it to false and utilize functions from the useVoiceVisualizer hook to manage audio control.	true	boolean (Optional)
isDownloadAudioButtonShown	Whether to display the Download audio button.	false	boolean (Optional)
fullscreen	Whether the visualization should be displayed in fullscreen mode. It begins from the center by default.	false	boolean (Optional)
animateCurrentPick	Whether to animate the current pick in the visualization.	true	boolean (Optional)
onlyRecording	Whether to show the visualization only during voice recording.	false	boolean (Optional)
isDefaultUIShown	Whether to show a default UI on Canvas before recording. If you want to create your own UI, set it to false.	true	boolean (Optional)
mainContainerClassName	The CSS class name for the main container.	-	string (Optional)
canvasContainerClassName	The CSS class name for the container of the visualization canvas.	-	string (Optional)
isProgressIndicatorShown	Whether to show the progress indicator after recording.	true	boolean (Optional)
progressIndicatorClassName	The CSS class name for the progress indicator.	-	string (Optional)
isProgressIndicatorTimeShown	Whether to show the progress indicator time.	true	boolean (Optional)
progressIndicatorTimeClassName	The CSS class name for the progress indicator with time.	-	string (Optional)
isProgressIndicatorOnHoverShown	Whether to show the progress indicator on hover.	true	boolean (Optional)
progressIndicatorOnHoverClassName	The CSS class name for the progress indicator on hover.	-	string (Optional)
isProgressIndicatorTimeOnHoverShown	Whether to show the progress indicator time on hover.	true	boolean (Optional)
progressIndicatorTimeOnHoverClassName	The CSS class name for the progress indicator with time on hover.	-	string (Optional)
isAudioProcessingTextShown	Whether to show the audio processing text.	true	boolean (Optional)
audioProcessingTextClassName	The CSS class name for the audio processing text.	-	string (Optional)
controlButtonsClassName	The CSS class name for the Clear Button and Download Audio button components.	-	string (Optional)

License

This library is distributed under the MIT License.

Issues

If you encounter any bugs or have suggestions for improvements, please report them in the GitHub Issues section.

Support

For support or general questions, you can reach out to [e-mail].

If you find my project valuable and would like to support its development, you can buy me a coffee ☕. Your contribution helps keep this project active and growing.

Your contribution is greatly appreciated! ❤️🚀

Credits

This library was created by Yurii Zarytskyi

LinkedIn