You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+45Lines changed: 45 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,3 +1,48 @@
1
+
### 3.0.2 (25 Feb 2025)
2
+
- fixed crash when trying to play a sound after deactivating its active filter #189
3
+
4
+
### 3.0.1 (20 Feb 2025)
5
+
- fix: error while calling listPlaybackDevices() #186.
6
+
- android example folder recreated.
7
+
8
+
### 3.0.0 (13 Feb 2025)
9
+
-`BufferStream` now supports 2 type of buffering:
10
+
-`BufferingType.preserved` (default): preserve the data already in the buffer while playing.
11
+
-`BufferingType.released`: free the memory of the already played data for longer playback.
12
+
- breaking change: splitted [maxBufferSize] to [maxBufferSizeBytes] and [maxBufferSizeDuration] in `SoLoud.setBufferStream`. This gives the user a way to choose the maximum buffer size using bytes or time.
13
+
- breaking change: removed `initialized` getter in favor of `isInitialized`
14
+
- removed deprecated `timeout` parameter in `SoLoud.init`.
- fix: on some unclear conditions `isInitialized` returning false on MacOS after engine starts with no error #177
18
+
- fix: Call `loadMem` will crash the application #174.
19
+
20
+
### 3.0.0-pre.0 (2 Feb 2025)
21
+
- fix: clicks and pops when changing waveform frequency #156.
22
+
- added `Limiter` and `Compressor` filters (see `example/lib/filters/`).
23
+
- added BufferStream #148. Now it's possible to add audio data and listen to them. It provides a customizable buffering length which automatycally pauses the playing handle if there is not enough data, for example when receiving audio data from the web. It also provides a callback that allows you to know when the buffering is started and stopped. The audio data can of of the following formats:
24
+
-`s8` signed 8 bit
25
+
-`s16le` signed 16 bit little endian
26
+
-`s32le` signed 32 bit little endian
27
+
-`f32le` float 32 bit little endian
28
+
-`opus` Opus codec compressed audio with Ogg container. Useful for streaming from the Web (ie using OpenAI APIs).
29
+
- fixed Web Worker initialization non fatal error that could occur on Web.
30
+
- fixed sound distortion using single pitchShift filter and changing relative play speed #154.
31
+
- fixed the use of `LoadMode.disk` on the Web platform which in some cases caused the `allInstancesFinished` event to not be emitted.
32
+
- improved performance on Web, MacOS and iOS.
33
+
- get wave and FFT samples is now simpler and faster.
34
+
- To avoid future incompatibilities when using other WASM compiled plugins, it is now necessary to add a new script to `index.html`:
Copy file name to clipboardExpand all lines: README.md
+56-7Lines changed: 56 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,10 +14,19 @@ A low-level audio plugin for Flutter.
14
14
* Ability to load sounds to RAM, or play from disk
15
15
* Multiple voices, playing different or even the same sound multiple times on top of each other
16
16
* Faders for attributes (e.g. fade out for 2 seconds, then stop)
17
+
* Oscillators for attributes
18
+
* Get audio wave and/or FFT audio data in real-time (useful for visualization)
19
+
* Read audio data samples from a file with a given time range
17
20
* 3D positional audio, including Doppler effect
18
21
* Support for MP3, WAV, OGG, and FLAC
19
-
* Audio effects such as echo, reverb, filter, equalizer
20
-
* Web support is still under testing. Your feedback is greatly appreciated. Please read the [web notes](https://github.com/alnitak/flutter_soloud/blob/main/WEB_NOTES.md) to start using this plugin on the Web.
22
+
* Generate waveforms with the following types: `square`, `saw`, `sin`, `triangle`, `bounce`, `jaws`, `humps`, `fSquare` and `fSaw`
23
+
* Audio effects such as `echo`, `reverb`, `filter`, `equalizer`, `pitch``shifter`, `limiter`, `compressor` etc.
24
+
* Stream audio from given audio data with buffering support with the following formats:
25
+
-`s8` signed 8 bit
26
+
-`s16le` signed 16 bit little endian
27
+
-`s32le` signed 32 bit little endian
28
+
-`f32le` float 32 bit little endian
29
+
-`opus` Opus codec compressed audio with Ogg container. Usefull for streaming from the Web (ie using OpenAI APIs).
21
30
22
31
23
32
## Overview
@@ -35,8 +44,31 @@ If you merely need to play audio (such as playing a single sound effect or a non
35
44
The `flutter_soloud` plugin uses the [SoLoud (C++) audio engine](https://solhsa.com/soloud/) with the [miniaudio](https://miniaud.io/) backend through [Dart's C interop](https://dart.dev/interop/c-interop) (`dart:ffi`).
36
45
In other words, it is calling the C/C++ methods of the underlying audio engine directly — there are no method channels in use.
37
46
47
+
#### Opus format for streaming
48
+
When using an `AudioSource` as an audio stream to play custom audio data (ie using setBufferStream/addAudioDataStream/setDataIsEnded), it is possible to add PCM RAW audio data in *s8*, *s16le*, *s32le*, *f32le* and since it supports also the *opus* format with the Ogg codec (ie to work with OpenAI APIs), the [Opus](https://www.opus-codec.org/) and [Ogg](https://xiph.org/ogg/) libraries from [Xiph.org](https://www.xiph.org/) are needed.
49
+
50
+
On Linux and MacOS theese libraries must be installed if you want to use this kind of `AudioSource`:
51
+
-**Linux**
52
+
- install them depending on the package manager used by you distribution
53
+
-**MacOS**
54
+
-`brew install opus libogg`
55
+
56
+
if the libraries are not found the plugin will throw an exception when calling `setBufferStream` using Opus format.
57
+
58
+
The `SoLoud.setBufferStream` supports also `BufferingType.preserved` which behaves the same as a normal `AudioSource`, and `BufferingType.released` which will free the memory of the already played audio for longer playback. The latter will accept to play only one instance of the audio stream at the same time.
|acts as normal leaving the whole audio data available for future re-play|while playing the already listened audio is freed. It can be listened to only once and the sound must be manually disposed|
63
+
38
64
#### Web platform
39
-
To use this plugin on the **Web platform**, please refer to [WEB_NOTES](https://github.com/alnitak/flutter_soloud/blob/main/WEB_NOTES.md).
65
+
To use this plugin on the **Web platform**, please add the following scripts to the `<head>` or `<body>` section of your `index.html`:
refer to [WEB_NOTES](https://github.com/alnitak/flutter_soloud/blob/main/WEB_NOTES.md) for more details.
40
72
41
73
#### Linux
42
74
Linux distributions usually install the alsa library by default. However, we've noticed that sometimes this isn't the case. For example, when installing Ubuntu Linux (24.04.1 LTS in this case) in a VM box on Windows, the alsa library is not installed. This will prevent `flutter_soloud` from building.
@@ -89,7 +121,24 @@ This handle is also added to the `AudioSource.handles` list so that you can alwa
89
121
90
122
The `SoundHandle` also allows you to modify the currently-playing sounds, such as changing their volume, pausing them, etc.
91
123
92
-
For more simple examples, check out the [example/project](https://github.com/alnitak/flutter_soloud/tree/main/example) included with the package.
124
+
---
125
+
126
+
For more simple examples, check out the [example/project](https://github.com/alnitak/flutter_soloud/tree/main/example) included with the package:
127
+
| Example | Description |
128
+
|-----------------|-------------|
129
+
|*lib/main.dart*|Very simple example where to start from. |
130
+
|*lib/audio_data/audio_data.dart*|Simple example to show how to use the `AudioData` to visualize audio. |
131
+
|*lib/buffer_stream/generate.dart*|Example of how to generate PCM audio inside an `Isolate` and play them. |
132
+
|*lib/buffer_stream/websocket.dart*|Shows how to use BufferStream with a websocket to get PCM and Opus audio data. |
133
+
|*lib/filters/compressor.dart*|Shows the use of the compressor filter. |
134
+
|*lib/filters/limiter.dart*|Shows the use of the limiter filter. |
135
+
|*lib/filters/pitchshift.dart*|Shows the use of the pitchshift filter. |
|*lib/output_device/output_device.dart*|Lists available output devices. |
138
+
|*lib/wave_data/wave_data.dart*|Demonstrates how to read audio samples from a file and display them. |
139
+
|*lib/waveform/waveform.dart*|Demonstrates how to generate a waveform, play it, and change it's frequency on the fly. |
140
+
141
+
93
142
For more complete examples, please look at [flutter_soloud_example](https://github.com/alnitak/flutter_soloud_example).
94
143
95
144
## Logging
@@ -151,10 +200,10 @@ Since I needed to modify the generated `.dart` file, I followed this flow:
151
200
This plugin uses the following structure:
152
201
153
202
*`lib`: Contains the Dart code that defines the API of the plugin relative to all platforms.
154
-
155
203
*`src`: Contains the native source code. Linux, Android and Windows have their own CmakeFile.txt file in their own subdir to build the code into a dynamic library.
156
-
157
-
*`src/soloud`: contains the SoLoud sources of my fork
204
+
*`src/soloud`: Contains the SoLoud sources of my fork
205
+
*`web`: Contains the scripts to build the plugin on the web platform.
206
+
*`xiph`: Contains the script to build `ogg` and `opus` libraries on Android, Windows, MacOS and iOS.
158
207
159
208
The `flutter_soloud` plugin utilizes a [forked](https://github.com/alnitak/soloud) repository of [SoLoud](https://github.com/jarikomppa/soloud), where the [miniaudio](https://github.com/mackron/miniaudio) audio backend (used by default) has been updated and it is located in `src/soloud/src/backend/miniaudio`.
In the `web` directory, there is a `compile_wasm.sh` script that generates the `.js` and `.wasm` files for the native C code located in the `src` dir. Run it after installing *emscripten*. There is also a `compile_web.sh` to compile the web worker needed by native code to communicate with Dart. The generated files are already provided, but if it is needed to modify C/C++ code or the `web/worker.dart` code, the scripts must be run to reflect the changes.
35
+
In the `web` directory, there is a `compile_wasm.sh` script that generates the `.js` and `.wasm` files for the native C code located in the `src` dir. Run it after installing *emscripten*. There is also a `compile_worker_and_init_module.sh` to compile the web worker needed by native code to communicate with Dart and the `init_module.dart` which initializes the WASM module. The default Module name is `Module_soloud` instead of the default `Module` to prevent some other WASM plugins from conflicting.
35
36
36
-
The `compile_wasm.sh` script uses the `-O3` code optimization flag.
37
-
To see a better errors logs, use `-O0 -g -s ASSERTIONS=1` in `compile_wasm.sh`.
37
+
The generated files are already provided, but if it is needed to modify C/C++ code or the `web/worker.dart` code, the scripts must be run to reflect the changes.
38
+
39
+
The `compile_wasm.sh` script uses the `-O3` code optimization flag. To see a better errors logs, use `-O0 -g -s ASSERTIONS=1` in `compile_wasm.sh`.
38
40
39
41
---
40
42
@@ -44,10 +46,10 @@ Here a sketch to show the step used:
44
46
45
47
46
48
**#1.** This function is called while initializing the player with `FlutterSoLoudWeb.setDartEventCallbacks()`.
47
-
It creates a Web Worker in the [WASM Module](https://emscripten.org/docs/api_reference/module.html) using the compiled `web/worker.dart`. After calling this, the WASM Module will have a new variable called `Module.wasmWorker` which will be used in Dart to receive messages.
49
+
It creates a Web Worker in the [WASM Module](https://emscripten.org/docs/api_reference/module.html) using the compiled `web/worker.dart`. After calling this, the WASM Module will have a new variable called `Module_soloud.wasmWorker` which will be used in Dart to receive messages.
48
50
By doing this it will be easy to use the Worker to send messages from within the CPP code.
49
51
50
-
**#2.** This function, like #1, uses [EM_ASM](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html#interacting-with-code-call-javascript-from-native) to inline JS. This JS code uses the `Module.wasmWorker` created in #1 to send a message.
52
+
**#2.** This function, like #1, uses [EM_ASM](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html#interacting-with-code-call-javascript-from-native) to inline JS. This JS code uses the `Module_soloud.wasmWorker` created in #1 to send a message.
51
53
52
54
**#3.** This is the JS used and created in #1. Every messages sent by #2 are managed here and sent to #4.
0 commit comments