init method

Future<void> init({ PlaybackDevice? device, bool automaticCleanup = false, int sampleRate = 44100, int bufferSize = 2048, Channels channels = Channels.stereo, bool lowLatency = true, AndroidAAudioAttributes androidAAudioAttributes = AndroidAAudioAttributes.mediaMusic, LinuxAudioBackend linuxAudioBackend = LinuxAudioBackend.auto, int? devicePeriodFrames, int? renderAheadFrames, })

Initializes the audio engine.

Run this before anything else, and await its result in a try/catch. Only when this method returns without throwing exceptions will the engine be ready.

If you call any other methods (such as play) before initialization completes, those calls will be ignored and you will get a SoLoudNotInitializedException exception. Could throw SoLoudNoPlaybackDevicesFoundCppException if there is not a playback device available or if the given device is not found.

NOTE: Calling this method while the engine is already initialized will first deinitialize the engine and then reinitialize it. This means that all sounds will be stopped, and all sound files will be unloaded.

If automaticCleanup is true, the temporary directory that the engine uses for storing sound files will be purged occasionally (e.g. on shutdown, and on startup in case shutdown never has the chance to properly finish). This is especially important when the program plays a lot of different files during its lifetime (e.g. a music player loading tracks from the network). For applications and games that play sounds from assets or from the file system, this is probably unnecessary, as the amount of data will be finite. The default is false.

sampleRate The sample rate represents the number of samples used, per second. Typical sample rates are 8000Hz, 22050Hz, 44100Hz and 48000Hz. Higher the sample rates mean clearer sound, but also bigger files, more memory and higher processing power requirements.

bufferSize Audio latency generally means the time it takes from triggering a sound to the sound actually coming out of the speakers. The smaller the latency, the better.

Unfortunately, there's always some latency. The primary source of latency (that a programmer can have any control over) is the size of audio buffer. Generally speaking, the smaller the buffer, the lower the latency, but at the same time, the smaller the buffer, the more likely the system hits buffer underruns (ie, the play head marches on but there's no data ready to be played) and the sound breaks down horribly. The default value is 2048.

channels mono, stereo, quad, 5.1, 7.1.

lowLatency selects the audio backend's performance profile and defaults to true (the historical behavior). On Android the low-latency profile uses AAudio's MMAP path, which cannot be captured by system screen recorders and leaves little CPU headroom for heavy filters (e.g. the FFT pitch shift). Pass false to use the conservative (legacy mixer) profile instead: the output becomes capturable by screen recording and gains callback headroom for DSP, at the cost of higher output latency. Only the native (miniaudio) backends honor this; the Web backend ignores it.

androidAAudioAttributes (Android, native, lowLatency: false only) controls the AAudio stream's AudioAttributes. The default AndroidAAudioAttributes.mediaMusic tags the stream as usage = media / contentType = music — sensible for a media app and capturable by screen recorders. Pass AndroidAAudioAttributes.unmanaged if you set the app's attributes/focus yourself (e.g. via the audio_session plugin): SoLoud then leaves usage/contentType unset so they don't fight your configuration. Either way the choice is preserved across output-device changes. (Note these are the stream's attributes; audio_session controls the focus request — for correct ducking they should match.) Ignored when lowLatency is true, on non-Android platforms, and on web.

devicePeriodFrames (native only) the output device period in frames used when renderAheadFrames enables the render-ahead ring. Smaller values reduce the output-path jitter and the granularity at which new audio reaches the device, at the cost of more frequent device callbacks. Defaults to 512 when omitted. Ignored when renderAheadFrames is not set and on web.

renderAheadFrames (native only) enables the render-ahead ring: the engine mixes this many frames ahead of the output device into an engine-owned ring buffer, decoupling the device period from bufferSize. This is the prerequisite for low-latency reactive playback with large mix buffers. When null or 0 (the default) the engine mixes directly into the device callback as before. Ignored on web.

Implementation

Future<void> init({
  PlaybackDevice? device,
  bool automaticCleanup = false,
  int sampleRate = 44100,
  int bufferSize = 2048,
  Channels channels = Channels.stereo,
  bool lowLatency = true,
  AndroidAAudioAttributes androidAAudioAttributes =
      AndroidAAudioAttributes.mediaMusic,
  LinuxAudioBackend linuxAudioBackend = LinuxAudioBackend.auto,
  int? devicePeriodFrames,
  int? renderAheadFrames,
}) {
  final requestGeneration = _lifecycleGeneration;
  final previous = _pendingInitialization;
  final initialization = _runQueuedInitialization(
    previous: previous,
    requestGeneration: requestGeneration,
    device: device,
    automaticCleanup: automaticCleanup,
    sampleRate: sampleRate,
    bufferSize: bufferSize,
    channels: channels,
    lowLatency: lowLatency,
    androidAAudioAttributes: androidAAudioAttributes,
    linuxAudioBackend: linuxAudioBackend,
    devicePeriodFrames: devicePeriodFrames,
    renderAheadFrames: renderAheadFrames,
  );
  _pendingInitialization = initialization;
  return initialization.whenComplete(() {
    if (identical(_pendingInitialization, initialization)) {
      _pendingInitialization = null;
    }
  });
}