flutter_oneshot_player
Low-latency one-shot audio sample player for Flutter. Native AVAudioEngine on iOS/macOS, Oboe on Android.
Load samples by key and fire them on demand. Calling play while a sample is already playing retriggers it from the beginning with no click or gap.
| Platform |
Implementation |
| iOS |
AVAudioEngine |
| macOS |
AVAudioEngine |
| Android |
Oboe |
Usage
final player = OneShotPlayer();
await player.initialize();
await player.prime(); // warms up the hardware audio session
await player.load('kick', bytes: kickBytes, extension: 'wav');
await player.load('snare', path: '/path/to/snare.wav');
// Standard play (awaitable)
await player.play('kick');
// Ultra-low-latency fire-and-forget (zero Dart allocations)
player.playFast('kick');
await player.dispose();
API
| Method |
Description |
initialize() |
Initialises the native audio engine. Call before anything else. |
prime() |
Plays 50 ms of silence to warm up the hardware session. Eliminates first-hit latency. |
load(key, {path, bytes, extension}) |
Loads a sample. Provide either a file path or raw bytes. |
play(key) |
Fires the sample. Retriggers if already playing. |
playFast(key) |
Lowest-latency variant — sends pre-encoded bytes directly via the binary messenger. |
stop(key) |
Stops the sample immediately. |
setVolume(double) |
Sets master output volume (0.0–1.0). |
unload(key) |
Removes a sample and frees its buffer. |
dispose() |
Stops all samples and releases all native resources. |
Streams
| Stream |
Description |
playingKeys |
Emits the set of currently-playing sample keys. |
errors |
Emits engine-level error messages. |
