just_audio_engine 1.0.0

High-performance audio processing pipeline for just_game_engine. Supports all platforms with native backends (AVAudioEngine, XAudio2, OpenAL) and Web Audio API.

Just Audio Engine

High-performance audio pipeline for just_game_engine.

just_audio_engine provides a single Dart façade over platform-native backends — AVAudioEngine on iOS/macOS, XAudio2 on Windows, OpenAL on Android/Linux, and the Web Audio API on web — so your audio code is identical across every target.

---

Features

• BGM — background music with fade-in/fade-out, loop, and cross-fade when switching tracks
• SFX — one-shot and looping sound effects; returns a clip ID for per-voice volume, pan, pitch, and speed control
• Channel routing — five logical channels (master, music, sfx, voice, ambient) each backed by an AudioBus
• DSP effects — reverb, lowpass, highpass, EQ, delay, chorus, distortion applied per voice
• Spatial 3D audio — Audio3DListener + Audio3DPosition for distance-based attenuation and panning
• Chunked streaming — AudioStream loads large files in chunks to keep memory usage flat
• Voice pool — up to 64 concurrent voices; oldest unprotected voice is evicted on overflow
• Convenience managers — MusicManager and SoundEffectManager for common patterns with less boilerplate

---

Getting started

Add the dependency to your pubspec.yaml:

dependencies:
  just_audio_engine: ^1.0.0

just_audio_engine is initialised automatically when it is first used (lazy init), but you can initialise it explicitly at startup:

final audio = AudioEngine();
await audio.initialize();

When used inside just_game_engine, the engine exposes pre-built managers:

final engine = Engine();
// engine.audio  → AudioEngine
// engine.music  → MusicManager
// engine.sfx    → SoundEffectManager

---

Usage

Background music

// Play with a 2-second fade-in, loop forever
await engine.music.play(
  'assets/audio/bgm.mp3',
  loop: true,
  fadeIn: true,
  fadeDuration: const Duration(seconds: 2),
);

engine.music.pause();
engine.music.resume();
engine.music.stop(fadeOut: true);
engine.music.setChannelVolume(0.7);

Sound effects

// Fire a one-shot SFX — returns an opaque ID for per-voice control
final id = await engine.sfx.play(
  'assets/audio/hit.wav',
  volume: 0.8,
  pan: -0.5,
  pitch: 1.2,
  speed: 0.9,
);

// Per-voice control while it's playing
engine.audio.setSfxVolume(id!, 0.5);
engine.audio.pauseSfx(id!);
engine.audio.resumeSfx(id!);
engine.audio.stopSfx(id!);

// Stop every active SFX at once
engine.audio.stopAllSfx();

Channel volume & mute

engine.audio.setMasterVolume(1.0);
engine.audio.setChannelVolume(AudioChannel.music,   0.7);
engine.audio.setChannelVolume(AudioChannel.sfx,     1.0);
engine.audio.setChannelVolume(AudioChannel.voice,   0.9);
engine.audio.setChannelVolume(AudioChannel.ambient, 0.5);

engine.audio.mute();
engine.audio.unmute();
engine.audio.toggleMute();
engine.audio.isMuted; // → bool

DSP effects

Effects are applied per voice at play time:

await engine.audio.playSfx(
  'assets/audio/hit.wav',
  effects: [
    AudioEffect.reverb(roomSize: 0.8, damping: 0.5, wetLevel: 0.4),
    AudioEffect.lowpass(frequency: 800, q: 1.0),
    AudioEffect.highpass(frequency: 200, q: 1.0),
    AudioEffect.delay(delayMs: 250, feedback: 0.3, mix: 0.3),
    AudioEffect.eq(frequency: 1000, gain: 3.0, q: 1.0),
  ],
);

Spatial 3D audio

// Call every frame to update the listener
engine.audio.setListener3D(Audio3DListener(
  position: Audio3DPosition(player.x, player.y, 0),
  forward:  const Audio3DPosition(0, 0, -1),
  up:       const Audio3DPosition(0, 1, 0),
));

// Call every frame to update a moving source
engine.audio.updateSfxPosition(sfxId, Audio3DPosition(emitter.x, emitter.y, 0));

Chunked streaming

Use AudioStream for music or long ambient loops to avoid loading the whole file into memory:

final stream = AudioStream(
  path: 'assets/audio/bgm.mp3',
  channel: AudioChannel.music,
);
await stream.open(engine.audio.backend);
await stream.play(volume: 0.8, loop: true);

await stream.setVolume(0.5);
await stream.fade(0.0, const Duration(seconds: 2));
await stream.pause();
await stream.resume();
await stream.stop();
await stream.dispose();

---

Platform support

Platform	Backend
Android	OpenAL (via NDK)
iOS	AVAudioEngine
macOS	AVAudioEngine
Windows	XAudio2
Linux	OpenAL
Web	Web Audio API

---

Additional information

• Source — github.com/just-unknown-dev/just-audio-engine
• Issues — file bugs and feature requests on the GitHub issue tracker
• Contributing — see CONTRIBUTING.md
• Code of Conduct — see CODE_OF_CONDUCT.md