Flutter Soloud 3D Audio

flutter_soloud wraps the SoLoud C++ engine's built-in 3D audio. Every voice started with play3d has a 3D position and velocity; a single global "listener" (usually your camera or player) hears them. The coordinate system is right-handed (Y up, X right, Z toward the viewer). Unlike audioplayers/just_audio there is no asset "player" object per sound: you get a SoundHandle per playing instance and mutate its 3D state through SoLoud.instance setters. Also unlike the web Audio API, SoLoud does not move anything for you — positions and velocities are snapshots you must update yourself each tick.

Minimal example

import 'package:flutter_soloud/flutter_soloud.dart';

Future<void> main() async {
  await SoLoud.instance.init();

  final sound = await SoLoud.instance.loadAsset('assets/sfx/whoosh.mp3');

  // Listener at origin, looking down -Z, head up along +Y.
  SoLoud.instance.set3dListenerParameters(
    0, 0, 0, // position
    0, 0, -1, // at (looking direction)
    0, 1, 0, // up
    0, 0, 0, // velocity (needed for Doppler)
  );

  // Play at (10, 0, -5) moving toward the listener at 5 units/s.
  final handle = SoLoud.instance.play3d(
    sound,
    10, 0, -5, // posX, posY, posZ (positional!)
    velX: -5, // velocity, for Doppler
    looping: true,
  );

  // Required to hear distance falloff — default attenuation is NONE.
  SoLoud.instance.set3dSourceAttenuation(handle, 2, 1); // linear
  SoLoud.instance.set3dSourceMinMaxDistance(handle, 1, 50);
}

The API shape

All methods are on SoLoud.instance (singleton), all positions/velocities are double in your world units. Playback methods return SoundHandle synchronously (not a Future) — different from the Future<...>-returning patterns in other packages.

Playback (all throw SoLoudNotInitializedException if you skipped init):

• SoundHandle play3d(AudioSource sound, double posX, double posY, double posZ, {double velX = 0, double velY = 0, double velZ = 0, int busId = 0, double volume = 1, bool paused = false, bool looping = false, Duration loopingStartAt = Duration.zero, Duration? loopingEndAt, int? loopingStartOffsetAt, int? loopingEndOffsetAt, double scale = 1}) — one-shot, lowest latency; start is quantized to output-buffer boundaries.
• SoundHandle play3dClocked(AudioSource sound, Duration soundTime, double posX, double posY, double posZ, {...}) — pass your app's monotonically increasing "physics time"; the engine spaces rapid-fire sounds sample-accurately so they don't clump at the next buffer boundary. Costs ~2 buffers of latency. Use for machine-gun / rhythmic 3D SFX.
• SoundHandle play3dScheduled(AudioSource sound, Duration atTime, double posX, double posY, double posZ, {Duration? duration, ...}) — starts at an absolute engine time (SoLoud.instance.getEngineTime()), sample-accurate; duration auto-stops it at atTime + duration.

Listener (one global listener; default position is (0,0,0)):

• set3dListenerParameters(posX, posY, posZ, atX, atY, atZ, upX, upY, upZ, velocityX, velocityY, velocityZ) — 12 positional doubles, no named parameters.
• set3dListenerPosition(x, y, z) / set3dListenerAt(x, y, z) / set3dListenerUp(x, y, z) / set3dListenerVelocity(x, y, z) — individual setters. at is the look direction; up is the head-up vector.

Per-source (take the SoundHandle returned by play3d*):

• set3dSourceParameters(handle, posX, posY, posZ, velocityX, velocityY, velocityZ) — positional doubles.
• set3dSourcePosition(handle, x, y, z) / set3dSourceVelocity(handle, x, y, z).
• set3dSourceMinMaxDistance(handle, minDistance, maxDistance) — defaults are 1 and 1000000. Inside min the sound is at full volume; beyond max it no longer gets quieter.
• set3dSourceAttenuation(handle, int attenuationModel, double attenuationRolloffFactor) — models: 0 NO_ATTENUATION, 1 INVERSE_DISTANCE, 2 LINEAR_DISTANCE, 3 EXPONENTIAL_DISTANCE. Default is 0 (none) with rolloff 1.
• set3dSourceDopplerFactor(handle, double dopplerFactor) — 0 disables, 1 normal, >1 exaggerated.

Global Doppler tuning:

• set3dSoundSpeed(double speed) / double get3dSoundSpeed() — default 343 (meters/second in dry air at ~20 °C). SoLoud doesn't know your unit scale, so if 1 world unit ≠ 1 meter, scale the sound speed accordingly or Doppler will be wrong.

Per-frame update pattern

Nothing moves unless you move it. In your game loop / Ticker / onTick:

void update(double dt) {
  // Listener follows the camera/player every frame.
  SoLoud.instance.set3dListenerParameters(
    cam.x, cam.y, cam.z,
    cam.forwardX, cam.forwardY, cam.forwardZ,
    cam.upX, cam.upY, cam.upZ,
    cam.velX, cam.velY, cam.velZ, // for Doppler
  );

  // Each moving emitter updates position AND velocity.
  for (final e in movingEmitters) {
    SoLoud.instance.set3dSourceParameters(
      e.handle, e.x, e.y, e.z, e.vx, e.vy, e.vz,
    );
  }
}