v2.0

CHANGELOG.md

@@ -1,3 +1,46 @@
+### 2.0.0 (5 Apr 2024)
+- A giant leap forward from the previous version (many thanks to Filip Hráček).
+- Major changes to API. There are quick fixes (`dart fix`) to automatically rename many changed APIs.
+- `SoLoud` methods now throw instead of returning a PlayerErrors object.
+- added `getActiveVoiceCount()` to get concurrent sounds that are playing at the moment.
+- added `countAudioSource()` to get concurrent sounds that are playing a specific audio source.
+- added `getVoiceCount()` to get the number of voices the application has told SoLoud to play.
+- added `getMaxActiveVoiceCount()` to get the current maximum active voice count.
+- added `setMaxActiveVoiceCount()` to set the current maximum active voice count.
+- added `setProtectVoice()` and `getProtectVoice()` to get/set the protect voice flag.
+- `SoLoud.activeSounds` is now an `Iterable` instead of a `List`.
+- All time-related parameters and return values are now `Duration` type.
+  Before, they were `double`.
+- Added new (experimental) `AudioSource.allInstancesFinished` stream. 
+  This can be used to more easily await times when it's safe to dispose 
+  the sound. For example:
+
+  ```dart
+  final source = soloud.loadAsset('...');
+  // Wait for the first time all the instances of the sound are finished
+  // (finished playing or were stopped with soloud.stop()).
+  source.allInstancesFinished.first.then(
+    // Dispose of the sound.
+    (_) => soloud.disposeSound(source)
+  );
+  soloud.play(source);
+  ```
+- added `looping` and `loopingStartAt` properties to `SoLoud.play()` and `SoLoud.play3d()`.
+- added `SoLoud.getLooping()` to retrieve the looping state of a sound.
+- added `SoLoud.getLoopPoint()` and `SoLoud.setLoopPoint()` to get and set the looping start position of a sound.
+- New methods `SoLoud.loadAsset()` and `SoLoud.loadUrl()` to load audio from assets and URLs, respectively.
+- added `mode` property to `SoLoud.loadFile()` and `SoloudTools.loadFrom*` to prevent to load the whole audio data into memory:
+    - *LoadMode.memory* by default. Means less CPU, more memory allocated.
+    - *LoadMode.disk* means more CPU, less memory allocated. Lags can occurs while seeking MP3s, especially when using a slider.
+- Switched from `print()` logging to using the standard `package:logging`.
+  See `README.md` to learn how to capture log messages and how to filter them.
+- The capture feature is on experimental stage to be fine tuned in the near future. All methods related to audio capture have been extracted to a separate class. 
+  So now, there are two classes:
+    - `SoLoud` for _playing_ audio
+    - `SoLoudCapture` for _capturing_ audio
+- The Web platform is a work in progress, stay tuned!
+- Switched LICENSE from Apache-2.0 to MIT.
+
 ### 2.0.0-pre.5 (4 Apr 2024)
 - getLoopPoint now returns Duration.
 - Major changes to API docs and README.

README.md

@@ -151,8 +151,6 @@ Since I needed to modify the generated `.dart` file, I followed this flow:
 2. The file `lib/flutter_soloud_FFIGEN.dart` will be generated.
 3. Copy the relevant code for the new functions from `lib/flutter_soloud_FFIGEN.dart` into `lib/flutter_soloud_bindings_ffi.dart`.
 
-Additionally, I have forked the [SoLoud](https://github.com/jarikomppa/soloud) repository and made modifications to include the latest [Miniaudio](https://github.com/mackron/miniaudio) audio backend. This backend is in the [new_miniaudio] branch of my [fork](https://github.com/alnitak/soloud) and is set as the default.
-
 #### Project structure
 
 This plugin uses the following structure:
@@ -165,8 +163,8 @@ This plugin uses the following structure:
 
 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 has been updated and
-is located in `src/soloud/src/backend/miniaudio`.
+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`.
 
 #### Debugging
 
@@ -207,11 +205,6 @@ For Windows users, SoLoud utilizes *Openmpt* through a DLL, which can be obtaine
 
 ***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.
 
-#### iOS
-There are some problems with Impeller engine when running the *visualizer* example on the simulator (20 Lug 2023). To disable it, run the following command:
-`flutter run --no-enable-impeller`
-Unfortunately, I don't have a real device to test it.
-
 #### Web
 
 Work on web support (using WASM) is tracked in

example/README.md

@@ -2,6 +2,9 @@
 
 Demonstrates how to use the `flutter_soloud` plugin.
 
+There are some problems with Impeller engine in iOS when running the *visualizer* example (the 2nd) on the simulator (20 Lug 2023). To disable it, run the following command:
+`flutter run --no-enable-impeller`.
+
 There are 5 examples:
 *(to use microphone on MacOs or iOS you should add audio input permission in the example app)*
 

example/tests/tests.dart

@@ -49,8 +49,8 @@ void main() async {
   }
 
   tests = <Future<void> Function()>[
-    // testSynchronousDeinit,
-    // testAsynchronousDeinit,
+    testSynchronousDeinit,
+    testAsynchronousDeinit,
   ];
   for (final f in tests) {
     await runZonedGuarded(
@@ -79,6 +79,7 @@ void main() async {
       ..writeln('See logs above for details.')
       ..writeln();
   } else {
+    debugPrint('===== TESTS PASSED! =====');
     stdout
       ..writeln('===== TESTS PASSED! =====')
       ..writeln();

lib/src/audio_isolate.dart

@@ -21,9 +21,7 @@ void debugIsolates(String text) {
 enum MessageEvents {
   exitIsolate,
   initEngine,
-  disposeEngine,
   startLoop,
-  stopLoop,
   loop,
   loadFile,
   loadWaveform,
@@ -116,13 +114,6 @@ void audioIsolate(SendPort isolateToMainStream) {
             .send({'event': event['event'], 'args': args, 'return': ret});
         break;
 
-      case MessageEvents.disposeEngine:
-        final args = event['args']! as ArgsDisposeEngine;
-        soLoudController.soLoudFFI.deinit();
-        isolateToMainStream
-            .send({'event': event['event'], 'args': args, 'return': ()});
-        break;
-
       case MessageEvents.loadFile:
         final args = event['args']! as ArgsLoadFile;
         final ret = soLoudController.soLoudFFI.loadFile(
@@ -369,12 +360,6 @@ void audioIsolate(SendPort isolateToMainStream) {
         );
         break;
 
-      case MessageEvents.stopLoop:
-        loopRunning = false;
-        isolateToMainStream
-            .send({'event': MessageEvents.stopLoop, 'args': (), 'return': ()});
-        break;
-
       case MessageEvents.loop:
         if (loopRunning) {
           for (final sound in activeSounds) {

lib/src/audio_source.dart

@@ -5,14 +5,6 @@ import 'package:flutter_soloud/src/sound_handle.dart';
 import 'package:flutter_soloud/src/sound_hash.dart';
 import 'package:meta/meta.dart';
 
-/// Deprecated alias to [SoundEventType].
-@Deprecated('Use SoundEventType instead')
-typedef SoundEvent = SoundEventType;
-
-/// A deprecated alias for [AudioSource].
-@Deprecated("Use 'AudioSource' instead")
-typedef SoundProps = AudioSource;
-
 /// the type sent back to the user when a sound event occurs
 typedef StreamSoundEvent = ({
   SoundEventType event,
@@ -74,11 +66,7 @@ class AudioSource {
   late final StreamController<StreamSoundEvent> soundEventsController =
       StreamController.broadcast();
 
-  /// This getter is [deprecated] and will be removed. Use [handles] instead.
-  @Deprecated("Use 'handles' instead")
-  UnmodifiableSetView<SoundHandle> get handle => handles;
-
-  /// the user can listen ie when a sound ends or key events (TODO)
+  /// the user can listen when a sound ends
   Stream<StreamSoundEvent> get soundEvents => soundEventsController.stream;
 
   /// Backing controller for [allInstancesFinished].