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
* Ability to load sounds to RAM, or play from disk
15
-
* Multiple voices, playing different or even the same sound multiple times on top of each other
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
20
-
* 3D positional audio, including Doppler effect
21
-
* Support for MP3, WAV, OGG, and FLAC
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).
30
-
6
+
||Linux|Windows|Android|MacOS|iOS|Web|
7
+
|-|:-:|:-:|:-:|:-:|:-:|:-:|
8
+
|Support|💙|💙|💙|💙|💙|💙|
9
+
|Minimum Version|Any|Any|21|10.15|13.0|Any|
31
10
32
11
## Overview
33
12
34
-
This plugin is mainly meant for games and immersive apps.
35
-
If you merely need to play audio (such as playing a single sound effect or a non-looped song), and you don't need to worry about latency, there are other Flutter plugins you can use, such as the popular [`audioplayers` plugin](https://pub.dev/packages/audioplayers).
36
-
37
-
> SoLoud is an easy to use, free, portable c/c++ audio engine for games.
38
-
>
39
-
> The engine has been designed to make simple things easy,
40
-
> while not making harder things impossible.
41
-
>
42
-
> [(from the underlying engine's homepage)](https://solhsa.com/soloud/index.html)
43
-
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`).
45
-
In other words, it is calling the C/C++ methods of the underlying audio engine directly — there are no method channels in use.
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
-
These libraries are embedded and enabled by default for all platforms. This leads to an increased binary size by 600~1500 kb depending on platform. If you don't need to use audio streaming, hence you don't need the Opus and Ogg libraries, you can read the [NO_OPUS_OGG_LIBS.md](https://github.com/alnitak/flutter_soloud/blob/main/NO_OPUS_OGG_LIBS.md) for details.
51
-
52
-
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|
57
-
58
-
#### Web platform
59
-
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.
66
-
67
-
#### Linux
68
-
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.
69
-
70
-
To fix this, also on other Debian based distro, simply install the library using the command `sudo apt-get install libasound2-dev`.
71
-
72
-
Other Linux distributions use different names for the *alsa* library:
73
-
- on Arch-based systems: **alsa-lib**
74
-
- on OpenSUSE: **alsa-devel**
75
-
76
-
Install them using the package manager provided by your Linux distribution.
77
-
78
-
#### Stripping iOS symbols
79
-
When creating a release archive (IPA), the symbols are [stripped by Xcode](https://docs.flutter.dev/platform-integration/ios/c-interop#stripping-ios-symbols), so the command `flutter build ipa` may throw a `Failed to lookup symbol ... symbol not found error`. To work around this:
13
+
A high-performance audio plugin designed primarily for games and immersive applications, providing low latency and advanced features.
80
14
81
-
1. In Xcode, go to Target Runner > Build Settings > Strip Style
82
-
2. Change from All Symbols to Non-Global Symbols
15
+
## Key Features
83
16
17
+
- ⚡ Low latency, high performance audio
18
+
- 🎮 3D positional audio with Doppler effect
19
+
- 🔄 Gapless looping and streaming
20
+
- 📊 Get audio wave and/or FFT audio data in real-time (useful for visualization)
21
+
- 🎛️ Rich effects system (reverb, echo, limiter, bassboost, etc.)
22
+
- ⚙️ Faders for attributes (e.g. fade out for 2 seconds, then stop)
23
+
- 🎚️ Oscillators for attributes
24
+
- 🌊 Waveform generation and visualization
25
+
- 🔊 Multiple voices, playing different or even the same sound multiple times
26
+
- 🎵 Support for MP3, WAV, OGG, and FLAC
27
+
- ⏱️ Read audio data samples from a file with a given time range
28
+
- 🔄 Stream audio from given audio data with buffering support for PCM and Opus
29
+
- 🌊 Generate waveforms in real-time with various types (sine, square, saw, triangle, etc.)
The following example loads an MP3 asset, plays it, then later stops it and disposes of the audio source to reclaim memory.
36
+
## Simple Example
89
37
90
38
```dart
91
39
void example() async {
92
40
final soloud = SoLoud.instance;
93
-
94
41
await soloud.init();
95
42
96
-
final source = await soloud.loadAsset('path/to/asset.mp3');
43
+
final source = await soloud.loadAsset('assets/sound.mp3');
97
44
final handle = await soloud.play(source);
98
-
99
-
// ...
100
-
45
+
46
+
// Later...
101
47
await soloud.stop(handle);
102
48
await soloud.disposeSource(source);
103
49
}
104
50
```
105
51
106
-
As you can see, most functionality in `flutter_soloud` is done through calling methods on the `SoLoud` instance.
107
-
108
-
[**Read the API reference**](https://pub.dev/documentation/flutter_soloud/latest/flutter_soloud/SoLoud-class.html) for the full listing of methods, and their documentation.
109
-
110
-
When you call a `loadAsset` (or `loadFile` or `loadUrl`) method, in return you get an `AudioSource`. This is the reference to the sound which is used by SoLoud.
111
-
The source needs to be disposed when it is needed no more.
112
-
113
-
Every time you play an `AudioSource`, you get a new `SoundHandle` which uniquely identifies the new playing instance of the sound.
114
-
This handle is also added to the `AudioSource.handles` list so that you can always check how many times any audio source is being played at the time.
115
-
116
-
The `SoundHandle` also allows you to modify the currently-playing sounds, such as changing their volume, pausing them, etc.
117
-
118
-
---
119
-
120
-
For more simple examples, check out the [example/project](https://github.com/alnitak/flutter_soloud/tree/main/example) included with the package:
121
-
| Example | Description |
122
-
|-----------------|-------------|
123
-
|*lib/main.dart*|Very simple example where to start from. |
124
-
|*lib/audio_data/audio_data.dart*|Simple example to show how to use the `AudioData` to visualize audio. |
125
-
|*lib/buffer_stream/generate.dart*|Example of how to generate PCM audio inside an `Isolate` and play them. |
126
-
|*lib/buffer_stream/websocket.dart*|Shows how to use BufferStream with a websocket to get PCM and Opus audio data. |
127
-
|*lib/filters/compressor.dart*|Shows the use of the compressor filter. |
128
-
|*lib/filters/limiter.dart*|Shows the use of the limiter filter. |
129
-
|*lib/filters/pitchshift.dart*|Shows the use of the pitchshift filter. |
|*lib/output_device/output_device.dart*|Lists available output devices. |
132
-
|*lib/wave_data/wave_data.dart*|Demonstrates how to read audio samples from a file and display them. |
133
-
|*lib/waveform/waveform.dart*|Demonstrates how to generate a waveform, play it, and change it's frequency on the fly. |
134
-
135
-
136
-
For more complete examples, please look at [flutter_soloud_example](https://github.com/alnitak/flutter_soloud_example).
137
-
138
-
## Logging
139
-
140
-
The `flutter_soloud` package logs everything (from severe warnings to fine debug messages) using the standard [`logging` package](https://pub.dev/packages/logging).
141
-
142
-
See the example's `lib/main.dart` to see how to capture these logs.
143
-
For example:
144
-
145
-
```dart
146
-
import 'dart:developer' as dev;
147
-
148
-
void main() {
149
-
// Cut-off for messages. (Lower levels than INFO will be discarded.)
150
-
Logger.root.level = Level.FINE;
151
-
Logger.root.onRecord.listen((record) {
152
-
// Forward logs to the console.
153
-
dev.log(
154
-
record.message,
155
-
time: record.time,
156
-
level: record.level.value,
157
-
name: record.loggerName,
158
-
zone: record.zone,
159
-
error: record.error,
160
-
stackTrace: record.stackTrace,
161
-
);
162
-
// TODO: if needed, forward to Sentry.io, Crashlytics, etc.
163
-
});
164
-
165
-
runApp(const MyApp());
166
-
}
167
-
```
168
-
169
-
If you don't set up a listener like the one above, there will be no logging from the package.
170
-
171
-
See the `logging` package's [documentation](https://pub.dev/packages/logging) to learn more about its functionality.
172
-
173
-
174
52
## License
175
53
176
-
The Dart plugin is covered by the MIT license.
177
-
178
-
For information regarding the license for the underlying SoLoud (C++) engine, please refer to [this link](https://solhsa.com/soloud/legal.html).
179
-
In short, the SoLoud code itself is covered by the ZLib/LibPNG license (which is [compatible](https://en.wikipedia.org/wiki/Zlib_License) with GNU GPL).
180
-
Some modules (such as MP3 or OGG support) are covered with other, but still permissive open source licenses.
181
-
182
-
183
-
## Contribute
184
-
185
-
To use native code, bindings from Dart to C/C++ are needed. To avoid writing these manually, they are generated from the header file (`src/ffi_gen_tmp.h`) using [package:ffigen](https://pub.dev/packages/ffigen) and temporarily stored in `lib/flutter_soloud_FFIGEN.dart`. You can generate the bindings by running `dart run ffigen`.
186
-
187
-
Since I needed to modify the generated `.dart` file, I followed this flow:
188
-
1. Copy the function declarations to be generated into `src/ffi_gen_tmp.h`.
189
-
2. The file `lib/flutter_soloud_FFIGEN.dart` will be generated.
190
-
3. Copy the relevant code for the new functions from `lib/flutter_soloud_FFIGEN.dart` into `lib/flutter_soloud_bindings_ffi.dart`.
191
-
192
-
#### Project structure
193
-
194
-
This plugin uses the following structure:
195
-
196
-
*`lib`: Contains the Dart code that defines the API of the plugin relative to all platforms.
197
-
*`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.
198
-
*`src/soloud`: Contains the SoLoud sources of my fork
199
-
*`web`: Contains the scripts to build the plugin on the web platform.
200
-
*`xiph`: Contains the script to build `ogg` and `opus` libraries on Android, Windows, MacOS and iOS.
201
-
202
-
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`.
203
-
204
-
#### Debugging
205
-
206
-
I have provided the necessary settings in the **.vscode** directory for debugging native C++ code on both Linux and Windows. To debug on Android, please use Android Studio and open the project located in the ***example/android*** directory. However, I am not familiar with the process of debugging native code on Mac and iOS.
207
-
208
-
##### Logging
209
-
210
-
When debugging the package using the `example/` app, you might want to change the logging level to something more granular. For example, in `main()`:
211
-
212
-
```dart
213
-
// Capture even the finest log messages.
214
-
Logger.root.level = Level.ALL;
215
-
```
216
-
217
-
One thing that's missing (as of March 2024) is logging from inside the audio isolate.
218
-
We'd have to send logs to the main isolate through an event, which might be too expensive and brittle.
219
-
Feel free to use `debugPrint` in `audio_isolate.dart` when working on the package.
220
-
Just make sure to delete those calls before submitting pull requests.
221
-
We don't want to pollute developers' console outputs.
222
-
223
-
#### Linux
224
-
225
-
If you encounter any glitches, they might be caused by PulseAudio. To troubleshoot this issue, you can try disabling PulseAudio within the `linux/src.cmake` file. Look for the line `add_definitions(-DMA_NO_PULSEAUDIO)` and uncomment it (now it is the default behavior).
226
-
227
-
#### Android
228
-
229
-
The default audio backend is `miniaudio`, which will automatically select the appropriate audio backend based on your Android version:
230
-
- AAudio with Android 11.0 and newer.
231
-
- OpenSL|ES for older Android versions.
232
-
233
-
#### Windows
234
-
235
-
For Windows users, SoLoud utilizes *Openmpt* through a DLL, which can be obtained from [https://lib.openmpt.org/](https://lib.openmpt.org/). If you wish to use this feature, install the DLL and enable it by modifying the first line in `windows/src.cmake`.
236
-
237
-
***Openmpt*** functions as a module-playing engine, capable of replaying a wide variety of multichannel music formats (669, amf, ams, dbm, digi, dmf, dsm, far, gdm, ice, imf, it, itp, j2b, m15, mdl, med, mid, mo3, mod, mptm, mt2, mtm, okt, plm, psm, ptm, s3m, stm, ult, umx, wow, xm). Additionally, it can load wav files and may offer better support for wav files compared to the stand-alone wav audio source.
238
-
239
-
#### Web
240
-
241
-
Please see [WEB_NOTES.md](https://github.com/alnitak/flutter_soloud/blob/main/WEB_NOTES.md).
54
+
The Dart plugin is covered by the MIT license. For information about the underlying SoLoud engine license, see the [documentation](https://docs.page/alnitak/flutter_soloud/get_started/license).
0 commit comments