audio_decode library
Native Ogg Vorbis and MP3 decoding to raw PCM for Dart, backed by Sean Barrett's stb_vorbis and lieff's minimp3 over FFI.
The C decoders are compiled from source by a Dart build hook, so there is no prebuilt binary to ship and no platform plugin or system library to install beyond a C toolchain. Decoding runs in native code and copies the result into a Dart Int16List, so callers never manage native memory. The same code path runs in pure Dart (CLI, servers, tests). Flutter runtime support is not verified in this repository.
The package also compiles for the web, where the parts written in Dart give the same results as on the VM. These are detectFormat, decodeWav, wavInfo, encodeWav, resample, toMono, toSpeechPcm, PcmAudio, and decodeAudio and audioInfo for WAV input. Ogg Vorbis and MP3 need the native decoders, which are not available on the web. There decodeOgg, decodeMp3, oggInfo and mp3Info throw an UnsupportedError, and so do decodeAudio and audioInfo for Ogg Vorbis or MP3 input.
Decoding is deterministic for a given build, and the geometry it reports is the same everywhere. Sample values are not bit-identical across CPU architectures: the decoders compute in floating point, so around 0.03% of samples can differ by one least-significant bit between arm64 and x86-64. Do not compare checksums of decoded PCM across a mixed fleet.
This is a decoder, not a player: it turns encoded bytes into PCM samples for waveforms, analysis, resampling, machine-learning preprocessing, games and servers. For playback, pair it with a player package such as just_audio or flutter_sound. encodeWav writes the decoded PCM back out as a WAV file so the samples can be saved or handed to other tools.
import 'dart:io';
import 'package:audio_decode/audio_decode.dart';
void main() {
final bytes = File('clip.mp3').readAsBytesSync();
final pcm = decodeAudio(bytes);
print('${pcm.sampleRate} Hz, ${pcm.channels} ch, ${pcm.duration}');
File('clip.wav').writeAsBytesSync(encodeWav(pcm));
}
See decodeAudio, decodeOgg, decodeMp3, detectFormat, PcmAudio and encodeWav for the full API.
Classes
Enums
- AudioFormat
- The container format of an encoded audio buffer, as identified by detectFormat.
Functions
-
audioInfo(
Uint8List bytes) → AudioInfo -
Reads
bytes's geometry after sniffing its format with detectFormat, dispatching to oggInfo, mp3Info or wavInfo. -
decodeAudio(
Uint8List bytes) → PcmAudio -
Decodes
bytesafter sniffing its format with detectFormat, dispatching to decodeOgg, decodeMp3 or decodeWav. -
decodeMp3(
Uint8List bytes) → PcmAudio - Decodes an MP3 stream to 16-bit PCM.
-
decodeOgg(
Uint8List bytes) → PcmAudio - Decodes an Ogg Vorbis stream to 16-bit PCM.
-
decodeWav(
Uint8List bytes) → PcmAudio - Decodes a RIFF/WAVE file holding uncompressed audio.
-
detectFormat(
Uint8List bytes) → AudioFormat -
Identifies the container format of
bytesfrom its leading bytes. -
encodeWav(
PcmAudio audio) → Uint8List -
Encodes
audioas a canonical 16-bit PCM WAV (RIFF) file. -
mp3Info(
Uint8List bytes) → AudioInfo - Reads an MP3 stream's geometry without producing any audio.
-
oggInfo(
Uint8List bytes) → AudioInfo - Reads an Ogg Vorbis stream's geometry without decoding any audio.
-
resample(
PcmAudio audio, int targetRate) → PcmAudio -
Resamples
audiototargetRate, keeping its channel count. -
toMono(
PcmAudio audio) → PcmAudio -
Mixes
audiodown to a single channel. -
toSpeechPcm(
PcmAudio audio, {int sampleRate = 16000}) → PcmAudio - Mono at 16 kHz, the input shape on-device speech models ask for.
-
wavInfo(
Uint8List bytes) → AudioInfo - Reads a WAV file's geometry from its header, without decoding the samples.
Exceptions / Errors
- AudioDecodeException
- Thrown when decoding fails: the bytes are not valid audio of the expected format, or the native decoder rejected them.