Propagate playback and voice errors

[Colton127]

Description

Several native paths report success when nothing is playing, so Dart gets back an unusable SoundHandle — or never learns the operation failed at all. This makes those failures observable.

Three commits, each self-contained and independently buildable:

1. soloud: make a failed voice allocation unambiguous

Soloud::play() returned UNKNOWN_ERROR when no voice could be allocated. Handles are encoded as (voice + 1) | (playIndex << 12), so UNKNOWN_ERROR's value — 7 — is itself a legal handle: voice slot 6 with play index 0. mPlayIndex wraps at 0xfffff, so once it comes back around while slots 0–5 are busy, a live voice really does own handle 7 and a failure becomes indistinguishable from it — isValidVoiceHandle() included, since it resolves the value like any other handle.

Callers that didn't re-validate then operated on someone else's voice: playClocked()/playScheduled() applied a delay and unpaused it; play3d()/play3dClocked() flagged it PROCESS_3D and pushed 3D parameters into it.

play() now returns 0, which can never encode a voice (the low 12 bits hold voice + 1) and is already the failure value used by getHandleFromVoice_internal() and every Bus::play*. The four compound helpers bail out on it.

Separately, findFreeVoice_internal() fell through to stopVoice_internal(-1) when every voice was protected, converting -1 to UINT_MAX and indexing mVoice[] out of bounds. It returns -1 now, which play() already handles.

test/voice_allocation_failure_test.cpp reproduces the aliasing state by wrapping the play index. Against the current engine it aborts on the out-of-bounds stopVoice_internal(-1); with the fix all 31 assertions pass. It uses the null backend, so ./test/run_voice_allocation_failure_test.sh needs no audio device.

2. Return real errors from the player

• Device startup: seven playback paths called soloud.resume() and discarded the result, continuing with no usable output. Player::ensureAudioDeviceStarted() is now the single place that inspects it. A voice requested paused is exempt — it makes no sound, so requiring the device would stop callers creating and configuring one during an interruption, and the later setPause() does the check when it unpauses. NOT_IMPLEMENTED counts as success (the backend simply has no pause/resume concept).
• Voice creation: newHandle != 0 checks replaced by an explicit sentinel test; no path registers a value the engine didn't give it. Looping playback rolls back cleanly if the final setPause() fails, rather than handing back a half-initialised handle.
• pauseSwitch(), setPause() and stop() return PlayerErrors. A failed unpause leaves the voice paused.
• textToSpeech() no longer creates bookkeeping — nor the stray empty sounds entry it appended on failure — before the voice exists.
• busPlayOnEngine() reports errors and never stores an invalid bus voice.
• SoLoud results are no longer cast to PlayerErrors. The enums agree only to fileLoadFailed (3), then diverge because PlayerErrors inserts fileAlreadyLoaded at 4. loadFile()/loadMem() reported a genuine OUT_OF_MEMORY as dllNotFound — telling users "The DLL was not found" when a large asset wouldn't fit in memory.
• iOS: a failed AVAudioSession activation is reported instead of starting the Audio Unit against an inactive session.

New errors appended so nothing is renumbered: audioDeviceFailedToStart (34), failedToStartPlayback (35).

3. Surface them in the public API

Playback methods throw on failure and only register a handle after a confirmed valid voice. A failed loadFile()/loadMem() no longer also raises an error nothing can catch — the listener threw after already delivering the same exception through the completer (a throw from a stream listener bypasses onError and escapes to the zone), and the result future was completed with an error before anything listened to it.

Compatibility notes

• pauseSwitch(), setPause(), stop() and Bus.playOnEngine() keep their signatures but can now throw. stop() stays idempotent — a voice ending between Dart's validity check and the native call is treated as success.
• maxActiveVoiceCountReached stays non-blocking: still logged, not thrown, same zeroed handle returned. The only change is that the handle is no longer added to handlesInternal, which is what made it look like a playing sound.
• Regenerated FFI binding inputs and the committed WASM artifact.

Testing

dart format · dart analyze --fatal-infos --fatal-warnings lib/ · flutter analyze · flutter test (12) · native suite (31) · flutter pub publish --dry-run (0 warnings) — all green, and each of the three commits builds and analyzes on its own.

Behaviour verified at runtime on Linux against the rebuilt plugin: play/valid-handle/registration, pause round-trip, stop + idempotency + invalid-handle throws, looping and paused-looping, paused: true creation, clocked, scheduled, 3D, bus, TTS, non-blocking max-voice, and load error mapping. Example builds for Linux and Web (--wasm).

Type of Change

• ✨ New feature (non-breaking change which adds functionality)
• 🛠️ Bug fix (non-breaking change which fixes an issue)
• ❌ Breaking change (fix or feature that would cause existing functionality to change)
• 🧹 Code refactor
• ✅ Build configuration change
• 📝 Documentation
• 🗑️ Chore

[alnitak]

Hey @Colton127, thanks for the thorough work here — the fixes themselves look great!

One request: could you shrink the changelog entry to 2–3 lines? Changelogs are read by end users of the plugin, and an entry this long won't be read — it also buries the part they actually need (e.g. that pauseSwitch/setPause/stop can now throw).
Internal details (handle encoding, error-enum arithmetic, defensive paths no current code can hit) belong in the commit message or PR description, not needed in the changelog. Something along these lines, I think, would be enough:

• 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.
• 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.
• fix: a failed load no longer also raises an uncatchable async error — the future you await is the only error channel now.

Feel free to add/modify this.

[alnitak]

Maybe also:

• added PlayerErrors.audioDeviceFailedToStart and PlayerErrors.failedToStartPlayback (with matching exceptions), so you can catch device/playback startup failures specifically.

[Colton127]

Hey @Colton127, thanks for the thorough work here — the fixes themselves look great!

One request: could you shrink the changelog entry to 2–3 lines? Changelogs are read by end users of the plugin, and an entry this long won't be read — it also buries the part they actually need (e.g. that pauseSwitch/setPause/stop can now throw). Internal details (handle encoding, error-enum arithmetic, defensive paths no current code can hit) belong in the commit message or PR description, not needed in the changelog. Something along these lines, I think, would be enough:

* **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.

* **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.

* **fix: a failed load no longer also raises an uncatchable async error** — the future you `await` is the only error channel now.

Feel free to add/modify this.

Done.