feat: WaveForm for complete Audiofile

[synchronisator]

Description

Its currently not possible to create a waveform of a complete audiofile. This is an example of Audacity:

To create something like this, there has to be a method to get all values from the file. At the moment there is only a way to get small parts of the currently playing audiopart.

Thanks

[alnitak]

Currently is not possible. You can get audio data while playing, but this is not convenient and does not guarantee that all audio chunks will be retrieved.

I plan to add this feature later on and it is somehow related to #27

[alnitak]

2 new methods to the plugin have been added:

• readSamplesFromFile()
• readSamplesFromMem()

updated

  /// Read [numSamplesNeeded] audio data from a file equally spaced in time.
  /// The returned Float32List is not guaranteed to be [numSamplesNeeded] long.
  /// Each value in the returned Float32List is in the range -1.0 to 1.0 and
  /// their values are the average of audio data from the previous
  /// index sample if [average] is true.
  /// NOTE: this is not available on Web. Use [readSamplesFromMem] instead.
  ///
  /// [completeFileName] the complete path to the audio file.
  /// [numSamplesNeeded] is not guaranteed to be the same length as the returned
  /// Float32List. This could happen if the [endTime] is greater than the audio
  /// lenght.
  /// [startTime] in seconds. Defaults to 0.
  /// [endTime] in seconds. Defaults to -1. If -1, the audio will be read until
  /// the end of the file.
  /// [average] if true, the returned Float32List will be filled with the
  /// average of the samples from the previous index sample. Defaults to false.
  /// When true it does not affect performance much.
  /// 
  /// Here a representation of the range [startTime] to [endTime] in the audio
  /// with [numSamplesNeeded]=10:
  /// 
  /// 0      1      2      3      4      5      6      7      8      9
  /// |------|------|------|------|------|------|------|------|------|
  ///                ------- with [average]=true all the samples are the
  ///                        average of the samples from 2 to 3 and it is
  ///                        stored in the returned Float32List at index 3.
  ///                      - with [average]=false the value returned at index
  ///                        3 is the value got at 3.
  Future<Float32List> readSamplesFromFile(
    String completeFileName,
    int numSamplesNeeded, {
    double startTime = 0,
    double endTime = -1,
    bool average = false,
  });

There is also readSamplesFromMem() which accepts a Uint8List buffer instead of String completeFileName. This works on all platforms but is useful for the web because the browser sandbox doesn't let you read files.

This is the result compared to the one from Audacity:

Audio channels are merged and averaged.

A web demo. Please note that on the web that method is synchronous.

This new feature is available on the feat_waveform branch.

[alnitak]

This feature is landed in v2.1.5!