Skip to content

Commit d2eac89

Browse files
kuldip-simformstavan-simform
kuldip-simform
authored and
stavan-simform
committed
feat(UNT-T20566): add readme file and update example app
1 parent ce970ad commit d2eac89

File tree

29 files changed

+667
-177
lines changed

29 files changed

+667
-177
lines changed

‎README.md‎

Lines changed: 323 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,332 @@
1-
react-native-audio-waveform<br />
2-
A React Native component to show audio waveform<br />
1+
# react-native-audio-waveform
2+
3+
[![react-native-audio-waveform on npm](https://img.shields.io/npm/v/react-native-audio-waveform.svg?style=flat)](https://www.npmjs.com/package/react-native-audio-waveform) [![react-native-audio-waveform downloads](https://img.shields.io/npm/dm/react-native-audio-waveform)](https://www.npmtrends.com/react-native-audio-waveform) [![react-native-audio-waveform install size](https://packagephobia.com/badge?p=react-native-audio-waveform)](https://packagephobia.com/result?p=react-native-audio-waveform) [![Android](https://img.shields.io/badge/Platform-Android-green?logo=android)](https://www.android.com) [![iOS](https://img.shields.io/badge/Platform-iOS-green?logo=apple)](https://developer.apple.com/ios) [![MIT](https://img.shields.io/badge/License-MIT-green)](https://opensource.org/licenses/MIT)
4+
5+
---
6+
7+
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.
8+
9+
---
10+
11+
## 🎬 Preview
12+
13+
## <a href="https://github.com/SimformSolutionsPvtLtd/react-native-audio-waveform"><img width="202" height="400" alt="SimformSolutions" src="./assets/audio_waveform.gif"> </a>
14+
15+
## Quick Access
16+
17+
- [Installation](#installation)
18+
- [Usage and Examples](#usage)
19+
- [Properties](#properties)
20+
- [Example Code](#example)
21+
- [License](#license)
22+
23+
## Getting Started 🔧
24+
25+
Here's how to get started with react-native-audio-waveform in your React Native project:
26+
27+
### Installation
28+
29+
##### 1. Install the package
30+
31+
```sh
32+
npm install react-native-audio-waveform react-native-gesture-handler
33+
```
34+
35+
###### --- or ---
36+
37+
```sh
38+
yarn add react-native-audio-waveform react-native-gesture-handler
39+
```
40+
41+
##### 2. Install cocoapods in the ios project
42+
43+
```bash
44+
npx pod-install
45+
```
46+
47+
##### Know more about [react-native-gesture-handler](https://www.npmjs.com/package/react-native-gesture-handler)
48+
49+
##### 3. Add Permission in iOS
50+
51+
if you want to use recorder features in iOS side you have to add **NSMicrophoneUsageDescription** permission in info.plist and add description based on your use-case.
52+
53+
here is a sample for info.plist permission and description
54+
55+
```plist
56+
<key>NSMicrophoneUsageDescription</key>
57+
<string>Needed permission to record audio</string>
58+
```
59+
60+
### Usage
61+
62+
#### 1. Static waveform
63+
64+
When you want to show a waveform for 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 assign ref type of `IPlayWaveformRef` to the waveform.
65+
66+
Check below example for more information.
67+
68+
```tsx
69+
import { IPlayWaveformRef, Waveform } from 'react-native-audio-waveform';
70+
71+
const path = ''; // path to the audio file for which you want to show waveform
72+
const ref = useRef<IPlayWaveformRef>(null);
73+
<Waveform<'static'>
74+
mode="static"
75+
ref={ref}
76+
path={item}
77+
candleSpace={2}
78+
candleWidth={4}
79+
scrubColor="white"
80+
onPlayerStateChange={playerState => console.log(playerState)}
81+
onPanStateChange={isMoving => console.log(isMoving)}
82+
/>;
83+
```
84+
85+
#### 2. Live recording waveform
86+
87+
When you are want to record a audio and show waveform that recording at that time you need to create waveform with `live` mode. Same as `static` mode we have type safety for ref. You can only provide `IRecordWaveformRef` to `live` mode waveform.
88+
89+
Check below example for more information.
90+
91+
```tsx
92+
import { IRecordWaveformRef, Waveform } from 'react-native-audio-waveform';
93+
94+
const ref = useRef<IRecordWaveformRef>(null);
95+
<Waveform<'live'>
96+
mode="live"
97+
ref={ref}
98+
candleSpace={2}
99+
candleWidth={4}
100+
onRecorderStateChange={recorderState => console.log(recorderState)}
101+
/>;
102+
```
103+
104+
you can check full example at [Example](./example/src/App.tsx).
105+
106+
---
107+
108+
## Properties
109+
110+
| **Props** | **defult** | **Available for** | **type** | **description** |
111+
| --------------------- | ---------- | ----------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
112+
| mode\* | - | both | 'live' or 'static' | Type of waveform. It can be either `static` for resources file or `live` if you want to record audio |
113+
| ref\* | - | both | IPlayWaveformRef or IRecordWaveformRef | Type of ref provided to waveform component. If waveform mode is `static`, ref type must be `IPlayWaveformRef` and if waveform mode is `live`, ref type must be `IRecordWaveformRef`.<br> Check [IPlayWaveformRef](#iplaywaveformref-methods) and [IRecordWaveformRef](#irecordwaveformref-methods) for more details about which methods these refs provides. |
114+
| path\* | - | static | string | Used for `static` type. It is resource path of audio source file. |
115+
| candleSpace | 2 | both | number | Space between two candlestick of waveform |
116+
| candleWidth | 5 | both | number | Width of single candlestick of waveform |
117+
| containerStyle | - | both | `StyleProp<ViewStyle>` | style of the container |
118+
| waveColor | #545454 | both | string | colour of candlestick of waveform |
119+
| scrubColor | #7b7b7b | static | string | colour of candlestick of waveform which has played |
120+
| onPlayerStateChange | - | static | ( playerState : PlayerState ) => void | callback function which returns player state whenever player state changes. |
121+
| onPanStateChange | - | static | ( panMoving : boolean ) => void | callback function which returns boolean indicating whether pan gesture is active or not. |
122+
| onRecorderStateChange | - | live | ( recorderState : RecorderState ) => void | callback function which returns the recorder state whenever the recorder state changes. Check RecorderState for more details |
123+
124+
##### Know more about [ViewStyle](https://reactnative.dev/docs/view-style-props), [PlayerState](#playerstate), and [RecorderState](#recorderstate)
3125

4126
---
5127

6-
#### Steps to Run & Build:
128+
### Methods
129+
130+
#### IPlayWaveformRef methods
131+
132+
#### startPlayer()
133+
134+
```ts
135+
startPlayer({
136+
finishMode?: FinishMode;
137+
}): Promise<boolean>
138+
```
139+
140+
starts playing the audio with the specified finish mode. If finish mode is not specified it will defaults to `FinishMode.stop`.
141+
142+
It returns boolean indicating whether playback is started.
143+
144+
#### stopPlayer()
145+
146+
```ts
147+
stopPlayer(): Promise<boolean>
148+
```
149+
150+
It returns boolean indicating whether playback is stopped.
151+
152+
#### pausePlayer()
153+
154+
```ts
155+
pausePlayer(): Promise<boolean>
156+
```
157+
158+
It returns boolean indicating whether playback is paused.
7159

8-
- Install dependencies `yarn`
9-
- Build `yarn build`
10-
- Install dependencies in example app `cd example && yarn && cd ios/ && pod install && cd ..`
11-
- Run example app `yarn ios`
160+
#### resumePlayer()
161+
162+
```ts
163+
resumePlayer(): Promise<boolean>
164+
```
165+
166+
It returns boolean indicating whether playback is resumed again.
167+
168+
#### IRecordWaveformRef methods
169+
170+
#### startRecord()
171+
172+
```ts
173+
startRecord({
174+
encoder: number;
175+
sampleRate: number;
176+
bitRate: number;
177+
fileNameFormat: string;
178+
useLegacy: boolean;
179+
updateFrequency?: UpdateFrequency;
180+
}): Promise<boolean>;
181+
```
182+
183+
Start a new audio recording with given parameters. It will return the if recording was started or not.
184+
185+
Check [UpdateFrequency](#updatefrequency) to know more.
186+
187+
> Note: Before starting the recording, User must have to allow **NSMicrophoneUsageDescription** for iOS. You can check the permissions by using **_checkHasAudioRecorderPermission_** from **_useAudioPermission_**. Check [useAudioPermission](#useaudiopermission-hook) to know more about various methods.
188+
189+
#### stopRecord()
190+
191+
```ts
192+
stopRecord(): Promise<string>
193+
```
194+
195+
It returns string representing the current recorded audio file path.
196+
197+
#### pauseRecord()
198+
199+
```ts
200+
pauseRecord(): Promise<boolean>
201+
```
202+
203+
It returns boolean indicating whether recording is paused.
204+
205+
#### resumeRecord()
206+
207+
```ts
208+
resumeRecord(): Promise<boolean>
209+
```
210+
211+
It returns boolean indicating whether recording is resumed again.
212+
213+
### useAudioPermission hook
214+
215+
By using this hook you can check and ask for permission from user for **NSMicrophoneUsageDescription** permission.
216+
217+
#### checkHasAudioRecorderPermission()
218+
219+
This method checks whether user has permission to use Microphone for recording new audio. It will return [PermissionStatus](#permissionstatus).
220+
221+
you can use this method as shown below:
222+
223+
```ts
224+
const hasPermission: PermissionStatus = await checkHasAudioRecorderPermission();
225+
```
226+
227+
#### getAudioRecorderPermission()
228+
229+
This method lets you ask for **NSMicrophoneUsageDescription** permission from user. It will return PermissionStatus.
230+
231+
By combining this and checkHasAudioRecorderPermission you can ask for permission and start recording if permission is granted.
232+
233+
Check the following example for example:
234+
235+
```ts
236+
let hasPermission: PermissionStatus = await checkHasAudioRecorderPermission();
237+
238+
if (hasPermission === PermissionStatus.granted) {
239+
startRecording();
240+
} else if (hasPermission === PermissionStatus.undetermined) {
241+
const permissionStatus = await getAudioRecorderPermission();
242+
if (permissionStatus === PermissionStatus.granted) {
243+
startRecording();
244+
}
245+
} else {
246+
Linking.openSettings();
247+
}
248+
```
12249

13250
---
14251

15-
- Run `yarn build` to sync package changes / updates
252+
#### PlayerState
253+
254+
```ts
255+
enum PlayerState {
256+
playing = 'playing',
257+
paused = 'paused',
258+
stopped = 'stopped',
259+
}
260+
```
261+
262+
#### RecorderState
263+
264+
```ts
265+
enum RecorderState {
266+
recording = 'recording',
267+
paused = 'paused',
268+
stopped = 'stopped',
269+
}
270+
```
271+
272+
#### UpdateFrequency
273+
274+
```ts
275+
// Update frequency in milliseconds
276+
enum UpdateFrequency {
277+
high = 250.0,
278+
medium = 500.0,
279+
low = 1000.0,
280+
}
281+
```
282+
283+
#### PermissionStatus
284+
285+
```ts
286+
enum PermissionStatus {
287+
denied = 'denied',
288+
undetermined = 'undetermined',
289+
granted = 'granted',
290+
}
291+
```
16292

17293
---
294+
295+
## Example
296+
297+
you check out the example app for react-native-audio-waveform in [Example](./example/src/App.tsx)
298+
299+
To use example app you need to first run below
300+
301+
```bash
302+
cd example && npx react-native-asset
303+
```
304+
305+
This command will our example audio sample files to iOS bundle so that we can access them inside iOS app.
306+
307+
```sh
308+
yarn
309+
yarn example ios // For ios
310+
yarn example android // For Android
311+
```
312+
313+
## Find this library useful? ❤️
314+
315+
Support it by joining [stargazers](https://github.com/SimformSolutionsPvtLtd/react-native-audio-waveform/stargazers) for this repository.⭐
316+
317+
## Bugs / Feature requests / Feedbacks
318+
319+
For bugs, feature requests, and discussion please use [GitHub Issues](https://github.com/SimformSolutionsPvtLtd/react-native-audio-waveform/issues/new?labels=bug&late=BUG_REPORT.md&title=%5BBUG%5D%3A), [GitHub New Feature](https://github.com/SimformSolutionsPvtLtd/react-native-audio-waveform/issues/new?labels=enhancement&late=FEATURE_REQUEST.md&title=%5BFEATURE%5D%3A), [GitHub Feedback](https://github.com/SimformSolutionsPvtLtd/react-native-audio-waveform/issues/new?labels=enhancement&late=FEATURE_REQUEST.md&title=%5BFEEDBACK%5D%3A)
320+
321+
## 🤝 How to Contribute
322+
323+
We'd love to have you improve this library or fix a problem 💪
324+
Check out our [Contributing Guide](CONTRIBUTING.md) for ideas on contributing.
325+
326+
## Awesome Mobile Libraries
327+
328+
- Check out our other [available awesome mobile libraries](https://github.com/SimformSolutionsPvtLtd/Awesome-Mobile-Libraries)
329+
330+
## License
331+
332+
- [MIT License](./LICENSE)

‎assets/audio_waveform.gif‎

1.34 MB
Loading

‎example/android/app/src/main/assets/custom/index.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
export default {
2+
mp3_1mg: './file_example_mp3_1mg.mp3',
3+
mp3_12s: './file_example_mp3_12s.mp3',
4+
mp3_15s: './file_example_mp3_15s.mp3',
5+
mp3_700kb: './file_example_mp3_700kb.mp3',
6+
};

‎example/android/app/src/main/res/raw/file_example_mp3_12s.mp3‎

201 KB
Binary file not shown.

‎example/android/app/src/main/res/raw/file_example_mp3_15s.mp3‎

300 KB
Binary file not shown.

‎example/android/link-assets-manifest.json‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,24 @@
22
"migIndex": 1,
33
"data": [
44
{
5-
"path": "src/assets/audio/file_example_MP3_1MG.mp3",
5+
"path": "src/assets/audio/file_example_mp3_12s.mp3",
6+
"sha1": "27c1fa5ab09a20ef4390a207e660320015922938"
7+
},
8+
{
9+
"path": "src/assets/audio/file_example_mp3_15s.mp3",
10+
"sha1": "7bd4d150fed7b6f6163d8b62afa87cd7ae810620"
11+
},
12+
{
13+
"path": "src/assets/audio/file_example_mp3_1mg.mp3",
614
"sha1": "e493d393c751d2bfa8807af52d306552b73ecae4"
715
},
816
{
9-
"path": "src/assets/audio/file_example_MP3_700KB.mp3",
17+
"path": "src/assets/audio/file_example_mp3_700kb.mp3",
1018
"sha1": "dcaa8815859ce4c1c02c5f3b8bf01c79d0053c1f"
19+
},
20+
{
21+
"path": "src/assets/audio/index.ts",
22+
"sha1": "b14b69084488672939485938fe5556e76d291b3b"
1123
}
1224
]
1325
}

0 commit comments

Comments
 (0)