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
acompressoraudio effect. - AcontrastSettings
-
Configuration for the
acontrastaudio effect. - AcrusherSettings
-
Configuration for the
acrusheraudio effect. - AdeclickSettings
-
Configuration for the
adeclickaudio effect. - AdeclipSettings
-
Configuration for the
adeclipaudio effect. - AdecorrelateSettings
-
Configuration for the
adecorrelateaudio effect. - AdelaySettings
-
Configuration for the
adelayaudio effect. - AdenormSettings
-
Configuration for the
adenormaudio effect. - AderivativeSettings
-
Configuration for the
aderivativeaudio effect. - AdrcSettings
-
Configuration for the
adrcaudio effect. - AdynamicequalizerSettings
-
Configuration for the
adynamicequalizeraudio effect. - AdynamicsmoothSettings
-
Configuration for the
adynamicsmoothaudio effect. - AechoSettings
-
Configuration for the
aechoaudio effect. - AemphasisSettings
-
Configuration for the
aemphasisaudio effect. - AevalSettings
-
Configuration for the
aevalaudio effect. - AexciterSettings
-
Configuration for the
aexciteraudio effect. - AfadeSettings
-
Configuration for the
afadeaudio effect. - AfftdnSettings
-
Configuration for the
afftdnaudio effect. - AfftfiltSettings
-
Configuration for the
afftfiltaudio effect. - AformatSettings
-
Configuration for the
aformataudio effect. - AfreqshiftSettings
-
Configuration for the
afreqshiftaudio effect. - AfwtdnSettings
-
Configuration for the
afwtdnaudio effect. - AgateSettings
-
Configuration for the
agateaudio effect. - AiirSettings
-
Configuration for the
aiiraudio effect. - AlimiterSettings
-
Configuration for the
alimiteraudio effect. - AllpassSettings
-
Configuration for the
allpassaudio effect. - AnequalizerSettings
-
Configuration for the
anequalizeraudio effect. - AnlmdnSettings
-
Configuration for the
anlmdnaudio effect. - ApadSettings
-
Configuration for the
apadaudio effect. - AphaserSettings
-
Configuration for the
aphaseraudio effect. - AphaseshiftSettings
-
Configuration for the
aphaseshiftaudio effect. - ApsyclipSettings
-
Configuration for the
apsyclipaudio effect. - ApulsatorSettings
-
Configuration for the
apulsatoraudio effect. - AresampleSettings
-
Configuration for the
aresampleaudio effect. - ArnndnSettings
-
Configuration for the
arnndnaudio effect. - AsoftclipSettings
-
Configuration for the
asoftclipaudio effect. - AsubboostSettings
-
Configuration for the
asubboostaudio effect. - AsubcutSettings
-
Configuration for the
asubcutaudio effect. - AsupercutSettings
-
Configuration for the
asupercutaudio effect. - AsuperpassSettings
-
Configuration for the
asuperpassaudio effect. - AsuperstopSettings
-
Configuration for the
asuperstopaudio effect. - AtempoSettings
-
Configuration for the
atempoaudio effect. - AtiltSettings
-
Configuration for the
atiltaudio 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
bandpassaudio effect. - BandrejectSettings
-
Configuration for the
bandrejectaudio effect. - BassSettings
-
Configuration for the
bassaudio effect. - BiquadSettings
-
Configuration for the
biquadaudio effect. - CacheSettings
-
Aggregate of mpv's five cache properties (
cache,cache-secs,cache-on-disk,cache-pause,cache-pause-wait). - ChannelmapSettings
-
Configuration for the
channelmapaudio effect. - Channels
-
How Player.setAudioChannels should resolve mpv's
audio-channelsproperty. - Chapter
-
A chapter entry in the current track's
chapter-list. - ChorusSettings
-
Configuration for the
chorusaudio effect. - CompandSettings
-
Configuration for the
compandaudio effect. - CompensationdelaySettings
-
Configuration for the
compensationdelayaudio effect. - CoverArt
- Cover-art payload extracted from the currently loaded file.
- CrossfeedSettings
-
Configuration for the
crossfeedaudio effect. - CrystalizerSettings
-
Configuration for the
crystalizeraudio effect. - DcshiftSettings
-
Configuration for the
dcshiftaudio effect. - DeesserSettings
-
Configuration for the
deesseraudio effect. - Device
- Represents an audio output device detected by mpv.
- DialoguenhanceSettings
-
Configuration for the
dialoguenhanceaudio effect. - DrmeterSettings
-
Configuration for the
drmeteraudio effect. - DynaudnormSettings
-
Configuration for the
dynaudnormaudio effect. - EarwaxSettings
-
Configuration for the
earwaxaudio effect. - Ebur128Settings
-
Configuration for the
ebur128audio effect. - EqualizerSettings
-
Configuration for the
equalizeraudio effect. - ExtrastereoSettings
-
Configuration for the
extrastereoaudio effect. - FftFrame
- One FFT frame — a frequency-domain snapshot of the audio currently playing through the player's output.
- FirequalizerSettings
-
Configuration for the
firequalizeraudio effect. - FlangerSettings
-
Configuration for the
flangeraudio effect. - HaasSettings
-
Configuration for the
haasaudio effect. - HdcdSettings
-
Configuration for the
hdcdaudio effect. - HeadphoneSettings
-
Configuration for the
headphoneaudio effect. - HighpassSettings
-
Configuration for the
highpassaudio effect. - HighshelfSettings
-
Configuration for the
highshelfaudio effect. - LoudnormSettings
-
Configuration for the
loudnormaudio effect. - LowpassSettings
-
Configuration for the
lowpassaudio effect. - LowshelfSettings
-
Configuration for the
lowshelfaudio effect. - McompandSettings
-
Configuration for the
mcompandaudio effect. - Media
- A piece of media that can be loaded into the Player.
- MpvAudioKit
-
One-time initialization for
mpv_audio_kit. Owns the libmpvDynamicLibrarylookup 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 carriesprefix: 'mpv_audio_kit'). Filter by level to reduce noise. - MpvLogError
-
A log message at
errororfatallevel from an mpv subsystem. - MpvPlayerError
-
Typed error events delivered on PlayerStream.error. A sealed union
over MpvEndFileError (playback failures) and MpvLogError
(
error/fatallog lines from an mpv subsystem). Pattern-match on the variant to distinguish them. - MpvTrack
-
A single track entry from mpv's
track-list(orcurrent-tracks/audio). - PanSettings
-
Configuration for the
panaudio 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
rubberbandaudio effect. - SilenceremoveSettings
-
Configuration for the
silenceremoveaudio effect. - SpectrumSettings
- Configuration for the real-time FFT spectrum + raw PCM streams.
- SpeechnormSettings
-
Configuration for the
speechnormaudio effect. - StereotoolsSettings
-
Configuration for the
stereotoolsaudio effect. - StereowidenSettings
-
Configuration for the
stereowidenaudio effect. - SuperequalizerSettings
-
Configuration for the
superequalizeraudio effect. - SurroundSettings
-
Configuration for the
surroundaudio effect. - TiltshelfSettings
-
Configuration for the
tiltshelfaudio effect. - Track
-
How Player.setAudioTrack should resolve mpv's
aidproperty. - TrebleSettings
-
Configuration for the
trebleaudio effect. - TremoloSettings
-
Configuration for the
tremoloaudio effect. - VibratoSettings
-
Configuration for the
vibratoaudio effect. - VirtualbassSettings
-
Configuration for the
virtualbassaudio effect.
Enums
- AcompressorDetection
- AcompressorLink
- AcompressorMode
- AcrusherMode
- AdeclickM
- AdeclipM
- AdenormType
- AdynamicequalizerAuto
- AdynamicequalizerDftype
- AdynamicequalizerMode
- AdynamicequalizerPrecision
- AdynamicequalizerTftype
- AemphasisMode
- AemphasisType
- AfadeCurve
- AfadeType
- AfftdnLink
- AfftdnMode
- AfftdnSample
- AfftdnType
- AfwtdnWavet
- AgateDetection
- AgateLink
- AgateMode
- AiirFormat
- AiirPrecision
- AiirProcess
- AnequalizerFscale
- AnlmdnMode
- AphaserType
- ApulsatorMode
- ApulsatorTiming
- AsoftclipTypes
- AudioOutputState
-
Lifecycle of mpv's audio output, reported by the
audio-output-statempv 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-formatproperty. - 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-levellevels verbatim. - Loop
- Looping behaviour for playback.
- LoudnormPrintFormat
- MpvEndFileReason
-
Why a file ended — mirrors
mpv_end_file_reasonfrom the C API. - MpvPlaybackState
-
Aggregate playback lifecycle, derived from
playing/buffering/completed/pausedForCache/duration. Subscribe viaPlayerStream.playbackStatewhen a single mutually-exclusive state fits the UI better than three separate booleans. The underlying booleans remain available onPlayerStreamfor 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
libmpvshared library cannot be loaded or resolved.