AudioPool¶
An AudioPool is a provider of AudioPlayers that are pre-loaded with local assets to minimize audio playback delays. This is particularly useful in fast-paced games where sound effects need to trigger quickly and potentially overlap with each other.
A single AudioPool always plays the same sound, usually a quick sound effect that might need to be played repeatedly or simultaneously, such as:
Shooting sounds in a space shooter
Jump sounds in a platformer
Explosion effects
Collecting coins or items
Enemy hit sounds
How It Works¶
AudioPool works by creating and pre-loading a pool of AudioPlayer instances that are all configured to play the same sound. When you need to play the sound:
The pool gives you an available player from its collection
If no player is available, a new player is created on demand
When a sound finishes playing or is stopped manually, the player is returned to the pool for reuse, unless the pool already has reached its maximum size limit, in which case the player is released
This approach significantly reduces latency compared to creating new AudioPlayer instances on demand, while also managing memory by limiting the maximum size of the pool.
Creating an AudioPool¶
There are multiple ways to create an AudioPool:
Using FlameAudio Helper¶
The simplest approach is to use the helper method in FlameAudio
, which conveniently uses Flame’s
global audio cache:
import 'package:flame_audio/flame_audio.dart';
Future<void> loadSounds() async {
// Create a pool with minimum 1 player and maximum 2 players
// This automatically uses Flame's global audio cache
AudioPool explosionSoundPool = await FlameAudio.createPool(
'explosion.mp3',
minPlayers: 1,
maxPlayers: 2,
);
}
Creating Directly with Source¶
You can also create an AudioPool by directly using the static factory methods:
import 'package:audioplayers/audioplayers.dart';
import 'package:flame_audio/flame_audio.dart';
Future<void> loadSounds() async {
// Create a pool with a specific Source
AudioPool explosionSoundPool = await AudioPool.create(
source: AssetSource('explosion.mp3'),
minPlayers: 1,
maxPlayers: 2,
audioCache: FlameAudio.audioCache, // Optional
);
}
Creating from Asset Path¶
For convenience, you can create an AudioPool from just the asset path:
import 'package:flame_audio/flame_audio.dart';
Future<void> loadSounds() async {
AudioPool explosionSoundPool = await AudioPool.createFromAsset(
path: 'explosion.mp3',
minPlayers: 1,
maxPlayers: 2,
audioCache: FlameAudio.audioCache, // Optional
);
}
The parameters are:
source
orpath
: The audio source to play (either as a Source object or asset path)minPlayers
: The initial number of AudioPlayers to create and preload (default: 1)maxPlayers
: The maximum number of AudioPlayers that can be kept in the poolaudioCache
: Optional AudioCache instance to useaudioContext
: Optional audio context to be used by all players in the pool
Using an AudioPool¶
Once you’ve created an AudioPool, you can start playing sounds:
// Play the sound with default volume (1.0)
final stopFunction = await audioPool.start();
// Play the sound with custom volume
final stopFunction = await audioPool.start(volume: 0.5);
// Later, you can stop the sound if needed
await stopFunction();
The start()
method returns a StopFunction
that you can call to stop the sound before it completes
naturally.
Managing the Pool¶
AudioPool provides a dispose()
method to release resources when you no longer need the pool:
// When you're done with the pool
await audioPool.dispose();
Example Usage¶
Here’s a complete example showing how to use AudioPools in a Flame game:
import 'package:flame/game.dart';
import 'package:flame_audio/flame_audio.dart';
class MyGame extends FlameGame {
late AudioPool laserSound;
late AudioPool explosionSound;
@override
Future<void> onLoad() async {
// Load sound effects into audio pools
laserSound = await FlameAudio.createPool(
'laser.mp3',
minPlayers: 3,
maxPlayers: 6,
);
explosionSound = await FlameAudio.createPool(
'explosion.mp3',
minPlayers: 2,
maxPlayers: 4,
);
}
void fireLaser() async {
// Play the laser sound effect - can be called rapidly
final stop = await laserSound.start();
// If you need to stop the sound early:
// await stop();
}
void enemyDestroyed() async {
// Play explosion sound effect
await explosionSound.start(volume: 0.7);
}
@override
Future<void> onRemove() async {
await super.onRemove();
// Clean up resources when the game component is removed
await laserSound.dispose();
await explosionSound.dispose();
}
}
You can also find the interactive example in Flame Basic