PlayerApi class abstract interface

Public surface of the Player: every method, getter, and stream a consumer interacts with.

Exists so test code can mock the player cleanly:

class MockPlayer extends Mock implements PlayerApi {}

Without this interface a mock would have to extend Player itself, which drags in the FFI handle, the event isolate, and the _PlayerBase initialization. None of that is mockable in a unit test.

Player implements PlayerApi. Production code that takes a Player argument should consider taking a PlayerApi instead unless it needs access to extension members not on the interface (none today).

Implementers

Properties

configuration → PlayerConfiguration
The configuration captured at construction time.
no setter
hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
state → PlayerState
Synchronous snapshot of the player's complete state. Updated on every observed property change before the corresponding stream emits.
no setter
stream → PlayerStream
Typed event streams for individual state fields and transient events.
no setter

Methods

add(Media media) → Future<void>
Appends media to the end of the playlist.
addAudioTrack(Media file, {bool select, String? title, String? lang}) → Future<void>
Loads an external audio file as an extra selectable track on the current file (mpv's audio-add). See Player.addAudioTrack.
clearPlaylist({bool keepCurrent = false}) → Future<void>
Removes every entry from the playlist; with keepCurrent true the current one stays and keeps playing. See Player.clearPlaylist.
continueHook(int id) → Future<void>
Releases the hook stage identified by id, letting mpv resume the gated operation. A no-op for an event already released, also by the timeout, and after dispose, which has already released every pending hook.
deleteResumeConfig({String? filename}) → Future<void>
Deletes the "watch later" resume point for the current file, or for filename when given. See Player.deleteResumeConfig.
dispose() → Future<void>
Tears down the player. Idempotent: every call returns the same teardown future.
getRawProperty(String name) → Future<String?>
Reads an arbitrary mpv property as a string; null if unset or unavailable. Escape hatch for properties without a typed accessor.
getRawPropertyNode(String name) → Future<Object?>
Reads an arbitrary mpv property as a decoded node tree (maps, lists, scalars or byte arrays); null if unset or unavailable. The structured counterpart of getRawProperty for properties like track-list.
insert(int index, Media media) → Future<void>
Inserts media at index in the playlist, before the entry there; index equal to the length appends. The current entry keeps playing. Throws RangeError if index is outside 0..length. See Player.insert.
jump(int index) → Future<void>
Jumps to the playlist entry at index and plays it. Throws RangeError if index is out of range.
move(int from, int to) → Future<void>
Moves the playlist entry from index from to index to. Throws RangeError if either is out of range.
next({bool force}) → Future<bool>
Advances to the next playlist entry and returns true, or false when there is none. With force true, advancing past the last entry stops playback; the default does nothing at the end.
nextPlaylist() → Future<bool>
Jumps to the next entry from a different source playlist (playlist-path), navigation across concatenated playlists. Returns false when there is none.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
open(Media media, {bool? play}) → Future<void>
Loads media as the sole playlist entry and optionally starts playback. When play is null the configuration's autoplay value decides. Replaces any currently loaded file or playlist.
openAll(List<Media> medias, {bool? play, int index = 0}) → Future<void>
Loads medias as the new playlist, optionally starting at index (clamped to the valid range) and optionally starting playback. The multi-item counterpart of open. It succeeds or fails as a whole: see Player.openAll.
openPcmStream(PcmFormat format, {bool play = true, Duration maxBuffered = const Duration(seconds: 30), bool lowLatency = false, Map<String, Object?>? extras}) → Future<PcmSource>
Creates a live PcmSource of format and opens it as the sole playlist entry. See Player.openPcmStream.
openPlaylistFile(Media playlist, {bool? play}) → Future<void>
Loads a playlist file or URL (.m3u, .m3u8, .pls or .cue) as the new playlist via mpv's loadlist, expanding its entries into the playlist: the path for internet-radio station lists and remote .m3u playlists. Contrast with open, which loads a single entry. See Player.openPlaylistFile for the per-Media option caveats.
pause() → Future<void>
Pauses playback, preserving the playhead position. Idempotent.
play() → Future<void>
Starts or resumes playback (sets the play-pause intent to play). Idempotent while playing. Once the queue has ended (PlaybackState.completed) it starts the last track again from its beginning; with nothing loaded, or at the end of a source that cannot seek back, the intent stays off.
previous({bool force}) → Future<bool>
Returns to the previous playlist entry and returns true, or false when there is none. With force true, going back past the first entry stops playback; the default does nothing at the start.
previousPlaylist() → Future<bool>
Jumps to the first of the previous entries from a different source playlist (playlist-path). The reverse of nextPlaylist.
registerHook(Hook hook, {int priority = 0, Duration? timeout}) → Future<void>
Registers a libmpv hook. Lower priority runs earlier, as in mpv, and 0 is the neutral default; timeout caps how long mpv waits before auto-continuing (without it, an earlier deadline for hook stays). Hook events surface on PlayerStream.hook and must be released with continueHook.
reloadAudio() → Future<void>
Closes and reopens the audio output (mpv's ao-reload). The decoder keeps running.
remove(int index) → Future<void>
Removes the playlist entry at index. Throws RangeError if index is out of range.
removeAudioTrack(Track track) → Future<void>
Removes an audio track (mpv's audio-remove); Track.id removes a specific one, Track.auto the current. See Player.removeAudioTrack.
replace(int index, Media media) → Future<void>
Replaces the playlist entry at index with media. Throws RangeError if index is out of range.
rescanExternalFiles({bool keepSelection}) → Future<void>
Re-scans the external files next to the current file (mpv's rescan-external-files), within mpv's auto-load options, which load none by default. See Player.rescanExternalFiles.
revertSeek() → Future<void>
Jumps back to where playback was before the last jump in the current file (mpv's revert-seek); throws MpvCommandException when there is none yet. See Player.revertSeek.
seek(Duration position, {bool relative, bool exact}) → Future<void>
Seeks within the current file. With relative false position is an absolute timestamp, a negative one going to the start; with true it is a signed offset from the playhead. exact forces a sample-accurate (slower) seek.
seekToPercent(double percent, {bool relative, bool exact}) → Future<void>
Seeks by percentage of the file duration (0 to 100). See Player.seekToPercent.
sendRawCommand(List<String> args) → Future<void>
Sends an arbitrary mpv command with its argument list. Escape hatch for commands without a typed wrapper. A command that writes af or pause, such as cycle pause, throws ArgumentError: see Player.sendRawCommand.
setAbLoopA(Duration? position) → Future<void>
Sets the A-B loop start point for the current file; null disables it. See Player.setAbLoopA.
setAbLoopB(Duration? position) → Future<void>
Sets the A-B loop end point for the current file; null disables it.
setAbLoopCount(int? count) → Future<void>
Sets how many times playback jumps back to A after the first pass; null loops infinitely and 0 turns the loop off.
setAudioBuffer(Duration size) → Future<void>
Sets the output device buffer size.
setAudioChannels(Channels channels) → Future<void>
Forces the output channel layout; Channels.auto lets mpv choose.
setAudioClientName(String name) → Future<void>
Sets the client name reported to the audio server.
setAudioDelay(Duration delay) → Future<void>
Sets the audio sync offset relative to the playback clock.
setAudioDevice(Device device) → Future<void>
Selects the audio output device.
setAudioDriver(String driver) → Future<void>
Selects the audio output driver (e.g. 'coreaudio', 'wasapi', 'pulse', 'alsa', 'pipewire'). Pass 'auto' or an empty string to let mpv auto-probe the best backend (the default).
setAudioEffects(List<AudioEffect> effects) → Future<void>
Replaces the whole DSP rack atomically with effects.
setAudioExclusive(bool exclusive) → Future<void>
Opens the audio device in exclusive mode when exclusive is true: WASAPI and CoreAudio take the device, PipeWire keeps other streams off the sink, and iOS and Android's default driver ignore it. See Player.setAudioExclusive.
setAudioFormat(Format format) → Future<void>
Forces the output sample format; Format.auto lets mpv choose.
setAudioMediaRole(bool enable) → Future<void>
Reports a "music" media role to the OS audio server (PulseAudio or PipeWire) when enable is true (mpv's audio-set-media-role). On Android it only tags the content type: see Player.setAudioMediaRole.
setAudioNullUntimed(bool enable) → Future<void>
Runs the null audio output untimed when enable is true.
setAudioSampleRate(int rate) → Future<void>
Sets the target output sample rate in Hz, 0 for mpv's choice. See Player.setAudioSampleRate.
setAudioSpdif(Set<Spdif> codecs) → Future<void>
Sets the set of codecs to pass through as bitstream rather than decode. See Player.setAudioSpdif for what stops applying to a track in passthrough.
setAudioStreamSilence(bool enable) → Future<void>
Streams silence to keep the device open while idle when enable is true.
setAudioTrack(Track track) → Future<void>
Selects the active audio track.
setCache(CacheSettings settings) → Future<void>
Applies the demuxer cache configuration atomically.
setChapter(int index) → Future<void>
Jumps to the 0-based chapter index in the current file; throws MpvCommandException when index is out of range.
setChapters(List<Chapter> chapters) → Future<void>
Replaces the current file's chapter markers with chapters, an external-chapters injection for sources whose container carries none (e.g. an extracted audio stream whose chapters are published separately). Writes mpv's chapter-list directly, so PlayerStream.chapters reflect them and setChapter navigates them. Call after the file is loaded; an empty list clears them.
setCookies(bool enable) → Future<void>
Enables mpv's HTTP cookie jar for network streams when enable is true.
setCoverArtAuto(Cover cover) → Future<void>
Sets the policy for scanning sidecar cover-art files.
setDemuxer(DemuxerSettings settings) → Future<void>
Applies the demuxer buffering configuration atomically (forward cache cap, seekback cap, readahead).
setGapless(Gapless gapless) → Future<void>
Sets the gapless-playback policy across playlist boundaries.
setHlsBitrate(HlsBitrate hlsBitrate) → Future<void>
Sets the HLS variant-selection policy for adaptive streams.
setHttpProxy(String url) → Future<void>
Sets the HTTP proxy URL for network streams; empty string clears it. http:// and https:// sources go through it.
setLogLevel(LogLevel level) → void
Sets the minimum severity of log messages mpv emits on PlayerStream.log at runtime (mpv_request_log_messages).
setLoop(Loop loop) → Future<void>
Sets the loop policy (off, current file, or whole playlist). Turned on once the queue has ended (PlaybackState.completed), it rewinds: Loop.file seeks the track to its start, Loop.playlist moves to the first entry, and both stay paused. Call play to start again.
setMediaSession(MediaSession? session) → Future<void>
Publishes the Player to the OS media session (lockscreen, SMTC or MPRIS), wiring up Bluetooth AVRCP, headset buttons, Siri or Google Assistant, and the platform's audio-session lifecycle per MediaSession.interruptionPolicy.
setMute(bool mute) → Future<void>
Mutes or unmutes the output.
setNetworkTimeout(Duration timeout) → Future<void>
Sets the network I/O timeout, capped at about 36 minutes, the most FFmpeg takes.
setPitch(double pitch) → Future<void>
Sets the pitch multiplier (1.0 leaves pitch unchanged).
setPitchCorrection(bool enable) → Future<void>
Enables or disables holding pitch constant when the rate changes.
setPrefetchPlaylist(bool enabled) → Future<void>
Enables or disables prefetching the next playlist entry during playback. Hooks and the source resolver then also run for the next entry while the current one plays: see Player.setPrefetchPlaylist.
setRate(double rate) → Future<void>
Sets the playback rate multiplier (1.0 is normal speed).
setRawProperty(String name, String value) → Future<void>
Writes an arbitrary mpv property from a string. Escape hatch for properties without a typed setter; writes to af and pause, also through options/ and file-local-options/, throw ArgumentError because they would desync the typed state.
setReplayGain(ReplayGainSettings settings) → Future<void>
Applies the ReplayGain configuration atomically.
setShuffle(bool shuffle) → Future<void>
Enables or disables shuffled playlist order.
setSourceResolver(SourceResolver? resolver, {Duration? timeout = const Duration(seconds: 15)}) → Future<void>
Installs a SourceResolver, the official callback for resolving or refreshing a playback URL right before each track opens (and once more after a failed open, with SourceResolveRequest.isRetry set), driven internally by the on_load, on_load_fail and on_prefetch hooks. Return null to keep the current URL; pass null to uninstall. timeout caps a hung resolver (default 15s, null disables). With setPrefetchPlaylist on, the next entry is resolved on on_prefetch while the current one plays, and its open reuses that URL.
setSpectrum(SpectrumSettings settings) → void
Applies the spectrum and PCM pipeline configuration, synchronously: it is in PlayerSettings.spectrum when the call returns.
setSystemMute(bool mute) → Future<void>
Sets the mute the audio driver exposes (ao-mute), distinct from the soft setMute, with the reach of setSystemVolume. Best-effort: silently ignored (no throw) when unsupported by the AO.
setSystemVolume(double volume) → Future<void>
Sets the volume the audio driver exposes in percent (ao-volume), distinct from the soft setVolume: the app's own stream on most drivers, the whole device with ALSA and WASAPI in exclusive mode. See Player.setSystemVolume. Throws RangeError outside [0, 100]. Best-effort: silently ignored (no throw) when the active audio output doesn't expose system volume, as on iOS and Android.
setTlsCaFile(String path) → Future<void>
Sets the path to a custom CA bundle for TLS verification.
setTlsVerify(bool enable) → Future<void>
Enables or disables TLS server-certificate verification.
setVolume(double volume) → Future<void>
Sets the soft volume in percent (100 is unattenuated), from 0 to 1000. setVolumeMax does not cap it: see Player.setVolume.
setVolumeGain(double gainDb) → Future<void>
Sets the gain in dB applied on top of the volume, from -150 to +150. setVolumeGainMin and setVolumeGainMax do not cap it.
setVolumeGainMax(double gainDb) → Future<void>
Sets mpv's volume-gain-max, in dB: the top of mpv's relative steps on the gain (add, cycle), not of setVolumeGain.
setVolumeGainMin(double gainDb) → Future<void>
Sets mpv's volume-gain-min, in dB: the floor of mpv's relative steps on the gain (add, cycle), not of setVolumeGain.
setVolumeMax(double limit) → Future<void>
Sets mpv's volume-max, in percent: the top of mpv's relative volume steps (add, cycle), and a natural top for a volume slider. It does not cap setVolume.
stop() → Future<void>
Stops playback and unloads the current file; the next track must be loaded with open.
toString() → String
A string representation of this object.
inherited
updateAudioEffects(List<AudioEffect> mapper(List<AudioEffect>)) → Future<void>
Mutates the current DSP rack incrementally by applying mapper to it and reapplying the result.
updateSpectrum(SpectrumSettings mapper(SpectrumSettings)) → void
Mutates the spectrum configuration by applying mapper to PlayerSettings.spectrum.
writeResumeConfig() → Future<void>
Saves a "watch later" resume point for the current file (mpv's write-watch-later-config). See Player.writeResumeConfig.

Operators

operator ==(Object other) → bool
The equality operator.
inherited