Devlog

How We Built Reliable Game Sound Effects in Flutter with SoLoud

Five colored lantern tiles with separate glowing sound ripples and overlapping trails of light

Place a lantern in Yodoku and a small, bright note rings out. Place another and the pitch rises. Finish the garden and the last lantern sounds together with a little celebration. It is a quiet game, but those tiny sounds do useful work: they make a move feel complete.

Getting that experience right takes more than calling a player’s play() method. A second tap should not cut off the first note. Muting should stop both the sound you hear and the sound still waiting to load. Leaving the board should not let an old effect appear on the next screen.

For these Flutter game effects, we use flutter_soloud, a Dart interface to the native SoLoud audio engine. We moved Yodoku and Find the Pets from pooled audio players to a small shared service built around SoLoud’s playback handles. Here is what changed, what the library takes care of, and the app behavior we still had to build around it.

First, listen to the lanterns

Yodoku’s placement notes follow D, E, F♯, A, and B, then continue in the next octave for larger gardens. The note depends on how many lanterns are on the board, rather than the color of the tile. Each new note is slightly quieter, keeping the higher pitches gentle.

A little lantern keyboard

Tap a note, then another before it fades. Or play the same note three times and listen to the overlapping tails.

Listen to each placement note with the audio players below.

These are Yodoku’s original sound files, played here by your browser. The keyboard illustrates the sounds and their overlap; it does not measure Flutter’s audio latency.

The sound files are synthesized offline from oscillators, envelopes, deterministic noise, and short reflections. They are bundled WAVs, so playing a lantern does not require generating audio or downloading it during a game. That also gives the playback system a simple job: prepare a small set of known sounds and make each requested instance behave properly.

Where the pooled-player approach got awkward

The first shared implementation used audioplayers and its AudioPool. Pooling is a sensible starting point for game effects: prepare players in advance, borrow one when a sound is needed, and return it for reuse. It avoids creating a whole new player for every tap.

Our implementation also had to decide when a borrowed player was finished. It read the duration from the WAV file and scheduled a stop for that duration plus 80 milliseconds. If the duration could not be read, it used a two-second fallback.

That is an estimate of the sound’s lifetime. The file tells us how much audio it contains, but the app’s timer does not observe when the native output actually begins or ends. Loading, output-device startup, and callbacks all have their own timing. Once players are reused, a delayed piece of cleanup also needs to be kept away from a newer playback.

This is a particularly relevant distinction in Android’s low-latency player mode: audioplayers documents that duration, position, and playback-completion events are unavailable in that mode. The package supports several kinds of playback. Our short-effects service needed a lifetime model we could use consistently for overlapping sounds.

We wanted to stop calculating when a note ought to be finished and let the audio engine tell us when that particular playback had ended.

One loaded sound, many independent voices

SoLoud separates a loaded source from a playing voice. A source holds the sound that can be reused. Every call to play it returns a handle identifying one instance of playback. Two taps can use the same source while their handles remain independent.

The basic shape is small:

final engine = SoLoud.instance;
await engine.init();
final lantern = await engine.loadAsset('assets/audio/lantern.wav');

final first = engine.play(lantern);
final second = engine.play(lantern);

await engine.stop(first); // The second voice can keep ringing.

In our app, those calls live inside the audio adapter, not in individual widgets. The adapter listens for the native handle’s end event and removes its bookkeeping. It does not schedule a second stop based on the WAV duration. A completion belonging to the first tap cannot retire the second tap’s handle.

Two staggered voices share one cached lantern source. Voice A ends first; voice B continues to its own end.
One sound file can produce several overlapping voices. Each voice has its own start, handle, and end.

The source stays decoded and ready for the next tap. That is a useful exchange for a small game palette: spend memory once, then avoid repeating preparation during every interaction. It also makes a subtle ownership rule important. Disposing the shared source would affect all voices using it, so a screen cannot treat that source as its private disposable player.

The shared layer is about ownership

Yodoku and Find the Pets use the same StudioAudio contract. The app supplies a semantic cue, its asset path, and a volume. The shared adapter owns playback. Neither the game’s rules nor its renderer needs to know about a SoLoud handle.

1. Game outcomeA lantern was placed.
2. App cueChoose the note and volume.
3. Shared serviceCheck settings and ownership.
4. Native voicePlay and observe its own end.

Within a running app, clients share one native engine and a cache keyed by the full asset path. If two clients prepare the same file at once, they wait for one load. Closing one client stops its voices; it does not reinitialize the engine underneath another screen. The final owner releases the engine and its cached sources.

That separation also keeps the audio package independent of Flame. A Flame game can use it, and so can an ordinary Flutter screen. Audio ownership follows the app’s lifetime rather than being tied to a particular renderer.

Overlap still needs a limit. The service defaults to 32 active voices per client and eight instances of one cue, with an additional shared admission check against the engine’s 32-voice budget. Normal playback can replace that client’s oldest eligible voice when its local limit is reached. It cannot quietly steal a voice belonging to another client. For an immediate, prepared request, the service can simply refuse admission instead of evicting a sound or queuing a late replacement.

Those limits are policy, not a promise that every burst must be audible. They keep repeated input from building an unlimited pile of effects.

Mute has to cancel the future, too

The easy version of mute stops the handles already playing. The harder case is a tap that has not reached playback yet:

  1. A tap starts loading a sound.
  2. The player turns sound off or leaves the screen.
  3. Loading completes.

Without another check, step three can start a sound that no longer belongs. Turning sound back on before the load finishes should not rescue that old request either.

We invalidate pending playback whenever a client is muted, stopped, interrupted, or disposed. An asynchronous request captures the current generation and checks it again after preparation. If the generation changed, the request is finished without playing. Returning to the app enables new, deliberate sounds; it does not replay effects from before the interruption.

The same rule applies to output startup. A decoded file can be ready while the audio device is idle. The normal playback path waits for startup, then checks whether its request is still allowed. Failed initialization, loading, or startup can be retried by a later interaction, but failure does not automatically replay a sound the player has already moved past.

On iOS, the adapter uses an ambient audio session that mixes with other audio and respects the silent switch. On Android, these optional effects do not request audio focus. App backgrounding and headphone disconnection still stop effects through explicit lifecycle handling. Audio-session policy is a separate responsibility from SoLoud playback, and it deserves its own tests.

Preparing audio before the moment that matters

There is another useful split: prepare now, play at the event.

For an ordinary tap, the service can prepare and play asynchronously. For a title reveal or coordinated feedback, waiting inside the event handler would move the sound away from the moment it is meant to accompany. Our prepared-audio API loads the source and starts the output ahead of time. At the event, a synchronous call either admits the prepared voice or declines it. It never queues a surprise note for later.

This matters because SoLoud releases idle output by default after a short grace period. Keeping a decoded source is not the same as keeping the device running. The app checks actual readiness at the point of use instead of assuming an earlier preparation future guarantees readiness forever.

In a Yodoku title investigation on the Mac, one engine initialization took about 2.43 seconds, while the first asset-load pipeline took about 11.4 milliseconds. Restarting output after idle took about 53 milliseconds. Those host observations pointed us toward preparation and lifecycle timing, rather than trimming a few bytes from a short WAV. They are not phone benchmarks, and the individual measurements describe different parts of startup.

We used the same boundary in a newer Yodoku change that coordinates outcome sounds with haptics. After preparation, the native sound admissions and the start of the haptic pattern happen in one synchronous dispatch. Sound-off and unavailable-audio paths still allow eligible tactile feedback.

That aligns the app’s commands. The speaker and vibration motor still have different native buffers, scheduling, and hardware. We have not established physically simultaneous onset, so a device-level claim would need a device-level measurement.

The tests that made this worth doing

A short effect has plenty of ways to go wrong without crashing the app. Our shared-audio tests deliberately hold up loading and output startup, deliver old completion events late, and interrupt playback while a native call is returning. They check that only the intended voice is stopped and that cancelled requests stay cancelled.

Other tests cover two clients sharing one engine, concurrent loads, failed initialization followed by a retry, and voice budgets filling up. A caller timeout is treated separately from native cancellation: timed-out native work is still tracked until it settles, so teardown cannot race ahead and destroy an engine that old work is still using.

We also ran a real native macOS smoke test with Find the Pets’ 200-millisecond effect. Captured mixer output preserved the source’s nonzero sample count and span, and two staggered plays had distinct handles and completed. That checks something useful beyond a fake driver, but it is still different from listening on the affected phone. The original migration’s Android cutoff report was not physically revalidated in that test, and the newer sound/haptic coordination needs its own device measurements.

There were practical costs, too. Moving to SoLoud 5.1.1 meant updating the pinned Flutter SDK and CI toolchain together. Predecoded sources stay in memory until the final audio owner closes. This wrapper is intentionally for short effects; narration sequencing, background playback, and a full music system are separate jobs.

What we would keep

The most valuable change was giving every sound a clear owner and an observable end. SoLoud supplied the native sources, voices, and handles. The app supplied the rules for when a sound still belongs, how much overlap is enough, and what should happen when the player leaves.

For a Flutter game with repeated short effects, that is a good place to start: preload the small palette, keep native ownership in one adapter, and test cancellation as carefully as playback. Then listen on the devices people will actually use.

If you want to hear how those little notes fit into a whole game, try Yodoku. Each lantern adds another piece of the garden, and another note.

← All posts