flutter_soloud

• fix: a device change that still fails now reports SoLoudAudioDeviceFailedToStartCppException instead of hanging. Thanks to @Colton127 #533
• fix: changeDevice() now selects the system default device when called without an argument and reports device-change failures instead of silently succeeding. Thanks to @Colton127 #533
• fix: init() no longer blocks the UI thread while the audio device starts. On Android a slow or busy audio HAL could stall the platform thread long enough for the app to be reported as not responding; engine startup and teardown now run on a short-lived worker isolate. Thanks to @Colton127 #533
• added deinitAsync(), a non-blocking counterpart to deinit(). deinit() is unchanged and still supported, but it can stall the UI thread when it lands while init() is still starting the device — prefer deinitAsync() in new code. Thanks to @Colton127 #533

• fix: iOS/macOS SPM build fails with error: unknown argument: '-Wl,-undefined,dynamic_lookup' #530
• web: dropped -pthread/SharedArrayBuffer from the WASM build. The requirement for COOP/COEP headers (cross-origin isolation) is gone and the plugin now works on hosts that cannot set them (e.g. game portals like CrazyGames/Poki). Moving the use of threads for a future release #523

• fix web: crash with --optimization-level=0 due to HEAPU8.buffer declared as JSArrayBuffer #526
• fix: missing guard for NO_XIPH_LIBS that prevents building when using it #528
• fix: playback errors are no longer silently ignored. play (and its variants), pauseSwitch, setPause and stop now report failures instead of returning success with an unusable handle. Note: these methods can now throw where they previously failed silently. Thanks to @Colton127 #527
  • added PlayerErrors.audioDeviceFailedToStart and PlayerErrors.failedToStartPlayback (with matching exceptions), so you can catch device/playback startup failures specifically.
• fix: wrong exceptions for loadFile/loadMem/seek. Out-of-memory and not-implemented errors were mapped to unrelated exceptions (e.g. "DLL not found" for low memory); they now throw the correct ones. Thanks to @Colton127 #527
• fix: a failed load no longer also raises an uncatchable async error — the future you await is the only error channel now. Thanks to @Colton127 #527

• fix: the voice-ended callback is no longer invoked while SoLoud's audio mutex is held. The symptom was a wedged engine: handles and sources still looked valid, no audio was produced, and deinit() never completed. Ended voices are now queued and dispatched once the mutex is released. Thanks to @Colton127 #518
• fix: on macOS/iOS, the first CocoaPods build after a clean no longer fails with "Build input file cannot be found: libflutter_soloud_plugin.a"
• fix: deactivate a sound filter couldn't be activate again #525

• another SPM fix: add wav_stream_decoder.cpp to SPM unity build (crash on Apple platforms)

• now when passing a time <= 0 to fadeFilterParameter or to oscillateFilterParameter the value is set. Before was a no-op #519
• added tests to check set, get, fade parameters for all the filters.

• ios SPM fix: include mixer_output with relative path #514

What's Changed

• get rid of stb_vorbis c file in favor of the Xiph OGG libraries by @alnitak in #491
• feat: capture the master mixer output as a Stream<Uint8List> by @alnitak in #495
• feat: add an isolate-safe singleton for running mixer output capture by @alnitak in #497
• feat: add native loop end points by @Kunstderfug in #499
• Add SUMOJI game to the list of apps by @3vmartinet in #506
• feat: pull buffer streaming support by @alnitak in #503
• feat: add playClocked/play3dClocked with sample-accurate scheduling by @alnitak in #505
• feat: add getEngineTime, playScheduled, stopScheduled and fadeScheduled (extends #505) by @alnitak in #509
• fix: stop() can throw uncaught "Bad state: Future already completed" when the native voiceEnded event races the internal 300 ms timeout by @alnitak in #510
• Output a warning when NO_OPUS_OGG_LIBS is set by @filiph in #511
• version 4.1.0 by @alnitak in #512

New Contributors

• @3vmartinet made their first contribution in #506

Full Changelog: v4.0.13...v4.1.0

• added pull-buffer streaming API (setPullBufferStream, addPullBufferDataStream, getPullBufferTimeRange) with support for MP3, WAV, FLAC, Ogg Opus, Ogg Vorbis, and Ogg FLAC.
• get rid of stb_vorbis c file in favor of the Xiph OGG libraries for Opus, Vorbis, and FLAC.
• buffer stream now supports FLAC and WAV formats besides Ogg with Opus, Vorbis, and FLAC containers.
• reduced initial buffer data from 32 to 4 KB to let the buffer to start playing faster.
• now the auto-pause when the buffer needs more audio works as expected and respect the player pause state (it doesn't automatically unpause when there is enough data in the buffer if the player was paused).
• websocket example: added play/pause and touch to seek to the buffer visual widget.
• added autoDispose parameter to setBufferStream to automatically dispose the sound when it is finished. This eliminates the need to manually call disposeSource.
• added mixer output capture: capture the master mixer output as a Stream<Uint8List> in PCM (F32LE, S8, S16LE, S32LE) or compressed formats (Opus, Vorbis, FLAC, WAV). See SoLoud.startMixerOutputStream / stopMixerOutputStream / isMixerOutputStreamRunning.
• added mixer_capture example (example/lib/mixer_capture/mixer_capture.dart) that shows how to capture the master mix and save it to a file.
• web note: the web build requires --wasm (or any server that sends Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp headers) because the WASM module uses SharedArrayBuffer for the audio thread. Running with flutter run -d chrome without --wasm is not supported by the default dev server. Please see the doc here.
• added SoLoudIsolate, an isolate-safe singleton for running mixer output capture (and other safe operations, for now only readSamplesFrom*) from a non-main isolate without touching the main isolate's loader, filters, or event callbacks.
• added example/lib/mixer_capture/isolate_capture_test.dart to demostrate mixer output capture from a separate isolate.
• added native loop end points through loopingEndAt and the live getLoopEndPoint / setLoopEndPoint APIs, allowing half-open [start, end) loop regions #499. Thanks to @Kunstderfug
• added playClocked and play3dClocked (plus Bus.playClocked / Bus.play3dClocked) for sample-accurate scheduled playback, along with the related setDelaySamples, getStreamTime and resetStreamTime (re-anchor the clocked-play clock) APIs. The sounds are spaced with sub-millisecond accuracy regardless of the engine buffer size instead of clumping at buffer boundaries.
• added a "use playClocked" checkbox to the metronome example to show the difference between play and playClocked.
• added getEngineTime, playScheduled, stopScheduled and fadeScheduled (plus Bus.playScheduled) for score/manifest-style scheduling pinned to the engine's own clock: read getEngineTime once and schedule a batch of sounds at absolute engine times, with sample accuracy and no ~2 s window limit like playClocked. playScheduled accepts an optional duration to stop the sound automatically, and fadeScheduled a thenStop flag to stop the sound when the fade ends. Scheduled stops are sample-accurate (not quantized to output buffer boundaries like scheduleStop).
• fix shutdown crash "Callback invoked after it has been deleted": deinit() now stops the engine (joining the audio thread) before closing the Dart NativeCallable trampolines, so voices ending from the mixing thread can no longer call into deleted callbacks while tearing down.
• fix: stop() can throw uncaught "Bad state: Future already completed" when the native voiceEnded event races the internal 300 ms timeout #510
• output a warning when NO_OPUS_OGG_LIBS is set #511. Thanks to @filiph

• fix: Waveform audio sources do not match engine sample rate #501. Thanks to @Colton127

• add lowLatency init option to allow recordable Android output #492. Thanks to @MjnMixael
• added WAV to Buffer streams supported formats. Fixes loading wav files from web #494

• fix web: don't spawn the deferred-pause std::thread on web (Aborted() in initEngine) #488. Thanks to @felixmin

• wait some ms to pause device when there are no more sounds playing #486

• Windows: prevent the compiler from complaining about min and max macros. Fixes #483

• fix released buffer stream size reporting #480. Thanks to @Kunstderfug
• load Ogg Opus/flac files through buffer stream fallback #479. Thanks to @Kunstderfug

• add look-ahead brickwall limiter and fix planar DSP indexing #468. Thanks to @Kunstderfug
• fix iOS CocoaPods wrapper double compile #467. Thanks to @DavidPluxia
• fix Apple: added linker settings to not strip symbols when building the ipa using SPM #472
• Android fix: fix audio crackling using BufferingType.released on some Android devices #476
• Android fix: quick play & stop causes glitches and probably UI jank #478
• fix: the wet parameter of parametric eq was not evaluated #477

• Fix iOS SPM miniaudio duplicate symbols #465. Thanks to @coolswood

• fix sample count calculations in BufferStreamInstance and BufferStream #462
• fix Apple: removed hardcoded -flto compile arg in Package.swift #463
• prevent header name collision build error when the app uses other native plugins like flutter_zxing which uses the common.h source file name too #464

• fix Apple: build forcing to add c++ std lib #456
• fix reading Opus with non-standard samplerate #457

• fix: rebind Dart callbacks after hot restart #444. Thanks to @skylartaylor
• fix: retain BufferStream callbacks until disposal #445. Thanks to @skylartaylor
• fix: removed the asserts in the init method #453
• web fix: small sound bleed after stop and play #446
• web fix: new way to load audio from memory (loadAssets and loadMem) on web to solve UI freeze when loading

• apple: fix building issue with XCode

• fixed get eq params other than bands values
• added frequency getter to parametric equalizer (ie: soloud.filters.parametricEqFilter.bandFrequency(index))
• removed some warnings from native build
• warn mac users to install cmake if not already installed

• fix: some OGG audio files don't trigger SoundEventType.handleIsNoMoreValid
• fix: setBufferStream fails to decode small MP3 files under 32 KB #434. Thanks to @chaudharydeepanshu
• fix web: createVoiceGroup return was interpreted as a signed int instead of an unsigned because it always has the sign bit flag
• fixed switching output devices on macOS and maybe on other platforms, didn't initialize the new one correctly
• added some more tests
• removed deprecated equalizerFilter in favor of parametricEqFilter

• fix: FFI symbol stripping causing "symbol not found" errors in iOS/macOS when uploading to App Store #431
• fix decreasing volume when adding a bus to another

• macOS/iOS fix: check for cmake in the path while building
• iOS simulator: fix libs linking

• macOS fix: build error

• added Mixing Bus feature and example https://docs.page/alnitak/flutter_soloud_docs/advanced/mixing_bus
• added getApproximateVolume to get the approximate volume of a channel of the player
• added autoDispose parameter to load* methods to automatically dispose the sound when it is finished. This eliminates the need to manually call disposeSource
• added playSource to play a source from assets, URLs, or a file and automatically dispose of its AudioSource when it is finished
• added filters/parametric_eq.dart example
• added parametric equalizer with 1 to 64 bands and FFT window size from 32 to 4096 for quality and performance
• added Swift Package Manager support
• improved quality and performance of the pitchshift filter #313
• CocoaPods now uses cmake to compile the plugin always in release mode for macOS and iOS
• conditional import of js and wasm only on web (no more included on other platforms)
• win fix: UTF8 file name conversion was causing crash or file not found #427
• fixed a possible crash during app shutdown
• possible fix for #333 which caused an ANR on Android when stopping/deinit or closing the app
• Linux feat: choose to link ogg, opus, vorbis, and flac libraries from the system with TRY_SYSTEM_LIBS_FIRST=1 environment variable #421. Useful for Raspberry Pi because the precompiled libs are available only for x86_64.
• Android fix: elevate audio thread priority on Android #396. Thanks to @djkingCanada
• Android: build optimizations

breaking changes

• bump Flutter version to 3.41.0 and Dart to 3.11.0
• play, play3d, speechText, are now sync
• renamed NO_OPUS_OGG_LIBS environment variable to NO_XIPH_LIBS
• renamed SoLoudOpusOggVorbisLibsNotAvailableException to SoLoudXiphLibsNotAvailableException
• renamed areOpusOggLibsAvailable to areXiphLibsAvailable

• remove wasm/js assets for non-web builds#425. Thanks to @adil192

• fix: compilation error on Windows #423

• fix: wire miniaudio backend pause/resume to stop AudioUnit on iOS #406. Thanks to @sbauly
• updated audio_context example to demostrate how to integrate with audio_session and audio_service

• getStreamTimeConsumed returns the wrong time for s16le and s8 #419
• win fix: hang on app exit #413
• win fix: prevent Windows message pump from going unresponsive with plugins like desktop_drop and maybe others #401
• fix: only unpause when buffer covers playback position #393. Thanks to @nukes
• wasm fix: runtimeType error when voice ended #414

• Harden loader temp directory logic #404. Thanks to @filiph
• updated audio_context example

• fix loadMem issue after deinit #399

• fix crash when seeking with a negative value #386
• Linux fix: don't use -msse on arm64 builds #395. Thanks to @adil192
• Android fix: enable AAudio with runtime API level check for safe fallback #397. Thanks to @djkingCanada

• fix MP3 stream decoding missing last few seconds of audio #381

• fix: null check before accessing sound in seek() #384. Thanks to @9AZX

• win fix: loadMem/loadAsset futures never finish when run in parallel with the same file #376

• fixed Bad state: Future already completed error during integration tests. Thanks to @Taormina #373
• win: don't copy pdb file when in profile mode avoiding build error. Fixes #372

• fix: Crash during hot-restart using Dart 3.10 #369

• fix Android: crashes after opus stream playback #365
• fix: Compressor seems to introduce "choppy" sound #367

• fix Android: NO_OPUS_OGG_LIBS for Android build used in gradle.properties not always worked #358. And Thanks to @mingjunsiek #361 #354
• fix: memory leak in FlutterSoLoudFfi.addAudioDataStream #359. Thanks to @DarthRainbows

• crash when adding data as PCM data on v3.4.0 #348
• builds failing for macOS with NO_OPUS_OGG_LIBS=1 #350
• using AudioData.getAudioData, when wave data is zero, also the FFT data should be zero #349

• added support for OGG FLAC and its metadata to BufferStream #294
• fix Opus BufferStream end clicks on short sounds #344. Thanks to @eddyleelin
• fix a crash on old Windows PCs with CPUs that don't support AVX2 extensions (using now SSE2) #340
• fixed Player::findByHandle crash in some circumstancies #342

• iOS: revert the fix for #330
• removed experimental tag for allInstancesFinished

• fix: audio stream with released mode failed to consume BufferStream #335 #318
• iOS fix: maybe fixed no sound probably in older iOS devices without AirPods #330
• fix: incorrect seek position on multi-channel audio streams #328

• iOS fix: update build_iOS.sh to make fat libraries #315. Thanks to @kumamotone
• fix: stop() takes too much time #312

• win fix: compilation error #309

• fix sample rate detection for Opus and Vorbis audio streams

• use of dr_mp3.h instead of minimp3 for streaming MP3
• fix crash when calling addAudioDataStream before play #306

• fix seek a buffer stream actually seeks at half the wanted position #296

• fixed stuttering with MP3 streams #301
• fixed a Web bug when compiling with WASM in release mode.

• fix win: fix build error #292

• Added support for mp3 streams
• Added support for Vorbis streams
• Added web_radio.dart example to demonstrate how to receive an audio stream (ie, an icecast stream) and then add the audio chunks to BufferStream
• Add BufferType.auto to auto detect ogg/opus/vorbis/mp3 streams
• Deprecate BufferType.opus in favor of BufferType.auto
• Get TAGs info also while streaming and not only by sending chunks of an audio file. For MP3s, the TAGs are obtained from ID3V2 or passing icy-metaint (obtained from the header of the online stream) before adding audio chunks to the BufferStream. New metadata is notified by the onMetadata callback of setBufferStream

• feat: allow to specify NO_OPUS_OGG_LIBS in Android build config #282. Thanks to @ekuleshov
• fix: 16KB memory page size for Android because of Play Console warning #283
• fix pub points

• macos fix: abseil not found when using this plugin with some other native plugins like firebase #280. Thanks to @jochy.

• ios fix: abseil not found when using this plugin with some other native plugins like firebase #271

• fix 16 KB native library alignment on Android #248
• fix build issue on iOS and macOS #265 #266
• fix: the seek method was causing inconsistent behavior when using BufferStream in BufferingType.released mode. It is now supported in BufferingType.preserved mode.

• OGG is now also supported using readSamplesFrom* methods.
• fix getPosition and buffering for released buffer.