Audio Waveforms

https://pub.dev/documentation/audio_waveforms/latest/
Admin
A Flutter package for generating waveforms during audio recording or playback with gesture controls,...
Tokens:42,459
Snippets:532
Trust Score:9.9
Update:4 months ago
Show doc for...
Tokens:
Raw
### record()

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController-class.html

Calls the platform to start recording. Optionally specify a path and recorder settings.

```APIDOC
## record()

### Description
Calls the platform to start recording. Optionally specify a path and recorder settings.

### Method
Future<void>

### Parameters
#### Query Parameters
- **path** (String?) - Optional - The path to save the recording.
- **recorderSettings** (RecorderSettings) - Optional - Settings for the recorder. Defaults to `const RecorderSettings()`.
```

--------------------------------

### startPlayer method

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface/startPlayer.html

Starts the audio player with the specified key. This method is a platform call to initiate playback.

```APIDOC
## startPlayer

### Description
Initiates audio playback by calling the platform-specific player with a given key. Returns a boolean indicating success.

### Method Signature
`Future<bool> startPlayer(String key)`

### Parameters
#### Path Parameters
- **key** (String) - Required - The unique identifier for the audio to be played.

### Request Example
```dart
// Example usage within a Dart application
await audioWaveformsInterface.startPlayer("myAudioKey");
```

### Response
#### Success Response
- **bool** - Returns `true` if the player started successfully, `false` otherwise.
```

--------------------------------

### Record Audio

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface/record.html

Starts audio recording with specified settings. Handles platform-specific configurations for iOS. Returns a future boolean indicating if recording started successfully.

```dart
Future<bool> record({
  required RecorderSettings recorderSetting,
  String? path,
  bool overrideAudioSession = true,
}) async {
  final isRecording = await _methodChannel.invokeMethod(
    Constants.startRecording,
    Platform.isIOS
        ? recorderSetting.iosToJson(
            path: path,
            overrideAudioSession: overrideAudioSession,
          )
        : null,
  );
  return isRecording ?? false;
}
```

--------------------------------

### startPlayer method

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController/startPlayer.html

Starts the player to play or resume audio. By default, the player is stopped and disposed when playback finishes. This behavior can be altered using the setFinishMode method.

```APIDOC
## startPlayer

### Description
Starts the player to play or resume audio. By default, the player is stopped and disposed when playback finishes. This behavior can be altered using the setFinishMode method.

### Method Signature
`Future<void> startPlayer({ bool forceRefresh = true })`

### Parameters
#### Optional Parameters
- **forceRefresh** (bool) - Optional - Defaults to `true`. If true, forces a refresh of the player state.

### Returns
- `Future<void>`: A future that completes when the player has started or an error has occurred.
```

--------------------------------

### startPlayer Method Implementation

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController/startPlayer.html

This snippet shows the implementation of the startPlayer method. It checks the current player state before attempting to start playback and updates the player state accordingly. It also handles the forceRefresh parameter and notifies listeners of changes.

```dart
Future<void> startPlayer({
  bool forceRefresh = true,
}) async {
  if (_playerState == PlayerState.initialized ||
      _playerState == PlayerState.paused) {
    final isStarted =
        await AudioWaveformsInterface.instance.startPlayer(playerKey);
    if (isStarted) {
      _setPlayerState(PlayerState.playing);
    } else {
      throw "Failed to start player";
    }
  }
  _setRefresh(forceRefresh);
  notifyListeners();
}
```

--------------------------------

### startPlayer Method Implementation

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface/startPlayer.html

This Dart code shows the implementation of the startPlayer method. It uses a method channel to invoke the native start player functionality with the provided key. Ensure the Constants class is properly defined and accessible.

```dart
Future<bool> startPlayer(String key) async {
  var result = await _methodChannel.invokeMethod(Constants.startPlayer, {
    Constants.playerKey: key,
  });
  return result ?? false;
}
```

--------------------------------

### onAudioChunks Implementation

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController/onAudioChunks.html

This snippet shows how the onAudioChunks stream is implemented by accessing the onRecordedBytes stream from the _platformStream. No setup is required beyond having an instance of RecorderController.

```dart
Stream<Uint8List> get onAudioChunks => _platformStream.onRecordedBytes;
```

--------------------------------

### record

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController/record.html

Starts or resumes audio recording. It checks for microphone permission and handles different recorder states. The path parameter is optional; if not provided, a default file name and extension (.m4a) will be used.

```APIDOC
## record

### Description
Starts or resumes audio recording. It checks for microphone permission and handles different recorder states. The path parameter is optional; if not provided, a default file name and extension (.m4a) will be used.

### Method
Future<void>

### Parameters
#### Path Parameters
- **path** (String?) - Optional - The path to save the recording. If not provided, a default path with the current datetime and '.m4a' extension will be used.
- **recorderSettings** (RecorderSettings) - Optional - Settings for the recorder, defaults to `const RecorderSettings()`.

### Behavior Notes
- If the recorder is paused, calling `record` will resume recording from where it left off.
- If the recorder is stopped, calling `record` will re-initialize the recorder and start a new recording.
- Microphone permission is checked before recording. If permission is not granted, the function completes with the recorder state set to `stopped`.
```

--------------------------------

### PlayerController Properties

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController-class.html

Exposes various properties to get information about the player's state, duration, and configuration.

```APIDOC
## Properties

### hashCode → int

The hash code for this object.

### hasListeners → bool

Whether any listeners are currently registered.

### maxDuration → int

Provides max duration of currently provided audio file.

### onCompletion → Stream<void>

A stream to get events when audio is finished playing.

### onCurrentDurationChanged → Stream<int>

A stream to get current duration. This stream will emit every 200 milliseconds. Emitted duration is in milliseconds.

### onPlayerStateChanged → Stream<PlayerState>

A stream to get current state of the player. This stream will emit event whenever there is change in the playerState.

### overrideAudioSession ↔ bool

IOS only.

### playerKey → String

An unique key string associated with `this` player only.

### playerState → PlayerState

Provides current state of the player.

### runtimeType → Type

A representation of the runtime type of the object.

### shouldClearLabels → bool

### shouldRefresh → bool

### updateFrequency ↔ UpdateFrequency

Rate of updating the reported current duration. Making it high will cause reporting duration at faster rate which also causes UI to look smoother.

### waveformExtraction → WaveformExtractionController

An WaveformExtractionController instance which is bound with PlayerController using playerKey and `WaveformExtractionController._extractorKey`.
```

--------------------------------

### Record Method Implementation

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController/record.html

This snippet shows the implementation of the record method. It handles microphone permission checks, platform-specific initialization for Android, resuming paused recordings, and starting new recordings on iOS and Android. It updates the recorder state and notifies listeners upon completion or failure.

```dart
Future<void> record({
  String? path,
  RecorderSettings recorderSettings = const RecorderSettings(),
}) async {
  if (!_recorderState.isRecording) {
    await checkPermission();
    if (_hasPermission) {
      if (Platform.isAndroid && _recorderState.isStopped) {
        await _initRecorder(
          path: path,
          recorderSettings: recorderSettings,
        );
      }
      if (_recorderState.isPaused) {
        _isRecording = await AudioWaveformsInterface.instance.resume();
        if (_isRecording) {
          _setRecorderState(RecorderState.recording);
        } else {
          throw "Failed to resume recording";
        }
        notifyListeners();
        return;
      }
      if (Platform.isIOS) {
        _setRecorderState(RecorderState.initialized);
      }
      if (_recorderState.isInitialized) {
        _isRecording = await AudioWaveformsInterface.instance.record(
          recorderSetting: recorderSettings,
          path: path,
          overrideAudioSession: overrideAudioSession,
        );
        if (_isRecording) {
          _setRecorderState(RecorderState.recording);
        } else {
          throw "Failed to start recording";
        }
        notifyListeners();
      }
    } else {
      _setRecorderState(RecorderState.stopped);
      notifyListeners();
    }
  }
}
```

--------------------------------

### Flutter StatefulWidget createState Example

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioFileWaveforms/createState.html

Subclasses of StatefulWidget must override this method to return a new instance of their associated State subclass. This ensures a fresh State object is created for each widget instance or re-insertion into the tree.

```dart
@override
State<SomeWidget> createState() => _SomeWidgetState();

```

--------------------------------

### stop method

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController/stop.html

Stops the current recording. Resources are freed after calling this and the file is saved. It returns the path where the file is saved and also clears the waveform and resets to the initial state. To change this behavior, pass false to the stop function's parameter, which will effectively not call reset to clear waves. When `callReset` is set to false, it will require calling reset manually; otherwise, it will start showing waveforms from the same place where it left off for the previous recording.

```APIDOC
## stop

### Description
Stops the current recording, frees resources, saves the file, and returns its path. Optionally resets the waveform and recorder state.

### Method Signature
`Future<String?> stop([bool callReset = true])`

### Parameters
#### Path Parameters
* `callReset` (bool) - Optional - If true (default), the recorder and waveform will be reset after stopping. If false, the reset must be called manually.

### Returns
* `Future<String?>` - A future that completes with the path to the saved audio file, or null if not recording.

### Implementation Notes
The method checks if the recorder is currently in a recording or paused state before proceeding. It interacts with `AudioWaveformsInterface.instance.stop()` to get audio information, including the file path and duration. The `recordedDuration` and `elapsedDuration` are updated, and the recorder state is set to `stopped`. The `reset()` method is called conditionally based on the `callReset` parameter.
```

--------------------------------

### preparePlayer Method

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface/preparePlayer.html

Prepares the audio player with the given path, key, frequency, and optional volume and override settings. This is a platform call to initialize the player.

```APIDOC
## preparePlayer

### Description
Prepares the audio player with the given path, key, frequency, and optional volume and override settings. This is a platform call to initialize the player.

### Method Signature
`Future<bool> preparePlayer({ required String path, required String key, required int frequency, double? volume, bool overrideAudioSession = false, })`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **path** (String) - Required - The path to the audio file.
- **key** (String) - Required - A unique key for the player instance.
- **frequency** (int) - Required - The update frequency for audio waveform data.
- **volume** (double?) - Optional - The volume level for the player (0.0 to 1.0).
- **overrideAudioSession** (bool) - Optional - Whether to override the audio session settings. Defaults to `false`.

### Request Example
```dart
// Example usage within Dart
await audioWaveformsPlugin.preparePlayer(
  path: "/path/to/audio.mp3",
  key: "player1",
  frequency: 60,
  volume: 0.8,
  overrideAudioSession: true,
);
```

### Response
#### Success Response
- Returns `true` if the player was prepared successfully, `false` otherwise.

#### Response Example
```json
// Dart Future<bool> result
// true or false
```
```

--------------------------------

### Get maxDuration

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController/maxDuration.html

Retrieves the maximum duration of the audio file. This is a getter method.

```dart
int get maxDuration => _maxDuration;
```

--------------------------------

### preparePlayer Method Implementation

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController/preparePlayer.html

This snippet shows the full implementation of the `preparePlayer` method. It includes parameter validation, path handling, player preparation, and waveform data extraction logic. Use this method to set up the audio player and generate waveform data for visualization.

```dart
Future<void> preparePlayer({
  required String path,
  double? volume,
  bool shouldExtractWaveform = true,
  int? noOfSamples,
  int? noOfSamplesPerSecond,
}) async {
  // Validate that user doesn't provide both parameters
  assert(
    !(noOfSamples != null && noOfSamplesPerSecond != null),
    'Cannot provide both noOfSamples and noOfSamplesPerSecond. '
    'Use noOfSamples for fixed count OR noOfSamplesPerSecond for dynamic calculation based on duration.',
  );

  if (!path.startsWith('http')) {
    // Keep the full URL for remote files and strip for local files
    final uri = Uri.tryParse(path);
    if (uri == null) {
      throw ArgumentError('Invalid path format: $path');
    }
    path = uri.path;
  }
  final isPrepared = await AudioWaveformsInterface.instance.preparePlayer(
    path: path,
    key: playerKey,
    frequency: updateFrequency.value,
    volume: volume,
    overrideAudioSession: overrideAudioSession,
  );
  if (isPrepared) {
    _maxDuration = await getDuration();
    _setPlayerState(PlayerState.initialized);
  }

  if (shouldExtractWaveform) {
    // Determine which sampling strategy to use
    final int actualNoOfSamples;
    if (noOfSamplesPerSecond != null) {
      // Use dynamic calculation based on duration
      if (_maxDuration > 0) {
        actualNoOfSamples = 
            (noOfSamplesPerSecond * (_maxDuration / 1000)).round();
      } else {
        actualNoOfSamples = 
            noOfSamplesPerSecond; // Fallback if duration unavailable
      }
    } else {
      // Use fixed sample count (default to 100 if not provided)
      actualNoOfSamples = noOfSamples ?? 100;
    }

    waveformExtraction
        .extractWaveformData(
      path: path,
      noOfSamples: actualNoOfSamples,
    )
        .then(
      (value) {
        waveformExtraction.waveformData
          ..clear()
          ..addAll(value);
        notifyListeners();
      },
    );
  }
  notifyListeners();
}
```

--------------------------------

### Get PlayerState

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController/playerState.html

This getter returns the current state of the player. It is part of the PlayerController implementation.

```dart
PlayerState get playerState => _playerState;
```

--------------------------------

### preparePlayer Method

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController/preparePlayer.html

Prepares the audio player with the specified audio file and configuration. It handles player initialization and optional waveform data extraction.

```APIDOC
## preparePlayer Method

### Description
Prepares the audio player with the specified audio file and configuration. It handles player initialization and optional waveform data extraction.

### Method Signature
`Future<void> preparePlayer({ required String path, double? volume, bool shouldExtractWaveform = true, int? noOfSamples, int? noOfSamplesPerSecond })`

### Parameters
#### Path Parameters
- **path** (String) - Required - The location of the audio file.

#### Optional Parameters
- **volume** (double?) - Optional - The volume of the player. Minimum value 0.0 (mute), maximum value 1.0 (max volume). Values greater than 1.0 are treated as 1.0.
- **shouldExtractWaveform** (bool) - Optional - If true (default), waveforms will be extracted. Set to false to prevent extraction.
- **noOfSamples** (int?) - Optional - The desired number of data points for the waveform. Determines the number of bars in the waveform. If both `noOfSamples` and `noOfSamplesPerSecond` are null, this defaults to 100.
- **noOfSamplesPerSecond** (int?) - Optional - An alternative to `noOfSamples`. Specifies the number of samples per second of audio. The actual `noOfSamples` will be calculated as: `noOfSamplesPerSecond * durationInSeconds`. Use either `noOfSamples` or `noOfSamplesPerSecond`, not both.

### Important Notes
- Provide only ONE of `noOfSamples` OR `noOfSamplesPerSecond`.
- If both `noOfSamples` and `noOfSamplesPerSecond` are null, `noOfSamples` defaults to 100.
- Waveform data can be accessed via the `waveformData` getter after extraction.
- The `extractWaveformData` function can be used separately to store waveform data locally or on a server for later use with the `AudioFileWaveforms` widget.
```

--------------------------------

### Get Recorded Duration

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController/recordedDuration.html

Accesses the recorded duration. Returns Duration.zero if recording is in progress or has been reset.

```dart
Duration get recordedDuration => _recordedDuration;
```

--------------------------------

### Get recorderState Property

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController/recorderState.html

Provides the current state of the recorder. This is a getter that returns the private _recorderState.

```dart
RecorderState get recorderState => _recorderState;
```

--------------------------------

### preparePlayer Method Implementation

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface/preparePlayer.html

This is the implementation of the preparePlayer method. It takes path, key, frequency, volume, and overrideAudioSession as parameters and invokes a platform method channel to prepare the audio player. Returns a boolean indicating success or failure.

```dart
Future<bool> preparePlayer({
  required String path,
  required String key,
  required int frequency,
  double? volume,
  bool overrideAudioSession = false,
}) async {
  var result = await _methodChannel.invokeMethod(Constants.preparePlayer, {
    Constants.path: path,
    Constants.volume: volume,
    Constants.playerKey: key,
    Constants.updateFrequency: frequency,
    Constants.overrideAudioSession: overrideAudioSession,
  });
  return result ?? false;
}
```

--------------------------------

### Get Waveform Data

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/WaveformExtractionController/waveformData.html

Retrieves the waveform data as a list of doubles. This data is used by AudioFileWaveforms for display.

```dart
List<double> get waveformData => _waveformData.toList();
```

--------------------------------

### record method

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface/record.html

Initiates an audio recording with specified settings. It allows for an optional file path and controls audio session behavior.

```APIDOC
## record method

### Description
Starts an audio recording using the provided recorder settings. You can specify an output path for the recording and control whether to override the current audio session.

### Method Signature
`Future<bool> record({required RecorderSettings recorderSetting, String? path, bool overrideAudioSession = true})`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
*   **recorderSetting** (RecorderSettings) - Required - Configuration settings for the recorder.
*   **path** (String?) - Optional - The file path where the recording should be saved. If null, a default path may be used.
*   **overrideAudioSession** (bool) - Optional - Defaults to `true`. If true, the current audio session will be overridden for this recording.

### Request Example
```dart
// Example usage:
final recorderSettings = RecorderSettings(...); // Initialize with your settings
final success = await audioWaveformsInterface.record(recorderSetting: recorderSettings, path: "/path/to/save/recording.wav");
if (success) {
  print("Recording started successfully.");
} else {
  print("Failed to start recording.");
}
```

### Response
#### Success Response
*   **bool** - Returns `true` if the recording was started successfully, `false` otherwise.

#### Response Example
```json
// Dart Future<bool> result
// true or false
```
```

--------------------------------

### Get waveData Property

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController/waveData.html

This snippet shows how to access the `waveData` property, which returns the current list of scaled waves.

```dart
List<double> get waveData => _waveData;
```

--------------------------------

### AudioWaveforms Constructor

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveforms-class.html

Initializes a new instance of the AudioWaveforms widget. It requires a size, a recorder controller, and optionally accepts wave style, gesture enablement, padding, margin, decoration, background color, and a flag for calculating scrolled position.

```APIDOC
## Constructors

AudioWaveforms({Key? key, required Size size, required RecorderController recorderController, WaveStyle waveStyle = const WaveStyle(), bool enableGesture = false, EdgeInsets? padding, EdgeInsets? margin, BoxDecoration? decoration, Color? backgroundColor, bool shouldCalculateScrolledPosition = false})
```

--------------------------------

### getPlayerState

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface-class.html

Gets the current playback state of a player. This method takes a finish model parameter to determine the state.

```APIDOC
## getPlayerState

### Description
Gets the current playback state of a player.

### Method
PlayerState

### Endpoint
getPlayerState(int finishModel)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **finishModel** (int) - Required - Model representing the finish state.

### Response
#### Success Response
- **PlayerState**: The current state of the player.

### Response Example
```json
{
  "player_state": "playing"
}
```
```

--------------------------------

### AudioFileWaveforms Constructor

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioFileWaveforms/AudioFileWaveforms.html

Constructs an AudioFileWaveforms widget to display audio waveforms. It requires a size and a PlayerController, and offers various customization options for appearance and interaction, including waveform data, styling, padding, margins, and gesture handling for seeking.

```APIDOC
## AudioFileWaveforms constructor

### Description
Generates waveforms from audio files using a provided PlayerController. The waves dynamically change color based on playback progress. Enables seeking to any audio position via gestures when `enableSeekGesture` is true.

### Parameters
#### Constructor Parameters
- **key** (Key?) - Optional - Used for widget identification.
- **size** (Size) - Required - The dimensions of the waveform widget.
- **playerController** (PlayerController) - Required - Controller to manage audio playback.
- **waveformData** (List<double>) - Optional - Predefined data for the waveform. Defaults to an empty list.
- **continuousWaveform** (bool) - Optional - Whether the waveform should be continuous. Defaults to true.
- **playerWaveStyle** (PlayerWaveStyle) - Optional - Styling options for the waveform. Defaults to `PlayerWaveStyle()`.
- **padding** (EdgeInsets?) - Optional - Padding around the waveform.
- **margin** (EdgeInsets?) - Optional - Margin around the waveform.
- **decoration** (BoxDecoration?) - Optional - BoxDecoration for the waveform container.
- **backgroundColor** (Color?) - Optional - Background color of the waveform area.
- **animationDuration** (Duration) - Optional - Duration for animations. Defaults to 500 milliseconds.
- **animationCurve** (Curve) - Optional - Curve for animations. Defaults to `Curves.easeIn`.
- **clipBehavior** (Clip) - Optional - How the waveform should be clipped. Defaults to `Clip.none`.
- **waveformType** (WaveformType) - Optional - Type of waveform to display. Defaults to `WaveformType.long`.
- **enableSeekGesture** (bool) - Optional - Enables seeking audio playback via gestures. Defaults to true.
- **onDragStart** (ValueSetter<DragStartDetails>?) - Optional - Callback when a seek drag starts.
- **onDragEnd** (ValueSetter<DragEndDetails>?) - Optional - Callback when a seek drag ends.
- **dragUpdateDetails** (ValueSetter<DragUpdateDetails>?) - Optional - Callback during seek drag updates.
- **onTapUp** (ValueSetter<TapUpDetails>?) - Optional - Callback when the waveform is tapped up.
- **seekOnTapUp** (bool) - Optional - Whether tapping up should seek the audio. Defaults to true.
- **onTapDown** (GestureTapDownCallback?) - Optional - Callback when the waveform is tapped down.
```

--------------------------------

### Check if WaveformRenderMode is RTL

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/WaveformRenderMode/isRtl.html

Use this getter to determine if the waveform rendering mode is set to right-to-left. No setup is required.

```dart
bool get isRtl => this == WaveformRenderMode.rtl;
```

--------------------------------

### elapsedDuration Property

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController/elapsedDuration.html

Provides the currently recorded audio duration. Use the onCurrentDuration stream to get the latest duration events.

```APIDOC
## elapsedDuration Property

### Description
Provides currently recorded audio duration. Use onCurrentDuration stream to get latest events duration.

### Property
`Duration get elapsedDuration`

### Implementation
```dart
Duration get elapsedDuration => _elapsedDuration;
```
```

--------------------------------

### PlayerController Methods

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController-class.html

Provides methods to control audio playback, manage player state, and interact with audio sessions.

```APIDOC
## Methods

### addListener(VoidCallback listener) → void

Register a closure to be called when the object changes.

### dispose() → void

Release any resources taken by this controller. Disposing this will stop the player and release resources from native.

### getDuration([DurationType? durationType]) → Future<int>

Returns maximum duration for DurationType.max and current duration for DurationType.current for playing media. The duration is in milliseconds, if no duration is available -1 is returned.

### noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

### notifyListeners() → void

Call all the registered listeners.

### pauseAllPlayers() → Future<bool>

Pauses all the players. Works similar to stopAllPlayer.

### pausePlayer() → Future<void>

Pauses currently playing audio.

### preparePlayer({required String path, double? volume, bool shouldExtractWaveform = true, int? noOfSamples, int? noOfSamplesPerSecond}) → Future<void>

Calls platform to prepare player.

### release() → Future<void>

Releases the resources associated with this player.

### removeListener(VoidCallback listener) → void

Remove a previously registered closure from the list of closures that are notified when the object changes.

### seekTo(int progress) → Future<void>

Moves the media to specified time(milliseconds) position.

### setFinishMode({FinishMode finishMode = FinishMode.stop}) → Future<void>

This method will be used to change behaviour of player when audio is finished playing.

### setRate(double rate) → Future<bool>

Sets playback rate for this player. Doesn't throw Exception. Returns false if it couldn't set the rate.

### setRefresh(bool refresh) → void

Sets `_shouldRefresh` flag with provided boolean parameter.

### setVolume(double volume) → Future<bool>

Sets volume for this player. Doesn't throw Exception. Returns false if it couldn't set the volume.

### startPlayer({bool forceRefresh = true}) → Future<void>

A function to start the player to play/resume the audio.

### stopAllPlayers() → Future<bool>

Frees `resources` used by all players simultaneously.

### stopPlayer() → Future<void>

A function to stop player.

### toString() → String

A string representation of this object.
```

--------------------------------

### Get isRecording Property

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController/isRecording.html

This snippet shows how to access the isRecording getter. It returns the current state of the internal _isRecording variable.

```dart
bool get isRecording => _isRecording;
```

--------------------------------

### WaveStyle Constructor

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/WaveStyle-class.html

Initializes a new instance of the WaveStyle class with customizable styling properties for audio waveforms.

```APIDOC
## WaveStyle()

### Description
A model class to provide style to the waveforms.

### Parameters
* **waveColor** (Color) - Optional - The color of the wave.
* **showMiddleLine** (bool) - Optional - Whether to show the middle line. Defaults to true.
* **spacing** (double) - Optional - Space between each wave. Defaults to 8.0.
* **showTop** (bool) - Optional - Whether to show the upper wave. Defaults to true.
* **showBottom** (bool) - Optional - Whether to show the bottom wave. Defaults to true.
* **bottomPadding** (double?) - Optional - Wave padding from the bottom.
* **waveCap** (StrokeCap) - Optional - The kind of finish to place on the end of lines drawn. Defaults to StrokeCap.round.
* **middleLineColor** (Color) - Optional - Color of the middle line. Defaults to Colors.redAccent.
* **middleLineThickness** (double) - Optional - Thickness of the middle line. Defaults to 3.0.
* **waveThickness** (double) - Optional - Width of each wave. Defaults to 3.0.
* **showDurationLabel** (bool) - Optional - Show duration labels. Defaults to false.
* **extendWaveform** (bool) - Optional - Extend the wave to the end of size.width. Defaults to false.
* **backgroundColor** (Color) - Optional - The background color of the waveform box. Defaults to Colors.black.
* **showHourInDuration** (bool) - Optional - Show duration label in HH:MM:SS format. Defaults to false.
* **durationLinesHeight** (double) - Optional - Height of duration lines. Defaults to 16.0.
* **durationStyle** (TextStyle) - Optional - Text style for duration labels.
* **extraClipperHeight** (double?) - Optional - Adjusts clipping for labels.
* **labelSpacing** (double) - Optional - Space between duration labels and waveform square. Defaults to 16.0.
* **durationTextPadding** (double) - Optional - Padding for duration text.
* **durationLinesColor** (Color) - Optional - Color of duration lines. Defaults to Colors.blueAccent.
* **gradient** (Shader?) - Optional - Applies a gradient to waveforms.
* **scaleFactor** (double) - Optional - Scales the normalized amplitude/power. Defaults to 20.0.
* **waveformRenderMode** (WaveformRenderMode) - Optional - Defines the rendering direction of the waveform. Defaults to WaveformRenderMode.ltr.
```

--------------------------------

### AVAudioSession Configuration

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController/overrideAudioSession.html

This snippet shows the default AVAudioSession category and options that can be overridden. Changes take effect after calling preparePlayer.

```swift
AVAudioSession.Category: .playback
AVAudioSession.CategoryOptions: [.default]

```

--------------------------------

### getDuration Method

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface/getDuration.html

Retrieves the duration of an audio waveform. This method makes a platform call to get the maximum or current duration.

```APIDOC
## getDuration

### Description
Retrieves the duration of an audio waveform. This method makes a platform call to get the maximum or current duration.

### Method Signature
`Future<int?> getDuration(String key, int durationType)`

### Parameters
#### Path Parameters
- **key** (String) - Required - The key identifying the audio waveform.
- **durationType** (int) - Required - The type of duration to retrieve (e.g., max or current).

### Implementation Notes
This method uses a platform channel to communicate with the native side to obtain the duration.
```

--------------------------------

### getDecibel Method

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface/getDecibel.html

Retrieves the decibel value from the audio waveforms. This method makes a platform call to get the decibel information.

```APIDOC
## getDecibel()

### Description
Retrieves the decibel value from the audio waveforms. This method makes a platform call to get the decibel information.

### Method Signature
`Future<double?> getDecibel()`

### Platform Call
This method invokes a platform-specific implementation to obtain the decibel value.
```

--------------------------------

### AudioWaveforms Constructor Implementation

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveforms/AudioWaveforms.html

Shows the implementation of the AudioWaveforms constructor, assigning the provided parameters to the widget's properties.

```dart
const AudioWaveforms({
  super.key,
  required this.size,
  required this.recorderController,
  this.waveStyle = const WaveStyle(),
  this.enableGesture = false,
  this.padding,
  this.margin,
  this.decoration,
  this.backgroundColor,
  this.shouldCalculateScrolledPosition = false,
});
```

--------------------------------

### AudioFileWaveforms Methods

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioFileWaveforms-class.html

This section details the methods available for the AudioFileWaveforms class, including those for widget creation, state management, and debugging.

```APIDOC
## Methods

### createElement()

Creates a StatefulElement to manage this widget's location in the tree.

### create_state()

Creates the mutable state for this widget at a given location in the tree.

### debugDescribeChildren()

Returns a list of DiagnosticsNode objects describing this node's children.

### debugFillProperties(DiagnosticPropertiesBuilder properties)

Add additional properties associated with the node.

### noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

### toDiagnosticsNode({String? name, DiagnosticTreeStyle? style})

Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.

### toString({DiagnosticLevel minLevel = DiagnosticLevel.info})

A string representation of this object.

### toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65})

Returns a string representation of this node and its descendants.

### toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug})

Returns a one-line detailed description of the object.

### toStringShort()

A short, textual description of this widget.
```

--------------------------------

### Get Elapsed Duration

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController/elapsedDuration.html

Retrieves the current recorded audio duration. This getter directly returns the value of the private _elapsedDuration variable.

```dart
Duration get elapsedDuration => _elapsedDuration;
```

--------------------------------

### Get Media Duration

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController/getDuration.html

Retrieves the playback duration of the media player. Returns the duration in milliseconds or -1 if unavailable. Defaults to DurationType.max.

```dart
Future<int> getDuration([DurationType? durationType]) async {
  final duration = await AudioWaveformsInterface.instance
      .getDuration(playerKey, durationType?.index ?? 1);
  return duration ?? -1;
}
```

--------------------------------

### PlayerController Constructors

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController-class.html

Initializes a new instance of the PlayerController class.

```APIDOC
## Constructors

### PlayerController()

Initializes a new instance of the PlayerController class.
```

--------------------------------

### RecorderSettings Constructor

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderSettings/RecorderSettings.html

Initializes RecorderSettings with optional encoder configurations, sample rate, and bit rate.

```APIDOC
## RecorderSettings Constructor

### Description
Initializes RecorderSettings with optional encoder configurations, sample rate, and bit rate.

### Parameters
#### Constructor Parameters
- **androidEncoderSettings** (AndroidEncoderSettings) - Optional - Specifies encoder settings for Android devices. Defaults to `const AndroidEncoderSettings()`.
- **iosEncoderSettings** (IosEncoderSetting) - Optional - Specifies encoder settings for iOS devices. Defaults to `const IosEncoderSetting()`.
- **sampleRate** (int) - Optional - Defines the sampling rate for audio recording. Defaults to 44100 Hz.
- **bitRate** (int) - Optional - Specifies the bit rate for encoding audio. Defaults to 128000.
```

--------------------------------

### Get currentScrolledDuration

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController/currentScrolledDuration.html

This snippet shows how to access the currentScrolledDuration ValueNotifier. Ensure 'shouldCalculateScrolledPosition' is enabled in the AudioWaveform widget for this property to be functional. The reported duration is in milliseconds.

```dart
ValueNotifier<int> get currentScrolledDuration => _currentScrolledDuration;
```

--------------------------------

### PlayerWaveStyle Constructor

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerWaveStyle-class.html

Initializes a new instance of the PlayerWaveStyle class with customizable properties for waveform appearance.

```APIDOC
## PlayerWaveStyle Constructor

### Description
Initializes a new instance of the PlayerWaveStyle class with customizable properties for waveform appearance.

### Parameters
- **fixedWaveColor** (Color) - Optional - Color of the `wave` which is behind the live wave. Defaults to `Colors.white54`.
- **liveWaveColor** (Color) - Optional - Color of the `live` wave which indicates currently played part. Defaults to `Colors.white`.
- **showTop** (bool) - Optional - Whether to show upper wave or not. Defaults to `true`.
- **showBottom** (bool) - Optional - Whether to show bottom wave or not. Defaults to `true`.
- **showSeekLine** (bool) - Optional - Shows seek line in the middle when enabled. Defaults to `true`.
- **waveCap** (StrokeCap) - Optional - The kind of finish to place on the end of lines drawn. Defaults to `StrokeCap.round`.
- **seekLineColor** (Color) - Optional - Color line in the middle. Defaults to `Colors.white`.
- **seekLineThickness** (double) - Optional - Thickness of seek line. For microphone recording this line is in the middle. Defaults to `2.0`.
- **waveThickness** (double) - Optional - Width of each wave. Defaults to `3.0`.
- **backgroundColor** (Color) - Optional - The background color of waveform box. Defaults to `Colors.black`.
- **fixedWaveGradient** (Shader?) - Optional - Provide gradient to waves which is behind the live wave. Use shader as shown in example.
- **scaleFactor** (double) - Optional - This is applied to each wave while generating. Use this to scale the waves. Defaults to `100.0`.
- **liveWaveGradient** (Shader?) - Optional - This gradient is applied to waves which indicates currently played part.
- **spacing** (double) - Optional - Space between two waves. Defaults to `5.0`.
- **scrollScale** (double) - Optional - Scales the wave when waveforms are seeked. The scaled waves returns back to original scale when gesture ends. To get result set value greater then 1. Defaults to `1.0`.
```

--------------------------------

### initRecorder Method Implementation

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface/initRecorder.html

This is the Dart implementation of the initRecorder method. It makes a platform call to initialize the recorder using the provided settings and returns a boolean indicating success. This method is only required for Android.

```dart
Future<bool> initRecorder({
  String? path,
  required RecorderSettings recorderSettings,
}) async {
  final initialized = await _methodChannel.invokeMethod(
    Constants.initRecorder,
    recorderSettings.androidToJson(path: path),
  );
  return initialized ?? false;
}
```

--------------------------------

### onRecordingEnded

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController/onRecordingEnded.html

A stream to get the duration of recording when the audio recorder has been stopped. Events are only emitted if the platform could extract the duration of the audio file when recording is ended.

```APIDOC
## onRecordingEnded

### Description
A stream that emits the duration of a recording once the audio recorder has been stopped. This stream will only emit events if the underlying platform is capable of determining the audio file's duration upon completion of the recording.

### Method
GET

### Endpoint
recorderController.onRecordingEnded

### Parameters
None

### Response
#### Success Response
- **onRecordingEnded** (Stream<Duration>) - A stream that emits Duration objects representing the length of the recorded audio.
```

--------------------------------

### initRecorder

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface/initRecorder.html

Initializes the audio recorder. This method is platform-specific to Android and requires recorder settings. It returns a Future<bool> indicating success or failure.

```APIDOC
## initRecorder

### Description
Initializes the audio recorder. This method is platform-specific to Android and requires recorder settings. It returns a Future<bool> indicating success or failure.

### Method Signature
Future<bool> initRecorder({ String? path, required RecorderSettings recorderSettings })

### Parameters
#### Path Parameters
* **path** (String?) - Optional - The path to store the audio recording.

#### Required Parameters
* **recorderSettings** (RecorderSettings) - Required - Settings for the recorder, including platform-specific configurations.

### Platform
Android only.

### Implementation Notes
This method makes a platform call to initialize the recorder using the provided settings. The `path` parameter is passed to the `androidToJson` method of `RecorderSettings`.
```

--------------------------------

### Get onCompletion Stream

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController/onCompletion.html

This snippet shows how to access the onCompletion stream, which emits events when audio playback is completed. It filters events based on a player key.

```dart
Stream<void> get onCompletion =>
    PlatformStreams.instance.onCompletion.filter(playerKey);
```

--------------------------------

### Initialize WaveformExtractionController

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerController/waveformExtraction.html

Instantiate the WaveformExtractionController, binding it to the PlayerController using playerKey. This controller is used for extracting, stopping, and monitoring waveform data.

```dart
late final waveformExtraction = WaveformExtractionController._(playerKey);
```

--------------------------------

### onDragStart Property Declaration

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioFileWaveforms/onDragStart.html

This snippet shows the declaration of the onDragStart property, which accepts an optional ValueSetter callback for DragStartDetails. Use this to define behavior when a drag gesture starts.

```dart
final ValueSetter<DragStartDetails>? onDragStart;
```

--------------------------------

### WaveformExtractionController()

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/WaveformExtractionController-class.html

Constructor for the WaveformExtractionController. Initializes a new instance of the controller.

```APIDOC
## Constructors

WaveformExtractionController()

### Description

Initializes a new instance of the WaveformExtractionController class.
```

--------------------------------

### Stream<double> get onExtractionProgress

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/WaveformExtractionController/onExtractionProgress.html

This stream emits double values indicating the current progress of waveform extraction. It filters the platform streams based on an extractor key.

```dart
Stream<double> get onExtractionProgress =>
    PlatformStreams.instance.onExtractionProgress.filter(_extractorKey);
```

--------------------------------

### PlayerWaveStyle Constructor Implementation

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerWaveStyle/PlayerWaveStyle.html

The actual implementation of the PlayerWaveStyle constructor, assigning provided values to instance variables and including assertions for valid input ranges.

```dart
const PlayerWaveStyle({
  this.fixedWaveColor = Colors.white54,
  this.liveWaveColor = Colors.white,
  this.showTop = true,
  this.showBottom = true,
  this.showSeekLine = true,
  this.waveCap = StrokeCap.round,
  this.seekLineColor = Colors.white,
  this.seekLineThickness = 2.0,
  this.waveThickness = 3.0,
  this.backgroundColor = Colors.black,
  this.fixedWaveGradient,
  this.scaleFactor = 100.0,
  this.liveWaveGradient,
  this.spacing = 5,
  this.scrollScale = 1.0,
})  : assert(spacing >= 0),
      assert(
        waveThickness < spacing,
        "waveThickness can't be greater than spacing",
      );
```

--------------------------------

### RecorderController()

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/RecorderController-class.html

Initializes a new instance of the RecorderController class. This class provides controls for recording audio and other useful handlers.

```APIDOC
## RecorderController()

### Description
Initializes a new instance of the RecorderController class. This class provides controls for recording audio and other useful handlers.

### Constructor
RecorderController()
```

--------------------------------

### Stop Recording and Get Audio Info

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface/stop.html

This snippet shows how to call the stop recording method and cast the returned map to the expected type. It's used when you need to finalize a recording session.

```dart
Future<Map<String, dynamic>> stop() async {
  Map<Object?, Object?> audioInfo =
      await _methodChannel.invokeMethod(Constants.stopRecording);
  return audioInfo.cast<String, dynamic>();
}
```

--------------------------------

### Applying a Linear Gradient to Waveforms

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/WaveStyle/gradient.html

Use this snippet to apply a linear gradient to your audio waveforms. Ensure you import `dart:ui` as `ui`. The gradient is defined by start and end points, and a list of colors.

```dart
import 'dart:ui' as ui show Gradient;

     ...

     ui.Gradient.linear(
                     const Offset(70, 50),
                     Offset(MediaQuery.of(context).size.width / 2, 0),
                     [Colors.red, Colors.green],
                   ),
```

--------------------------------

### PlayerWaveStyle Constructor

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/PlayerWaveStyle/PlayerWaveStyle.html

Constructs a PlayerWaveStyle object to define the visual appearance of an audio waveform player. It allows customization of colors, thickness, gradients, and visibility for both fixed and live waveform segments, as well as seek line properties.

```APIDOC
## PlayerWaveStyle Constructor

### Description
Initializes a new instance of the PlayerWaveStyle class with customizable visual properties for audio waveforms.

### Method
`PlayerWaveStyle()`

### Parameters
#### Constructor Parameters
- **fixedWaveColor** (Color) - Optional - The color of the fixed part of the waveform. Defaults to `Colors.white54`.
- **liveWaveColor** (Color) - Optional - The color of the live (playing) part of the waveform. Defaults to `Colors.white`.
- **showTop** (bool) - Optional - Whether to display the top part of the waveform. Defaults to `true`.
- **showBottom** (bool) - Optional - Whether to display the bottom part of the waveform. Defaults to `true`.
- **showSeekLine** (bool) - Optional - Whether to display the seek line. Defaults to `true`.
- **waveCap** (StrokeCap) - Optional - The cap style for the waveform strokes. Defaults to `StrokeCap.round`.
- **seekLineColor** (Color) - Optional - The color of the seek line. Defaults to `Colors.white`.
- **seekLineThickness** (double) - Optional - The thickness of the seek line. Defaults to `2.0`.
- **waveThickness** (double) - Optional - The thickness of the waveform lines. Defaults to `3.0`.
- **backgroundColor** (Color) - Optional - The background color of the waveform area. Defaults to `Colors.black`.
- **fixedWaveGradient** (Shader?) - Optional - A shader to apply to the fixed part of the waveform.
- **scaleFactor** (double) - Optional - A scaling factor for the waveform. Defaults to `100.0`.
- **liveWaveGradient** (Shader?) - Optional - A shader to apply to the live part of the waveform.
- **spacing** (double) - Optional - The spacing between waveform elements. Defaults to `5`.
- **scrollScale** (double) - Optional - The scaling factor for scrolling the waveform. Defaults to `1.0`.

### Assertions
- `spacing` must be greater than or equal to 0.
- `waveThickness` must be less than `spacing`.
```

--------------------------------

### Get Audio Duration

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveformsInterface/getDuration.html

This method is used to retrieve the duration of an audio file. It takes a player key and a duration type as arguments and returns the duration as an integer. Ensure the Constants class is properly defined with necessary keys.

```dart
Future<int?> getDuration(String key, int durationType) async {
  var duration = await _methodChannel.invokeMethod(Constants.getDuration, {
    Constants.durationType: durationType,
    Constants.playerKey: key,
  });
  return duration;
}
```

--------------------------------

### AudioWaveforms Constructor

Source: https://pub.dev/documentation/audio_waveforms/latest/audio_waveforms/AudioWaveforms/AudioWaveforms.html

The constructor for the AudioWaveforms widget allows for customization of its appearance and behavior.

```APIDOC
## AudioWaveforms Constructor

### Description
Initializes a new instance of the AudioWaveforms widget with specified parameters for size, recording control, visual style, and interaction.

### Parameters
#### Constructor Parameters
- **key** (Key?) - Optional - Used for widget identification.
- **size** (Size) - Required - The dimensions of the waveform display.
- **recorderController** (RecorderController) - Required - Controller for managing audio recording.
- **waveStyle** (WaveStyle) - Optional - Defines the visual style of the waveform, defaults to `WaveStyle()`.
- **enableGesture** (bool) - Optional - Enables gesture detection on the waveform, defaults to `false`.
- **padding** (EdgeInsets?) - Optional - Padding around the waveform.
- **margin** (EdgeInsets?) - Optional - Margin around the waveform.
- **decoration** (BoxDecoration?) - Optional - BoxDecoration for styling the waveform container.
- **backgroundColor** (Color?) - Optional - Background color of the waveform.
- **shouldCalculateScrolledPosition** (bool) - Optional - Determines if scrolled position should be calculated, defaults to `false`.
```
Tokens:
Raw