audio_decoder

v0.8.1

A patch release focused on decoding robustness on Windows and Android, plus more consistent error handling on Web. Fully backward compatible — no API changes.

Windows: Media Foundation chunk-windowing fixes

Hardened the Windows (Media Foundation) AAC/M4A decoding path against several edge cases that could read past a chunk boundary or produce malformed output:

• Fixed an AAC chunk boundary overshoot, where the WMF reader could read beyond the intended window (#44).
• Guarded the byte-based chunk windowing against a zero block-align and an open (unbounded) start, and folded the sample rate into the byte-window guard (#47).
• An empty trim window now yields empty output instead of an error (#47).

Android: waveform crash on long files

Fixed an IndexOutOfBoundsException in getWaveform / getWaveformBytes on medium-to-large audio (e.g. a 5-minute MP3). The per-window offset i * totalSamples overflowed a 32-bit Int and wrapped to a negative index; window bounds are now computed with 64-bit arithmetic. Covered by a new on-device long-file regression test (#45, #48).

Web: consistent error delivery

The file-based methods (convertToWav, convertToM4a, getAudioInfo, trimAudio, getWaveform) are unsupported on Web and throw UnsupportedError. They now deliver that error through the returned Future instead of throwing synchronously, so await and .catchError handle it consistently. The example app also disables these actions on Web with an inline note pointing to the bytes-based API.

PRs included

• Fix WMF AAC chunk boundary overshoot on Windows by @EliStoreplay in #44
• Harden WMF byte-based chunk windowing by @sjoenk in #47
• Fix Android waveform IndexOutOfBoundsException on long files by @sjoenk in #48

New Contributors

• @EliStoreplay made their first contribution in #44 — thanks for catching the AAC chunk-boundary overshoot on Windows!

Full Changelog: v0.8.0...v0.8.1

• Fix IndexOutOfBoundsException on Android for long files (#45) — getWaveform / getWaveformBytes crashed on medium-to-large audio (e.g. a 5-minute MP3) because the per-window offset i * totalSamples overflowed a 32-bit Int and wrapped to a negative index. The window bounds are now computed with 64-bit arithmetic.
• Web: file-based methods reject their Future instead of throwing synchronously — convertToWav, convertToM4a, getAudioInfo, trimAudio, and getWaveform are unsupported on web; the UnsupportedError is now delivered through the returned Future, so await / .catchError handle it consistently.
• Example app: file-based actions are disabled on web with an explanatory note, since they rely on dart:io (use the bytes-based API instead).

v0.8.0

Cross-track loudness option

Added a new WaveformNormalization enum that lets callers opt into absolute amplitude scaling on getWaveform and getWaveformBytes. The default behavior is unchanged, so this release is non-breaking.

• WaveformNormalization.perFile (default) — each waveform is rescaled so its loudest window equals 1.0. Best for single-track UI: voice memos, podcast previews, chat voice messages.
• WaveformNormalization.absolute — amplitudes are scaled against the maximum signed 16-bit PCM magnitude (32768), so absolute loudness is preserved across files. Best for music apps that show several tracks side by side, where a quiet recording should visibly look quieter.

final waveform = await AudioDecoder.getWaveform(
  '/path/to/song.mp3',
  numberOfSamples: 100,
  normalization: WaveformNormalization.absolute,
);

Implemented across all platforms: Android, iOS/macOS, Linux, Windows, and Web. numberOfSamples is now also validated up front (> 0, throws ArgumentError otherwise).

Cross-platform build fixes

Resolves build failures on newer compilers, contributed by @navidicted:

• Linux: Forward typedefs for G_DEFINE_TYPE so the plugin compiles with GCC 15.2.1.
• Windows: Parenthesize std::min / std::max to avoid the MSVC min/max macro clash, cast MF_SOURCE_READER_MEDIASOURCE to DWORD, include <cctype> and <flutter/encodable_value.h>, and fix a std::tolower data-loss warning.

PRs included

• Fix build failures on Linux and Windows by @navidicted in #42
• Add WaveformNormalization option for cross-track loudness by @sjoenk in #43

New Contributors

• @navidicted made their first contribution in #42 — thanks for fixing the GCC 15 + MSVC build issues!

Full Changelog: v0.7.4...v0.8.0

• WaveformNormalization option — opt into absolute amplitude scaling on getWaveform / getWaveformBytes to preserve loudness differences between tracks (useful for music apps that show several songs side by side).
  • WaveformNormalization.perFile (default) keeps the existing 0.7.x behavior: each waveform is rescaled so its loudest window equals 1.0.
  • WaveformNormalization.absolute divides by the maximum signed 16-bit PCM magnitude (32768), so a quiet recording stays visibly quieter than a loud one.
  • Implemented across all platforms: Android, iOS/macOS, Linux, Windows, Web.
• Validate numberOfSamples (> 0) on the public Dart API before dispatching to the platform.
• Fix cross-platform build failures (contributed by @navidicted):
  • Linux: add the missing forward typedefs for G_DEFINE_TYPE so the plugin compiles with GCC 15.2.1.
  • Windows: parenthesize std::min / std::max to avoid the MSVC min/max macro clash, cast MF_SOURCE_READER_MEDIASOURCE to DWORD, include <cctype> and <flutter/encodable_value.h>, and fix a std::tolower data-loss warning.

v0.7.4

Swift Package Manager support

The plugin can now be consumed via SPM in addition to CocoaPods on both iOS and macOS. An Apple privacy manifest (PrivacyInfo.xcprivacy) is included for iOS 17+ compliance.

Example app & branding

• Restyled waveform widget with responsive AspectRatio layout
• Replaced pub.dev screenshot with package logo
• Unified formatter settings and extracted hardcoded asset paths to constants

PRs included

• Update iOS example app for new Flutter engine API by @sjoenk in #35
• Add Swift Package Manager support for iOS and macOS by @sjoenk in #36
• Clean up code style and documentation after SPM migration by @sjoenk in #37
• Restyle waveform widget and update package screenshots by @sjoenk in #39

Full Changelog: v0.7.3...v0.7.4

• Swift Package Manager support for iOS and macOS — plugin can now be consumed via SPM in addition to CocoaPods.
• Add Apple privacy manifest (PrivacyInfo.xcprivacy) for iOS 17+ compliance.
• Restyle example app waveform widget with responsive AspectRatio layout.
• Replace pub.dev screenshot with package logo.
• Documentation and code cleanup (formatter unification, constant extraction, CHANGELOG correction).

v0.7.3

Documentation & presentation improvements

Deze release verbetert de pub.dev presentatie en developer experience met een volledig vernieuwde Material 3 example app en uitgebreide code documentatie. Geen API changes - safe to upgrade.

Changes

• Added Material 3 example app screenshot voor pub.dev showcase
• Redesigned example app met Material 3 design system
  • Color-coded status display (blauw=loading, groen=success, rood=error)
  • Gradient waveform visualization met rounded corners
  • Modern FilledButton.tonalIcon styling
• Enhanced code documentation met inline comments bij alle AudioDecoder API calls
• Improved code organization met duidelijke sectie headers (Business logic, Bytes API, UI helpers)
• Added pub.dev quality badges (license, pub points, likes) to README
• Standardized numberOfSamples parameter naar 100 voor consistentie

Full Changelog: v0.7.2...v0.7.3

• Documentation & presentation improvements (no API changes)
  • Added screenshot of example app with waveform visualization for pub.dev.
  • Redesigned example app with Material 3 design system (color-coded status, modern buttons, gradient waveform).
  • Enhanced code documentation with helpful comments at all API call sites.
  • Added pub.dev quality badges (license, pub points, likes) to README.

v0.7.2

Fix: streaming resampling to avoid OOM on large files (Android)

Resampling verwerkt PCM data nu chunk-voor-chunk in de streaming decode pipeline, in plaats van het hele bestand in geheugen te bufferen. Dit voorkomt OOM crashes bij grote bestanden op devices met weinig geheugen.

Changes

• Replace in-memory resampling with stateful chunk-based streaming (ResamplerState met linear interpolation over chunk-grenzen)
• Flush trailing fractional samples bij end-of-stream
• Pre-allocate resampler output buffer (minder GC pressure)
• Cap targetSampleRate op 384 kHz ter bescherming tegen pathologische allocaties
• WAV size validatie toegevoegd aan resampler flush branch
• ~90 regels duplicated decode loop code verwijderd

Full Changelog: v0.7.1...v0.7.2

• Android: streaming resampling — replace in-memory resampling with chunk-based streaming to avoid OOM on large files.
• Fix trailing sample loss when EOS arrives on an empty MediaCodec buffer.
• Pre-allocate resampler output buffer instead of using ByteArrayOutputStream to reduce GC pressure.
• Cap maximum target sample rate at 384 kHz to prevent pathological allocations.
• Add MAX_WAV_DATA_SIZE validation to the resampler flush path.

0.7.1

Bug fix

• Fix iOS build failure (Module 'audio_decoder' not found) when used as a pub dependency (#25)

Changes

• Use sharedDarwinSource for shared iOS/macOS podspec resolution (#26)
• Remove orphaned ios/ and macos/ podspec directories
• Sync podspec version with pubspec.yaml

Full Changelog: v0.7.0...v0.7.1

• Fix iOS build failure (Module 'audio_decoder' not found) when used as a pub dependency.
• Use sharedDarwinSource for shared iOS/macOS podspec resolution.
• Remove orphaned platform-specific podspec files.

v0.7.0

Streaming WAV conversion & internal improvements

WAV conversion now streams decoded PCM chunks directly to disk instead of buffering everything in memory. This significantly reduces peak memory usage, especially for large audio files.

Changes

• Streaming WAV conversion — stream decoded PCM to disk instead of buffering in memory
  • Android (#20)
  • iOS / macOS (#21)
  • Linux / Windows (#23)
• Input validation — sampleRate, channels, and bitDepth are now validated at the Dart level before calling native code (#17)
• Shared Swift source — consolidated duplicate iOS/macOS plugin code into darwin/Classes/ (#24)

Full Changelog: v0.6.0...v0.7.0

• Streaming WAV conversion — decoded PCM chunks are now streamed directly to disk during WAV conversion, significantly reducing peak memory usage for large files.
  • Implemented on Android, iOS, macOS, Linux, and Windows.
• Add Dart-level input validation for convertToWav and convertToWavBytes parameters.
  • sampleRate, channels, and bitDepth are validated before calling native code, throwing ArgumentError for invalid values.
• Consolidate duplicate iOS/macOS Swift plugin code into shared source under darwin/audio_decoder/Sources/audio_decoder/.

v0.6.0

Raw PCM output

convertToWavBytes accepts a new includeHeader: false parameter that returns only raw interleaved PCM samples — no 44-byte RIFF/WAV header. Useful for real-time audio pipelines, direct hardware interfaces, and custom audio processing.

Dart 3 class modifiers

All library classes now use Dart 3 class modifiers (base, final) to enforce intended usage contracts at compile time. Non-breaking for existing consumers.

Testing

Expanded integration tests to cover all native platform operations. Added web integration tests.

Full Changelog: v0.5.0...v0.6.0

• Add includeHeader parameter to convertToWavBytes (default true).
• When false, returns only raw interleaved PCM data without the 44-byte RIFF/WAV header.
• Useful for real-time audio pipelines, direct hardware interfaces, and custom audio processing.
• Supported on all platforms: Android, iOS, macOS, Windows, Linux, and Web.
• Add Dart 3 class modifiers to all library classes.
• AudioDecoderPlatform is now abstract base class — enforces extension over implementation.
• MethodChannelAudioDecoder, AudioDecoderWeb, AudioDecoder, AudioConversionException, and AudioInfo are now final class — prevents unintended subclassing.

WAV Conversion Parameters

convertToWav and convertToWavBytes now accept optional sampleRate, channels, and bitDepth parameters, giving full control over WAV output encoding. When omitted, the source sample rate and channels are preserved with 16-bit depth (existing behavior).

// Convert to mono 44.1kHz 24-bit WAV
final path = await AudioDecoder.convertToWav(
  'input.mp3', 'output.wav',
  sampleRate: 44100,
  channels: 1,
  bitDepth: 24,
);

// Same for in-memory bytes
final wavBytes = await AudioDecoder.convertToWavBytes(
  mp3Bytes,
  formatHint: 'mp3',
  sampleRate: 22050,
  channels: 1,
  bitDepth: 16,
);

Supported values

Platform implementation

Full Changelog: v0.4.0...v0.5.0

• Add optional sampleRate, channels, and bitDepth parameters to convertToWav and convertToWavBytes.
• Control output sample rate (e.g., 44100, 22050), channel count (1 for mono, 2 for stereo), and bit depth (8, 16, 24, 32).
• When omitted, defaults to the source sample rate/channels and 16-bit depth.
• Supported on all platforms: Android, iOS, macOS, Windows, Linux, and Web.

Web Support

audio_decoder now runs in the browser! The web platform uses the Web Audio API to decode and process audio entirely client-side.

What's supported on web

• convertToWavBytes — decode any browser-supported format and encode to WAV
• getAudioInfoBytes — extract duration, sample rate, channels, and bit rate
• trimAudioBytes — trim audio to a time range (WAV output)
• getWaveformBytes — extract normalized amplitude data for visualizations

Web limitations

• File-based methods are not available — use the bytes-based API instead
• M4A encoding is not supported (browsers lack an AAC encoding API)
• Trim output is always WAV

Other improvements

• Added API documentation comments to all public classes and members
• Plugin now supports all 6 Flutter platforms: Android, iOS, macOS, Windows, Linux, and Web

Full Changelog: v0.3.0...v0.4.0

• Add web support using the Web Audio API.
• Bytes-based methods (convertToWavBytes, getAudioInfoBytes, trimAudioBytes, getWaveformBytes) are fully supported on web.
• File-based methods throw UnsupportedError on web — use the bytes API instead.
• M4A encoding is not available on web (browser limitation).

• Initial release of audio_decoder.
• Convert audio files to WAV format (convertToWav) — supports MP3, M4A, AAC, OGG, OPUS, FLAC, WMA, AIFF, AMR, CAF, ALAC, and WebM.
• Convert audio files to M4A/AAC format (convertToM4a).
• Retrieve audio metadata (getAudioInfo) — duration, sample rate, channels, bit rate, and format.
• Trim audio files to a specific time range (trimAudio).
• Extract waveform amplitude data for visualizations (getWaveform).
• Platform support: Android, iOS, macOS, and Windows.
• Typed exception handling via AudioConversionException.