Add flame_audio, put MP3, OGG or WAV files in assets/audio/, and call FlameAudio.play('hit.mp3') for a sound effect or FlameAudio.bgm.play('theme.mp3') for looping music. Preload files in onLoad so the first play is less likely to lag. On the web, start audio from a tap.

This is for Flutter developers whose Flame game feels silent. It uses flame_audio 2.12.2 with flame 1.38.2, the latest stable versions in October 2026.

In short:

  • flame_audio is a thin wrapper around the audioplayers package.
  • Use play for effects, bgm for music that pauses with the app.
  • AudioPool reuses players for an effect that repeats rapidly.
  • Browsers may block audio until the user taps, clicks or presses a key.

Set up in three steps

  1. Run flutter pub add flame_audio.
  2. Put files such as theme.mp3 and hit.mp3 in assets/audio/.
  3. List the folder in pubspec.yaml under flutter: assets: with - assets/audio/.

The default folder for FlameAudio is assets/audio, so you pass bare file names. Flame's audio page recommends MP3, OGG and WAV because they work across devices.

play is for effects, bgm is for music

Use play for effects and bgm for music. The long-audio calls are a last resort.

Call Use it for
FlameAudio.play('hit.mp3') Short effects, optimised for low lag
FlameAudio.loop('wind.mp3') A short looped sound, no gap
FlameAudio.bgm.play('theme.mp3') Music that pauses when the app goes to the background
FlameAudio.playLongAudio Long files, but frame drops and a gap when looped

Prefer the first three whenever you can. The docs say playLongAudio and loopLongAudio allow any length, but they cause frame rate drops and a small gap between loops. Both play and loop accept a volume between 0 and 1 and return an AudioPlayer you can stop.

bgm needs one line in onLoad

The Bgm class pauses the music when the app is sent to the background and resumes it on return. It needs an observer registered once, after Flutter's binding exists, so the docs advise calling this in onLoad:

@override
            Future<void> onLoad() async {
              FlameAudio.bgm.initialize();
              await FlameAudio.audioCache.loadAll(['theme.mp3', 'hit.mp3']);
            }
            

Later, FlameAudio.bgm.play('theme.mp3', volume: 0.4) starts the loop, and stop, pause and resume do what they say. A manual pause stops the app from auto-resuming the music when it returns.

Preload, or the first hit lags

A sound is stored in memory the first time it is requested, so the first play of each file can be late. audioCache.loadAll([...]) in onLoad moves that cost to the loading screen. If your levels use different sounds, audioCache.clear('file.mp3') or clearAll() frees memory between levels.

AudioPool makes rapid effects cheap

A laser fired ten times a second needs overlapping playback. An AudioPool keeps several players ready for one sound.

late AudioPool laser;
            
            @override
            Future<void> onLoad() async {
              laser = await FlameAudio.createPool('laser.mp3',
                  minPlayers: 3, maxPlayers: 6);
            }
            
            void fire() => laser.start(volume: 0.5);
            

minPlayers are created and loaded up front. If all are busy, a new player is created on demand. When a sound ends, its player returns to the pool, unless the pool already holds maxPlayers, in which case it is released. One pool plays one sound, so make a pool per effect. Call laser.dispose() when the game is removed.

Web browsers need a tap first

Browsers commonly refuse to play audio before the user interacts with the page. Music started in onLoad runs before any touch, so the browser can block it. Start it from a tap, such as the "Play" button of your title screen.

In the GrowApps game starter, music begins when the game state changes to playing, which only happens from a tap or key press, and stops on the end screens.

In our measurements in Chrome on the starter, the loop was fetched on the start tap and played with no autoplay error. See the menus and overlays article for the title screen pattern.

Variety comes from several sound files

FlameAudio.play takes a file and a volume, with no pitch option. So the fiftieth jump does not sound like the first, make three to five variants of the sound and pick one at random.

Test your mix in 10 minutes

Add a short hit.mp3, call FlameAudio.play('hit.mp3', volume: 0.6) from a collision callback, and loop a theme.mp3 at volume 0.3 under it. Effects should sit clearly above the music. For hooking the sound to collision callbacks, use onCollisionStart, not onCollision, or the sound fires on every frame.

Sources and further reading