Flutter SoLoud Audio Loading

Loading in flutter_soloud is a two-step model, unlike audioplayers/just_audio: you first load bytes into the SoLoud C++ engine and get an AudioSource handle, then play() it any number of times, and finally dispose it yourself. There is no setUrl/AudioPlayer object that owns a resource for you — the AudioSource is just a hash (soundHash) referencing native memory until you dispose it.

Minimal example

import 'package:flutter_soloud/flutter_soloud.dart';

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

  final source = await SoLoud.instance.loadAsset(
    'assets/sound.mp3',
    autoDispose: true, // disposed automatically when playback finishes
  );

  final handle = SoLoud.instance.play(source);
  // One source, many concurrent instances:
  final handle2 = SoLoud.instance.play(source);

  // If not using autoDispose, dispose manually when done:
  await SoLoud.instance.disposeSource(source);
}

The API shape

All loaders are on SoLoud.instance and require await SoLoud.instance.init() first (otherwise every loader throws SoLoudNotInitializedException).

• Future<AudioSource> loadAsset(String key, {LoadMode mode = LoadMode.memory, AssetBundle? assetBundle, bool autoDispose = false}) — key is an asset key like 'assets/sound.mp3' (NOT a file path). On native, the asset is copied to a temp file and loaded from there. On Web it reads the bundle bytes and delegates to loadMem, so it works everywhere.
• Future<AudioSource> loadMem(String path, Uint8List buffer, {LoadMode mode = LoadMode.memory, bool autoDispose = false}) — buffer is the bytes of a supported audio file (MP3/WAV/OGG/FLAC), not raw PCM. path is only a reference name to distinguish this buffer (e.g. 'my_sound.mp3'), not a real filesystem path. The only loader usable on Web (and the one loadAsset/loadUrl delegate to there); on Web mode is ignored and data is fed to the engine in chunks, yielding to the event loop to keep the UI responsive.
• Future<AudioSource> loadFile(String path, {LoadMode mode = LoadMode.memory, bool autoDispose = false}) — absolute filesystem path. NOT available on Web (use loadMem instead).
• Future<AudioSource> loadUrl(String url, {LoadMode mode = LoadMode.memory, http.Client? httpClient, bool autoDispose = false}) — downloads the file, then loads it (temp file on native, loadMem on Web). Non-200 status throws SoLoudNetworkStatusCodeException. Pass your own http.Client when loading many URLs at startup — otherwise a new client is created per call. On Web the request is subject to normal CORS rules.
• Future<AudioSource> joinTwoSources(String path, Uint8List bufferLeft, Uint8List bufferRight, {bool autoDispose = false}) — builds one stereo AudioSource from two buffers (bytes of supported audio files). Non-mono input is converted to mono on the native side; both sides are resampled to the engine sample rate; if lengths differ, the shorter side is padded with silence to match the longer. Always loads fully into RAM (LoadMode.memory), no mode parameter.

LoadMode

enum LoadMode {
  memory, // decode entire file into RAM: less CPU, low latency, fast seek
  disk,   // stream chunks from the file: less RAM, more CPU
}

Use memory (the default) for sound effects and anything you seek. Use disk for large background music — but note that with disk mode, seeking lags with MP3s.

Supported formats:

• Core formats: MP3, WAV, OGG (Vorbis/Opus/FLAC), FLAC.
• OS-native formats (via platform decoders on macOS, iOS, Android, Windows, Web, Linux): M4A, MP4 (audio tracks), AAC, AC-3 (Dolby Digital), and E-AC-3 (Dolby Digital Plus). Linux note: On Linux, decoding these formats requires FFmpeg shared libraries (libavcodec and libavformat) installed on the host system (e.g. sudo apt install ffmpeg libavcodec-extra, sudo pacman -S ffmpeg, or sudo dnf install ffmpeg-free). Core formats work out of the box without FFmpeg.

[!NOTE] MP4 and M4A containers are supported for file, asset, URL, and memory loading, but are NOT supported for chunk streaming (setBufferStream/setPullBufferStream). For real-time streaming, use elementary streams such as AAC ADTS, AC-3, E-AC-3, OGG, MP3, WAV, or raw PCM.

AudioSource lifecycle

AudioSource cannot be constructed directly; loaders return it.

• await SoLoud.instance.disposeSource(source) — stops all handles of the source and reclaims memory. Never play() a disposed source.
• await SoLoud.instance.disposeAllSources() — disposes everything loaded (not needed at engine shutdown).
• SoLoud.instance.isValidAudioSource(source) — true while the source is loaded.
• source.autoDispose (settable property or loader parameter) — when true, the source is disposed automatically once all its handles finish. Ideal for one-shot SFX; don't use for sources you replay.
• source.soundPath — the parameter (file path, asset key, URL, or buffer identifier) used to load this audio source ('' for waveforms/speech).
• source.tempFilePath — the path to the temporary file created on disk when loading an asset or URL on native platforms ('' if none was created).
• source.handles — unmodifiable set of SoundHandles of currently playing instances.
• source.soundEvents — broadcast stream of ({SoundEventType event, AudioSource sound, SoundHandle handle}) records. SoundEventType has only handleIsNoMoreValid (a handle finished or was stopped) and soundDisposed.
• source.allInstancesFinished — stream that fires each time the count of playing instances drops to zero; the safe-dispose signal:

source.allInstancesFinished.first.then((_) {
  SoLoud.instance.disposeSource(source);
});
SoLoud.instance.play(source);