feat: setInaudibleBehavior #96

.vscode/launch.json

@@ -8,7 +8,7 @@
             "name": "Flutter debug",
             "type": "dart",
             "request": "launch",
-            "program": "lib/waveform/waveform.dart",
+            "program": "lib/main.dart",
             "flutterMode": "debug",
             "cwd": "${workspaceFolder}/example"
         },
@@ -24,7 +24,7 @@
             "name": "Flutter release",
             "type": "dart",
             "request": "launch",
-            "program": "lib/buffer_stream/websocket.dart",
+            "program": "lib/main.dart",
             "flutterMode": "release",
             "cwd": "${workspaceFolder}/example"
         },

.vscode/tasks.json

@@ -9,7 +9,7 @@
         },
         {
             "label": "compile linux debug",
-            "command": "cd ${workspaceFolder}/example; flutter build linux -t lib/waveform/waveform.dart --debug",
+            "command": "cd ${workspaceFolder}/example; flutter build linux -t lib/main.dart --debug",
             "type": "shell"
         },
         {
@@ -29,7 +29,7 @@
         },
         {
             "label": "compile web debug",
-            "command": "cd ${workspaceFolder}/example; flutter run -d chrome --web-renderer canvaskit --web-browser-flag '--disable-web-security' -t lib/waveform/waveform.dart --release",
+            "command": "cd ${workspaceFolder}/example; flutter run -d chrome --web-renderer canvaskit --web-browser-flag '--disable-web-security' -t lib/main.dart --release",
             "type": "shell"
         },
         {

CHANGELOG.md

@@ -2,6 +2,7 @@
 - fix: clicks and pops when changing waveform frequency #156
 - added BufferStream #148. Now it's possible to add audio data and listen to them. It provides a customizable buffering length which automatycally pause the playing handle for example when receiving audio data from the web.
 - added Limiter and Compressor filters (see `example/lib/filters`)
+- added `setInaudibleBehavior`. When a 3D sound is too far to be eard, you can tell `flutter_soloud` to kill it.
 
 ### 2.1.7 (29 Oct 2024)
 - added `listPlaybackDevices` to get all the OS output devices available.

example/lib/main.dart

@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'dart:developer' as dev;
 
 import 'package:flutter/foundation.dart';

lib/src/bindings/bindings_player.dart

@@ -518,6 +518,19 @@ abstract class FlutterSoLoud {
   @mustBeOverridden
   bool getProtectVoice(SoundHandle handle);
 
+  /// Set the inaudible behavior of a live sound. By default,
+  /// if a sound is inaudible, it's paused, and will resume when it
+  /// becomes audible again. With this function you can tell SoLoud
+  /// to either kill the sound if it becomes inaudible, or to keep
+  /// ticking the sound even if it's inaudible.
+  ///
+  /// [handle] handle to check.
+  /// [mustTick] whether to keep ticking or not when the sound becomes
+  /// inaudible.
+  /// [kill] whether to kill the sound or not when the sound becomes inaudible.
+  @mustBeOverridden
+  void setInaudibleBehavior(SoundHandle handle, bool mustTick, bool kill);
+
   /// Set a sound's protection state.
   ///
   /// Normally, if you try to play more sounds than there are voices,

lib/src/bindings/bindings_player_ffi.dart

@@ -1049,6 +1049,26 @@ class FlutterSoLoudFfi extends FlutterSoLoud {
   late final _setProtectVoice =
       _setProtectVoicePtr.asFunction<void Function(int, int)>();
 
+  @override
+  void setInaudibleBehavior(
+    SoundHandle handle,
+    bool mustTick,
+    bool kill,
+  ) {
+    return _setInaudibleBehavior(
+      handle.id,
+      mustTick,
+      kill,
+    );
+  }
+
+  late final _setInaudibleBehaviorPtr = _lookup<
+      ffi.NativeFunction<
+          ffi.Void Function(
+              ffi.UnsignedInt, ffi.Bool, ffi.Bool)>>('setInaudibleBehavior');
+  late final _setInaudibleBehavior =
+      _setInaudibleBehaviorPtr.asFunction<void Function(int, bool, bool)>();
+
   @override
   int getMaxActiveVoiceCount() {
     return _getMaxActiveVoiceCount();

lib/src/bindings/bindings_player_web.dart

@@ -549,6 +549,11 @@ class FlutterSoLoudWeb extends FlutterSoLoud {
     return wasmSetProtectVoice(handle.id, protect ? 1 : 0);
   }
 
+  @override
+  void setInaudibleBehavior(SoundHandle handle, bool mustTick, bool kill) {
+    return wasmSetInaudibleBehavior(handle.id, mustTick ? 1 : 0, kill ? 1 : 0);
+  }
+
   @override
   int getMaxActiveVoiceCount() {
     return wasmGetMaxActiveVoiceCount();

lib/src/bindings/js_extension.dart

@@ -262,6 +262,9 @@ external int wasmGetVoiceCount();
 @JS('Module._getProtectVoice')
 external int wasmGetProtectVoice(int handle);
 
+@JS('Module._setInaudibleBehavior')
+external void wasmSetInaudibleBehavior(int handle, int mustTick, int kill);
+
 @JS('Module._setProtectVoice')
 external void wasmSetProtectVoice(int handle, int protect);
 

lib/src/soloud.dart

@@ -1611,6 +1611,51 @@ interface class SoLoud {
     _controller.soLoudFFI.setProtectVoice(handle, protect);
   }
 
+  /// Set the inaudible behavior of a live 3D sound. By default,
+  /// if a sound is inaudible, it's paused, and will resume when it
+  /// becomes audible again. With this function you can tell SoLoud
+  /// to either kill the sound if it becomes inaudible, or to keep
+  /// ticking the sound even if it's inaudible.
+  ///
+  /// [handle] handle to check.
+  /// [mustTick] whether to keep ticking or not when the sound becomes
+  /// inaudible.
+  /// [kill] whether to kill the sound or not when the sound becomes inaudible.
+  ///
+  /// **Example**:
+  /// ```dart
+  /// final sound = SoLoud.instance.load('path/to/sound.mp3');
+  /// final handle = SoLoud.instance.play3d(sound, 0, 0, 0);
+  /// double xPos = 0;
+  ///
+  /// // set the sound to be inaudible if it's more than 10 units away
+  /// SoLoud.instance.set3dSourceMinMaxDistance(handle, 0, 10);
+  /// // set the attenuation to `LINEAR_DISTANCE` and when its position
+  /// // is 10 units away, the volume will be 0 (inaudible).
+  /// SoLoud.instance.set3dSourceAttenuation(handle, 2, 1);
+  ///
+  /// // if the sound is inaudible, it will be killed and the [handle]
+  /// // becomes invalid.
+  /// SoLoud.instance.setInaudibleBehavior(handle, false, true);
+  ///
+  /// // here we shift the sound position away (up to you to cancel the Timer!)
+  /// // When [xPos] reaches 10 units, the handle will stop.
+  /// Timer.periodic(
+  ///   const Duration(milliseconds: 100),
+  ///   (timer) {
+  ///       SoLoud.instance
+  ///           .set3dSourcePosition(handle, xPos += 0.1, 0, 0);
+  ///   },
+  /// );
+  /// ```
+  @mustBeOverridden
+  void setInaudibleBehavior(SoundHandle handle, bool mustTick, bool kill) {
+    if (!isInitialized) {
+      throw const SoLoudNotInitializedException();
+    }
+    _controller.soLoudFFI.setInaudibleBehavior(handle, mustTick, kill);
+  }
+
   /// Gets the current maximum active voice count.
   int getMaxActiveVoiceCount() {
     if (!isInitialized) {
@@ -2289,6 +2334,7 @@ interface class SoLoud {
 
   /// Sets the minimum and maximum distance parameters
   /// of a live 3D audio source.
+  /// Default values are 1 and 1000000.
   void set3dSourceMinMaxDistance(
       SoundHandle handle, double minDistance, double maxDistance) {
     _controller.soLoudFFI
@@ -2304,6 +2350,7 @@ interface class SoLoud {
   /// 2 LINEAR_DISTANCE       Linear distance attenuation model
   /// 3 EXPONENTIAL_DISTANCE  Exponential distance attenuation model
   /// ```
+  /// The default values are NO_ATTENUATION and 1.
   ///
   /// See https://solhsa.com/soloud/concepts3d.html.
   void set3dSourceAttenuation(

src/bindings.cpp

@@ -1021,6 +1021,23 @@ extern "C"
         player.get()->setProtectVoice(handle, protect);
     }
 
+    /// Set the inaudible behavior of a live sound. By default,
+    /// if a sound is inaudible, it's paused, and will resume when it
+    /// becomes audible again. With this function you can tell SoLoud
+    /// to either kill the sound if it becomes inaudible, or to keep
+    /// ticking the sound even if it's inaudible.
+    ///
+    /// [handle]  handle to check.
+    /// [mustTick] whether to keep ticking or not when the sound becomes inaudible.
+    /// [kill] whether to kill the sound or not when the sound becomes inaudible.
+    FFI_PLUGIN_EXPORT void setInaudibleBehavior(unsigned int handle, bool mustTick, bool kill)
+    {
+        if (player.get() == nullptr || !player.get()->isInited() ||
+            !player.get()->isValidHandle(handle))
+            return;
+        player.get()->setInaudibleBehavior(handle, mustTick, kill);
+    }
+
     /// Get the current maximum active voice count.
     FFI_PLUGIN_EXPORT unsigned int getMaxActiveVoiceCount()
     {

src/enums.h

@@ -3,6 +3,8 @@
 #ifndef ENUMS_H
 #define ENUMS_H
 
+#include <stdbool.h> // for ffigen to not complain about bool type
+
 /// Possible player errors.
 ///
 /// WARNING: Keep these in sync with `lib/src/enums.dart`.
@@ -127,7 +129,7 @@ typedef struct PCMformat
   unsigned int sampleRate;
   unsigned int channels;
   unsigned int bytesPerSample;
-  BufferPcmType dataType;
+  enum BufferPcmType dataType;
 } PCMformat;
 
 

src/ffi_gen_tmp.h

@@ -19,6 +19,13 @@
 
 //--------------------- copy here the new functions to generate
 
-// Get the current buffer size in bytes of this sound with hash [hash].
-// [hash] the hash of the stream sound.
-FFI_PLUGIN_EXPORT enum PlayerErrors getBufferSize(unsigned int hash, unsigned int *sizeInBytes);
+/// Set the inaudible behavior of a live sound. By default,
+/// if a sound is inaudible, it's paused, and will resume when it
+/// becomes audible again. With this function you can tell SoLoud
+/// to either kill the sound if it becomes inaudible, or to keep
+/// ticking the sound even if it's inaudible.
+///
+/// [handle]  handle to check.
+/// [mustTick] whether to keep ticking or not when the sound becomes inaudible.
+/// [kill] whether to kill the sound or not when the sound becomes inaudible.
+FFI_PLUGIN_EXPORT void setInaudibleBehavior(unsigned int handle, bool mustTick, bool kill);

src/player.cpp

@@ -750,6 +750,11 @@ void Player::setProtectVoice(SoLoud::handle handle, bool protect)
     soloud.setProtectVoice(handle, protect);
 }
 
+void Player::setInaudibleBehavior(SoLoud::handle handle, bool mustTick, bool kill)
+{
+    soloud.setInaudibleBehavior(handle, mustTick, kill);
+}
+
 unsigned int Player::getMaxActiveVoiceCount()
 {
     return soloud.getMaxActiveVoiceCount();

src/player.h

@@ -364,6 +364,13 @@ class Player
     /// https://github.com/jarikomppa/soloud/issues/298
     void setProtectVoice(SoLoud::handle handle, bool protect);
 
+    /// @brief Set the inaudible behavior of a live sound. By default,
+    /// if a sound is inaudible, it's paused, and will resume when it
+    /// becomes audible again. With this function you can tell SoLoud
+    /// to either kill the sound if it becomes inaudible, or to keep
+    /// ticking the sound even if it's inaudible.
+    void setInaudibleBehavior(SoLoud::handle handle, bool mustTick, bool kill);
+
     /// @brief Get the current maximum active voice count.
     unsigned int getMaxActiveVoiceCount();