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.
AechoTap
One echo tap of the lavfi aecho filter.
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.
AiirChannel
One channel slot of the lavfi aiir filter — the per-channel gain plus the polynomial coefficients of its IIR transfer function.
AiirSettings
Configuration for the aiir audio effect.
AlimiterSettings
Configuration for the alimiter audio effect.
AllpassSettings
Configuration for the allpass audio effect.
AnequalizerBand
One logical band of the lavfi anequalizer filter.
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.
BandProcessor
Stateful PCM-to-bands processor — runs the same FFT, windowing, log-band aggregation and asymmetric-EMA smoothing the library uses internally to back PlayerStream.fft.
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.
ChorusVoice
One voice of the lavfi chorus filter.
CompandEnvelope
One per-channel envelope of the lavfi compand filter — the attack and decay time-constants the level detector uses on that channel.
CompandPoint
One break-point of the lavfi compand filter's transfer function.
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.
FirequalizerEntry
One break-point of the lavfi firequalizer filter's gain curve.
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.
McompandBand
One band of the lavfi mcompand filter — a self-contained compander stage with its own dynamics envelope, transfer function, soft-knee, makeup gain, and crossover frequency.
McompandSettings
Configuration for the mcompand audio effect.
Media
A piece of media that can be loaded into the Player.
MediaSession
Configuration and metadata for the OS media session — the lockscreen / SMTC / MPRIS entry, Bluetooth AVRCP, headset buttons, and (on iOS/Android) the AVAudioSession / AudioFocus integration.
MediaSessionArtwork
Artwork shown on the OS media session (lockscreen, Control Center, SMTC, MPRIS). Set via MediaSession.artwork.
MediaSessionCommand
A command issued by the operating system's media session — pressed on the lockscreen, sent by a Bluetooth headset, triggered by Siri / Google Assistant, or forwarded by Android Auto / CarPlay.
MediaSessionCommandLike
The MediaSessionCommand.like variant — the favourite/like control was pressed. Emit-only (no built-in player effect).
MediaSessionCommandNext
The MediaSessionCommand.next variant — skip to the next track.
MediaSessionCommandPause
The MediaSessionCommand.pause variant — pause playback.
MediaSessionCommandPlay
The MediaSessionCommand.play variant — start or resume playback.
MediaSessionCommandPlayPause
The MediaSessionCommand.playPause variant — toggle between play and pause.
MediaSessionCommandPrevious
The MediaSessionCommand.previous variant — skip to the previous track.
MediaSessionCommandSeekBy
The MediaSessionCommand.seekBy variant — seek by a relative offset. Negative offsets rewind.
MediaSessionCommandSeekTo
The MediaSessionCommand.seekTo variant — seek to an absolute position, carrying the target position.
MediaSessionCommandSetPlaybackRate
The MediaSessionCommand.setPlaybackRate variant — change playback speed to the carried rate.
MediaSessionCommandSetRepeatMode
The MediaSessionCommand.setRepeatMode variant — change the repeat mode to the carried loop.
MediaSessionCommandSetShuffle
The MediaSessionCommand.setShuffle variant — toggle shuffle to the carried shuffle state.
MediaSessionCommandStop
The MediaSessionCommand.stop variant — stop playback and clear the now-playing entry.
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
Mirror of libmpv's mpv_error return codes (the subset this package uses).
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.
WaveformData
Mono min/max amplitude envelope of the audio currently loaded.

Enums

AcompressorDetection
Values for the detection option of the acompressor audio filter.
Values for the link option of the acompressor audio filter.
AcompressorMode
Values for the mode option of the acompressor audio filter.
AcrusherMode
Values for the mode option of the acrusher audio filter.
AdeclickM
Values for the m option of the adeclick audio filter.
AdeclipM
Values for the m option of the adeclip audio filter.
AdenormType
Values for the type option of the adenorm audio filter.
AdynamicequalizerAuto
Values for the auto option of the adynamicequalizer audio filter.
AdynamicequalizerDftype
Values for the dftype option of the adynamicequalizer audio filter.
AdynamicequalizerMode
Values for the mode option of the adynamicequalizer audio filter.
AdynamicequalizerPrecision
Values for the precision option of the adynamicequalizer audio filter.
AdynamicequalizerTftype
Values for the tftype option of the adynamicequalizer audio filter.
AemphasisMode
Values for the mode option of the aemphasis audio filter.
AemphasisType
Values for the type option of the aemphasis audio filter.
AfadeCurve
Values for the c option of the afade audio filter.
AfadeType
Values for the t option of the afade audio filter.
Values for the nl option of the afftdn audio filter.
AfftdnMode
Values for the om option of the afftdn audio filter.
AfftdnSample
Values for the sample_noise option of the afftdn audio filter.
AfftdnType
Values for the noise_type option of the afftdn audio filter.
AfftfiltWinFunc
Values for the win_func option of the afftfilt audio filter.
AfwtdnWavet
Values for the wavet option of the afwtdn audio filter.
AgateDetection
Values for the detection option of the agate audio filter.
Values for the link option of the agate audio filter.
AgateMode
Values for the mode option of the agate audio filter.
AiirFormat
Values for the f option of the aiir audio filter.
AiirPrecision
Values for the e option of the aiir audio filter.
AiirProcess
Values for the process option of the aiir audio filter.
AllpassPrecision
Values for the precision option of the allpass audio filter.
AllpassTransformType
Values for the a option of the allpass audio filter.
AllpassWidthType
Values for the t option of the allpass audio filter.
AnequalizerBandType
lavfi anequalizer filter shape. Matches t=0|1|2 on the wire.
AnequalizerFscale
Values for the fscale option of the anequalizer audio filter.
AnlmdnMode
Values for the o option of the anlmdn audio filter.
AphaserType
Values for the type option of the aphaser audio filter.
ApulsatorMode
Values for the mode option of the apulsator audio filter.
ApulsatorTiming
Values for the timing option of the apulsator audio filter.
AsoftclipTypes
Values for the type option of the asoftclip audio filter.
AudioEffect
Identifies a single typed audio filter from the AudioEffects bundle.
AudioOutputState
Lifecycle of mpv's audio output, reported by the audio-output-state mpv property.
BandpassPrecision
Values for the precision option of the bandpass audio filter.
BandpassTransformType
Values for the a option of the bandpass audio filter.
BandpassWidthType
Values for the t option of the bandpass audio filter.
BandrejectPrecision
Values for the precision option of the bandreject audio filter.
BandrejectTransformType
Values for the a option of the bandreject audio filter.
BandrejectWidthType
Values for the t option of the bandreject audio filter.
BassPrecision
Values for the precision option of the bass audio filter.
BassTransformType
Values for the a option of the bass audio filter.
BassWidthType
Values for the t option of the bass audio filter.
BiquadPrecision
Values for the precision option of the biquad audio filter.
BiquadTransformType
Values for the a option of the biquad audio filter.
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
Values for the s option of the deesser audio filter.
Ebur128Gaugetype
Values for the gauge option of the ebur128 audio filter.
Ebur128Level
Values for the framelog option of the ebur128 audio filter.
Ebur128Mode
Values for the peak option of the ebur128 audio filter.
Ebur128Scaletype
Values for the scale option of the ebur128 audio filter.
EqualizerPrecision
Values for the precision option of the equalizer audio filter.
EqualizerTransformType
Values for the a option of the equalizer audio filter.
EqualizerWidthType
Values for the t option of the equalizer audio filter.
FirequalizerScale
Values for the dumpscale option of the firequalizer audio filter.
FirequalizerWfunc
Values for the wfunc option of the firequalizer audio filter.
FlangerItype
Values for the interp option of the flanger audio filter.
FlangerType
Values for the shape option of the flanger audio filter.
Format
Audio sample format passed to mpv's audio-format property.
Gapless
Gapless playback mode, mirroring --gapless-audio=<no|yes|weak>.
HaasSource
Values for the middle_source option of the haas audio filter.
HdcdAnalyzeMode
Values for the analyze_mode option of the hdcd audio filter.
HdcdBitsPerSample
Values for the bits_per_sample option of the hdcd audio filter.
HeadphoneHrir
Values for the hrir option of the headphone audio filter.
HeadphoneType
Values for the type option of the headphone audio filter.
HighpassPrecision
Values for the precision option of the highpass audio filter.
HighpassTransformType
Values for the a option of the highpass audio filter.
HighpassWidthType
Values for the t option of the highpass audio filter.
HighshelfPrecision
Values for the precision option of the highshelf audio filter.
HighshelfTransformType
Values for the a option of the highshelf audio filter.
HighshelfWidthType
Values for the t option of the highshelf audio filter.
Hook
Lifecycle hook fired by mpv during file loading and unloading.
InterruptionPolicy
How the player reacts when the OS interrupts audio — a phone call, Siri, an alarm, or another app taking audio focus. Set via MediaSession.interruptionPolicy.
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
Values for the print_format option of the loudnorm audio filter.
LowpassPrecision
Values for the precision option of the lowpass audio filter.
LowpassTransformType
Values for the a option of the lowpass audio filter.
LowpassWidthType
Values for the t option of the lowpass audio filter.
LowshelfPrecision
Values for the precision option of the lowshelf audio filter.
LowshelfTransformType
Values for the a option of the lowshelf audio filter.
LowshelfWidthType
Values for the t option of the lowshelf audio filter.
MediaAction
Capabilities to advertise to the operating system's media session (lockscreen controls, Bluetooth AVRCP, headset buttons, …).
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
Values for the channels option of the rubberband audio filter.
RubberbandDetector
Values for the detector option of the rubberband audio filter.
RubberbandFormant
Values for the formant option of the rubberband audio filter.
RubberbandPhase
Values for the phase option of the rubberband audio filter.
RubberbandPitch
Values for the pitchq option of the rubberband audio filter.
RubberbandSmoothing
Values for the smoothing option of the rubberband audio filter.
RubberbandTransients
Values for the transients option of the rubberband audio filter.
RubberbandWindow
Values for the window option of the rubberband audio filter.
SilenceremoveDetection
Values for the detection option of the silenceremove audio filter.
SilenceremoveMode
Values for the start_mode option of the silenceremove audio filter.
SilenceremoveTimestamp
Values for the timestamp option of the silenceremove audio filter.
Spdif
S/PDIF (or HDMI) compressed-audio passthrough codec.
StereotoolsBmode
Values for the bmode_in option of the stereotools audio filter.
StereotoolsMode
Values for the mode option of the stereotools audio filter.
SurroundLfeMode
Values for the lfe_mode option of the surround audio filter.
SurroundWinFunc
Values for the win_func option of the surround audio filter.
TapSide
Side of an audio filter at which a per-filter tap captures samples.
TiltshelfPrecision
Values for the precision option of the tiltshelf audio filter.
TiltshelfTransformType
Values for the a option of the tiltshelf audio filter.
TiltshelfWidthType
Values for the t option of the tiltshelf audio filter.
TreblePrecision
Values for the precision option of the treble audio filter.
TrebleTransformType
Values for the a option of the treble audio filter.
TrebleWidthType
Values for the t option of the treble audio filter.
WindowFunction
Window function applied to each FFT block before transform.

Extensions

AdelayChannelsX on AdelaySettings
Typed access over lavfi's adelay.delays — a pipe-separated list of per-channel delays. The Nth entry is the delay applied to the Nth output channel.
AechoTapsX on AechoSettings
Typed access over the parallel pipe-separated CSVs lavfi's aecho packs as delays/decays.
AfftdnBandNoiseX on AfftdnSettings
Typed access over the band_noise (alias bn) string lavfi's afftdn packs as space- or pipe-separated noise levels per band.
AiirChannelsX on AiirSettings
Typed access over aiir's three parallel string parameters (gains/k, poles/p, zeros/z). The Nth |-section of each string belongs to the Nth output channel; coefficient lists within a channel are space-separated.
AnequalizerBandsX on AnequalizerSettings
Typed access over the raw params CSV held by AnequalizerSettings.
AudioEffectsX on AudioEffects
Cross-link between the singular AudioEffect enum and the plural AudioEffects bundle: yields the AudioEffect for every slot whose *Settings.enabled is true, in the same declaration order as the bundle's fields.
ChorusVoicesX on ChorusSettings
Typed access over the four parallel pipe-separated CSVs (delays/decays/depths/speeds) lavfi's chorus exposes.
CompandEnvelopesX on CompandSettings
Typed access over the parallel pipe-separated CSVs lavfi's compand packs as attacks/decays.
CompandPointsX on CompandSettings
Typed access over the points string lavfi's compand carries (space-separated inDb/outDb pairs).
CompandSoftKneeX on CompandSettings
Typed access over compand.soft-knee — the smoothing applied across the breakpoints of the transfer function.
FirequalizerEntriesX on FirequalizerSettings
Typed access over the gain_entry string lavfi's firequalizer carries (entry(freq,gain);entry(freq,gain);…).
McompandBandsX on McompandSettings
Typed access over the raw args string held by McompandSettings.
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.
SuperequalizerBandsX on SuperequalizerSettings
Typed access over the digit-prefixed 1b, 2b, …, 18b parameters that lavfi's superequalizer packs into the bundle's raw params: Map<String, double>.

Constants

kAfftdnBandCount → const int
Number of fixed bands lavfi's afftdn uses for its custom noise profile — the filter splits the spectrum into 15 logarithmic bands and lets the consumer set a noise floor per band.
kAfftdnBandNoiseDefault → const double
Default per-band noise floor when none is provided.
kCompandSoftKneeDefault → const double
lavfi-side default for compand.soft-knee — leaves the transfer-function knee hard.
kSuperequalizerBandCount → const int
Number of bands the superequalizer filter exposes — fixed by the underlying ISO half-octave grid.
kSuperequalizerFrequencies → const List<double>
18 fixed band centre frequencies of the lavfi superequalizer, in Hz, lows-to-highs in declaration order. The frequencies are hard-coded inside af_superequalizer.c and are not configurable — only the per-band gain is.
kSuperequalizerUnityGain → const double
Default linear gain for an unmodified band (1.0 = unity, no change to that frequency's level).

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.