react-native-audio-waveform

A React Native package featuring native modules for generating and rendering audio waveforms. Designed to efficiently produce visual representations for pre-recorded audio files and dynamically draw waveforms in real-time during audio recording within React Native applications.

🎬 Preview

Audio Playback Waveform	Audio Record Waveform	Audio Waveform with Speed

Getting Started 🔧

Here's how to get started with react-native-audio-waveform in your React Native project:

Installation

1. Install the package

npm install @simform_solutions/react-native-audio-waveform react-native-gesture-handler

--- or ---

yarn add @simform_solutions/react-native-audio-waveform react-native-gesture-handler

2. Install CocoaPods in the iOS project

npx pod-install

Know more about react-native-gesture-handler

3. Add audio recording permissions

iOS

If you want to use recorder features in iOS, you have to add NSMicrophoneUsageDescription permission in info.plist and add a description based on your use case.

Here is a sample for info.plist permission and a description.

<key>NSMicrophoneUsageDescription</key>
<string>Needed permission to record audio</string>

Android

If you want to use recorder features in Android, you have to add RECORD_AUDIO permission in AndroidManifest.xml.

<uses-permission android:name="android.permission.RECORD_AUDIO" />

Usage

1. Static waveform

When you want to show a waveform for a pre-existing audio file, you need to use static mode for the waveform. We have provided type safety for forward ref so that if you pass the static mode then you can only access methods which are available for static mode other methods will reject promise.

Check the example below for more information.

import {
  Waveform,
  type IWaveformRef,
} from '@simform_solutions/react-native-audio-waveform';

const path = ''; // path to the audio file for which you want to show waveform
const ref = useRef<IWaveformRef>(null);
<Waveform
  mode="static"
  ref={ref}
  path={item}
  candleSpace={2}
  candleWidth={4}
  scrubColor="white"
  onPlayerStateChange={playerState => console.log(playerState)}
  onPanStateChange={isMoving => console.log(isMoving)}
/>;

2. Live recording waveform

When you want to record audio and show a waveform for that recording, you need to create a waveform with live mode. Same as static mode, we have safety for ref methods.

Check the example below for more information.

import {
  Waveform,
  type IWaveformRef,
} from '@simform_solutions/react-native-audio-waveform';

const ref = useRef<IWaveformRef>(null);
<Waveform
  mode="live"
  ref={ref}
  candleSpace={2}
  candleWidth={4}
  onRecorderStateChange={recorderState => console.log(recorderState)}
/>;

You can check out the full example at Example.

Properties

Props	Default	Static Mode	Live Mode	Type	Description
mode*	-	✅	✅	'live' or 'static'	Type of waveform. It can be either `static` for the resource file or `live` if you want to record audio
ref*	-	✅	✅	IWaveformRef	Type of ref provided to waveform component. If waveform mode is `static`, some methods from ref will throw error and same for `live`. Check IWaveformRef for more details about which methods these refs provides.
path*	-	✅	❌	string	Used for `static` type. It is the resource path of an audio source file.
playbackSpeed	1.0	✅	❌	1.0 / 1.5 / 2.0	The playback speed of the audio player. Note: Currently playback speed only supports, Normal (1x) Faster(1.5x) and Fastest(2.0x), any value passed to playback speed greater than 2.0 will be automatically adjusted to normal playback speed
candleSpace	2	✅	✅	number	Space between two candlesticks of waveform
candleWidth	5	✅	✅	number	Width of single candlestick of waveform
candleHeightScale	3	✅	✅	number	Scaling height of candlestick of waveform
maxCandlesToRender	300	❌	✅	number	Number of candlestick in waveform
containerStyle	-	✅	✅	`StyleProp<ViewStyle>`	style of the container
waveColor	#545454	✅	✅	string	color of candlestick of waveform
scrubColor	#7b7b7b	✅	❌	string	color of candlestick of waveform which has played
onPlayerStateChange	-	✅	❌	( playerState : PlayerState ) => void	callback function, which returns player state whenever player state changes.
onPanStateChange	-	✅	❌	( panMoving : boolean ) => void	callback function which returns boolean indicating whether audio seeking is active or not.
onRecorderStateChange	-	❌	✅	( recorderState : RecorderState ) => void	callback function which returns the recorder state whenever the recorder state changes. Check RecorderState for more details
onCurrentProgressChange	-	✅	❌	( currentProgress : number, songDuration: number ) => void	callback function, which returns current progress of audio and total song duration.
onChangeWaveformLoadState	-	✅	❌	( state : boolean ) => void	callback function which returns the loading state of waveform candlestick.
onError	-	✅	❌	( error : Error ) => void	callback function which returns the error for static audio waveform

Know more about ViewStyle, PlayerState, and RecorderState

IWaveformRef Methods

For Static mode

startPlayer()

startPlayer({
    finishMode?: FinishMode;
}): Promise<boolean>

starts playing the audio with the specified finish mode. If finish mode is not specified, it will default to FinishMode.stop.

It returns a boolean indicating whether playback is started.

stopPlayer()

stopPlayer(): Promise<boolean>

It returns a boolean indicating whether playback is stopped.

pausePlayer()

pausePlayer(): Promise<boolean>

It returns a boolean indicating whether playback is paused.

resumePlayer()

resumePlayer(): Promise<boolean>

It returns a boolean indicating whether playback is resumed again.

For Live mode

startRecord()

startRecord({
    encoder:number;
    sampleRate: number;
    bitRate: number;
    fileNameFormat: string;
    useLegacy: boolean;
    updateFrequency?: UpdateFrequency;
}): Promise<boolean>

Start a new audio recording with the given parameters. It will return whether the recording was started or not.

Check UpdateFrequency to know more.

Note: Before starting the recording, the user must allow NSMicrophoneUsageDescription for iOS. You can check the permissions by using checkHasAudioRecorderPermission from useAudioPermission. Check useAudioPermission to know more about various methods.

stopRecord()

stopRecord(): Promise<string>

It returns a string representing the current recorded audio file path.

pauseRecord()

pauseRecord(): Promise<boolean>

It returns a boolean indicating whether the recording is paused.

resumeRecord()

resumeRecord(): Promise<boolean>

It returns a boolean indicating whether the recording is resumed again.

useAudioPermission hook

By using this hook, you can check and ask for permission from the user for NSMicrophoneUsageDescription permission.

checkHasAudioRecorderPermission()

This method checks whether the user has permission to use a microphone for recording new audio. It will return PermissionStatus.

You can use this method as shown below:

const hasPermission: PermissionStatus = await checkHasAudioRecorderPermission();

getAudioRecorderPermission()

This method lets you ask for NSMicrophoneUsageDescription permission from the user. It will return PermissionStatus.

By combining this with checkHasAudioRecorderPermission you can ask for permission and start recording if permission is granted.

Check out the following example:

let hasPermission = await checkHasAudioRecorderPermission();

if (hasPermission === PermissionStatus.granted) {
  startRecording();
} else if (hasPermission === PermissionStatus.undetermined) {
  const permissionStatus = await getAudioRecorderPermission();
  if (permissionStatus === PermissionStatus.granted) {
    startRecording();
  }
} else {
  Linking.openSettings();
}

PlayerState

enum PlayerState {
  playing = 'playing',
  paused = 'paused',
  stopped = 'stopped',
}

RecorderState

enum RecorderState {
  recording = 'recording',
  paused = 'paused',
  stopped = 'stopped',
}

UpdateFrequency

// Update frequency in milliseconds
enum UpdateFrequency {
  high = 250.0,
  medium = 500.0,
  low = 1000.0,
}

PermissionStatus

enum PermissionStatus {
  denied = 'denied',
  undetermined = 'undetermined',
  granted = 'granted',
}

Example

You can check out the example app for react-native-audio-waveform in Example

To use example app you need to first run below command

cd example && npx react-native-asset

Note: If link-assets-manifest.json file already exists then make sure to delete that before running npx react-native-asset command.

This command will add our example audio sample files to the iOS bundle so that we can access them inside the iOS app.

yarn
yarn example ios // For iOS
yarn example android // For Android

Find this library useful? ❤️

Support it by joining stargazers for this repository.⭐

Bugs / Feature requests / Feedback

For bugs, feature requests, and discussion, please use GitHub Issues, GitHub New Feature, GitHub Feedback

🤝 How to Contribute

We'd love to have you improve this library or fix a problem 💪 Check out our Contributing Guide for ideas on contributing.

Awesome Mobile Libraries

Check out our other available awesome mobile libraries

License

MIT License

t4dek/react-native-audio-waveform