mpv_audio_kit 0.2.3

Dart audio player built on mpv. Supports audio filters, equalizer, visualizer, waveform and more. Targets macOS, Windows, Linux, iOS and Android.

0.2.3 25-05-2026

Docs

• Branding realignment with the rest of the libraries.

0.2.2 23-05-2026

Added

• AevalSettings and AformatSettings now expose their typed parameters (previously toggle-only).
• Correct numeric bounds on ~116 more parameters that were null before — including the whole biquad family's width_type, transform and precision, atempo.tempo, and many others. The matching <param>Min / <param>Max constants now reflect the real ffmpeg ranges.
• New typed enums for the biquad family's width_type and transform, plus SurroundWinFunc.
• Param doc comments now flag which AVOptions ffmpeg marks as runtime-tunable, deprecated, or array-typed. Deprecated parameters also carry a Dart @Deprecated annotation.

Changed

• The six EBU R128 stat fields (integrated, range, lra_low, lra_high, sample_peak, true_peak) are no longer setter fields on Ebur128Settings — ffmpeg flags them as read-only outputs and rejected any attempt to set them. Read them via af-metadata/<label> instead.

Fixed

• compand.points, mcompand.args, aiir.{p,z,k,gains,…}, firequalizer.gain, anequalizer.colors and other string-grammar parameters now carry their ffmpeg default value instead of an empty default. The hand-written list-typed extensions (CompandSettings.transferPoints, AiirSettings.channels, McompandSettings.bands, …) consequently decode the real ffmpeg default state when the filter is constructed without overrides.

Build

• Improvements to Swift Package Manager on both iOS and macOS.

0.2.1 21-05-2026

Fixed

• Incorrect README mentions.

0.2.0 21-05-2026

Added

• Player.stream.waveform: a min-max amplitude envelope of the whole track (WaveformData) for a static overview strip. Listener-gated, so the background analyzer runs only while a consumer is subscribed.
• Player.stream.tap(AudioEffect, side: TapSide): typed per-filter PCM tap that picks a slot in the effect chain and a pre or post side. Lazy, arming on the first listener and tearing down on the last cancel.
• BandProcessor: public PCM-to-bands processor running the same FFT pipeline as Player.stream.fft, for per-filter spectrum curves built from a tap.
• AudioEffectsX.active: yields the AudioEffect for every enabled slot, so the live effect rack can be iterated without enumerating each typed field.
• Typed extensions for every filter whose lavfi grammar packs structured data into an opaque string: compand, aecho, chorus, adelay, aiir, firequalizer, afftdn, mcompand, superequalizer, anequalizer. Each exposes a typed model (CompandPoint, AechoTap, AnequalizerBand, …) and round-trips losslessly.
• <name>Min, <name>Max, and <name>Default constants on every typed *Settings class, so UI builders can read each parameter's engine range and default directly.
• The biquad-family *Settings (equalizer, bass, treble, bandpass, highpass, lowpass, …) now expose every parameter ffmpeg's biquad chain accepts (width, mix, channels, normalize, transform, …).
• SpectrumSettings.overlapFactor: overlap-add factor for smoother visualizer motion (default 4, i.e. 75% overlap).
• Enum-typed parameters with a symbolic ffmpeg default are now non-nullable, carrying that documented default.

Changed

• The real-time FFT frame stream moved from Player.stream.spectrum to the new Player.stream.fft. Player.stream.spectrum is now a reactive view of the current SpectrumSettings, emitted on every setSpectrum or updateSpectrum call.

Fixed

• Filter values containing : = , or | (e.g. anequalizer.params, pan.args) are now accepted instead of being rejected at chain build.
• Spectrum band magnitudes follow the Web Audio AnalyserNode convention (normalised by half the FFT size before the dB conversion). New SpectrumSettings defaults: minDb: -100, maxDb: -30.

Build

• Switched to OpenSSL for TLS.
• Ffmpeg updated to 8.1.1 and bumped all its dependencies.
• Restored 32-bit ARM Android, Intel macOS, and the Intel iOS Simulator to the bundled binaries.
• iOS and macOS libmpv now ships as a dynamic xcframework (Swift Package Manager builds no longer fail).
• Updated libmpv to libmpv-r7 across all platforms.

0.1.3 9-05-2026

Fixed

• Flutter Hot Restart no longer hangs in debug builds when a Player is alive.

0.1.2 7-05-2026

Changed

• Player() returns immediately during cold start: the heavy libmpv init (library open, handle creation and initialisation, ~80 property observers) now runs on the background event isolate instead of the host isolate.
• The background event isolate now blocks on mpv_wait_event instead of polling every 50 ms, eliminating ~20 spurious wake-ups per second during idle playback.
• dispose() is robust against being called before Player() finishes coming up: it waits for init to settle (or fail) before issuing the cooperative quit and tearing down the streams, so the safety timeout never fires on construction-then-dispose patterns.

Fixed

• Media.httpHeaders now validate keys and values and throw ArgumentError on inputs that would corrupt the outgoing HTTP request.
• Player.add() and Player.replace() now wait for the bundled CA file before emitting loadfile, matching Player.open(). The first HTTPS append issued immediately after construction no longer races peer verification.
• The Player finalizer now issues a cooperative quit instead of tearing down the handle directly, eliminating a possible crash when a Player is garbage-collected without dispose().

0.1.1 6-05-2026

Changed

• Numeric setters now validate at the wrapper boundary and throw ArgumentError with a precise stack trace instead of waiting for a round-trip MpvException. Affects setVolume, setRate, setPitch, setVolumeMax.
• SpectrumSettings rejects out-of-range values at construction (FFT size must be a power of two in [256, 4096], smoothing in [0, 1], bandHighHz > bandLowHz, etc.) instead of letting them surface as visually-broken output downstream.

Fixed

• Media.httpHeaders now reach mpv on every track, including the first one. Previously they were silently dropped on the first open() and applied to the wrong file on subsequent calls.
• replace() on the currently-playing entry is now seamless instead of briefly stopping playback before resuming on the new track.
• setNetworkTimeout honours sub-second precision; durations below 1s no longer collapse to "no timeout".
• setTlsCaFile('') restores the bundled CA default instead of silently disabling peer verification.
• setTlsCaFile is now declared on the public PlayerApi interface.
• setReplayGain, setCache, and setLoop are now atomic: if any partial write fails, the previous values are restored before the error is rethrown.
• dispose() no longer falls through its safety timeout when racing an in-flight open().
• state.position is cleared synchronously on open() so a UI reading the playhead on track-change no longer briefly shows the previous track's value.
• state.chapters and state.currentChapter are now refreshed after every load. Two consecutive files with structurally-identical chapter lists previously left both fields stranded at the prior track's value.

Build

• Added AudioToolbox decoders for macOS and iOS.
• Fixed TLS on macOS and iOS (now aligned with the others).
• Updated libmpv to libmpv-r6 across all platforms.

0.1.0 5-05-2026

Major release. The Dart API has been redesigned for type safety, ergonomics, and atomic state mutations.

Added

• A new AudioEffects bundle covering equalizer, compressor, loudness, pitch, tempo, bass, treble, stereo width, headphone crossfeed, silence trim, and raw lavfi effects applied atomically through one setter.
• A-B loop and chapter navigation.
• Aggregate playback-state stream (idle, loading, buffering, playing, paused, completed) for one-line UI bindings.
• 20+ new observable streams covering timing, file metadata, cache, demuxer, and version info.
• Typed Hook enum for the file-loading lifecycle.
• New MpvPrefetchState.failed variant for when background prefetch fails.
• Typed errors via the MpvPlayerError hierarchy and a public MpvException for raw-API failures.
• Real-time FFT spectrum and raw PCM streams (Player.stream.spectrum / Player.stream.pcm) captured post-DSP for visualizers.
• setTlsCaFile(path) with custom root-CA bundle.

Changed

• DSP effects, ReplayGain, and cache settings now live in atomic config objects applied in one call instead of multiple granular setters.
• Track selection, format, channel layout, S/PDIF passthrough, log levels, and hooks are now typed enums and sealed classes instead of free-form strings.
• Embedded cover art is exposed as raw codec bytes through a dedicated state.coverArt + stream.coverArt pair, with Flutter conveniences (art.image returns an ImageProvider, plus art.extension, art.isPng, art.isJpeg, …).
• setAudioDisplay, setImageDisplayDuration, and the Display enum are removed - they controlled mpv's video pipeline, which the audio-only build no longer ships. Cover bytes are surfaced regardless via state.coverArt.
• Raw-API escape hatches (getRawProperty, setRawProperty, sendRawCommand) are now Future<...> and surface mpv-side errors as MpvException instead of silently no-oping. getRawProperty still returns null on failure.
• Every typed setter (setVolume, setRate, setAudioEffects, setCache, …) now throws MpvException when mpv rejects the write, instead of silently advancing the optimistic state.
• Player.openPlaylist renamed to Player.openAll (matches Dart's addAll / removeAll convention).
• See the Migration section in the README for the full 0.0.9 → 0.1.0.

Fixed

• The initial player state (volume, format, channels, params, …) is now reliably populated before the first await. A startup race could previously leave one or more state fields at their default until the next user-driven setter.
• Calling dispose() immediately after construction no longer throws.
• Player instances that get garbage-collected without an explicit dispose() now release their native handle automatically. Always prefer await player.dispose(); this is just a safety net.
• Player.dispose() completes in milliseconds instead of falling through a 2-second timeout.
• HTTP headers no longer leak across open() calls; per-file headers stay scoped to their Media.
• Android content:// file descriptors are released on aborted loads, including when an openAll([...]) fails mid-batch.
• state.coverArt now mirrors the latest stream.coverArt emit synchronously (was permanently null despite being documented).
• print(state) and print(audioEffects) now render the actual values instead of placeholder text.
• Hot-Restart cleanup is hardened against false positives so a long-lived dev process can't have it trip on memory belonging to other tools.
• Several correctness fixes around playlist equality, hook idempotency, cache precision, and lifecycle stream synchronisation.
• HTTPS streams now connect on Android out of the box; previously TLS verification had no trust roots and every handshake failed.

Example

• Spectrum visualizer in the Player tab driven by Player.stream.spectrum, plus a Settings page exposing every SpectrumSettings knob (FFT size, window, band count, range, emit rate, attack, release smoothing, dB range) for live exploration.
• Filters page reorganised into category sub-pages covering every filter shipped with the build, plus a dedicated 18-band visualizer for superequalizer.

Build

• Patched prefetch to also support .failed state.
• Patched audio output state to report AO immediately.
• Patched audio frames to extract PCM streams (visualizer).
• Fixed Android audiotrack driver not working.
• Bundled libmpv binaries reduced by ~55% (e.g. macOS 29 MB → 13 MB).
• Bumped minimum deployment targets to iOS 15.0 and macOS 12.0.
• iOS Simulator is now Apple Silicon only (dropped x86_64).
• Added arm64 support for Linux and Windows.
• Updated libmpv to libmpv-r5 across all platforms.

0.0.9 27-04-2026

Fixed

• Lifecycle streams (stream.playing / stream.buffering / stream.completed) silently desynced from state on file boundaries - stream.completed never fired on natural EOF and stream.buffering never emitted at all. All three now stay in sync with state across every lifecycle transition.
• dispose() leaked four stream controllers (audio display, cover-art auto, image display duration, prefetch state). All now closed on teardown.
• Use-after-dispose hazards on open() / openPlaylist(): disposing the player while URI normalisation was still in flight could SIGSEGV on Android intent:// loads. Added disposed re-checks after every async boundary.
• Defensive disposal guards on the position polling and embedded-cover pipelines so in-flight work bails instead of writing to closed controllers.
• setEqualizerGains() now respects the disposal contract.
• setAudioFilters() and setEqualizerGains() now route state mutation through the same path as every other setter.
• openPlaylist(medias, index: N) no longer silently no-ops when N >= medias.length; the index is clamped to medias.length - 1.

Changed

• Reordered the dispose() teardown sequence so the event loop exits cleanly without ever calling mpv_wait_event on a freed handle.

0.0.8 24-04-2026

Added

• stream.prefetchState - observable lifecycle of mpv's background playlist-prefetch (MpvPrefetchState: idle, loading, ready, used).
• stream.seekCompleted - authoritative "seek finished" signal that fires exactly once per seek or initial file load.

Changed

• on_load hook now runs for prefetched tracks, so custom URL schemes resolve uniformly whether mpv is opening the current track or pre-opening the next one.
• DASH segment downloads now reuse a single TCP connection across segment GETs (matches HLS persistent-HTTP behaviour).

Fixed

• Spurious position = 0 no longer emits on stream.position during seek / playback-restart.
• Audible click at every segment boundary on well-formed fragmented-MP4 / DASH streams (AAC encoder priming edit lists are now respected on fMP4).

Example

• Rewrote the seek slider to release its drag value via stream.seekCompleted instead of a fixed delay.

Build

• Updated libmpv binaries to libmpv-r4 across all platforms.

0.0.7 12-04-2026

Changed

• audio-format (u8, s16, s32, float, etc.) now accepts "no" and "" for instant reset to default - previously a full player restart was required.

Example

• Updated deprecated APIs that prevented the example app from running.

Build

• Updated libmpv binaries to libmpv-r3 across all platforms.

0.0.6 08-04-2026

Added

• SMB2/3 protocol support (smb2://) for Samba (CIFS) network shares via libsmb2.
• Typed error stream - Stream<MpvPlayerError> (sealed: MpvEndFileError, MpvLogError) replaces Stream<String>.
• stream.endFile (MpvFileEndedEvent) for all file-end events, including premature EOF detection.
• stream.pausedForCache and stream.demuxerViaNetwork for network state monitoring.
• Optional timeout parameter on registerHook for automatic safety continuation.

Fixed

• Incorrect name for the audio-stream-silence property.

Build

• Updated libmpv binaries from libmpv-r1 to libmpv-r2 across all platforms.

0.0.5+1 30-03-2026

Docs

• Improved README documentation.

0.0.5 24-03-2026

Added

• Stream hooks API (registerHook, continueHook, player.stream.hook) to intercept mpv's file-loading pipeline.

Docs

• README fixes and consistency improvements.

0.0.4 23-03-2026

Added

• New APIs to configure embedded and external cover-art handling: setAudioDisplay, setCoverArtAuto, setImageDisplayDuration.

Changed

• Fast jump into playlist now automatically starts playback.

Example

• Refined Queue tab design and improved stability.
• Added new sliders to DSP filters.

0.0.3+2 21-03-2026

Fixed

• Minor fixes.

0.0.3+1 21-03-2026

Build

• New tag system for versioning libmpv binaries (libmpv-r1, libmpv-r2, …) to avoid conflicts with the pub version number on GitHub Releases.

0.0.3 21-03-2026

Changed

• Linux: bumped minimum supported OS version to Ubuntu 24.04 - required because mpv 0.41.0 enforces a strict dependency on libpipewire-0.3 >= 0.3.57 for its native PipeWire backend.

Docs

• Added a detailed Troubleshooting section in the README explaining how to correctly satisfy Linux system dependencies when building on containers.

Example

• Fixed AO menu not showing the default driver automatically.

0.0.2+3 20-03-2026

Build

• Updated Linux libmpv: ALSA, PipeWire, and PulseAudio now all work without external dependencies.

0.0.2+2 18-03-2026

Changed

• Cleaned up files.

0.0.2+1 17-03-2026

Fixed

• Minor fixes.

0.0.2 17-03-2026

Added

• Extended documentation.

Changed

• Restructured the example app's settings UI: each mpv property has its own dedicated page; the stream lab moved to main navigation.

Fixed

• File picker on macOS.
• Other audio-engine fixes.

0.0.1+9 16-03-2026

Added

• New option to choose the AO driver in the example app.
• Added audio_service to the example app to test the native OS audio controls.

Changed

• Re-added the audiounit driver alongside avfoundation in libmpv for iOS - audio_service now works with both.

0.0.1+8 16-03-2026

Changed

• Removed the audiounit driver from libmpv to fix the native iOS widget for audio control when using the audio_service library.

Fixed

• File picker error in the example app.

0.0.1+7 16-03-2026

Fixed

• macOS libs build.

0.0.1+6 15-03-2026

Fixed

• Shuffle bug.

0.0.1+5 15-03-2026

Fixed

• Minor fixes.

0.0.1+4 15-03-2026

Fixed

• Minor fixes.

0.0.1+3 15-03-2026

Fixed

• Minor fixes.

0.0.1+2 15-03-2026

Fixed

• Minor fixes.

0.0.1+1 15-03-2026

Added

• Swift Package Manager support for iOS and macOS.

Fixed

• Broken image links on pub.dev (now use absolute GitHub URLs).
• All static analysis warnings; enforced curly braces in flow control structures.

0.0.1 15-03-2026

Added

• Initial release. High-performance audio library for Flutter powered by libmpv v0.41.0.
• Cross-platform support: iOS, Android, macOS, Windows, and Linux.
• Comprehensive example app demonstrating DSP, hardware routing, and queue management.