Introduction

The React library offers components like <AudioPlayer />, <Audio />, and <AudioStream /> for versatile audio playback, visualization, and streaming, including support for dynamic and static visualizations. Its hooks, such as useAudio, useCanvas, and detectNotes, provide comprehensive audio handling, canvas management, and musical note detection features.

Compaitibility

This library is compatible with React supporting libraries such as Vite, Next.js, and Remix.

Installation

Imports

Available React Components

Available React Hooks

<Audio/>

The <Audio/> component is a versatile and customizable audio player with various options for controlling playback, visualization, volume, and more.It shows the full Audio visualization upon load, the visualization is not dynamic, it's more on like a spectrograph of the audio input.It allows integration with custom visualizers, buttons, and volume controls. Below is a detailed documentation of the props available for this component.

Props

Prop Name	Default Value	Valid Value / Description
src	`null`	The audio source URL as a string.
clickableCanvas	`false`	`boolean` - If true, clicking on the canvas toggles audio playback.
width	`500`	`number` - The width of the canvas element.
height	`100`	`number` - The height of the canvas element.
controls	`true`	`boolean` - If true, playback controls are displayed.
pauseButton	`"Pause"`	`string` or `React.Component` - Text or a custom React component to display for the pause button.
playButton	`"Play"`	`string` or `React.Component` - Text or a custom React component to display for the play button.
dataCount	`64`	`number` - The number of data points used in the visualizer.
className	`""`	`string` - Custom CSS classes for the root `div` element.
controlsClassName	`""`	`string` - Custom CSS classes for the controls `div` element.
constrolsStyle	`false`	`object` - Inline styles for the controls `div` element.
customVolume	`false`	`React.Component` - A custom volume control component. Example: `<input type="range" min={0} max={100} />`.
volumeLevel	`false`	`boolean` - If true, the current volume level is displayed as a percentage.
enableDuration	`false`	`boolean` - If true, the audio duration is displayed.
durationClassName	`""`	`string` - Custom CSS classes for the duration element.
durationStyle	`false`	`object` - Inline styles for the duration element.
enableCurrentTime	`false`	`boolean` - If true, the current playback time is displayed.
currentTimeClassName	`""`	`string` - Custom CSS classes for the current time element.
currentTimeStyle	`false`	`object` - Inline styles for the current time element.
hideVolume	`true`	`boolean` - If true, the volume control is hidden.
volumeControlClassName	`""`	`string` - Custom CSS classess for the main element of the volume control.
volumeControlStyle	`{}`	`object` - Inline style for the main element of the volume control.
volumeLabelClassName	`""`	`string` - Custom CSS classess for the volume label.
volumeLabelStyle	`{}`	`object` - Inline style for the volume label.
volumeLabelIndicator	`"%"`	`string` - Volume level indicator.
disableVolume	`false`	`boolean` - If true, the volume is set to 0.
style	`false`	`object` - Inline styles for the root `div` element.
canvasClassName	`""`	`string` - Custom CSS classes for the canvas element.
canvasStyle	`false`	`object` - Inline styles for the canvas element.
toggleClassName	`""`	`string` - Custom CSS classes for the play/pause button.
toggleStyle	`false`	`object` - Inline styles for the play/pause button.
stopButton	`false`	`boolean` - If true, a stop button is displayed.
customStopButton	`false`	`React.Component` - A custom stop button component. Example: `<button onClick={stopAudio}>Stop</button>`.
barWidth	`false`	`number` - Width of each bar in the visualizer.
barHeight	`false`	`number` - Height of each bar in the visualizer.
horizontalOffset	`0`	`number` - Horizontal offset for the visualizer drawing.
color	`"black"`	`string` - Default color for the visualizer bars.
colorFunction	`false`	`function` - Custom function to determine the color of each bar. Example: ({barHeight, barWidth, index, dataArray, audioDuration}) => { return ``rgb(${barHeight * index},0,0)``; }.
customVisualizer	`false`	`function` - Custom visualizer function. Example: `({barHeight,barWidth, canvasContext,x,color,colorFunction, audioDuration, dataArray, bufferLength, canvasNode }) => { canvasContext.fillRect(x, y, width, height); }`.
customFunction	`false`	`function` - Custom function that receives audio data. Example: `({audioNode,audioFrequencyData,audioDuration}) => { console.log({audioNode,audioFrequencyData,audioDuration}); }`.

Example Usage

Structure

<AudioPlayer/>

The <AudioPlayer/> component is a customizable audio player with various options for controlling playback, visualization, volume, and more. It shows Audio visualization while the audio is playing, the visualization is dynamic. It allows you to integrate custom visualizers, buttons, and volume controls. Below is a detailed documentation of the props available for this component.

Props

Prop Name	Default Value	Valid Value / Description
src	`null`	The audio source URL as a string.
clickableCanvas	`false`	`boolean` - If true, clicking on the canvas toggles audio playback.
width	`500`	`number` - The width of the canvas element.
height	`100`	`number` - The height of the canvas element.
controls	`true`	`boolean` - If true, playback controls are displayed.
pauseButton	`"Pause"`	`string` or `React.Component` - Text or a custom React component to display for the pause button.
playButton	`"Play"`	`string` or `React.Component` - Text or a custom React component to display for the play button.
dataCount	`64`	`number` - The number of data points used in the visualizer.
className	`""`	`string` - Custom CSS classes for the root `div` element.
controlsClassName	`""`	`string` - Custom CSS classes for the controls `div` element.
constrolsStyle	`false`	`object` - Inline styles for the controls `div` element.
customVolume	`false`	`React.Component` - A custom volume control component. Example: `<input type="range" min={0} max={100} />`.
volumeLevel	`false`	`boolean` - If true, the current volume level is displayed as a percentage.
enableDuration	`false`	`boolean` - If true, the audio duration is displayed.
durationClassName	`""`	`string` - Custom CSS classes for the duration element.
durationStyle	`false`	`object` - Inline styles for the duration element.
enableCurrentTime	`false`	`boolean` - If true, the current playback time is displayed.
currentTimeClassName	`""`	`string` - Custom CSS classes for the current time element.
currentTimeStyle	`false`	`object` - Inline styles for the current time element.
hideVolume	`true`	`boolean` - If true, the volume control is hidden.
volumeControlClassName	`""`	`string` - Custom CSS classess for the main element of the volume control.
volumeControlStyle	`{}`	`object` - Inline style for the main element of the volume control.
volumeLabelClassName	`""`	`string` - Custom CSS classess for the volume label.
volumeLabelStyle	`{}`	`object` - Inline style for the volume label.
volumeLabelIndicator	`"%"`	`string` - Volume level indicator.
disableVolume	`false`	`boolean` - If true, the volume is set to 0.
style	`false`	`object` - Inline styles for the root `div` element.
canvasClassName	`""`	`string` - Custom CSS classes for the canvas element.
canvasStyle	`false`	`object` - Inline styles for the canvas element.
toggleClassName	`""`	`string` - Custom CSS classes for the play/pause button.
toggleStyle	`false`	`object` - Inline styles for the play/pause button.
stopButton	`false`	`boolean` - If true, a stop button is displayed.
customStopButton	`false`	`React.Component` - A custom stop button component. Example: `<button>Stop</button>`.
barWidth	`false`	`number` - Width of each bar in the visualizer.
barHeight	`false`	`number` - Height of each bar in the visualizer.
horizontalOffset	`0`	`number` - Horizontal offset for the visualizer drawing.
color	`"black"`	`string` - Default color for the visualizer bars.
colorFunction	`false`	`function` - Custom function to determine the color of each bar. Example: ({barHeight, barWidth, index, dataArray, audioDuration}) => { return ``rgb(${barHeight * index},0,0)``; }.
customVisualizer	`false`	`function` - Custom visualizer function. Example: `({barHeight,barWidth, canvasContext,x,color,colorFunction, audioDuration, dataArray, bufferLength, canvasNode }) => { canvasContext.fillRect(x, y, width, height); }`.
customFunction	`false`	`function` - Custom function that receives audio data. Example: `({audioNode,audioDuration, dataArray, bufferLength}) => { console.log({audioNode,audioDuration, dataArray, bufferLength}); }`.

Example Usage

Structure

<AudioStream/>

The <AudioStream/> component provides a customizable interface for streaming audio with various controls and visualizations. It supports microphone input, custom visualizations, and configurable buttons for controlling audio playback and visualization. Below is the detailed documentation of the props available for this component.

Props

Prop Name	Default Value	Valid Value / Description
clickableCanvas	`false`	`boolean` - If true, clicking on the canvas toggles the microphone state (mute/unmute).
width	`500`	`number` - The width of the canvas element.
height	`100`	`number` - The height of the canvas element.
controls	`true`	`boolean` - If true, playback controls are displayed.
muteButton	`"Mute"`	`string` - Text to display for the mute button.
unmuteButton	`"Unmute"`	`string` - Text to display for the unmute button.
dataCount	`64`	`number` - The number of data points used in the visualizer.
className	`""`	`string` - Custom CSS classes for the root `div` element.
controlsClassName	`""`	`string` - Custom CSS classes for the controls `div` element.
constrolsStyle	`false`	`object` - Inline styles for the controls `div` element.
style	`false`	`object` - Inline styles for the root `div` element.
canvasClassName	`""`	`string` - Custom CSS classes for the canvas element.
canvasStyle	`false`	`object` - Inline styles for the canvas element.
toggleClassName	`""`	`string` - Custom CSS classes for the mute/unmute button.
toggleStyle	`false`	`object` - Inline styles for the mute/unmute button.
stopButton	`true`	`boolean` - If true, a stop button is displayed.
customStopButton	`false`	`React.Component` - A custom stop button component. Example: `<button>Stop</button>`.
startButton	`true`	`boolean` - If true, a start button is displayed.
customStartButton	`false`	`React.Component` - A custom start button component. Example: `<button>Start</button>`.
barWidth	`false`	`number` - Width of each bar in the visualizer.
barHeight	`false`	`number` - Height of each bar in the visualizer.
horizontalOffset	`0`	`number` - Horizontal offset for the visualizer drawing.
color	`"black"`	`string` - Default color for the visualizer bars.
colorFunction	`false`	`function` - Custom function to determine the color of each bar. Example: `({barHeight, barWidth, index, dataArray, audioDuration}) => { return \`rgb(${barHeight * index},0,0)`; }`.
customVisualizer	`false`	`function` - Custom visualizer function. Example: `({barHeight, barWidth, canvasContext, x, color, colorFunction, audioDuration, dataArray, bufferLength, canvasNode }) => { canvasContext.fillRect(x, y, width, height); }`.
customFunction	`false`	`function` - Custom function that receives audio data. Example: `({audioNode,microphoneSource, mediaStream}) => { console.log({audioNode,microphoneSource, mediaStream}); }`.

Example Usage

Structure

useAudio

The useAudio hook provides a comprehensive set of functionalities for handling audio in a React application. This hook supports playing, pausing, stopping, and controlling audio, as well as capturing and analyzing audio from a microphone. It also includes utilities for converting audio to Base64 and detecting musical notes.

API

Parameters

src (string | File | Blob): The source of the audio. Can be a URL, File, or Blob.
fftSize (number): The size of the FFT used for frequency analysis. Defaults to 64.
detector (boolean): If true, enables pitch detection. Defaults to false.

Returns

An object containing the following properties and methods:

audioNode: The Audio element used for playback.
audioContext: The AudioContext used for audio processing.
audioSource: The MediaElementSourceNode created from the audioNode.
isPlaying: A boolean indicating whether the audio is currently playing.
play(): Starts playback of the audio.
pause(): Pauses playback of the audio.
toggleAudio(): Toggles between playing and pausing the audio.
stopAudio(): Stops playback and resets the audio to the beginning.
setVolume(volume): Sets the volume of the audio. volume is a number between 0 and 100.
analyzer: The AnalyserNode used for frequency analysis.
bufferLength: The length of the frequency data array.
dataArray: The frequency data array.
audioToBase64(source): Converts an audio source to a Base64 encoded string. Supports File, Blob, and URL sources.
captureMicrophone(): Starts capturing audio from the microphone.
muteMicrophone(): Mutes the microphone.
unmuteMicrophone(): Unmutes the microphone.
stopMicrophone(): Stops capturing audio from the microphone and cleans up resources.
microphoneSource: The MediaStreamAudioSourceNode created from the microphone stream.
mediaStream: The MediaStream obtained from the microphone.
isMute: A boolean indicating whether the microphone is muted.
audioFrequencyData: The frequency data array for the audio.
audioDuration: The duration of the audio in seconds.
audioCurrentTime: The current playback time of the audio in seconds.
audioVolume: The current volume level of the audio.
detectedNotes: An array of detected musical notes if detector is enabled.

For further customization or issues, please refer to the source code or open an issue on the repository.

Example Usage

useCanvas

The useCanvashook provides a convenient way to manage a canvas element and its context in a React component. It returns a Canvas component that you can use to render a <canvas> element and provides access to the canvas context through the canvasContext property.

API

Parameters

width (number): The width of the canvas.
height (number): The height of the canvas.

Returns

The useCanvas hook returns an object with the following properties:

Canvas: A React component that renders a <canvas> element with the specified width and height.
canvasContext: The 2D rendering context of the canvas, or null if the canvas is not yet rendered. Or null if the canvas is not yet initialized.
canvasNode: The actual <canvas> DOM element, or null if the canvas is not yet rendered.

For further customization or issues, please refer to the source code or open an issue on the repository.

Example Usage

detectNotes

Detects musical notes from an array of audio sample data using auto-correlation.

API

Parameters

dataArray(Float32Array or Unit8Array ): An array of audio sample data. The data should be in the range of 0 to 255.
sampleRate(number, optional): The sample rate of the audio data. Defaults to 44100.

Returns

An array of detected notes, each represented as an object containing the following properties:

frequency(string): The fundamental frequency of the note.
pitch(string): The musical pitch of the note, including its octave.
octave(number): The octave number of the note.
confidence(string): The confidence level of the note detection.
note(string): The note name (e.g., 'C', 'D#').
cents(number): The deviation in cents from the exact pitch.

If no notes are detected, returns null.

Description

The detectNotes function analyzes the given audio sample data to detect musical notes. It uses auto-correlation to identify peaks in the signal and calculates the fundamental frequency of each peak. The function then converts the frequency to a musical note and calculates its octave, confidence, and deviation in cents.

Example Usage

Notes

The valid values for dataCount prop are :- 32,64,128,256, 512, 1024, 2048 and 4096.
Ensure that your application has the appropriate permissions to access the microphone.
The audioToBase64 function supports both File and Blob sources, as well as URLs.

Developement

To get started with development, simply clone the repository and use npm install. Then, run `npm install` to install dependencies. You can use npm link to link the package locally and npm run build to compile your changes. We appreciate all contributions and look forward to building something amazing together!

Contributions

We welcome and encourage contributions to our open-source React library! Whether you're interested in improving existing features, adding new components, or fixing bugs, your contributions are invaluable. However, it is advised to follow the few code of conduct as mentioned below:-

Selft Explainatory Variable & Function Names
Comprehensive Documentation of newly added features/patches/code.
Anything new should make sense for the library and should be useful.
Keep it Vanilla, no external dependencies.