mpv_audio_kit library

mpv_audio_kit — Flutter audio player powered by libmpv.

Supports macOS, Windows, Linux, iOS, and Android.

Quick start

import 'package:mpv_audio_kit/mpv_audio_kit.dart';

final player = Player();

player.stream.position.listen((pos) => print(pos));
player.stream.playing.listen((p)   => print('playing: $p'));

await player.open(Media('https://example.com/audio.mp3'));
await player.play();

// ...
await player.dispose();

Classes

AcompressorSettings
Configuration for the acompressor audio effect.
AcontrastSettings
Configuration for the acontrast audio effect.
AcrusherSettings
Configuration for the acrusher audio effect.
AdeclickSettings
Configuration for the adeclick audio effect.
AdeclipSettings
Configuration for the adeclip audio effect.
AdecorrelateSettings
Configuration for the adecorrelate audio effect.
AdelaySettings
Configuration for the adelay audio effect.
AdenormSettings
Configuration for the adenorm audio effect.
AderivativeSettings
Configuration for the aderivative audio effect.
AdrcSettings
Configuration for the adrc audio effect.
AdynamicequalizerSettings
Configuration for the adynamicequalizer audio effect.
AdynamicsmoothSettings
Configuration for the adynamicsmooth audio effect.
AechoSettings
Configuration for the aecho audio effect.
AemphasisSettings
Configuration for the aemphasis audio effect.
AevalSettings
Configuration for the aeval audio effect.
AexciterSettings
Configuration for the aexciter audio effect.
AfadeSettings
Configuration for the afade audio effect.
AfftdnSettings
Configuration for the afftdn audio effect.
AfftfiltSettings
Configuration for the afftfilt audio effect.
AformatSettings
Configuration for the aformat audio effect.
AfreqshiftSettings
Configuration for the afreqshift audio effect.
AfwtdnSettings
Configuration for the afwtdn audio effect.
AgateSettings
Configuration for the agate audio effect.
AiirSettings
Configuration for the aiir audio effect.
AlimiterSettings
Configuration for the alimiter audio effect.
AllpassSettings
Configuration for the allpass audio effect.
AnequalizerSettings
Configuration for the anequalizer audio effect.
AnlmdnSettings
Configuration for the anlmdn audio effect.
ApadSettings
Configuration for the apad audio effect.
AphaserSettings
Configuration for the aphaser audio effect.
AphaseshiftSettings
Configuration for the aphaseshift audio effect.
ApsyclipSettings
Configuration for the apsyclip audio effect.
ApulsatorSettings
Configuration for the apulsator audio effect.
AresampleSettings
Configuration for the aresample audio effect.
ArnndnSettings
Configuration for the arnndn audio effect.
AsoftclipSettings
Configuration for the asoftclip audio effect.
AsubboostSettings
Configuration for the asubboost audio effect.
AsubcutSettings
Configuration for the asubcut audio effect.
AsupercutSettings
Configuration for the asupercut audio effect.
AsuperpassSettings
Configuration for the asuperpass audio effect.
AsuperstopSettings
Configuration for the asuperstop audio effect.
AtempoSettings
Configuration for the atempo audio effect.
AtiltSettings
Configuration for the atilt audio effect.
AudioEffects
All audio effects bundled into a single atomic configuration applied via Player.setAudioEffects / Player.updateAudioEffects.
AudioParams
Audio format parameters reported by mpv. Used both for the decoder side (audio-params + audio-codec*) and for the hardware output side (audio-out-params).
BandpassSettings
Configuration for the bandpass audio effect.
BandrejectSettings
Configuration for the bandreject audio effect.
BassSettings
Configuration for the bass audio effect.
BiquadSettings
Configuration for the biquad audio effect.
CacheSettings
Aggregate of mpv's five cache properties (cache, cache-secs, cache-on-disk, cache-pause, cache-pause-wait).
ChannelmapSettings
Configuration for the channelmap audio effect.
Channels
How Player.setAudioChannels should resolve mpv's audio-channels property.
Chapter
A chapter entry in the current track's chapter-list.
ChorusSettings
Configuration for the chorus audio effect.
CompandSettings
Configuration for the compand audio effect.
CompensationdelaySettings
Configuration for the compensationdelay audio effect.
CoverArt
Cover-art payload extracted from the currently loaded file.
CrossfeedSettings
Configuration for the crossfeed audio effect.
CrystalizerSettings
Configuration for the crystalizer audio effect.
DcshiftSettings
Configuration for the dcshift audio effect.
DeesserSettings
Configuration for the deesser audio effect.
Device
Represents an audio output device detected by mpv.
DialoguenhanceSettings
Configuration for the dialoguenhance audio effect.
DrmeterSettings
Configuration for the drmeter audio effect.
DynaudnormSettings
Configuration for the dynaudnorm audio effect.
EarwaxSettings
Configuration for the earwax audio effect.
Ebur128Settings
Configuration for the ebur128 audio effect.
EqualizerSettings
Configuration for the equalizer audio effect.
ExtrastereoSettings
Configuration for the extrastereo audio effect.
FftFrame
One FFT frame — a frequency-domain snapshot of the audio currently playing through the player's output.
FirequalizerSettings
Configuration for the firequalizer audio effect.
FlangerSettings
Configuration for the flanger audio effect.
HaasSettings
Configuration for the haas audio effect.
HdcdSettings
Configuration for the hdcd audio effect.
HeadphoneSettings
Configuration for the headphone audio effect.
HighpassSettings
Configuration for the highpass audio effect.
HighshelfSettings
Configuration for the highshelf audio effect.
LoudnormSettings
Configuration for the loudnorm audio effect.
LowpassSettings
Configuration for the lowpass audio effect.
LowshelfSettings
Configuration for the lowshelf audio effect.
McompandSettings
Configuration for the mcompand audio effect.
Media
A piece of media that can be loaded into the Player.
MpvAudioKit
One-time initialization for mpv_audio_kit. Owns the libmpv DynamicLibrary lookup and the orphaned-handle cleanup that fires across Flutter Hot-Restarts.
MpvEndFileError
Playback of a file ended with an error or unexpected EOF.
MpvError
MpvFileEndedEvent
Emitted for every file-end event, regardless of whether an error occurred.
MpvHookEvent
Emitted by PlayerStream.hook when mpv fires a registered hook.
MpvLogEntry
A structured log entry. Emitted on PlayerStream.log for messages from the mpv engine ('ffmpeg', 'demux', 'ao', …) and on PlayerStream.internalLog for library-side diagnostics (parse warnings, hook timeouts; always carries prefix: 'mpv_audio_kit'). Filter by level to reduce noise.
MpvLogError
A log message at error or fatal level from an mpv subsystem.
MpvPlayerError
Typed error events delivered on PlayerStream.error. A sealed union over MpvEndFileError (playback failures) and MpvLogError (error / fatal log lines from an mpv subsystem). Pattern-match on the variant to distinguish them.
MpvTrack
A single track entry from mpv's track-list (or current-tracks/audio).
PanSettings
Configuration for the pan audio effect.
PcmFrame
One PCM frame — raw post-DSP audio samples captured at the player's output, before they're handed to the OS audio driver.
Player
A high-performance audio player powered by libmpv.
PlayerApi
Public surface of the Player — every method, getter, and stream a consumer interacts with.
PlayerConfiguration
Initial configuration for a Player instance.
PlayerState
Immutable snapshot of the Player's complete playback state.
PlayerStream
Typed event streams for subscribing to individual Player state changes.
Playlist
An ordered list of Media items loaded into the Player.
ReplayGainSettings
Aggregate of mpv's four ReplayGain properties (replaygain, replaygain-preamp, replaygain-clip, replaygain-fallback).
RubberbandSettings
Configuration for the rubberband audio effect.
SilenceremoveSettings
Configuration for the silenceremove audio effect.
SpectrumSettings
Configuration for the real-time FFT spectrum + raw PCM streams.
SpeechnormSettings
Configuration for the speechnorm audio effect.
StereotoolsSettings
Configuration for the stereotools audio effect.
StereowidenSettings
Configuration for the stereowiden audio effect.
SuperequalizerSettings
Configuration for the superequalizer audio effect.
SurroundSettings
Configuration for the surround audio effect.
TiltshelfSettings
Configuration for the tiltshelf audio effect.
Track
How Player.setAudioTrack should resolve mpv's aid property.
TrebleSettings
Configuration for the treble audio effect.
TremoloSettings
Configuration for the tremolo audio effect.
VibratoSettings
Configuration for the vibrato audio effect.
VirtualbassSettings
Configuration for the virtualbass audio effect.

Enums

AcompressorDetection
AcompressorMode
AcrusherMode
AdeclickM
AdeclipM
AdenormType
AdynamicequalizerAuto
AdynamicequalizerDftype
AdynamicequalizerMode
AdynamicequalizerPrecision
AdynamicequalizerTftype
AemphasisMode
AemphasisType
AfadeCurve
AfadeType
AfftdnMode
AfftdnSample
AfftdnType
AfwtdnWavet
AgateDetection
AgateMode
AiirFormat
AiirPrecision
AiirProcess
AnequalizerFscale
AnlmdnMode
AphaserType
ApulsatorMode
ApulsatorTiming
AsoftclipTypes
AudioOutputState
Lifecycle of mpv's audio output, reported by the audio-output-state mpv property.
Cache
Network cache mode, mirroring --cache=<auto|yes|no>.
Cover
External cover-art auto-load behaviour, mirroring --cover-art-auto=<no|exact|fuzzy|all>.
DeesserMode
Ebur128Gaugetype
Ebur128Level
Ebur128Mode
Ebur128Scaletype
FirequalizerScale
FirequalizerWfunc
FlangerItype
FlangerType
Format
Audio sample format passed to mpv's audio-format property.
Gapless
Gapless playback mode, mirroring --gapless-audio=<no|yes|weak>.
HaasSource
HdcdAnalyzeMode
HdcdBitsPerSample
HeadphoneHrir
HeadphoneType
Hook
Lifecycle hook fired by mpv during file loading and unloading.
LogLevel
Severity threshold for the mpv log stream and library-side diagnostics. Mirrors mpv's --msg-level levels verbatim.
Loop
Looping behaviour for playback.
LoudnormPrintFormat
MpvEndFileReason
Why a file ended — mirrors mpv_end_file_reason from the C API.
MpvPlaybackState
Aggregate playback lifecycle, derived from playing / buffering / completed / pausedForCache / duration. Subscribe via PlayerStream.playbackState when a single mutually-exclusive state fits the UI better than three separate booleans. The underlying booleans remain available on PlayerStream for granular use cases.
MpvPrefetchState
Lifecycle phase of mpv's background playlist-prefetch.
ReplayGain
ReplayGain normalization mode, mirroring --replaygain=<no|track|album>.
RubberbandChannels
RubberbandDetector
RubberbandFormant
RubberbandPhase
RubberbandPitch
RubberbandSmoothing
RubberbandTransients
RubberbandWindow
SilenceremoveDetection
SilenceremoveMode
SilenceremoveTimestamp
Spdif
S/PDIF (or HDMI) compressed-audio passthrough codec.
StereotoolsBmode
StereotoolsMode
SurroundLfeMode
WindowFunction
Window function applied to each FFT block before transform.

Extensions

MpvEndFileErrorX on MpvEndFileError
Convenience predicates for MpvEndFileError.
MpvFileEndedEventX on MpvFileEndedEvent
Whether the file ended naturally and not because of a stop, error, redirect, or shutdown.

Exceptions / Errors

MpvException
Thrown by Player.setRawProperty / Player.sendRawCommand when libmpv rejects the request — typically a typo in the property name, an out-of-range value, or an unknown command.
MpvLibraryException
Exception thrown when the libmpv shared library cannot be loaded or resolved.