Skip to content

Commit 12379bf

Browse files
apurva010Sahil-Simform
apurva010
authored and
Sahil-Simform
committed
doc: separate out readme content
1 parent 87eb656 commit 12379bf

File tree

6 files changed

+255
-0
lines changed

6 files changed

+255
-0
lines changed

‎doc/advance_usage.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
**Advance usage**
2+
```dart
3+
controller.updateFrequency = const Duration(milliseconds: 100); // Update speed of new wave
4+
controller.androidEncoder = AndroidEncoder.aac; // Changing android encoder
5+
controller.androidOutputFormat = AndroidOutputFormat.mpeg4; // Changing android output format
6+
controller.iosEncoder = IosEncoder.kAudioFormatMPEG4AAC; // Changing ios encoder
7+
controller.sampleRate = 44100; // Updating sample rate
8+
controller.bitRate = null; // Updating bitrate
9+
controller.onRecorderStateChanged.listen((state){}); // Listening to recorder state changes
10+
controller.onCurrentDuration.listen((duration){}); // Listening to current duration updates
11+
controller.onRecordingEnded.listen((duration)); // Listening to audio file duration
12+
controller.recordedDuration; // Get recorded audio duration
13+
controller.elapsedDuration; // Get currently recorded audio duration
14+
controller.currentScrolledDuration; // Current duration position notifier
15+
controller.overrideAudioSession = true // Use default AudioSession config or not
16+
```
17+
18+
## Player
19+
20+
### Usage
21+
```dart
22+
PlayerController controller = PlayerController(); // Initialise
23+
// Extract waveform data
24+
final waveformData = await controller.extractWaveformData(
25+
path: 'path',
26+
noOfSamples: 100,
27+
);
28+
// Or directly extract from preparePlayer and initialise audio player
29+
await controller.preparePlayer(
30+
path: 'path',
31+
shouldExtractWaveform: true,
32+
noOfSamples: 100,
33+
volume: 1.0,
34+
);
35+
await controller.startPlayer(finishMode: FinishMode.stop); // Start audio player
36+
await controller.pausePlayer(); // Pause audio player
37+
await controller.stopPlayer(); // Stop audio player
38+
await controller.setVolume(1.0); // Set volume level
39+
await controller.seekTo(5000); // Seek audio
40+
await controller.setRate(1.0); // Update speed audio playback
41+
final duration = await controller.getDuration(DurationType.max); // Get duration of audio player
42+
controller.updateFrequency = UpdateFrequency.low; // Update reporting rate of current duration.
43+
controller.onPlayerStateChanged.listen((state) {}); // Listening to player state changes
44+
controller.onCurrentDurationChanged.listen((duration) {}); // Listening to current duration changes
45+
controller.onCurrentExtractedWaveformData.listen((data) {}); // Listening to latest extraction data
46+
controller.onExtractionProgress.listen((progress) {}); // Listening to extraction progress
47+
controller.onCompletion.listen((_){}); // Listening to audio completion
48+
controller.stopAllPlayer(); // Stop all registered audio players
49+
controller.dispose(); // Dispose controller
50+
```
51+
52+
**Use `AudioFileWaveforms` widget in widget tree**
53+
```dart
54+
AudioFileWaveforms(
55+
size: Size(MediaQuery.of(context).size.width, 100.0),
56+
playerController: controller,
57+
enableSeekGesture: true,
58+
waveformType: WaveformType.long,
59+
waveformData: [],
60+
playerWaveStyle: const PlayerWaveStyle(
61+
fixedWaveColor: Colors.white54,
62+
liveWaveColor: Colors.blueAccent,
63+
spacing: 6,
64+
...
65+
),
66+
...
67+
);
68+
```

‎doc/basic_usage.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
## Basic usage
2+
1. Recording audio
3+
```dart
4+
RecorderController controller = RecorderController(); // Initialise
5+
await controller.record(path: 'path'); // Record (path is optional)
6+
final hasPermission = await controller.checkPermission(); // Check mic permission (also called during record)
7+
await controller.pause(); // Pause recording
8+
final path = await controller.stop(); // Stop recording and get the path
9+
controller.refresh(); // Refresh waveform to original position
10+
controller.dispose(); // Dispose controller
11+
```
12+
13+
2. Use `AudioWaveforms` widget in widget tree
14+
```dart
15+
AudioWaveforms(
16+
size: Size(MediaQuery.of(context).size.width, 200.0),
17+
recorderController: controller,
18+
enableGesture: true,
19+
waveStyle: WaveStyle(
20+
...
21+
color: Colors.white,
22+
showDurationLabel: true,
23+
spacing: 8.0,
24+
showBottom: false,
25+
extendWaveform: true,
26+
showMiddleLine: false,
27+
gradient: ui.Gradient.linear(
28+
const Offset(70, 50),
29+
Offset(MediaQuery.of(context).size.width / 2, 0),
30+
[Colors.red, Colors.green],
31+
),
32+
...
33+
),
34+
),
35+
```

‎doc/contributor.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
## Main Contributors
2+
3+
| ![img](https://avatars.githubusercontent.com/u/56400956?s=300) | ![img](https://avatars.githubusercontent.com/u/26064415?s=300) |
4+
|:--------------------------------------------------------------:|:--------------------------------------------------------------:|
5+
| [Ujas Majithiya](https://github.com/Ujas-Majithiya) | [Devarsh Ranpara](https://github.com/DevarshRanpara) |

‎doc/installation.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
## Installing
2+
3+
1. Add dependencies to `pubspec.yaml`
4+
5+
Get the latest version in the 'Installing' tab
6+
on [pub.dev](https://pub.dev/packages/audio_waveforms/install)
7+
8+
```yaml
9+
dependencies:
10+
audio_waveforms: <latest-version>
11+
```
12+
13+
2. Run pub get.
14+
15+
```shell
16+
flutter pub get
17+
```
18+
19+
3. Import package.
20+
21+
```dart
22+
import 'package:audio_waveforms/audio_waveforms.dart';
23+
```
24+
25+
## Recorder
26+
27+
### Platform specific configuration
28+
29+
30+
**Android**
31+
32+
Change the minimum Android sdk version to 21 (or higher) in your `android/app/build.gradle` file.
33+
```
34+
minSdkVersion 21
35+
```
36+
37+
Add RECORD_AUDIO permission in `AndroidManifest.xml`
38+
```
39+
<uses-permission android:name="android.permission.RECORD_AUDIO" />
40+
```
41+
42+
43+
**IOS**
44+
45+
Add this two rows in `ios/Runner/Info.plist`
46+
```
47+
<key>NSMicrophoneUsageDescription</key>
48+
<string>This app requires Mic permission.</string>
49+
```
50+
This plugin requires ios 10.0 or higher. So add this line in `Podfile`
51+
```
52+
platform :ios, '12.0'
53+
```

‎doc/migration_guide.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
## Migration guide for release 0.1.5+1 to 1.0.0
2+
3+
From 1.0.0, waveform extraction has been reworked.
4+
5+
## New extraction function
6+
7+
```dart
8+
extractWaveformData(path: 'path', noOfSamples: 100);
9+
```
10+
11+
## How to use?
12+
13+
First, extract waveform sample data using the above function which will return waveform data. Or you
14+
can directly use `preparPlayer` function and it will by default extract the waveform data. This can
15+
be disabled by setting `shouldExtractWaveform` to false. You can access waveform data
16+
using `waveformData` parameter from PlayerController or use `onCurrentExtractedWaveformData`
17+
stream to get the latest waveform data.
18+
19+
To extract the data first set the audio file path to `path` parameter and `noOfSamples` parameter will
20+
determine no of waveform data in the returned list. So effectively it will determine no of waveform
21+
bars.
22+
23+
Now, if you want the shorter waveforms which will fit inside the given width then you can calculate
24+
no of samples by using `getSamplesForWidth` function from `PlayerWaveStyle`. This function requires
25+
width and it will calculate no of samples based width and spacing (which was set during
26+
the initialization PlayerWaveStyle instance).
27+
28+
Now set this value like this,
29+
```dart
30+
final samples = getSamplesForWidth(200);
31+
extractWaveformData(path: 'path', noOfSamples: samples);
32+
```
33+
If you need longer waveform then you can pass any no of sample directly.
34+
35+
If `preparePlayer` was used with `shouldExtractWaveform` enabled then `AudioFileWaveform` widget will
36+
directly receive the waveform data other wise you have to pass it manually.
37+
38+
Now let's create the widget,
39+
```dart
40+
AudioFileWaveforms(
41+
size: Size(200, 100),
42+
controller: controller,
43+
waveformType: WaveformType.fitWidth,
44+
continuousWaveform: true,
45+
);
46+
```
47+
Now, there are two types of waveforms for this,
48+
1. fitWidth
49+
2. long
50+
51+
* fitWidth -: These waveforms are preferable for limited with as above we used. With these waveforms,
52+
we can seek through them with continuous drag gestures or tap gestures.
53+
54+
* long -: These waveforms are preferable where waveform bars exceed the screen and need to be
55+
scrolled to reach the end. With this waveform, we can seek through only by dragging them.
56+
57+
Extracting the waveform data is a resource heavy task so it may take some time to extract. Now based on
58+
that, you can directly show the waveforms as soon as newer values get extracted by setting
59+
`continousWaveform` to true. If it's set to false then it will wait for the whole extraction process to
60+
complete.
61+
62+
As extraction process is resource heavy, we can directly provide waveformData to `AudioFileWaveforms`
63+
widget and it will ignore the `continuousWaveform` flag and directly show the waveforms without any waiting.
64+
So the process will be as below,
65+
```dart
66+
final waveformData = await extractWaveformData(path: 'path', noOfSamples: samples);
67+
...
68+
AudioFileWaveforms(
69+
waveformData: waveformData,
70+
);
71+
```
72+
73+
Now one last thing, as these waveformData have very small values, We can scale using scaleFactor.
74+
And to provide some scale feedback while scrolling we can use scrollScale to scale waves while scrolling
75+
and they will be scaled down to the original scale when scrolling ends.
76+
```dart
77+
PlayerWaveStyle(
78+
scaleFactor: 100,
79+
scrollScale: 1.2,
80+
);
81+
```
82+
83+
To see the list of all parameters and detailed description of parameters visit [documentation](https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/audio_waveforms-library.html).

‎doc/overview.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
![Audio Waveforms - Simform LLC.](https://raw.githubusercontent.com/SimformSolutionsPvtLtd/audio_waveforms/main/preview/banner.png)
2+
3+
# Audio Waveforms
4+
5+
Use this plugin to generate waveforms while recording audio in any file formats supported
6+
by given encoders or from audio files. We can use gestures to scroll through the waveforms or seek to
7+
any position while playing audio and also style waveforms.
8+
9+
## Preview
10+
11+
![preview](https://raw.githubusercontent.com/SimformSolutionsPvtLtd/audio_waveforms/main/preview/demo.gif)

0 commit comments

Comments
 (0)