Skip to main content

Variable: MpvProperty

const MpvProperty: {
  audioChannels: "audio-channels";
  audioFilters: "af";
  cacheBufferingState: "cache-buffering-state";
  cacheSecs: "cache-secs";
  chapter: "chapter";
  chapterList: "chapter-list";
  chapters: "chapters";
  coreIdle: "core-idle";
  demuxerCacheTime: "demuxer-cache-time";
  duration: "duration";
  eofReached: "eof-reached";
  gaplessAudio: "gapless-audio";
  idleActive: "idle-active";
  loopFile: "loop-file";
  loopPlaylist: "loop-playlist";
  mediaTitle: "media-title";
  metadata: "metadata";
  metadataCount: "metadata/list/count";
  mute: "mute";
  pause: "pause";
  pcmTap: "pcm-tap";
  pcmTapFrame: "pcm-tap-frame";
  pitch: "pitch";
  playlist: "playlist";
  playlistCount: "playlist-count";
  playlistPos: "playlist-pos";
  prefetchPlaylist: "prefetch-playlist";
  replayGain: "replaygain";
  replayGainClip: "replaygain-clip";
  replayGainFallback: "replaygain-fallback";
  replayGainPreamp: "replaygain-preamp";
  seekable: "seekable";
  seeking: "seeking";
  speed: "speed";
  streamLavfO: "stream-lavf-o";
  timePos: "time-pos";
  volume: "volume";
};

Defined in: packages/player/src/properties.ts:18

mpv property names this library observes, as string constants so that the reducer's switch and the observation table can never drift apart.

Type Declaration​

audioChannels​

readonly audioChannels: "audio-channels" = 'audio-channels';

audio-channels — the output channel layout, UPDATE_AUDIO (options/options.c, mpv 0.41.0) so it applies without a reload.

mpv 0.41.0 options.rst: "--audio-channels=<stereo|mono> — Force a downmix to stereo or mono."

audioFilters​

readonly audioFilters: "af" = 'af';

af — the audio filter chain (mpv options.rst "Audio Filters").

Runtime-settable: mpv lists af explicitly among the options it allows to change during playback (options/options.c, the runtime-updatable name table), and setting it rebuilds the filter chain in place rather than reloading the file. The value is an ordered list; see compileAudioFilters in filters.ts for the exact grammar, which is mpv's own (options/m_option.c: print_obj_settings_list).

Setting it is atomic and validating: mpv parses the whole string first (parse_obj_settings, which rejects an unknown filter name outright with "Option af: doesn't exist.") and leaves the existing chain untouched if any entry fails.

cacheBufferingState​

readonly cacheBufferingState: "cache-buffering-state" = 'cache-buffering-state';

cache-buffering-state — int, "The percentage (0-100) of the cache fill status until the player will unpause (related to paused-for-cache)" (mpv 0.41.0 input.rst).

Read that sentence literally: it is not a general buffer gauge, it is how close mpv is to resuming from a stall. See PlayerState.bufferingPercent, which publishes it only while the player is actually stalled.

cacheSecs​

readonly cacheSecs: "cache-secs" = 'cache-secs';

cache-secs — double, "How many seconds of audio/video to prefetch if the cache is active" (options.rst), range M_RANGE(0, DBL_MAX) (demux/demux.c).

chapter​

readonly chapter: "chapter" = 'chapter';

chapter — int64, RW. mpv 0.41.0 input.rst: "Current chapter number. The number of the first chapter is 0. A value of -1 indicates that the current playback position is before the start of the first chapter."

"Setting this property results in an absolute seek to the start of the chapter." Unavailable while nothing is loaded.

chapterList​

readonly chapterList: "chapter-list" = 'chapter-list';

chapter-list — node, read as one MPV_FORMAT_NODE array of maps (MpvClient.getChapters). mpv 0.41.0 input.rst documents the node shape verbatim: "title" MPV_FORMAT_STRING, "time" MPV_FORMAT_DOUBLE.

chapters​

readonly chapters: "chapters" = 'chapters';

chapters — int64, "Number of chapters" (input.rst).

coreIdle​

readonly coreIdle: "core-idle" = 'core-idle';

core-idle — flag. true when no audio is being produced.

demuxerCacheTime​

readonly demuxerCacheTime: "demuxer-cache-time" = 'demuxer-cache-time';

demuxer-cache-time — double, absolute demuxer cache end timestamp.

duration​

readonly duration: "duration" = 'duration';

duration — double, seconds. Unavailable until the file is loaded.

eofReached​

readonly eofReached: "eof-reached" = 'eof-reached';

eof-reached — flag. true once the end of the file was reached.

gaplessAudio​

readonly gaplessAudio: "gapless-audio" = 'gapless-audio';

gapless-audio — choice no | yes | weak, "Try to play consecutive audio files with no silence or disruption at the point of file change. Default: weak" (mpv 0.41.0 options.rst).

This is an audio-output policy, not a demuxer one: it decides whether the AO is kept open across a file change. See GaplessAudioMode in player.ts for what each value costs.

idleActive​

readonly idleActive: "idle-active" = 'idle-active';

idle-active — flag. true when nothing at all is loaded.

loopFile​

readonly loopFile: "loop-file" = 'loop-file';

loop-file — "no", "inf" or a repeat count, read as a string.

loopPlaylist​

readonly loopPlaylist: "loop-playlist" = 'loop-playlist';

loop-playlist — "no", "inf" or a repeat count, read as a string.

mediaTitle​

readonly mediaTitle: "media-title" = 'media-title';

media-title — string, the best available title for the current entry.

metadata​

readonly metadata: "metadata" = 'metadata';

metadata — the current entry's tag map.

Observed purely as a change edge: mpv's input.rst (0.35.1) says of this property "Trying to retrieve this property as a raw string doesn't work", so the delivered string is never interpreted. The typed map comes from one MPV_FORMAT_NODE read of this same property (MpvClient.getPropertyMap), which is the format the manual says to use.

metadataCount​

readonly metadataCount: "metadata/list/count" = 'metadata/list/count';

metadata/list/count — int, "Number of metadata entries" (input.rst). Read on demand; never observed (a tag value change leaves it equal, so it is not a usable change signal).

mute​

readonly mute: "mute" = 'mute';

mute — flag.

pause​

readonly pause: "pause" = 'pause';

pause — flag. Playback intent; true means paused.

pcmTap​

readonly pcmTap: "pcm-tap" = 'pcm-tap';

pcm-tap — int, read/write. Samples per channel mpv retains for the visualizer; 0 (the default) disarms the tap.

Added by this project's libmpv patch (ARCHITECTURE §11, §21), so reading it is also the availability probe: a libmpv without the patch answers "property not found" and player.visualizer.capabilities.fft is false. Identical on both platforms — it is the same source patch in both forks.

Setting it directly is legal and does nothing useful on its own: the sampler thread that reads pcmTapFrame lives in native code and is driven by player.visualizer.subscribe().

pcmTapFrame​

readonly pcmTapFrame: "pcm-tap-frame" = 'pcm-tap-frame';

pcm-tap-frame — node, read-only. The newest retained window, as a map of sample_rate / channels / frames / pts_us / seq plus samples, a byte array of interleaved float32.

Listed for completeness; nothing in TypeScript reads it. It is consumed by the native sampler, which never lets the PCM cross into JavaScript.

pitch​

readonly pitch: "pitch" = 'pitch';

pitch — double, M_RANGE(0.01, 100.0) (options/options.c, mpv 0.41.0).

mpv 0.41.0 options.rst: "Raise or lower the audio's pitch by the factor given as parameter. Does not affect playback speed. Playing with an altered pitch automatically inserts the scaletempo2 audio filter." Added upstream in mpv 0.40, i.e. it exists on every binary this library pins.

An option, therefore also a property ("Most options can be set at runtime via properties as well. Just remove the leading --", input.rst), which is what makes it observable.

playlist​

readonly playlist: "playlist" = 'playlist';

playlist — the whole queue as one node.

Read on demand through MpvClient.getPlaylistEntries() (one MPV_FORMAT_NODE round-trip), never observed: the array would be a second copy of mpv's own state crossing the bridge on every edit, and the cursor (playlist-pos/playlist-count) is what state actually needs. See PlaylistApi.entries.

playlistCount​

readonly playlistCount: "playlist-count" = 'playlist-count';

playlist-count — int64, number of playlist entries.

playlistPos​

readonly playlistPos: "playlist-pos" = 'playlist-pos';

playlist-pos — int64, -1 when no entry is current.

prefetchPlaylist​

readonly prefetchPlaylist: "prefetch-playlist" = 'prefetch-playlist';

prefetch-playlist — flag, "Prefetch next playlist entry while playback of the current entry is ending (default: no)" (options.rst).

replayGain​

readonly replayGain: "replaygain" = 'replaygain';

replaygain — choice no | track | album (mpv 0.35.1 options.rst). Settable at runtime: the option carries UPDATE_VOL, which re-runs audio_update_volume() immediately (mpv options/options.c, player/audio.c).

replayGainClip​

readonly replayGainClip: "replaygain-clip" = 'replaygain-clip';

replaygain-clip — flag. yes means "allow clipping", i.e. it disables mpv's automatic gain reduction; the default no keeps the protection on. See ReplayGainOptions.clip in player.ts for why the 0.35.1 manual reads the other way round. Runtime-settable (UPDATE_VOL).

replayGainFallback​

readonly replayGainFallback: "replaygain-fallback" = 'replaygain-fallback';

replaygain-fallback — "Gain in dB to apply if the file has no replay gain tags. This option is always applied if the replaygain logic is somehow inactive" (mpv 0.41.0 options.rst) — *"somehow inactive" includes replaygain=no: the fallback branch is the else of the mode check in compute_replaygain() (player/audio.c), so a non-zero fallback keeps applying after the mode is switched off. mpv clamps it to M_RANGE(-200, 60) (options/options.c). Runtime-settable (UPDATE_VOL).

replayGainPreamp​

readonly replayGainPreamp: "replaygain-preamp" = 'replaygain-preamp';

replaygain-preamp — "Pre-amplification gain in dB to apply to the selected replaygain gain (default: 0)" (options.rst). mpv clamps it to M_RANGE(-150, 150) (options/options.c). Runtime-settable (UPDATE_VOL).

seekable​

readonly seekable: "seekable" = 'seekable';

seekable — flag. mpv: "Whether it's generally possible to seek in the current file" (input.rst, mpv 0.35.1). false is how an unseekable live stream announces itself; see PlayerState.isLive.

seeking​

readonly seeking: "seeking" = 'seeking';

seeking — flag. true while mpv is repositioning.

speed​

readonly speed: "speed" = 'speed';

speed — double, playback rate multiplier.

streamLavfO​

readonly streamLavfO: "stream-lavf-o" = 'stream-lavf-o';

stream-lavf-o — "Set AVOptions on streams opened with libavformat" (mpv 0.41.0 options.rst), a key/value list.

Applied by mp_setup_av_network_options() last, after every option mpv derives from its own settings (stream/stream_lavf.c:242, mp_set_avdict(dict, opts->avopts)), so an entry here wins over mpv's defaults. The same function is called from both stream_lavf.c:407 (the top-level connection) and demux_lavf.c:1024 (an AVFMT_NOFILE demuxer opening its own connections, which is how HLS fetches segments) — so one value covers both layers.

This library uses it for exactly one thing: FFmpeg's HTTP reconnect options. See PlayerOptions.networkReconnect.

timePos​

readonly timePos: "time-pos" = 'time-pos';

time-pos — double. NEVER observed; read one-shot on discontinuities.

volume​

readonly volume: "volume" = 'volume';

volume — double, mpv's 0–100 scale (see MPV_VOLUME_SCALE).