COMMAND INTERFACE

The mpv core can be controlled with commands and properties. A number of ways to interact with the player use them: key bindings (input.conf), OSD (showing information with properties), JSON IPC, the client API (libmpv), and the classic slave mode.

input.conf

The input.conf file consists of a list of key bindings, for example:

s screenshot      # take a screenshot with the s key
LEFT seek 15      # map the left-arrow key to seeking forward by 15 seconds

Each line maps a key to an input command. Keys are specified with their literal value (upper case if combined with Shift), or a name for special keys. For example, a maps to the a key without shift, and A maps to a with shift.

The file is located in the mpv configuration directory (normally at ~/.config/mpv/input.conf depending on platform). The default bindings are defined here:

https://github.com/mpv-player/mpv/blob/master/etc/input.conf

A list of special keys can be obtained with

mpv --input-keylist

In general, keys can be combined with Shift, Ctrl and Alt:

ctrl+q quit

mpv can be started in input test mode, which displays key bindings and the commands they're bound to on the OSD, instead of executing the commands:

mpv --input-test --force-window --idle

(Only closing the window will make mpv exit, pressing normal keys will merely display the binding, even if mapped to quit.)

Also see Key names.

input.conf syntax

[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command> )*

Note that by default, the right Alt key can be used to create special characters, and thus does not register as a modifier. This can be changed with --input-right-alt-gr option.

Newlines always start a new binding. # starts a comment (outside of quoted string arguments). To bind commands to the # key, SHARP can be used.

<key> is either the literal character the key produces (ASCII or Unicode character), or a symbolic name (as printed by --input-keylist).

<section> (braced with { and }) is the input section for this command.

<command> is the command itself. It consists of the command name and multiple (or none) arguments, all separated by whitespace. String arguments should be quoted, typically with ". See Flat command syntax.

You can bind multiple commands to one key. For example:

a show-text "command 1" ; show-text "command 2"

It's also possible to bind a command to a sequence of keys:

a-b-c show-text "command run after a, b, c have been pressed"

(This is not shown in the general command syntax.)

If a or a-b or b are already bound, this will run the first command that matches, and the multi-key command will never be called. Intermediate keys can be remapped to ignore in order to avoid this issue. The maximum number of (non-modifier) keys for combinations is currently 4.

Key names

All mouse and keyboard input is to converted to mpv-specific key names. Key names are either special symbolic identifiers representing a physical key, or a text key names, which are unicode code points encoded as UTF-8. These are what keyboard input would normally produce, for example a for the A key. As a consequence, mpv uses input translated by the current OS keyboard layout, rather than physical scan codes.

Currently there is the hardcoded assumption that every text key can be represented as a single unicode code point (in NFKC form).

All key names can be combined with the modifiers Shift, Ctrl, Alt, Meta. They must be prefixed to the actual key name, where each modifier is followed by a + (for example ctrl+q).

The Shift modifier requires some attention. For instance Shift+2 should usually be specified as key-name @ at input.conf, and similarly the combination Alt+Shift+2 is usually Alt+@, etc. Special key names like Shift+LEFT work as expected. If in doubt - use --input-test to check how a key/combination is seen by mpv.

Symbolic key names and modifier names are case-insensitive. Unicode key names are case-sensitive because input bindings typically respect the shift key.

Another type of key names are hexadecimal key names, that serve as fallback for special keys that are neither unicode, nor have a special mpv defined name. They will break as soon as mpv adds proper names for them, but can enable you to use a key at all if that does not happen.

All symbolic names are listed by --input-keylist. --input-test is a special mode that prints all input on the OSD.

Comments on some symbolic names:

KP*

Keypad names. Behavior varies by backend (whether they implement this, and on how they treat numlock), but typically, mpv tries to map keys on the keypad to separate names, even if they produce the same text as normal keys.

MOUSE_BTN*, MBTN*

Various mouse buttons.

Depending on backend, the mouse wheel might also be represented as a button. In addition, MOUSE_BTN3 to MOUSE_BTN6 are deprecated aliases for WHEEL_UP, WHEEL_DOWN, WHEEL_LEFT, WHEEL_RIGHT.

MBTN* are aliases for MOUSE_BTN*.

WHEEL_*

Mouse wheels (typically).

AXIS_*

Deprecated aliases for WHEEL_*.

*_DBL

Mouse button double clicks.

MOUSE_MOVE, MOUSE_ENTER, MOUSE_LEAVE

Emitted by mouse move events. Enter/leave happens when the mouse enters or leave the mpv window (or the current mouse region, using the deprecated mouse region input section mechanism).

CLOSE_WIN

Pseudo key emitted when closing the mpv window using the OS window manager (for example, by clicking the close button in the window title bar).

GAMEPAD_*

Keys emitted by the SDL gamepad backend.

UNMAPPED

Pseudo-key that matches any unmapped key. (You should probably avoid this if possible, because it might change behavior or get removed in the future.)

ANY_UNICODE

Pseudo-key that matches any key that produces text. (You should probably avoid this if possible, because it might change behavior or get removed in the future.)

Flat command syntax

This is the syntax used in input.conf, and referred to "input.conf syntax" in a number of other places.

<command> ::= [<prefixes>] <command_name> (<argument>)*

<argument> ::= (<unquoted> | " <double_quoted> " | ' <single_quoted> ' | `X <custom_quoted> X`)

command_name is an unquoted string with the command name itself. See List of Input Commands for a list.

Arguments are separated by whitespaces even if the command expects only one argument. Arguments with whitespaces or other special characters must be quoted, or the command cannot be parsed correctly.

Double quotes interpret JSON/C-style escaping, like \t or \" or \\. JSON escapes according to RFC 8259, minus surrogate pair escapes. This is the only form which allows newlines at the value - as \n.

Single quotes take the content literally, and cannot include the single-quote character at the value.

Custom quotes also take the content literally, but are more flexible than single quotes. They start with ` (back-quote) followed by any ASCII character, and end at the first occurrence of the same pair in reverse order, e.g. `-foo-` or ``bar``. The final pair sequence is not allowed at the value - in these examples -` and `` respectively. In the second example the last character of the value also can't be a back-quote.

Mixed quoting at the same argument, like 'foo'"bar", is not supported.

Note that argument parsing and property expansion happen at different stages. First, arguments are determined as described above, and then, where applicable, properties are expanded - regardless of argument quoting. However, expansion can still be prevented with the raw prefix or $>. See Input Command Prefixes and Property Expansion.

Commands specified as arrays

This applies to certain APIs, such as mp.commandv() or mp.command_native() (with array parameters) in Lua scripting, or mpv_command() or mpv_command_node() (with MPV_FORMAT_NODE_ARRAY) in the C libmpv client API.

The command as well as all arguments are passed as a single array. Similar to the Flat command syntax, you can first pass prefixes as strings (each as separate array item), then the command name as string, and then each argument as string or a native value.

Since these APIs pass arguments as separate strings or native values, they do not expect quotes, and do support escaping. Technically, there is the input.conf parser, which first splits the command string into arguments, and then invokes argument parsers for each argument. The input.conf parser normally handles quotes and escaping. The array command APIs mentioned above pass strings directly to the argument parsers, or can sidestep them by the ability to pass non-string values.

Property expansion is disabled by default for these APIs. This can be changed with the expand-properties prefix. See Input Command Prefixes.

Sometimes commands have string arguments, that in turn are actually parsed by other components (e.g. filter strings with vf add) - in these cases, you you would have to double-escape in input.conf, but not with the array APIs.

For complex commands, consider using Named arguments instead, which should give slightly more compatibility. Some commands do not support named arguments and inherently take an array, though.

Named arguments

This applies to certain APIs, such as mp.command_native() (with tables that have string keys) in Lua scripting, or mpv_command_node() (with MPV_FORMAT_NODE_MAP) in the C libmpv client API.

The name of the command is provided with a name string field. The name of each command is defined in each command description in the List of Input Commands. --input-cmdlist also lists them. See the subprocess command for an example.

Some commands do not support named arguments (e.g. run command). You need to use APIs that pass arguments as arrays.

Named arguments are not supported in the "flat" input.conf syntax, which means you cannot use them for key bindings in input.conf at all.

Property expansion is disabled by default for these APIs. This can be changed with the expand-properties prefix. See Input Command Prefixes.

List of Input Commands

Commands with parameters have the parameter name enclosed in < / >. Don't add those to the actual command. Optional arguments are enclosed in [ / ]. If you don't pass them, they will be set to a default value.

Remember to quote string arguments in input.conf (see Flat command syntax).

Playback Control

seek <target> [<flags>]

Change the playback position. By default, seeks by a relative amount of seconds.

The second argument consists of flags controlling the seek mode:

relative (default): Seek relative to current position (a negative value seeks backwards).
absolute: Seek to a given time (a negative value starts from the end of the file).
absolute-percent: Seek to a given percent position.
relative-percent: Seek relative to current position in percent.
keyframes: Always restart playback at keyframe boundaries (fast).
exact: Always do exact/hr/precise seeks (slow).

Multiple flags can be combined, e.g.: absolute+keyframes.

By default, keyframes is used for relative, relative-percent, and absolute-percent seeks, while exact is used for absolute seeks.

Before mpv 0.9, the keyframes and exact flags had to be passed as 3rd parameter (essentially using a space instead of +). The 3rd parameter is still parsed, but is considered deprecated.

revert-seek [<flags>]

Undoes the seek command, and some other commands that seek (but not necessarily all of them). Calling this command once will jump to the playback position before the seek. Calling it a second time undoes the revert-seek command itself. This only works within a single file.

The first argument is optional, and can change the behavior:

mark: Mark the current time position. The next normal revert-seek command will seek back to this point, no matter how many seeks happened since last time.
mark-permanent: If set, mark the current position, and do not change the mark position before the next revert-seek command that has mark or mark-permanent set (or playback of the current file ends). Until this happens, revert-seek will always seek to the marked point. This flag cannot be combined with mark.

Using it without any arguments gives you the default behavior.

sub-seek <skip> <flags>

Change video and audio position such that the subtitle event after <skip> subtitle events is displayed. For example, sub-seek 1 skips to the next subtitle, sub-seek -1 skips to the previous subtitles, and sub-seek 0 seeks to the beginning of the current subtitle.

This is similar to sub-step, except that it seeks video and audio instead of adjusting the subtitle delay.

Secondary argument:

primary (default): Seeks through the primary subtitles.
secondary: Seeks through the secondary subtitles.

For embedded subtitles (like with Matroska), this works only with subtitle events that have already been displayed, or are within a short prefetch range. See `Cache`_ for details on how to control the available prefetch range.

frame-step

Play one frame, then pause. Does nothing with audio-only playback.

frame-back-step

Go back by one frame, then pause. Note that this can be very slow (it tries to be precise, not fast), and sometimes fails to behave as expected. How well this works depends on whether precise seeking works correctly (e.g. see the --hr-seek-demuxer-offset option). Video filters or other video post-processing that modifies timing of frames (e.g. deinterlacing) should usually work, but might make backstepping silently behave incorrectly in corner cases. Using --hr-seek-framedrop=no should help, although it might make precise seeking slower.

This does not work with audio-only playback.

stop [<flags>]

Stop playback and clear playlist. With default settings, this is essentially like quit. Useful for the client API: playback can be stopped without terminating the player.

The first argument is optional, and supports the following flags:

keep-playlist: Do not clear the playlist.

Property Manipulation

set <name> <value>

Set the given property or option to the given value.

del <name>

Delete the given property. Most properties cannot be deleted.

add <name> [<value>]

Add the given value to the property or option. On overflow or underflow, clamp the property to the maximum. If <value> is omitted, assume 1.

multiply <name> <value>

Similar to add, but multiplies the property or option with the numeric value.

cycle <name> [<value>]

Cycle the given property or option. The second argument can be up or down to set the cycle direction. On overflow, set the property back to the minimum, on underflow set it to the maximum. If up or down is omitted, assume up.

Whether or not key-repeat is enabled by default depends on the property. Currently properties with continuous values are repeatable by default (like volume), while discrete values are not (like osd-level).

cycle-values [<"!reverse">] <property> <value1> [<value2> [...]]

Cycle through a list of values. Each invocation of the command will set the given property to the next value in the list. The command will use the current value of the property/option, and use it to determine the current position in the list of values. Once it has found it, it will set the next value in the list (wrapping around to the first item if needed).

This command has a variable number of arguments, and cannot be used with named arguments.

The special argument !reverse can be used to cycle the value list in reverse. The only advantage is that you don't need to reverse the value list yourself when adding a second key binding for cycling backwards.

change-list <name> <operation> <value>

This command changes list options as described in `List Options`_. The <name> parameter is the normal option name, while <operation> is the suffix or action used on the option.

Some operations take no value, but the command still requires the value parameter. In these cases, the value must be an empty string.

Example

change-list glsl-shaders append file.glsl

Add a filename to the glsl-shaders list. The command line equivalent is --glsl-shaders-append=file.glsl or alternatively --glsl-shader=file.glsl.

Playlist Manipulation

playlist-next <flags>

Go to the next entry on the playlist.

First argument:

weak (default): If the last file on the playlist is currently played, do nothing.
force: Terminate playback if there are no more files on the playlist.

playlist-prev <flags>

Go to the previous entry on the playlist.

First argument:

weak (default): If the first file on the playlist is currently played, do nothing.
force: Terminate playback if the first file is being played.

playlist-next-playlist

Go to the next entry on the playlist with a different playlist-path.

playlist-prev-playlist

Go to the first of the previous entries on the playlist with a different playlist-path.

playlist-play-index <integer|current|none>

Start (or restart) playback of the given playlist index. In addition to the 0-based playlist entry index, it supports the following values:

<current>: The current playlist entry (as in playlist-current-pos) will be played again (unload and reload). If none is set, playback is stopped. (In corner cases, playlist-current-pos can point to a playlist entry even if playback is currently inactive,
<none>: Playback is stopped. If idle mode (--idle) is enabled, the player will enter idle mode, otherwise it will exit.

This command is similar to loadfile in that it only manipulates the state of what to play next, without waiting until the current file is unloaded, and the next one is loaded.

Setting playlist-pos or similar properties can have a similar effect to this command. However, it's more explicit, and guarantees that playback is restarted if for example the new playlist entry is the same as the previous one.

loadfile <url> [<flags> [<index> [<options>]]]

Load the given file or URL and play it. Technically, this is just a playlist manipulation command (which either replaces the playlist or adds an entry to it). Actual file loading happens independently. For example, a loadfile command that replaces the current file with a new one returns before the current file is stopped, and the new file even begins loading.

Second argument:

<replace> (default): Stop playback of the current file, and play the new file immediately.
<append>: Append the file to the playlist.
<append-play>: Append the file, and if nothing is currently playing, start playback. (Always starts with the added file, even if the playlist was not empty before running this command.)
<insert-next>: Insert the file into the playlist, directly after the current entry.
<insert-next-play>: Insert the file next, and if nothing is currently playing, start playback. (Always starts with the added file, even if the playlist was not empty before running this command.)
<insert-at>: Insert the file into the playlist, at the index given in the third argument.
<insert-at-play>: Insert the file at the index given in the third argument, and if nothing is currently playing, start playback. (Always starts with the added file, even if the playlist was not empty before running this command.)

The third argument is an insertion index, used only by the insert-at and insert-at-play actions. When used with those actions, the new item will be inserted at the index position in the playlist, or appended to the end if index is less than 0 or greater than the size of the playlist. This argument will be ignored for all other actions. This argument is added in mpv 0.38.0.

The fourth argument is a list of options and values which should be set while the file is playing. It is of the form opt1=value1,opt2=value2,... When using the client API, this can be a MPV_FORMAT_NODE_MAP (or a Lua table), however the values themselves must be strings currently. These options are set during playback, and restored to the previous value at end of playback (see `Per-File Options`_).

Warning

Since mpv 0.38.0, an insertion index argument is added as the third argument. This breaks all existing uses of this command which make use of the argument to include the list of options to be set while the file is playing. To address this problem, the third argument now needs to be set to -1 if the fourth argument needs to be used.

loadlist <url> [<flags> [<index>]]

Load the given playlist file or URL (like --playlist).

Second argument:

<replace> (default): Stop playback and replace the internal playlist with the new one.
<append>: Append the new playlist at the end of the current internal playlist.
<append-play>: Append the new playlist, and if nothing is currently playing, start playback. (Always starts with the new playlist, even if the internal playlist was not empty before running this command.)
<insert-next>: Insert the new playlist into the current internal playlist, directly after the current entry.
<insert-next-play>: Insert the new playlist, and if nothing is currently playing, start playback. (Always starts with the new playlist, even if the internal playlist was not empty before running this command.)
<insert-at>: Insert the new playlist at the index given in the third argument.
<insert-at-play>: Insert the new playlist at the index given in the third argument, and if nothing is currently playing, start playback. (Always starts with the new playlist, even if the internal playlist was not empty before running this command.)

The third argument is an insertion index, used only by the insert-at and insert-at-play actions. When used with those actions, the new playlist will be inserted at the index position in the internal playlist, or appended to the end if index is less than 0 or greater than the size of the internal playlist. This argument will be ignored for all other actions.

playlist-clear

Clear the playlist, except the currently played file.

playlist-remove <index>

Remove the playlist entry at the given index. Index values start counting with 0. The special value current removes the current entry. Note that removing the current entry also stops playback and starts playing the next entry.

playlist-move <index1> <index2>

Move the playlist entry at index1, so that it takes the place of the entry index2. (Paradoxically, the moved playlist entry will not have the index value index2 after moving if index1 was lower than index2, because index2 refers to the target entry, not the index the entry will have after moving.)

playlist-shuffle

Shuffle the playlist. This is similar to what is done on start if the --shuffle option is used.

playlist-unshuffle

Attempt to revert the previous playlist-shuffle command. This works only once (multiple successive playlist-unshuffle commands do nothing). May not work correctly if new recursive playlists have been opened since a playlist-shuffle command.

Track Manipulation

sub-add <url> [<flags> [<title> [<lang>]]]

Load the given subtitle file or stream. By default, it is selected as current subtitle after loading.

The flags argument is one of the following values:

Select the subtitle immediately (default).

<auto>

Don't select the subtitle. (Or in some special situations, let the default stream selection mechanism decide.)

Select the subtitle. If a subtitle with the same filename was already added, that one is selected, instead of loading a duplicate entry. (In this case, title/language are ignored, and if the was changed since it was loaded, these changes won't be reflected.)

The title argument sets the track title in the UI.

The lang argument sets the track language, and can also influence stream selection with flags set to auto.

sub-remove [<id>]

Remove the given subtitle track. If the id argument is missing, remove the current track. (Works on external subtitle files only.)

sub-reload [<id>]

Reload the given subtitle tracks. If the id argument is missing, reload the current track. (Works on external subtitle files only.)

This works by unloading and re-adding the subtitle track.

sub-step <skip> <flags>

Change subtitle timing such, that the subtitle event after the next <skip> subtitle events is displayed. <skip> can be negative to step backwards.

Secondary argument:

primary (default): Steps through the primary subtitles.
secondary: Steps through the secondary subtitles.

audio-add <url> [<flags> [<title> [<lang>]]]

Load the given audio file. See sub-add command.

audio-remove [<id>]

Remove the given audio track. See sub-remove command.

audio-reload [<id>]

Reload the given audio tracks. See sub-reload command.

video-add <url> [<flags> [<title> [<lang> [<albumart>]]]]

Load the given video file. See sub-add command for common options.

albumart (MPV_FORMAT_FLAG): If enabled, mpv will load the given video as album art.

video-remove [<id>]

Remove the given video track. See sub-remove command.

video-reload [<id>]

Reload the given video tracks. See sub-reload command.

rescan-external-files [<mode>]

Rescan external files according to the current --sub-auto, --audio-file-auto and --cover-art-auto settings. This can be used to auto-load external files after the file was loaded.

The mode argument is one of the following:

<reselect> (default): Select the default audio and subtitle streams, which typically selects external files with the highest preference. (The implementation is not perfect, and could be improved on request.)
<keep-selection>: Do not change current track selections.

Text Manipulation

print-text <text>: Print text to stdout. The string can contain properties (see Property Expansion). Take care to put the argument in quotes.
expand-text <text>: Property-expand the argument and return the expanded string. This can be used only through the client API or from a script using mp.command_native. (see Property Expansion).
expand-path "<text>": Expand a path's double-tilde placeholders into a platform-specific path. As expand-text, this can only be used through the client API or from a script using mp.command_native.

Example

mp.osd_message(mp.command_native({"expand-path", "~~home/"}))

This line of Lua would show the location of the user's mpv configuration directory on the OSD.
normalize-path <filename>: Return a canonical representation of the path filename by converting it to an absolute path, removing consecutive slashes, removing . components, resolving .. components, and converting slashes to backslashes on Windows. Symlinks are not resolved unless the platform is Unix-like and one of the path components is ... If filename is a URL, it is returned unchanged. This can only be used through the client API or from a script using mp.command_native.

Example

mp.osd_message(mp.command_native({"normalize-path", "/foo//./bar"}))

This line of Lua prints "/foo/bar" on the OSD.
escape-ass <text>: Modify text so that commands and functions that interpret ASS tags, such as osd-overlay and mp.create_osd_overlay, will display it verbatim, and return it. This can only be used through the client API or from a script using mp.command_native.

Example

mp.osd_message(mp.command_native({"escape-ass", "foo {bar}"}))

This line of Lua prints "foo \{bar}" on the OSD.

Configuration Commands

apply-profile <name> [<mode>]

Apply the contents of a named profile. This is like using profile=name in a config file, except you can map it to a key binding to change it at runtime.

The mode argument:

default: Apply the profile. Default if the argument is omitted.
restore: Restore options set by a previous apply-profile command for this profile. Only works if the profile has profile-restore set to a relevant mode. Prints a warning if nothing could be done. See `Runtime profiles`_ for details.

load-config-file <filename>

Load a configuration file, similar to the --include option. If the file was already included, its previous options are not reset before it is reparsed.

write-watch-later-config

Write the resume config file that the quit-watch-later command writes, but continue playback normally.

delete-watch-later-config [<filename>]

Delete any existing resume config file that was written by quit-watch-later or write-watch-later-config. If a filename is specified, then the deleted config is for that file; otherwise, it is the same one as would be written by quit-watch-later or write-watch-later-config in the current circumstance.

OSD Commands

show-text <text> [<duration>|-1 [<level>]]

Show text on the OSD. The string can contain properties, which are expanded as described in Property Expansion. This can be used to show playback time, filename, and so on. no-osd has no effect on this command.

<duration>: The time in ms to show the message for. By default, it uses the same value as --osd-duration.
<level>: The minimum OSD level to show the text at (see --osd-level).

show-progress

Show the progress bar, the elapsed time and the total duration of the file on the OSD. no-osd has no effect on this command.

overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride> <dw> <dh>

Add an OSD overlay sourced from raw data. This might be useful for scripts and applications controlling mpv, and which want to display things on top of the video window.

Overlays are usually displayed in screen resolution, but with some VOs, the resolution is reduced to that of the video's. You can read the osd-width and osd-height properties. At least with --vo-xv and anamorphic video (such as DVD), osd-par should be read as well, and the overlay should be aspect-compensated.

This has the following named arguments. The order of them is not guaranteed, so you should always call them with named arguments, see Named arguments.

id is an integer between 0 and 63 identifying the overlay element. The ID can be used to add multiple overlay parts, update a part by using this command with an already existing ID, or to remove a part with overlay-remove. Using a previously unused ID will add a new overlay, while reusing an ID will update it.

x and y specify the position where the OSD should be displayed.

file specifies the file the raw image data is read from. It can be either a numeric UNIX file descriptor prefixed with @ (e.g. @4), or a filename. The file will be mapped into memory with mmap(), copied, and unmapped before the command returns (changed in mpv 0.18.1).

It is also possible to pass a raw memory address for use as bitmap memory by passing a memory address as integer prefixed with an & character. Passing the wrong thing here will crash the player. This mode might be useful for use with libmpv. The offset parameter is simply added to the memory address (since mpv 0.8.0, ignored before).

offset is the byte offset of the first pixel in the source file. (The current implementation always mmap's the whole file from position 0 to the end of the image, so large offsets should be avoided. Before mpv 0.8.0, the offset was actually passed directly to mmap, but it was changed to make using it easier.)

fmt is a string identifying the image format. Currently, only bgra is defined. This format has 4 bytes per pixels, with 8 bits per component. The least significant 8 bits are blue, and the most significant 8 bits are alpha (in little endian, the components are B-G-R-A, with B as first byte). This uses premultiplied alpha: every color component is already multiplied with the alpha component. This means the numeric value of each component is equal to or smaller than the alpha component. (Violating this rule will lead to different results with different VOs: numeric overflows resulting from blending broken alpha values is considered something that shouldn't happen, and consequently implementations don't ensure that you get predictable behavior in this case.)

w, h, and stride specify the size of the overlay. w is the visible width of the overlay, while stride gives the width in bytes in memory. In the simple case, and with the bgra format, stride==4*w. In general, the total amount of memory accessed is stride * h. (Technically, the minimum size would be stride * (h - 1) + w * 4, but for simplicity, the player will access all stride * h bytes.)

dw and dh specify the (optional) display size of the overlay. The overlay visible portion of the overlay (w and h) is scaled to in display to dw and dh. If parameters are not present, the values for w and h are used.

Note

Before mpv 0.18.1, you had to do manual "double buffering" when updating an overlay by replacing it with a different memory buffer. Since mpv 0.18.1, the memory is simply copied and doesn't reference any of the memory indicated by the command's arguments after the command returns. If you want to use this command before mpv 0.18.1, reads the old docs to see how to handle this correctly.

overlay-remove <id>

Remove an overlay added with overlay-add and the same ID. Does nothing if no overlay with this ID exists.

osd-overlay

Add/update/remove an OSD overlay.

(Although this sounds similar to overlay-add, osd-overlay is for text overlays, while overlay-add is for bitmaps. Maybe overlay-add will be merged into osd-overlay to remove this oddity.)

You can use this to add text overlays in ASS format. ASS has advanced positioning and rendering tags, which can be used to render almost any kind of vector graphics.

This command accepts the following parameters:

id

Arbitrary integer that identifies the overlay. Multiple overlays can be added by calling this command with different id parameters. Calling this command with the same id replaces the previously set overlay.

There is a separate namespace for each libmpv client (i.e. IPC connection, script), so IDs can be made up and assigned by the API user without conflicting with other API users.

If the libmpv client is destroyed, all overlays associated with it are also deleted. In particular, connecting via --input-ipc-server, adding an overlay, and disconnecting will remove the overlay immediately again.

format

String that gives the type of the overlay. Accepts the following values (HTML rendering of this is broken, view the generated manpage instead, or the raw RST source):

ass-events

The data parameter is a string. The string is split on the newline character. Every line is turned into the Text part of a Dialogue ASS event. Timing is unused (but behavior of timing dependent ASS tags may change in future mpv versions).

Note that it's better to put multiple lines into data, instead of adding multiple OSD overlays.

This provides 2 ASS Styles. OSD contains the text style as defined by the current --osd-... options. Default is similar, and contains style that OSD would have if all options were set to the default.

In addition, the res_x and res_y options specify the value of the ASS PlayResX and PlayResY header fields. If res_y is set to 0, PlayResY is initialized to an arbitrary default value (but note that the default for this command is 720, not 0). If res_x is set to 0, PlayResX is set based on res_y such that a virtual ASS pixel has a square pixel aspect ratio.

none

Special value that causes the overlay to be removed. Most parameters other than id and format are mostly ignored.

data

String defining the overlay contents according to the format parameter.

res_x, res_y

Used if format is set to ass-events (see description there). Optional, defaults to 0/720.

z

The Z order of the overlay. Optional, defaults to 0.

Note that Z order between different overlays of different formats is static, and cannot be changed (currently, this means that bitmap overlays added by overlay-add are always on top of the ASS overlays added by osd-overlay). In addition, the builtin OSD components are always below any of the custom OSD. (This includes subtitles of any kind as well as text rendered by show-text.)

It's possible that future mpv versions will randomly change how Z order between different OSD formats and builtin OSD is handled.

hidden

If set to true, do not display this (default: false).

compute_bounds

If set to true, attempt to determine bounds and write them to the command's result value as x0, x1, y0, y1 rectangle (default: false). If the rectangle is empty, not known, or somehow degenerate, it is not set. x1/y1 is the coordinate of the bottom exclusive corner of the rectangle.

The result value may depend on the VO window size, and is based on the last known window size at the time of the call. This means the results may be different from what is actually rendered.

For ass-events, the result rectangle is recomputed to PlayRes coordinates (res_x/res_y). If window size is not known, a fallback is chosen.

You should be aware that this mechanism is very inefficient, as it renders the full result, and then uses the bounding box of the rendered bitmap list (even if hidden is set). It will flush various caches. Its results also depend on the used libass version.

This feature is experimental, and may change in some way again.

Note

Always use named arguments (mpv_command_node()). Lua scripts should use the mp.create_osd_overlay() helper instead of invoking this command directly.

Input and Keybind Commands

mouse <x> <y> [<button> [<mode>]]

Send a mouse event with given coordinate (<x>, <y>).

Second argument:

<button>: The button number of clicked mouse button. This should be one of 0-19. If <button> is omitted, only the position will be updated.

Third argument:

<single> (default): The mouse event represents regular single click.
<double>: The mouse event represents double-click.

keypress <name> [<scale>]

Send a key event through mpv's input handler, triggering whatever behavior is configured to that key. name uses the input.conf naming scheme for keys and modifiers. scale is used to scale numerical change effected by the bound command (same mechanism as precise scrolling). Useful for the client API: key events can be sent to libmpv to handle internally.

keydown <name>

Similar to keypress, but sets the KEYDOWN flag so that if the key is bound to a repeatable command, it will be run repeatedly with mpv's key repeat timing until the keyup command is called.

keyup [<name>]

Set the KEYUP flag, stopping any repeated behavior that had been triggered. name is optional. If name is not given or is an empty string, KEYUP will be set on all keys. Otherwise, KEYUP will only be set on the key specified by name.

keybind <name> <cmd> [<comment>]

Binds a key to an input command. cmd must be a complete command containing all the desired arguments and flags. Both name and cmd use the input.conf naming scheme. comment is an optional string which can be read as the comment entry of input-bindings. This is primarily useful for the client API.

enable-section <name> [<flags>]

This command is deprecated, except for mpv-internal uses.

Enable all key bindings in the named input section.

The enabled input sections form a stack. Bindings in sections on the top of the stack are preferred to lower sections. This command puts the section on top of the stack. If the section was already on the stack, it is implicitly removed beforehand. (A section cannot be on the stack more than once.)

The flags parameter can be a combination (separated by +) of the following flags:

<exclusive>: All sections enabled before the newly enabled section are disabled. They will be re-enabled as soon as all exclusive sections above them are removed. In other words, the new section shadows all previous sections.
<allow-hide-cursor>: This feature can't be used through the public API.
<allow-vo-dragging>: Same.

disable-section <name>

This command is deprecated, except for mpv-internal uses.

Disable the named input section. Undoes enable-section.

define-section <name> <contents> [<flags>]

This command is deprecated, except for mpv-internal uses.

Create a named input section, or replace the contents of an already existing input section. The contents parameter uses the same syntax as the input.conf file (except that using the section syntax in it is not allowed), including the need to separate bindings with a newline character.

If the contents parameter is an empty string, the section is removed.

The section with the name default is the normal input section.

In general, input sections have to be enabled with the enable-section command, or they are ignored.

The last parameter has the following meaning:

<default> (also used if parameter omitted): Use a key binding defined by this section only if the user hasn't already bound this key to a command.
<force>: Always bind a key. (The input section that was made active most recently wins if there are ambiguities.)

This command can be used to dispatch arbitrary keys to a script or a client API user. If the input section defines script-binding commands, it is also possible to get separate events on key up/down, and relatively detailed information about the key state. The special key name unmapped can be used to match any unmapped key.

load-input-conf <filename>

Load an input configuration file, similar to the --input-conf option. If the file was already included, its previous bindings are not reset before it is reparsed.

Execution Commands

run <command> [<arg1> [<arg2> [...]]]

Run the given command. Unlike in MPlayer/mplayer2 and earlier versions of mpv (0.2.x and older), this doesn't call the shell. Instead, the command is run directly, with each argument passed separately. Each argument is expanded like in Property Expansion.

This command has a variable number of arguments, and cannot be used with named arguments.

The program is run in a detached way. mpv doesn't wait until the command is completed, but continues playback right after spawning it.

To get the old behavior, use /bin/sh and -c as the first two arguments.

Example

run "/bin/sh" "-c" "echo ${title} > /tmp/playing"

This is not a particularly good example, because it doesn't handle escaping, and a specially prepared file might allow an attacker to execute arbitrary shell commands. It is recommended to write a small shell script, and call that with run.

subprocess

Similar to run, but gives more control about process execution to the caller, and does not detach the process.

You can avoid blocking until the process terminates by running this command asynchronously. (For example mp.command_native_async() in Lua scripting.)

This has the following named arguments. The order of them is not guaranteed, so you should always call them with named arguments, see Named arguments.

args (MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING])

Array of strings with the command as first argument, and subsequent command line arguments following. This is just like the run command argument list.

The first array entry is either an absolute path to the executable, or a filename with no path components, in which case the executable is searched in the directories in the PATH environment variable. On Unix, this is equivalent to posix_spawnp and execvp behavior.

playback_only (MPV_FORMAT_FLAG)

Boolean indicating whether the process should be killed when playback of the current playlist entry terminates (optional, default: true). If enabled, stopping playback will automatically kill the process, and you can't start it outside of playback.

capture_size (MPV_FORMAT_INT64)

Integer setting the maximum number of stdout plus stderr bytes that can be captured (optional, default: 64MB). If the number of bytes exceeds this, capturing is stopped. The limit is per captured stream.

capture_stdout (MPV_FORMAT_FLAG)

Capture all data the process outputs to stdout and return it once the process ends (optional, default: no).

capture_stderr (MPV_FORMAT_FLAG)

Same as capture_stdout, but for stderr.

detach (MPV_FORMAT_FLAG)

Whether to run the process in detached mode (optional, default: no). In this mode, the process is run in a new process session, and the command does not wait for the process to terminate. If neither capture_stdout nor capture_stderr have been set to true, the command returns immediately after the new process has been started, otherwise the command will read as long as the pipes are open.

env (MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING])

Set a list of environment variables for the new process (default: empty). If an empty list is passed, the environment of the mpv process is used instead. (Unlike the underlying OS mechanisms, the mpv command cannot start a process with empty environment. Fortunately, that is completely useless.) The format of the list is as in the execle() syscall. Each string item defines an environment variable as in NAME=VALUE.

On Lua, you may use utils.get_env_list() to retrieve the current environment if you e.g. simply want to add a new variable.

stdin_data (MPV_FORMAT_STRING)

Feed the given string to the new process' stdin. Since this is a string, you cannot pass arbitrary binary data. If the process terminates or closes the pipe before all data is written, the remaining data is silently discarded. Probably does not work on win32.

passthrough_stdin (MPV_FORMAT_FLAG)

If enabled, wire the new process' stdin to mpv's stdin (default: no). Before mpv 0.33.0, this argument did not exist, but the behavior was as if this was set to true.

The command returns the following result (as MPV_FORMAT_NODE_MAP):

status (MPV_FORMAT_INT64)

Typically this is the process exit code (0 or positive) if the process terminates normally, or negative for other errors (failed to start, terminated by mpv, and others). The meaning of negative values is undefined, other than meaning error (and does not correspond to OS low level exit status values).

On Windows, it can happen that a negative return value is returned even if the process terminates normally, because the win32 UINT exit code is assigned to an int variable before being set as int64_t field in the result map. This might be fixed later.

stdout (MPV_FORMAT_BYTE_ARRAY)

Captured stdout stream, limited to capture_size.

stderr (MPV_FORMAT_BYTE_ARRAY)

Same as stdout, but for stderr.

error_string (MPV_FORMAT_STRING)

Empty string if the process terminated normally. The string killed if the process was terminated in an unusual way. The string init if the process could not be started.

On Windows, killed is only returned when the process has been killed by mpv as a result of playback_only being set to true.

killed_by_us (MPV_FORMAT_FLAG)

Whether the process has been killed by mpv, for example as a result of playback_only being set to true, aborting the command (e.g. by mp.abort_async_command()), or if the player is about to exit.

Note that the command itself will always return success as long as the parameters are correct. Whether the process could be spawned or whether it was somehow killed or returned an error status has to be queried from the result value.

This command can be asynchronously aborted via API. Also see Asynchronous command details. Only the run command can start processes in a truly detached way.

Note

The subprocess will always be terminated on player exit if it wasn't started in detached mode, even if playback_only is false.

Warning

Don't forget to set the playback_only field to false if you want the command to run while the player is in idle mode, or if you don't want the end of playback to kill the command.

Example

local r = mp.command_native({
    name = "subprocess",
    playback_only = false,
    capture_stdout = true,
    args = {"cat", "/proc/cpuinfo"},
})
if r.status == 0 then
    print("result: " .. r.stdout)
end

This is a fairly useless Lua example, which demonstrates how to run a process in a blocking manner, and retrieving its stdout output.

quit [<code>]

Exit the player. If an argument is given, it's used as process exit code.

quit-watch-later [<code>]

Exit player, and store current playback position. Playing that file later will seek to the previous position on start. The (optional) argument is exactly as in the quit command. See `RESUMING PLAYBACK`_.

Scripting Commands

script-message [<arg1> [<arg2> [...]]]

Send a message to all clients, and pass it the following list of arguments. What this message means, how many arguments it takes, and what the arguments mean is fully up to the receiver and the sender. Every client receives the message, so be careful about name clashes (or use script-message-to).

This command has a variable number of arguments, and cannot be used with named arguments.

script-message-to <target> [<arg1> [<arg2> [...]]]

Same as script-message, but send it only to the client named <target>. Each client (scripts etc.) has a unique name. For example, Lua scripts can get their name via mp.get_script_name(). Note that client names only consist of alphanumeric characters and _.

This command has a variable number of arguments, and cannot be used with named arguments.

script-binding <name>

Invoke a script-provided key binding. This can be used to remap key bindings provided by external Lua scripts.

The argument is the name of the binding.

It can optionally be prefixed with the name of the script, using / as separator, e.g. script-binding scriptname/bindingname. Note that script names only consist of alphanumeric characters and _.

For completeness, here is how this command works internally. The details could change any time. On any matching key event, script-message-to or script-message is called (depending on whether the script name is included), with the following arguments:

The string key-binding.
The name of the binding (as established above).
The key state as string (see below).
The key name (since mpv 0.15.0).
The text the key would produce, or empty string if not applicable.

The 5th argument is only set if no modifiers are present (using the shift key with a letter is normally not emitted as having a modifier, and results in upper case text instead, but some backends may mess up).

The key state consists of 3 characters:

One of d (key was pressed down), u (was released), r (key is still down, and was repeated; only if key repeat is enabled for this binding), p (key was pressed; happens if up/down can't be tracked).
Whether the event originates from the mouse, either m (mouse button) or - (something else).
Whether the event results from a cancellation (e.g. the key is logically released but not physically released), either c (canceled) or - (something else). Not all types of cancellations set this flag.

Future versions can add more arguments and more key state characters to support more input peculiarities.

load-script <filename>

Load a script, similar to the --script option. Whether this waits for the script to finish initialization or not changed multiple times, and the future behavior is left undefined.

On success, returns a mpv_node with a client_id field set to the return value of the mpv_client_id() API call of the newly created script handle.

Screenshot Commands

screenshot <flags>

Take a screenshot.

Multiple flags are available (some can be combined with +):

<subtitles> (default): Save the video image, in its original resolution, and with subtitles. Some video outputs may still include the OSD in the output under certain circumstances.
<video>: Like subtitles, but typically without OSD or subtitles. The exact behavior depends on the selected video output.
<window>: Save the contents of the mpv window. Typically scaled, with OSD and subtitles. The exact behavior depends on the selected video output.
<each-frame>: Take a screenshot each frame. Issue this command again to stop taking screenshots. Note that you should disable frame-dropping when using this mode - or you might receive duplicate images in cases when a frame was dropped. This flag can be combined with the other flags, e.g. video+each-frame.

Older mpv versions required passing single and each-frame as second argument (and did not have flags). This syntax is still understood, but deprecated and might be removed in the future.

If you combine this command with another one using ;, you can use the async flag to make encoding/writing the image file asynchronous. For normal standalone commands, this is always asynchronous, and the flag has no effect. (This behavior changed with mpv 0.29.0.)

On success, returns a mpv_node with a filename field set to the saved screenshot location.

screenshot-to-file <filename> <flags>

Take a screenshot and save it to a given file. The format of the file will be guessed by the extension (and --screenshot-format is ignored - the behavior when the extension is missing or unknown is arbitrary).

The second argument is like the first argument to screenshot and supports subtitles, video, window.

If the file already exists, it's overwritten.

Like all input command parameters, the filename is subject to property expansion as described in Property Expansion.

screenshot-raw [<flags>]

Return a screenshot in memory. This can be used only through the client API. The MPV_FORMAT_NODE_MAP returned by this command has the w, h, stride fields set to obvious contents. The format field is set to bgr0 by default. This format is organized as B8G8R8X8 (where B is the LSB). The contents of the padding X are undefined. The data field is of type MPV_FORMAT_BYTE_ARRAY with the actual image data. The image is freed as soon as the result mpv_node is freed. As usual with client API semantics, you are not allowed to write to the image data.

The stride is the number of bytes from a pixel at (x0, y0) to the pixel at (x0, y0 + 1). This can be larger than w * 4 if the image was cropped, or if there is padding. This number can be negative as well. You access a pixel with byte_index = y * stride + x * 4 (assuming the bgr0 format).

The flags argument is like the first argument to screenshot and supports subtitles, video, window.

Filter Commands

af <operation> <value>

Change audio filter chain. See vf command.

vf <operation> <value>

Change video filter chain.

The semantics are exactly the same as with option parsing (see `VIDEO FILTERS`_). As such the text below is a redundant and incomplete summary.

The first argument decides what happens:

<set>

Overwrite the previous filter chain with the new one.

<add>

Append the new filter chain to the previous one.

<toggle>

Check if the given filter (with the exact parameters) is already in the video chain. If it is, remove the filter. If it isn't, add the filter. (If several filters are passed to the command, this is done for each filter.)

A special variant is combining this with labels, and using @name without filter name and parameters as filter entry. This toggles the enable/disable flag.

<remove>

Like toggle, but always remove the given filter from the chain.

<clr>

Remove all filters. Note that like the other sub-commands, this does not control automatically inserted filters.

The argument is always needed. E.g. in case of clr use vf clr "".

You can assign labels to filter by prefixing them with @name: (where name is a user-chosen arbitrary identifier). Labels can be used to refer to filters by name in all of the filter chain modification commands. For add, using an already used label will replace the existing filter.

The vf command shows the list of requested filters on the OSD after changing the filter chain. This is roughly equivalent to show-text ${vf}. Note that auto-inserted filters for format conversion are not shown on the list, only what was requested by the user.

Normally, the commands will check whether the video chain is recreated successfully, and will undo the operation on failure. If the command is run before video is configured (can happen if the command is run immediately after opening a file and before a video frame is decoded), this check can't be run. Then it can happen that creating the video chain fails.

Example for input.conf

a vf set vflip turn the video upside-down on the a key
b vf set "" remove all video filters on b
c vf toggle gradfun toggle debanding on c

Example how to toggle disabled filters at runtime

Add something like vf-add=@deband:!gradfun to mpv.conf. The @deband: is the label, an arbitrary, user-given name for this filter entry. The ! before the filter name disables the filter by default. Everything after this is the normal filter name and possibly filter parameters, like in the normal --vf syntax.
Add a vf toggle @deband to input.conf. This toggles the "disabled" flag for the filter with the label deband when the a key is hit.

vf-command <label> <command> <argument> [<target>]

Send a command to the filter. Note that currently, this only works with the lavfi filter. Refer to the libavfilter documentation for the list of supported commands for each filter.

<label> is a mpv filter label, use all to send it to all filters at once.

<command> and <argument> are filter-specific strings.

<target> is a filter or filter instance name and defaults to all. Note that the target is an additional specifier for filters that support them, such as complex lavfi filter chains.

af-command <label> <command> <argument> [<target>]

Same as vf-command, but for audio filters.

Miscellaneous Commands

ignore

Use this to "block" keys that should be unbound, and do nothing. Useful for disabling default bindings, without disabling all bindings with --input-default-bindings=no.

drop-buffers

Drop audio/video/demuxer buffers, and restart from fresh. Might help with unseekable streams that are going out of sync. This command might be changed or removed in the future.

dump-cache <start> <end> <filename>

Dump the current cache to the given filename. The <filename> file is overwritten if it already exists. <start> and <end> give the time range of what to dump. If no data is cached at the given time range, nothing may be dumped (creating a file with no packets).

Dumping a larger part of the cache will freeze the player. No effort was made to fix this, as this feature was meant mostly for creating small excerpts.

See --stream-record for various caveats that mostly apply to this command too, as both use the same underlying code for writing the output file.

If <filename> is an empty string, an ongoing dump-cache is stopped.

If <end> is no, then continuous dumping is enabled. Then, after dumping the existing parts of the cache, anything read from network is appended to the cache as well. This behaves similar to --stream-record (although it does not conflict with that option, and they can be both active at the same time).

If the <end> time is after the cache, the command will _not_ wait and write newly received data to it.

The end of the resulting file may be slightly damaged or incomplete at the end. (Not enough effort was made to ensure that the end lines up properly.)

Note that this command will finish only once dumping ends. That means it works similar to the screenshot command, just that it can block much longer. If continuous dumping is used, the command will not finish until playback is stopped, an error happens, another dump-cache command is run, or an API like mp.abort_async_command was called to explicitly stop the command. See Synchronous vs. Asynchronous.

Note

This was mostly created for network streams. For local files, there may be much better methods to create excerpts and such. There are tons of much more user-friendly Lua scripts, that will re-encode parts of a file by spawning a separate instance of ffmpeg. With network streams, this is not that easily possible, as the stream would have to be downloaded again. Even if --stream-record is used to record the stream to the local filesystem, there may be problems, because the recorded file is still written to.

This command is experimental, and all details about it may change in the future.

ab-loop

Cycle through A-B loop states. The first command will set the A point (the ab-loop-a property); the second the B point, and the third will clear both points.

ab-loop-dump-cache <filename>

Essentially calls dump-cache with the current AB-loop points as arguments. Like dump-cache, this will overwrite the file at <filename>. Likewise, if the B point is set to no, it will enter continuous dumping after the existing cache was dumped.

The author reserves the right to remove this command if enough motivation is found to move this functionality to a trivial Lua script.

ab-loop-align-cache

Re-adjust the A/B loop points to the start and end within the cache the ab-loop-dump-cache command will (probably) dump. Basically, it aligns the times on keyframes. The guess might be off especially at the end (due to granularity issues due to remuxing). If the cache shrinks in the meantime, the points set by the command will not be the effective parameters either.

This command has an even more uncertain future than ab-loop-dump-cache and might disappear without replacement if the author decides it's useless.

begin-vo-dragging

Begin window dragging if supported by the current VO. This command should only be called while a mouse button is being pressed, otherwise it will be ignored. The exact effect of this command depends on the VO implementation of window dragging. For example, on Windows only the left mouse button can begin window dragging, while X11 and Wayland allow other mouse buttons.

context-menu

Show context menu on the video window. See `Context Menu`_ section for details.

Undocumented commands: ao-reload (experimental/internal).

List of events

This is a partial list of events. This section describes what mpv_event_to_node() returns, and which is what scripting APIs and the JSON IPC sees. Note that the C API has separate C-level declarations with mpv_event, which may be slightly different.

Note that events are asynchronous: the player core continues running while events are delivered to scripts and other clients. In some cases, you can use hooks to enforce synchronous execution.

All events can have the following fields:

event: Name as the event (as returned by mpv_event_name()).
id: The reply_userdata field (opaque user value). If reply_userdata is 0, the field is not added.
error: Set to an error string (as returned by mpv_error_string()). This field is missing if no error happened, or the event type does not report error. Most events leave this unset.

This list uses the event name field value, and the C API symbol in brackets:

start-file (MPV_EVENT_START_FILE)

Happens right before a new file is loaded. When you receive this, the player is loading the file (or possibly already done with it).

This has the following fields:

playlist_entry_id: Playlist entry ID of the file being loaded now.

end-file (MPV_EVENT_END_FILE)

Happens after a file was unloaded. Typically, the player will load the next file right away, or quit if this was the last file.

The event has the following fields:

reason

Has one of these values:

eof: The file has ended. This can (but doesn't have to) include incomplete files or broken network connections under circumstances.
stop: Playback was ended by a command.
quit: Playback was ended by sending the quit command.
error: An error happened. In this case, an error field is present with the error string.
redirect: Happens with playlists and similar. Details see MPV_END_FILE_REASON_REDIRECT in the C API.
unknown: Unknown. Normally doesn't happen, unless the Lua API is out of sync with the C API. (Likewise, it could happen that your script gets reason strings that did not exist yet at the time your script was written.)

playlist_entry_id

Playlist entry ID of the file that was being played or attempted to be played. This has the same value as the playlist_entry_id field in the corresponding start-file event.

file_error

Set to mpv error string describing the approximate reason why playback failed. Unset if no error known. (In Lua scripting, this value was set on the error field directly. This is deprecated since mpv 0.33.0. In the future, this error field will be unset for this specific event.)

playlist_insert_id

If loading ended, because the playlist entry to be played was for example a playlist, and the current playlist entry is replaced with a number of other entries. This may happen at least with MPV_END_FILE_REASON_REDIRECT (other event types may use this for similar but different purposes in the future). In this case, playlist_insert_id will be set to the playlist entry ID of the first inserted entry, and playlist_insert_num_entries to the total number of inserted playlist entries. Note this in this specific case, the ID of the last inserted entry is playlist_insert_id+num-1. Beware that depending on circumstances, you may observe the new playlist entries before seeing the event (e.g. reading the "playlist" property or getting a property change notification before receiving the event). If this is 0 in the C API, this field isn't added.

playlist_insert_num_entries

See playlist_insert_id. Only present if playlist_insert_id is present.

file-loaded (MPV_EVENT_FILE_LOADED)

Happens after a file was loaded and begins playback.

seek (MPV_EVENT_SEEK)

Happens on seeking. (This might include cases when the player seeks internally, even without user interaction. This includes e.g. segment changes when playing ordered chapters Matroska files.)

playback-restart (MPV_EVENT_PLAYBACK_RESTART)

Start of playback after seek or after file was loaded.

shutdown (MPV_EVENT_SHUTDOWN)

Sent when the player quits, and the script should terminate. Normally handled automatically. See `Details on the script initialization and lifecycle`_.

log-message (MPV_EVENT_LOG_MESSAGE)

Receives messages enabled with mpv_request_log_messages() (Lua: mp.enable_messages).

This contains, in addition to the default event fields, the following fields:

prefix: The module prefix, identifies the sender of the message. This is what the terminal player puts in front of the message text when using the --v option, and is also what is used for --msg-level.
level: The log level as string. See msg.log for possible log level names. Note that later versions of mpv might add new levels or remove (undocumented) existing ones.
text: The log message. The text will end with a newline character. Sometimes it can contain multiple lines.

Keep in mind that these messages are meant to be hints for humans. You should not parse them, and prefix/level/text of messages might change any time.

hook

The event has the following fields:

hook_id: ID to pass to mpv_hook_continue(). The Lua scripting wrapper provides a better API around this with mp.add_hook().

get-property-reply (MPV_EVENT_GET_PROPERTY_REPLY)

See C API.

set-property-reply (MPV_EVENT_SET_PROPERTY_REPLY)

See C API.

command-reply (MPV_EVENT_COMMAND_REPLY)

This is one of the commands for which the `error field is meaningful.

JSON IPC and Lua and possibly other backends treat this specially and may not pass the actual event to the user. See C API.

The event has the following fields:

result: The result (on success) of any mpv_node type, if any.

client-message (MPV_EVENT_CLIENT_MESSAGE)

Lua and possibly other backends treat this specially and may not pass the actual event to the user.

The event has the following fields:

args: Array of strings with the message data.

video-reconfig (MPV_EVENT_VIDEO_RECONFIG)

Happens on video output or filter reconfig.

audio-reconfig (MPV_EVENT_AUDIO_RECONFIG)

Happens on audio output or filter reconfig.

property-change (MPV_EVENT_PROPERTY_CHANGE)

Happens when a property that is being observed changes value.

The event has the following fields:

name: The name of the property.
data: The new value of the property.

The following events also happen, but are deprecated: idle, tick Use mpv_observe_property() (Lua: mp.observe_property()) instead.

Hooks

Hooks are synchronous events between player core and a script or similar. This applies to client API (including the Lua scripting interface). Normally, events are supposed to be asynchronous, and the hook API provides an awkward and obscure way to handle events that require stricter coordination. There are no API stability guarantees made. Not following the protocol exactly can make the player freeze randomly. Basically, nobody should use this API.

The C API is described in the header files. The Lua API is described in the Lua section.

Before a hook is actually invoked on an API clients, it will attempt to return new values for all observed properties that were changed before the hook. This may make it easier for an application to set defined "barriers" between property change notifications by registering hooks. (That means these hooks will have an effect, even if you do nothing and make them continue immediately.)

The following hooks are currently defined:

on_load

Called when a file is to be opened, before anything is actually done. For example, you could read and write the stream-open-filename property to redirect an URL to something else (consider support for streaming sites which rarely give the user a direct media URL), or you could set per-file options with by setting the property file-local-options/<option name>. The player will wait until all hooks are run.

Ordered after start-file and before playback-restart.

on_load_fail

Called after after a file has been opened, but failed to. This can be used to provide a fallback in case native demuxers failed to recognize the file, instead of always running before the native demuxers like on_load. Demux will only be retried if stream-open-filename was changed. If it fails again, this hook is _not_ called again, and loading definitely fails.

Ordered after on_load, and before playback-restart and end-file.

on_preloaded

Called after a file has been opened, and before tracks are selected and decoders are created. This has some usefulness if an API users wants to select tracks manually, based on the set of available tracks. It's also useful to initialize --lavfi-complex in a specific way by API, without having to "probe" the available streams at first.

Note that this does not yet apply default track selection. Which operations exactly can be done and not be done, and what information is available and what is not yet available yet, is all subject to change.

Ordered after on_load_fail etc. and before playback-restart.

on_unload

Run before closing a file, and before actually uninitializing everything. It's not possible to resume playback in this state.

Ordered before end-file. Will also happen in the error case (then after on_load_fail).

on_before_start_file

Run before a start-file event is sent. (If any client changes the current playlist entry, or sends a quit command to the player, the corresponding event will not actually happen after the hook returns.) Useful to drain property changes before a new file is loaded.

on_after_end_file

Run after an end-file event. Useful to drain property changes after a file has finished.

Input Command Prefixes

These prefixes are placed between key name and the actual command. Multiple prefixes can be specified. They are separated by whitespace.

osd-auto: Use the default behavior for this command. This is the default for input.conf commands. Some libmpv/scripting/IPC APIs do not use this as default, but use no-osd instead.
no-osd: Do not use any OSD for this command.
osd-bar: If possible, show a bar with this command. Seek commands will show the progress bar, property changing commands may show the newly set value.
osd-msg: If possible, show an OSD message with this command. Seek command show the current playback time, property changing commands show the newly set value as text.
osd-msg-bar: Combine osd-bar and osd-msg.
raw: Do not expand properties in string arguments. (Like "${property-name}".) This is the default for some libmpv/scripting/IPC APIs.
expand-properties: All string arguments are expanded as described in Property Expansion. This is the default for input.conf commands.
repeatable: For some commands, keeping a key pressed doesn't run the command repeatedly. This prefix forces enabling key repeat in any case. For a list of commands: the first command determines the repeatability of the whole list (up to and including version 0.33 - a list was always repeatable).
nonrepeatable: For some commands, keeping a key pressed runs the command repeatedly. This prefix forces disabling key repeat in any case.
nonscalable: When some commands (e.g. add) are bound to scalable keys associated to a high-precision input device like a touchpad (e.g. WHEEL_UP), the value specified in the command is scaled to smaller steps based on the high resolution input data if available. This prefix forces disabling this behavior, so the value is always changed in the discrete unit specified in the key binding.
async: Allow asynchronous execution (if possible). Note that only a few commands will support this (usually this is explicitly documented). Some commands are asynchronous by default (or rather, their effects might manifest after completion of the command). The semantics of this flag might change in the future. Set it only if you don't rely on the effects of this command being fully realized when it returns. See Synchronous vs. Asynchronous.
sync: Allow synchronous execution (if possible). Normally, all commands are synchronous by default, but some are asynchronous by default for compatibility with older behavior.

All of the osd prefixes are still overridden by the global --osd-level settings.

Synchronous vs. Asynchronous

The async and sync prefix matter only for how the issuer of the command waits on the completion of the command. Normally it does not affect how the command behaves by itself. There are the following cases:

Normal input.conf commands are always run asynchronously. Slow running commands are queued up or run in parallel.
"Multi" input.conf commands (1 key binding, concatenated with ;) will be executed in order, except for commands that are async (either prefixed with async, or async by default for some commands). The async commands are run in a detached manner, possibly in parallel to the remaining sync commands in the list.
Normal Lua and libmpv commands (e.g. mpv_command()) are run in a blocking manner, unless the async prefix is used, or the command is async by default. This means in the sync case the caller will block, even if the core continues playback. Async mode runs the command in a detached manner.
Async libmpv command API (e.g. mpv_command_async()) never blocks the caller, and always notify their completion with a message. The sync and async prefixes make no difference.
Lua also provides APIs for running async commands, which behave similar to the C counterparts.
In all cases, async mode can still run commands in a synchronous manner, even in detached mode. This can for example happen in cases when a command does not have an asynchronous implementation. The async libmpv API still never blocks the caller in these cases.

Before mpv 0.29.0, the async prefix was only used by screenshot commands, and made them run the file saving code in a detached manner. This is the default now, and async changes behavior only in the ways mentioned above.

Currently the following commands have different waiting characteristics with sync vs. async: sub-add, audio-add, sub-reload, audio-reload, rescan-external-files, screenshot, screenshot-to-file, dump-cache, ab-loop-dump-cache.

Asynchronous command details

On the API level, every asynchronous command is bound to the context which started it. For example, an asynchronous command started by mpv_command_async is bound to the mpv_handle passed to the function. Only this mpv_handle receives the completion notification (MPV_EVENT_COMMAND_REPLY), and only this handle can abort a still running command directly. If the mpv_handle is destroyed, any still running async. commands started by it are terminated.

The scripting APIs and JSON IPC give each script/connection its own implicit mpv_handle.

If the player is closed, the core may abort all pending async. commands on its own (like a forced mpv_abort_async_command() call for each pending command on behalf of the API user). This happens at the same time MPV_EVENT_SHUTDOWN is sent, and there is no way to prevent this.

Input Sections

Input sections group a set of bindings, and enable or disable them at once. In input.conf, each key binding is assigned to an input section, rather than actually having explicit text sections.

See also: enable-section and disable-section commands.

Predefined bindings:

default: Bindings without input section are implicitly assigned to this section. It is enabled by default during normal playback.
encode: Section which is active in encoding mode. It is enabled exclusively, so that bindings in the default sections are ignored.

Properties

Properties are used to set mpv options during runtime, or to query arbitrary information. They can be manipulated with the set/add/cycle commands, and retrieved with show-text, or anything else that uses property expansion. (See Property Expansion.)

If an option is referenced, the property will normally take/return exactly the same values as the option. In these cases, properties are merely a way to change an option at runtime.

Note that many properties are unavailable at startup. See `Details on the script initialization and lifecycle`_.

Property list

Note

Most options can be set at runtime via properties as well. Just remove the leading -- from the option name. These are not documented below, see `OPTIONS`_ instead. Only properties which do not exist as option with the same name, or which have very different behavior from the options are documented below.

Properties marked as (RW) are writeable, while those that aren't are read-only.

audio-speed-correction, video-speed-correction

Factor multiplied with speed at which the player attempts to play the file. Usually it's exactly 1. (Display sync mode will make this useful.)

OSD formatting will display it in the form of +1.23456%, with the number being (raw - 1) * 100 for the given raw property value.

display-sync-active

Whether --video-sync=display is actually active.

filename

Currently played file, with path stripped. If this is an URL, try to undo percent encoding as well. (The result is not necessarily correct, but looks better for display purposes. Use the path property to get an unmodified filename.)

This has a sub-property:

filename/no-ext: Like the filename property, but if the text contains a ., strip all text after the last .. Usually this removes the file extension.

file-size

Length in bytes of the source file/stream. (This is the same as ${stream-end}. For segmented/multi-part files, this will return the size of the main or manifest file, whatever it is.)

estimated-frame-count

Total number of frames in current file.

Note

This is only an estimate. (It's computed from two unreliable quantities: fps and stream length.)

estimated-frame-number

Number of current frame in current stream.

Note

This is only an estimate. (It's computed from two unreliable quantities: fps and possibly rounded timestamps.)

pid

Process-id of mpv.

path

Full path of the currently played file. Usually this is exactly the same string you pass on the mpv command line or the loadfile command, even if it's a relative path. If you expect an absolute path, you will have to determine it yourself, for example by using the normalize-path command.

stream-open-filename

The full path to the currently played media. This is different from path only in special cases. In particular, if --ytdl=yes is used, and the URL is detected by youtube-dl, then the script will set this property to the actual media URL. This property should be set only during the on_load or on_load_fail hooks, otherwise it will have no effect (or may do something implementation defined in the future). The property is reset if playback of the current media ends.

media-title

If the currently played file has a title tag, use that.

Otherwise, return the filename property.

file-format

Symbolic name of the file format. In some cases, this is a comma-separated list of format names, e.g. mp4 is mov,mp4,m4a,3gp,3g2,mj2 (the list may grow in the future for any format).

current-demuxer

Name of the current demuxer. (This is useless.)

(Renamed from demuxer.)

stream-path

Filename (full path) of the stream layer filename. (This is probably useless and is almost never different from path.)

stream-pos

Raw byte position in source stream. Technically, this returns the position of the most recent packet passed to a decoder.

stream-end

Raw end position in bytes in source stream.

duration

Duration of the current file in seconds. If the duration is unknown, the property is unavailable. Note that the file duration is not always exactly known, so this is an estimate.

This replaces the length property, which was deprecated after the mpv 0.9 release. (The semantics are the same.)

This has a sub-property:

duration/full: duration with milliseconds.

avsync

Last A/V synchronization difference. Unavailable if audio or video is disabled.

total-avsync-change

Total A-V sync correction done. Unavailable if audio or video is disabled.

decoder-frame-drop-count

Video frames dropped by decoder, because video is too far behind audio (when using --framedrop=decoder). Sometimes, this may be incremented in other situations, e.g. when video packets are damaged, or the decoder doesn't follow the usual rules. Unavailable if video is disabled.

frame-drop-count

Frames dropped by VO (when using --framedrop=vo).

mistimed-frame-count

Number of video frames that were not timed correctly in display-sync mode for the sake of keeping A/V sync. This does not include external circumstances, such as video rendering being too slow or the graphics driver somehow skipping a vsync. It does not include rounding errors either (which can happen especially with bad source timestamps). For example, using the display-desync mode should never change this value from 0.

vsync-ratio

For how many vsyncs a frame is displayed on average. This is available if display-sync is active only. For 30 FPS video on a 60 Hz screen, this will be 2. This is the moving average of what actually has been scheduled, so 24 FPS on 60 Hz will never remain exactly on 2.5, but jitter depending on the last frame displayed.

vo-delayed-frame-count

Estimated number of frames delayed due to external circumstances in display-sync mode. Note that in general, mpv has to guess that this is happening, and the guess can be inaccurate.

percent-pos (RW)

Position in current file (0-100). The advantage over using this instead of calculating it out of other properties is that it properly falls back to estimating the playback position from the byte position, if the file duration is not known.

time-pos (RW)

Position in current file in seconds.

This has a sub-property:

time-pos/full: time-pos with milliseconds.

time-start

Deprecated. Always returns 0. Before mpv 0.14, this used to return the start time of the file (could affect e.g. transport streams). See --rebase-start-time option.

time-remaining

Remaining length of the file in seconds. Note that the file duration is not always exactly known, so this is an estimate.

This has a sub-property:

time-remaining/full: time-remaining with milliseconds.

audio-pts

Current audio playback position in current file in seconds. Unlike time-pos, this updates more often than once per frame. This is mostly equivalent to time-pos for audio-only files however it also takes into account the audio driver delay. This can lead to negative values in certain cases, so in general you probably want to simply use time-pos.

This has a sub-property:

audio-pts/full: audio-pts with milliseconds.

playtime-remaining

time-remaining scaled by the current speed.

This has a sub-property:

playtime-remaining/full: playtime-remaining with milliseconds.

playback-time (RW)

Alias for time-pos.

Prior to mpv 0.39.0, time-pos and playback-time could report different values in certain edge cases.

This has a sub-property:

playback-time/full: playback-time with milliseconds.

remaining-file-loops

How many more times the current file is going to be looped. This is initialized from the value of --loop-file. This counts the number of times it causes the player to seek to the beginning of the file, so it is 0 the last the time is played. -1 corresponds to infinity.

remaining-ab-loops

How many more times the current A-B loop is going to be looped, if one is active. This is initialized from the value of --ab-loop-count. This counts the number of times it causes the player to seek to --ab-loop-a, so it is 0 the last the time the loop is played. -1 corresponds to infinity.

chapter (RW)

Current chapter number. The number of the first chapter is 0.

edition (RW)

Current MKV edition number. Setting this property to a different value will restart playback. The number of the first edition is 0.

Before mpv 0.31.0, this showed the actual edition selected at runtime, if you didn't set the option or property manually. With mpv 0.31.0 and later, this strictly returns the user-set option or property value, and the current-edition property was added to return the runtime selected edition (this matters with --edition=auto, the default).

current-edition

Currently selected edition. This property is unavailable if no file is loaded, or the file has no editions. (Matroska files make a difference between having no editions and a single edition, which will be reflected by the property, although in practice it does not matter.)

chapters

Number of chapters.

editions

Number of MKV editions.

edition-list

List of editions, current entry marked.

This has a number of sub-properties. Replace N with the 0-based edition index.

edition-list/count: Number of editions. If there are no editions, this can be 0 or 1 (1 if there's a useless dummy edition).
edition-list/N/id (RW): Edition ID as integer. Use this to set the edition property. Currently, this is the same as the edition index.
edition-list/N/default: Whether this is the default edition.
edition-list/N/title: Edition title as stored in the file. Not always available.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each edition)
        "id"                MPV_FORMAT_INT64
        "title"             MPV_FORMAT_STRING
        "default"           MPV_FORMAT_FLAG

metadata

Metadata key/value pairs.

If the property is accessed with Lua's mp.get_property_native, this returns a table with metadata keys mapping to metadata values. If it is accessed with the client API, this returns a MPV_FORMAT_NODE_MAP, with tag keys mapping to tag values.

For OSD, it returns a formatted list. Trying to retrieve this property as a raw string doesn't work.

This has a number of sub-properties:

metadata/by-key/<key>: Value of metadata entry <key>.
metadata/list/count: Number of metadata entries.
metadata/list/N/key: Key name of the Nth metadata entry. (The first entry is 0).
metadata/list/N/value: Value of the Nth metadata entry.
metadata/<key>: Old version of metadata/by-key/<key>. Use is discouraged, because the metadata key string could conflict with other sub-properties.

The layout of this property might be subject to change. Suggestions are welcome how exactly this property should work.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_MAP
    (key and string value for each metadata entry)

filtered-metadata

Like metadata, but includes only fields listed in the --display-tags option. This is the same set of tags that is printed to the terminal.

chapter-metadata

Metadata of current chapter. Works similar to metadata property. It also allows the same access methods (using sub-properties).

Per-chapter metadata is very rare. Usually, only the chapter name (title) is set.

For accessing other information, like chapter start, see the chapter-list property.

vf-metadata/<filter-label>

Metadata added by video filters. Accessed by the filter label, which, if not explicitly specified using the @filter-label: syntax, will be <filter-name>.NN.

Works similar to metadata property. It allows the same access methods (using sub-properties).

An example of this kind of metadata are the cropping parameters added by --vf=lavfi=cropdetect.

af-metadata/<filter-label>

Equivalent to vf-metadata/<filter-label>, but for audio filters.

deinterlace-active

Returns yes/true if mpv's deinterlacing filter is active. Note that it will not detect any manually inserted deinterlacing filters done via --vf.

idle-active

Returns yes/true if no file is loaded, but the player is staying around because of the --idle option.

(Renamed from idle.)

core-idle

Whether the playback core is paused. This can differ from pause in special situations, such as when the player pauses itself due to low network cache.

This also returns yes/true if playback is restarting or if nothing is playing at all. In other words, it's only no/false if there's actually video playing. (Behavior since mpv 0.7.0.)

cache-speed

Current I/O read speed between the cache and the lower layer (like network). This gives the number bytes per seconds over a 1 second window (using the type MPV_FORMAT_INT64 for the client API).

This is the same as demuxer-cache-state/raw-input-rate.

demuxer-cache-duration

Approximate duration of video buffered in the demuxer, in seconds. The guess is very unreliable, and often the property will not be available at all, even if data is buffered.

demuxer-cache-time

Approximate time of video buffered in the demuxer, in seconds. Same as demuxer-cache-duration but returns the last timestamp of buffered data in demuxer.

demuxer-cache-idle

Whether the demuxer is idle, which means that the demuxer cache is filled to the requested amount, and is currently not reading more data.

demuxer-cache-state

Each entry in seekable-ranges represents a region in the demuxer cache that can be seeked to, with a start and end fields containing the respective timestamps. If there are multiple demuxers active, this only returns information about the "main" demuxer, but might be changed in future to return unified information about all demuxers. The ranges are in arbitrary order. Often, ranges will overlap for a bit, before being joined. In broken corner cases, ranges may overlap all over the place.

The end of a seek range is usually smaller than the value returned by the demuxer-cache-time property, because that property returns the guessed buffering amount, while the seek ranges represent the buffered data that can actually be used for cached seeking.

bof-cached indicates whether the seek range with the lowest timestamp points to the beginning of the stream (BOF). This implies you cannot seek before this position at all. eof-cached indicates whether the seek range with the highest timestamp points to the end of the stream (EOF). If both bof-cached and eof-cached are true, and there's only 1 cache range, the entire stream is cached.

fw-bytes is the number of bytes of packets buffered in the range starting from the current decoding position. This is a rough estimate (may not account correctly for various overhead), and stops at the demuxer position (it ignores seek ranges after it).

file-cache-bytes is the number of bytes stored in the file cache. This includes all overhead, and possibly unused data (like pruned data). This member is missing if the file cache wasn't enabled with --cache-on-disk=yes.

cache-end is demuxer-cache-time. Missing if unavailable.

reader-pts is the approximate timestamp of the start of the buffered range. Missing if unavailable.

cache-duration is demuxer-cache-duration. Missing if unavailable.

raw-input-rate is the estimated input rate of the network layer (or any other byte-oriented input layer) in bytes per second. May be inaccurate or missing.

ts-per-stream is an array containing an entry for each stream type: video, audio, and subtitle. For each stream type, the details for the demuxer cache for that stream type are available as cache-duration, reader-pts and cache-end.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_MAP
    "seekable-ranges"   MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP
            "start"             MPV_FORMAT_DOUBLE
            "end"               MPV_FORMAT_DOUBLE
    "bof-cached"        MPV_FORMAT_FLAG
    "eof-cached"        MPV_FORMAT_FLAG
    "fw-bytes"          MPV_FORMAT_INT64
    "file-cache-bytes"  MPV_FORMAT_INT64
    "cache-end"         MPV_FORMAT_DOUBLE
    "reader-pts"        MPV_FORMAT_DOUBLE
    "cache-duration"    MPV_FORMAT_DOUBLE
    "raw-input-rate"    MPV_FORMAT_INT64
    "ts-per-stream"     MPV_FORMAT_NODE_ARRAY
        MPV_FORMAT_NODE_MAP
              "type"            MPV_FORMAT_STRING
              "cache-duration"  MPV_FORMAT_DOUBLE
              "reader-pts"      MPV_FORMAT_DOUBLE
              "cache-end"       MPV_FORMAT_DOUBLE

Other fields (might be changed or removed in the future):

eof: Whether the reader thread has hit the end of the file.
underrun: Whether the reader thread could not satisfy a decoder's request for a new packet.
idle: Whether the thread is currently not reading.
total-bytes: Sum of packet bytes (plus some overhead estimation) of the entire packet queue, including cached seekable ranges.

demuxer-via-network

Whether the stream demuxed via the main demuxer is most likely played via network. What constitutes "network" is not always clear, might be used for other types of untrusted streams, could be wrong in certain cases, and its definition might be changing. Also, external files (like separate audio files or streams) do not influence the value of this property (currently).

demuxer-start-time

The start time reported by the demuxer in fractional seconds.

paused-for-cache

Whether playback is paused because of waiting for the cache.

cache-buffering-state

The percentage (0-100) of the cache fill status until the player will unpause (related to paused-for-cache).

eof-reached

Whether the end of playback was reached. Note that this is usually interesting only if --keep-open is enabled, since otherwise the player will immediately play the next file (or exit or enter idle mode), and in these cases the eof-reached property will logically be cleared immediately after it's set.

seeking

Whether the player is currently seeking, or otherwise trying to restart playback. (It's possible that it returns yes/true while a file is loaded. This is because the same underlying code is used for seeking and resyncing.)

mixer-active

Whether the audio mixer is active.

This option is relatively useless. Before mpv 0.18.1, it could be used to infer behavior of the volume property.

ao-volume (RW)

System volume. This property is available only if mpv audio output is currently active, and only if the underlying implementation supports volume control. What this option does depends on the API. For example, on ALSA this usually changes system-wide audio, while with PulseAudio this controls per-application volume.

ao-mute (RW)

Similar to ao-volume, but controls the mute state. May be unimplemented even if ao-volume works.

audio-params

Audio format as output by the audio decoder. This has a number of sub-properties:

audio-params/format: The sample format as string. This uses the same names as used in other places of mpv.
audio-params/samplerate: Samplerate.
audio-params/channels: The channel layout as a string. This is similar to what the --audio-channels accepts.
audio-params/hr-channels: As channels, but instead of the possibly cryptic actual layout sent to the audio device, return a hopefully more human readable form. (Usually only audio-out-params/hr-channels makes sense.)
audio-params/channel-count: Number of audio channels. This is redundant to the channels field described above.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_MAP
    "format"            MPV_FORMAT_STRING
    "samplerate"        MPV_FORMAT_INT64
    "channels"          MPV_FORMAT_STRING
    "channel-count"     MPV_FORMAT_INT64
    "hr-channels"       MPV_FORMAT_STRING

audio-out-params

Same as audio-params, but the format of the data written to the audio API.

colormatrix

Redirects to video-params/colormatrix. This parameter (as well as similar ones) can be overridden with the format video filter.

colormatrix-input-range

See colormatrix.

colormatrix-primaries

See colormatrix.

hwdec (RW)

Reflects the --hwdec option.

Writing to it may change the currently used hardware decoder, if possible. (Internally, the player may reinitialize the decoder, and will perform a seek to refresh the video properly.) You can watch the other hwdec properties to see whether this was successful.

Unlike in mpv 0.9.x and before, this does not return the currently active hardware decoder. Since mpv 0.18.0, hwdec-current is available for this purpose.

hwdec-current

The current hardware decoding in use. If decoding is active, return one of the values used by the hwdec option/property. no/false indicates software decoding. If no decoder is loaded, the property is unavailable.

hwdec-interop

This returns the currently loaded hardware decoding/output interop driver. This is known only once the VO has opened (and possibly later). With some VOs (like gpu), this might be never known in advance, but only when the decoder attempted to create the hw decoder successfully. (Using --gpu-hwdec-interop can load it eagerly.) If there are multiple drivers loaded, they will be separated by ,.

If no VO is active or no interop driver is known, this property is unavailable.

This does not necessarily use the same values as hwdec. There can be multiple interop drivers for the same hardware decoder, depending on platform and VO.

width, height

Video size. This uses the size of the video as decoded, or if no video frame has been decoded yet, the (possibly incorrect) container indicated size.

video-params

Video parameters, as output by the decoder (with overrides like aspect etc. applied). This has a number of sub-properties:

video-params/pixelformat: The pixel format as string. This uses the same names as used in other places of mpv.
video-params/hw-pixelformat: The underlying pixel format as string. This is relevant for some cases of hardware decoding and unavailable otherwise.
video-params/average-bpp: Average bits-per-pixel as integer. Subsampled planar formats use a different resolution, which is the reason this value can sometimes be odd or confusing. Can be unavailable with some formats.
video-params/w, video-params/h: Video size as integers, with no aspect correction applied.
video-params/dw, video-params/dh: Video size as integers, scaled for correct aspect ratio.
video-params/crop-x, video-params/crop-y: Crop offset of the source video frame.
video-params/crop-w, video-params/crop-h: Video size after cropping.
video-params/aspect: Display aspect ratio as float.
video-params/aspect-name: Display aspect ratio name as string. The name corresponds to motion picture film format that introduced given aspect ratio in film.
video-params/par: Pixel aspect ratio.
video-params/sar: Storage aspect ratio.
video-params/sar-name: Storage aspect ratio name as string.
video-params/colormatrix: The colormatrix in use as string. (Exact values subject to change.)
video-params/colorlevels: The colorlevels as string. (Exact values subject to change.)
video-params/primaries: The primaries in use as string. (Exact values subject to change.)
video-params/gamma: The gamma function in use as string. (Exact values subject to change.)
video-params/sig-peak (deprecated): The video file's tagged signal peak as float.
video-params/light: The light type in use as a string. (Exact values subject to change.)
video-params/chroma-location: Chroma location as string. (Exact values subject to change.)
video-params/rotate: Intended display rotation in degrees (clockwise).
video-params/stereo-in: Source file stereo 3D mode. (See the format video filter's stereo-in option.)
video-params/alpha: Alpha type. If the format has no alpha channel, this will be unavailable (but in future releases, it could change to no). If alpha is present, this is set to straight or premul.
video-params/min-luma: Minimum luminance, as reported by HDR10 metadata (in cd/m²)
video-params/max-luma: Maximum luminance, as reported by HDR10 metadata (in cd/m²)
video-params/max-cll: Maximum content light level, as reported by HDR10 metadata (in cd/m²)
video-params/max-fall: Maximum frame average light level, as reported by HDR10 metadata (in cd/m²)
video-params/scene-max-r: MaxRGB of a scene for R component, as reported by HDR10+ metadata (in cd/m²)
video-params/scene-max-g: MaxRGB of a scene for G component, as reported by HDR10+ metadata (in cd/m²)
video-params/scene-max-b: MaxRGB of a scene for B component, as reported by HDR10+ metadata (in cd/m²)
video-params/max-pq-y: Maximum PQ luminance of a frame, as reported by peak detection (in PQ, 0-1)
video-params/avg-pq-y: Average PQ luminance of a frame, as reported by peak detection (in PQ, 0-1)

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_MAP
    "pixelformat"       MPV_FORMAT_STRING
    "hw-pixelformat"    MPV_FORMAT_STRING
    "w"                 MPV_FORMAT_INT64
    "h"                 MPV_FORMAT_INT64
    "dw"                MPV_FORMAT_INT64
    "dh"                MPV_FORMAT_INT64
    "aspect"            MPV_FORMAT_DOUBLE
    "par"               MPV_FORMAT_DOUBLE
    "colormatrix"       MPV_FORMAT_STRING
    "colorlevels"       MPV_FORMAT_STRING
    "primaries"         MPV_FORMAT_STRING
    "gamma"             MPV_FORMAT_STRING
    "sig-peak"          MPV_FORMAT_DOUBLE
    "light"             MPV_FORMAT_STRING
    "chroma-location"   MPV_FORMAT_STRING
    "rotate"            MPV_FORMAT_INT64
    "stereo-in"         MPV_FORMAT_STRING
    "average-bpp"       MPV_FORMAT_INT64
    "alpha"             MPV_FORMAT_STRING
    "min-luma"          MPV_FORMAT_DOUBLE
    "max-luma"          MPV_FORMAT_DOUBLE
    "max-cll"           MPV_FORMAT_DOUBLE
    "max-fall"          MPV_FORMAT_DOUBLE
    "scene-max-r"       MPV_FORMAT_DOUBLE
    "scene-max-g"       MPV_FORMAT_DOUBLE
    "scene-max-b"       MPV_FORMAT_DOUBLE
    "max-pq-y"          MPV_FORMAT_DOUBLE
    "avg-pq-y"          MPV_FORMAT_DOUBLE

dwidth, dheight

Video display size. This is the video size after filters and aspect scaling have been applied. The actual video window size can still be different from this, e.g. if the user resized the video window manually.

These have the same values as video-out-params/dw and video-out-params/dh.

video-dec-params

Exactly like video-params, but no overrides applied.

video-out-params

Same as video-params, but after video filters have been applied. If there are no video filters in use, this will contain the same values as video-params. Note that this is still not necessarily what the video window uses, since the user can change the window size, and all real VOs do their own scaling independently from the filter chain.

Has the same sub-properties as video-params.

video-target-params

Same as video-params, but with the target properties that VO outputs to.

Has the same sub-properties as video-params.

video-frame-info

Approximate information of the current frame. Note that if any of these are used on OSD, the information might be off by a few frames due to OSD redrawing and frame display being somewhat disconnected, and you might have to pause and force a redraw.

This has a number of sub-properties:

video-frame-info/picture-type: The type of the picture. It can be "I" (intra), "P" (predicted), "B" (bi-dir predicted) or unavailable.
video-frame-info/interlaced: Whether the content of the frame is interlaced.
video-frame-info/tff: If the content is interlaced, whether the top field is displayed first.
video-frame-info/repeat: Whether the frame must be delayed when decoding.
video-frame-info/gop-timecode: String with the GOP timecode encoded in the frame.
video-frame-info/smpte-timecode: String with the SMPTE timecode encoded in the frame.
video-frame-info/estimated-smpte-timecode: Estimated timecode based on the current playback position and frame count.

container-fps

Container FPS. This can easily contain bogus values. For videos that use modern container formats or video codecs, this will often be incorrect.

(Renamed from fps.)

estimated-vf-fps

Estimated/measured FPS of the video filter chain output. (If no filters are used, this corresponds to decoder output.) This uses the average of the 10 past frame durations to calculate the FPS. It will be inaccurate if frame-dropping is involved (such as when framedrop is explicitly enabled, or after precise seeking). Files with imprecise timestamps (such as Matroska) might lead to unstable results.

current-window-scale (RW)

The window-scale value calculated from the current window size. This has the same value as window-scale if the window size was not changed since setting the option, and the window size was not restricted in other ways. If the window is fullscreened, this will return the scale value calculated from the last non-fullscreen size of the window. The property is unavailable if no video is active.

It is also possible to write to this property. This has the same behavior as writing window-scale. Note that writing to current-window-scale will not affect the value of window-scale.

focused

Whether the window has focus. Might not be supported by all VOs.

display-names

Names of the displays that the mpv window covers. On X11, these are the xrandr names (LVDS1, HDMI1, DP1, VGA1, etc.). On Windows, these are the GDI names (\.DISPLAY1, \.DISPLAY2, etc.) and the first display in the list will be the one that Windows considers associated with the window (as determined by the MonitorFromWindow API.) On macOS these are the Display Product Names as used in the System Information with a serial number in parentheses and only one display name is returned since a window can only be on one screen. On Wayland, these are the wl_output names if protocol version >= 4 is used (LVDS-1, HDMI-A-1, X11-1, etc.), or the wl_output model reported by the geometry event if protocol version < 4 is used.

display-fps

The refresh rate of the current display. Currently, this is the lowest FPS of any display covered by the video, as retrieved by the underlying system APIs (e.g. xrandr on X11). It is not the measured FPS. It's not necessarily available on all platforms. Note that any of the listed facts may change any time without a warning.

estimated-display-fps

The actual rate at which display refreshes seem to occur, measured by system time. Only available if display-sync mode (as selected by --video-sync) is active.

vsync-jitter

Estimated deviation factor of the vsync duration.

display-width, display-height

The current display's horizontal and vertical resolution in pixels. Whether or not these values update as the mpv window changes displays depends on the windowing backend. It may not be available on all platforms.

display-hidpi-scale

The HiDPI scale factor as reported by the windowing backend. If no VO is active, or if the VO does not report a value, this property is unavailable. It may be saner to report an absolute DPI, however, this is the way HiDPI support is implemented on most OS APIs. See also --hidpi-window-scale.

osd-width, osd-height

Last known OSD width (can be 0). This is needed if you want to use the overlay-add command. It gives you the actual OSD/window size (not including decorations drawn by the OS window manager).

Alias to osd-dimensions/w and osd-dimensions/h.

osd-par

Last known OSD display pixel aspect (can be 0).

Alias to osd-dimensions/osd-par.

osd-dimensions

Last known OSD dimensions.

Has the following sub-properties (which can be read as MPV_FORMAT_NODE or Lua table with mp.get_property_native):

osd-dimensions/w: Size of the VO window in OSD render units (usually pixels, but may be scaled pixels with VOs like xv).
osd-dimensions/h: Size of the VO window in OSD render units,
osd-dimensions/par: Pixel aspect ratio of the OSD (usually 1).
osd-dimensions/aspect: Display aspect ratio of the VO window. (Computing from the properties above.)
osd-dimensions/mt, osd-dimensions/mb, osd-dimensions/ml, osd-dimensions/mr: OSD to video margins (top, bottom, left, right). This describes the area into which the video is rendered.

Any of these properties may be unavailable or set to dummy values if the VO window is not created or visible.

term-size

The current terminal size.

This has two sub-properties.

term-size/w: width of the terminal in cells
term-size/h: height of the terminal in cells

This property is not observable. Reacting to size changes requires polling.

window-id

Read-only - mpv's window id. May not always be available, i.e due to window not being opened yet or not being supported by the VO.

mouse-pos

Read-only - last known mouse position, normalized to OSD dimensions.

Has the following sub-properties (which can be read as MPV_FORMAT_NODE or Lua table with mp.get_property_native):

mouse-pos/x, mouse-pos/y: Last known coordinates of the mouse pointer.
mouse-pos/hover: Boolean - whether the mouse pointer hovers the video window. The coordinates should be ignored when this value is false, because the video backends update them only when the pointer hovers the window.

touch-pos

Read-only - last known touch point positions, normalized to OSD dimensions.

This has a number of sub-properties. Replace N with the 0-based touch point index. Whenever a new finger touches the screen, a new touch point is added to the list of touch points with the smallest unused N available.

touch-pos/count: Number of active touch points.
touch-pos/N/x, touch-pos/N/y: Position of the Nth touch point.
touch-pos/N/id: Unique identifier of the touch point. This can be used to identify individual touch points when their indexes change.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each touch point)
        "x"        MPV_FORMAT_INT64
        "y"        MPV_FORMAT_INT64
        "id"       MPV_FORMAT_INT64

sub-ass-extradata

The current ASS subtitle track's extradata. There is no formatting done. The extradata is returned as a string as-is. This property is not available for non-ASS subtitle tracks.

sub-text

The current subtitle text regardless of sub visibility. Formatting is stripped. If the subtitle is not text-based (i.e. DVD/BD subtitles), an empty string is returned.

This has sub-properties for different formats:

sub-text/ass

Like sub-text, but return the text in ASS format. Text subtitles in other formats are converted. For native ASS subtitles, events that do not contain any text (but vector drawings etc.) are not filtered out. If multiple events match with the current playback time, they are concatenated with line breaks. Contains only the "Text" part of the events.

This property is not enough to render ASS subtitles correctly, because ASS header and per-event metadata are not returned. Use /ass-full for that.

sub-text/ass-full

Like sub-text-ass, but return the full event with all fields, formatted as lines in a .ass text file. Use with sub-ass-extradata for style information.

sub-text-ass (deprecated)

Deprecated alias for sub-text/ass.

secondary-sub-text

Same as sub-text (with the same sub-properties), but for the secondary subtitles.

sub-start

The current subtitle start time (in seconds). If there's multiple current subtitles, returns the first start time. If no current subtitle is present null is returned instead.

This has a sub-property:

sub-start/full: sub-start with milliseconds.

secondary-sub-start

Same as sub-start, but for the secondary subtitles.

sub-end

The current subtitle end time (in seconds). If there's multiple current subtitles, return the last end time. If no current subtitle is present, or if it's present but has unknown or incorrect duration, null is returned instead.

This has a sub-property:

sub-end/full: sub-end with milliseconds.

secondary-sub-end

Same as sub-end, but for the secondary subtitles.

playlist-pos (RW)

Current position on playlist. The first entry is on position 0. Writing to this property may start playback at the new position.

In some cases, this is not necessarily the currently playing file. See explanation of current and playing flags in playlist.

If there the playlist is empty, or if it's non-empty, but no entry is "current", this property returns -1. Likewise, writing -1 will put the player into idle mode (or exit playback if idle mode is not enabled). If an out of range index is written to the property, this behaves as if writing -1. (Before mpv 0.33.0, instead of returning -1, this property was unavailable if no playlist entry was current.)

Writing the current value back to the property will have no effect. Use playlist-play-index to restart the playback of the current entry if desired.

playlist-pos-1 (RW)

Same as playlist-pos, but 1-based.

playlist-current-pos (RW)

Index of the "current" item on playlist. This usually, but not necessarily, the currently playing item (see playlist-playing-pos). Depending on the exact internal state of the player, it may refer to the playlist item to play next, or the playlist item used to determine what to play next.

For reading, this is exactly the same as playlist-pos.

For writing, this only sets the position of the "current" item, without stopping playback of the current file (or starting playback, if this is done in idle mode). Use -1 to remove the current flag.

This property is only vaguely useful. If set during playback, it will typically cause the playlist entry after it to be played next. Another possibly odd observable state is that if playlist-next is run during playback, this property is set to the playlist entry to play next (unlike the previous case). There is an internal flag that decides whether the current playlist entry or the next one should be played, and this flag is currently inaccessible for API users. (Whether this behavior will kept is possibly subject to change.)

playlist-playing-pos

Index of the "playing" item on playlist. A playlist item is "playing" if it's being loaded, actually playing, or being unloaded. This property is set during the MPV_EVENT_START_FILE (start-file) and the MPV_EVENT_START_END (end-file) events. Outside of that, it returns -1. If the playlist entry was somehow removed during playback, but playback hasn't stopped yet, or is in progress of being stopped, it also returns -1. (This can happen at least during state transitions.)

In the "playing" state, this is usually the same as playlist-pos, except during state changes, or if playlist-current-pos was written explicitly.

playlist-count

Number of total playlist entries.

playlist-path

The original path of the playlist for the current entry before mpv expanded the entries. Unavailable if the file was not originally associated with a playlist in some way.

playlist

Playlist, current entry marked. Currently, the raw property value is useless.

This has a number of sub-properties. Replace N with the 0-based playlist entry index.

playlist/count: Number of playlist entries (same as playlist-count).
playlist/N/filename: Filename of the Nth entry.
playlist/N/playing: yes/true if the playlist-playing-pos property points to this entry, no/false or unavailable otherwise.
playlist/N/current: yes/true if the playlist-current-pos property points to this entry, no/false or unavailable otherwise.
playlist/N/title: Name of the Nth entry. Available if the playlist file contains such fields and mpv's parser supports it for the given playlist format, or if the playlist entry has been opened before and a media-title other than filename has been acquired.
playlist/N/id: Unique ID for this entry. This is an automatically assigned integer ID that is unique for the entire life time of the current mpv core instance. Other commands, events, etc. use this as playlist_entry_id fields.
playlist/N/playlist-path: The original path of the playlist for this entry before mpv expanded it. Unavailable if the file was not originally associated with a playlist in some way.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each playlist entry)
        "filename"  MPV_FORMAT_STRING
        "current"   MPV_FORMAT_FLAG (might be missing; since mpv 0.7.0)
        "playing"   MPV_FORMAT_FLAG (same)
        "title"     MPV_FORMAT_STRING (optional)
        "id"        MPV_FORMAT_INT64

track-list

List of audio/video/sub tracks, current entry marked.

This has a number of sub-properties. Replace N with the 0-based track index.

track-list/count: Total number of tracks.
track-list/video: The list of video tracks. This is only usable for printing and its value can't be retrieved.
track-list/audio: The list of audio tracks. This is only usable for printing and its value can't be retrieved.
track-list/sub: The list of sub tracks. This is only usable for printing and its value can't be retrieved.
track-list/N/id: The ID as it's used for --sid/--aid/--vid. This is unique within tracks of the same type (sub/audio/video), but otherwise not.
track-list/N/type: String describing the media type. One of audio, video, sub.
track-list/N/src-id: Track ID as used in the source file. Not always available. (It is missing if the format has no native ID, if the track is a pseudo-track that does not exist in this way in the actual file, or if the format is handled by libavformat, and the format was not whitelisted as having track IDs.)
track-list/N/title: Track title as it is stored in the file. Not always available.
track-list/N/lang: Track language as identified by the file. Not always available.
track-list/N/image: yes/true if this is a video track that consists of a single picture, no/false or unavailable otherwise. The heuristic used to determine if a stream is an image doesn't attempt to detect images in codecs normally used for videos. Otherwise, it is reliable.
track-list/N/albumart: yes/true if this is an image embedded in an audio file or external cover art, no/false or unavailable otherwise.
track-list/N/default: yes/true if the track has the default flag set in the file, no/false or unavailable otherwise.
track-list/N/forced: yes/true if the track has the forced flag set in the file, no/false or unavailable otherwise.
track-list/N/dependent: yes/true if the track has the dependent flag set in the file, no/false or unavailable otherwise.
track-list/N/visual-impaired: yes/true if the track has the visual impaired flag set in the file, no/false or unavailable otherwise.
track-list/N/hearing-impaired: yes/true if the track has the hearing impaired flag set in the file, no/false or unavailable otherwise.
track-list/N/hls-bitrate: The bitrate of the HLS stream, if available.
track-list/N/program-id: The program ID of the HLS stream, if available.
track-list/N/codec: The codec name used by this track, for example h264. Unavailable in some rare cases.
track-list/N/codec-desc: The codec descriptive name used by this track.
track-list/N/codec-profile: The codec profile used by this track. Available only if the track has been already decoded.
track-list/N/external: yes/true if the track is an external file, no/false or unavailable otherwise. This is set for separate subtitle files.
track-list/N/external-filename: The filename if the track is from an external file, unavailable otherwise.
track-list/N/selected: yes/true if the track is currently decoded, no/false or unavailable otherwise.
track-list/N/main-selection: It indicates the selection order of tracks for the same type. If a track is not selected, or is selected by the --lavfi-complex, it is not available. For subtitle tracks, 0 represents the sid, and 1 represents the secondary-sid.
track-list/N/ff-index: The stream index as usually used by the FFmpeg utilities. Note that this can be potentially wrong if a demuxer other than libavformat (--demuxer=lavf) is used. For mkv files, the index will usually match even if the default (builtin) demuxer is used, but there is no hard guarantee.
track-list/N/decoder: If this track is being decoded, the short decoder name,
track-list/N/decoder-desc: If this track is being decoded, the human-readable decoder name,
track-list/N/demux-w, track-list/N/demux-h: Video size hint as indicated by the container. (Not always accurate.)
track-list/N/demux-crop-x, track-list/N/demux-crop-y: Crop offset of the source video frame.
track-list/N/demux-crop-w, track-list/N/demux-crop-h: Video size after cropping.
track-list/N/demux-channel-count: Number of audio channels as indicated by the container. (Not always accurate - in particular, the track could be decoded as a different number of channels.)
track-list/N/demux-channels: Channel layout as indicated by the container. (Not always accurate.)
track-list/N/demux-samplerate: Audio sample rate as indicated by the container. (Not always accurate.)
track-list/N/demux-fps: Video FPS as indicated by the container. (Not always accurate.)
track-list/N/demux-bitrate: Audio average bitrate, in bits per second. (Not always accurate.)
track-list/N/demux-rotation: Video clockwise rotation metadata, in degrees.
track-list/N/demux-par: Pixel aspect ratio.
track-list/N/format-name: Short name for format from ffmpeg. If the track is audio, this will be the name of the sample format. If the track is video, this will be the name of the pixel format.
track-list/N/audio-channels (deprecated): Deprecated alias for track-list/N/demux-channel-count.
track-list/N/replaygain-track-peak, track-list/N/replaygain-track-gain: Per-track replaygain values. Only available for audio tracks with corresponding information stored in the source file.
track-list/N/replaygain-album-peak, track-list/N/replaygain-album-gain: Per-album replaygain values. If the file has per-track but no per-album information, the per-album values will be copied from the per-track values currently. It's possible that future mpv versions will make these properties unavailable instead in this case.
track-list/N/dolby-vision-profile, track-list/N/dolby-vision-level: Dolby Vision profile and level. May not be available if the container does not provide this information.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each track)
        "id"                MPV_FORMAT_INT64
        "type"              MPV_FORMAT_STRING
        "src-id"            MPV_FORMAT_INT64
        "title"             MPV_FORMAT_STRING
        "lang"              MPV_FORMAT_STRING
        "image"             MPV_FORMAT_FLAG
        "albumart"          MPV_FORMAT_FLAG
        "default"           MPV_FORMAT_FLAG
        "forced"            MPV_FORMAT_FLAG
        "dependent"         MPV_FORMAT_FLAG
        "visual-impaired"   MPV_FORMAT_FLAG
        "hearing-impaired"  MPV_FORMAT_FLAG
        "hls-bitrate"       MPV_FORMAT_INT64
        "program-id"        MPV_FORMAT_INT64
        "selected"          MPV_FORMAT_FLAG
        "main-selection"    MPV_FORMAT_INT64
        "external"          MPV_FORMAT_FLAG
        "external-filename" MPV_FORMAT_STRING
        "codec"             MPV_FORMAT_STRING
        "codec-desc"        MPV_FORMAT_STRING
        "codec-profile"     MPV_FORMAT_STRING
        "ff-index"          MPV_FORMAT_INT64
        "decoder"           MPV_FORMAT_STRING
        "decoder-desc"      MPV_FORMAT_STRING
        "demux-w"           MPV_FORMAT_INT64
        "demux-h"           MPV_FORMAT_INT64
        "demux-crop-x"      MPV_FORMAT_INT64
        "demux-crop-y"      MPV_FORMAT_INT64
        "demux-crop-w"      MPV_FORMAT_INT64
        "demux-crop-h"      MPV_FORMAT_INT64
        "demux-channel-count" MPV_FORMAT_INT64
        "demux-channels"    MPV_FORMAT_STRING
        "demux-samplerate"  MPV_FORMAT_INT64
        "demux-fps"         MPV_FORMAT_DOUBLE
        "demux-bitrate"     MPV_FORMAT_INT64
        "demux-rotation"    MPV_FORMAT_INT64
        "demux-par"         MPV_FORMAT_DOUBLE
        "format-name"       MPV_FORMAT_STRING
        "audio-channels"    MPV_FORMAT_INT64
        "replaygain-track-peak" MPV_FORMAT_DOUBLE
        "replaygain-track-gain" MPV_FORMAT_DOUBLE
        "replaygain-album-peak" MPV_FORMAT_DOUBLE
        "replaygain-album-gain" MPV_FORMAT_DOUBLE
        "dolby-vision-profile" MPV_FORMAT_INT64
        "dolby-vision-level" MPV_FORMAT_INT64

current-tracks/...

This gives access to currently selected tracks. It redirects to the correct entry in track-list.

The following sub-entries are defined: video, audio, sub, sub2

For example, current-tracks/audio/lang returns the current audio track's language field (the same value as track-list/N/lang).

If tracks of the requested type are selected via --lavfi-complex, the first one is returned.

chapter-list (RW)

List of chapters, current entry marked.

This has a number of sub-properties. Replace N with the 0-based chapter index.

chapter-list/count: Number of chapters.
chapter-list/N/title: Chapter title as stored in the file. Not always available.
chapter-list/N/time: Chapter start time in seconds as float.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each chapter)
        "title" MPV_FORMAT_STRING
        "time"  MPV_FORMAT_DOUBLE

af, vf (RW)

See --vf/--af and the vf/af command.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each filter entry)
        "name"      MPV_FORMAT_STRING
        "label"     MPV_FORMAT_STRING [optional]
        "enabled"   MPV_FORMAT_FLAG [optional]
        "params"    MPV_FORMAT_NODE_MAP [optional]
            "key"   MPV_FORMAT_STRING
            "value" MPV_FORMAT_STRING

It's also possible to write the property using this format.

seekable

Whether it's generally possible to seek in the current file.

partially-seekable

Whether the current file is considered seekable, but only because the cache is active. This means small relative seeks may be fine, but larger seeks may fail anyway. Whether a seek will succeed or not is generally not known in advance.

If this property returns yes/true, so will seekable.

playback-abort

Whether playback is stopped or is to be stopped. (Useful in obscure situations like during on_load hook processing, when the user can stop playback, but the script has to explicitly end processing.)

cursor-autohide (RW)

See --cursor-autohide. Setting this to a new value will always update the cursor, and reset the internal timer.

term-clip-cc

Inserts the symbol to force line truncation to the current terminal width. This can be used for show-text and other OSD messages. It must be the first character in the line. It takes effect until the end of the line.

osd-sym-cc

Inserts the current OSD symbol as opaque OSD control code (cc). This makes sense only with the show-text command or options which set OSD messages. The control code is implementation specific and is useless for anything else.

osd-ass-cc

${osd-ass-cc/0} disables escaping ASS sequences of text in OSD, ${osd-ass-cc/1} enables it again. By default, ASS sequences are escaped to avoid accidental formatting, and this property can disable this behavior. Note that the properties return an opaque OSD control code, which only makes sense for the show-text command or options which set OSD messages.

Example

--osd-msg3='This is ${osd-ass-cc/0}{\\b1}bold text'
show-text "This is ${osd-ass-cc/0}{\\b1}bold text"

Any ASS override tags as understood by libass can be used.

Note that you need to escape the \ character, because the string is processed for C escape sequences before passing it to the OSD code. See Flat command syntax for details.

A list of tags can be found here: https://aegisub.org/docs/latest/ass_tags/

vo-configured

Whether the VO is configured right now. Usually this corresponds to whether the video window is visible. If the --force-window option is used, this usually always returns yes/true.

vo-passes

Contains introspection about the VO's active render passes and their execution times. Not implemented by all VOs.

This is further subdivided into two frame types, vo-passes/fresh for fresh frames (which have to be uploaded, scaled, etc.) and vo-passes/redraw for redrawn frames (which only have to be re-painted). The number of passes for any given subtype can change from frame to frame, and should not be relied upon.

Each frame type has a number of further sub-properties. Replace TYPE with the frame type, N with the 0-based pass index, and M with the 0-based sample index.

vo-passes/TYPE/count: Number of passes.
vo-passes/TYPE/N/desc: Human-friendy description of the pass.
vo-passes/TYPE/N/last: Last measured execution time, in nanoseconds.
vo-passes/TYPE/N/avg: Average execution time of this pass, in nanoseconds. The exact timeframe varies, but it should generally be a handful of seconds.
vo-passes/TYPE/N/peak: The peak execution time (highest value) within this averaging range, in nanoseconds.
vo-passes/TYPE/N/count: The number of samples for this pass.
vo-passes/TYPE/N/samples/M: The raw execution time of a specific sample for this pass, in nanoseconds.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_MAP
"TYPE" MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP
        "desc"    MPV_FORMAT_STRING
        "last"    MPV_FORMAT_INT64
        "avg"     MPV_FORMAT_INT64
        "peak"    MPV_FORMAT_INT64
        "count"   MPV_FORMAT_INT64
        "samples" MPV_FORMAT_NODE_ARRAY
             MP_FORMAT_INT64

Note that directly accessing this structure via subkeys is not supported, the only access is through aforementioned MPV_FORMAT_NODE.

perf-info

Further performance data. Querying this property triggers internal collection of some data, and may slow down the player. Each query will reset some internal state. Property change notification doesn't and won't work. All of this may change in the future, so don't use this. The builtin stats script is supposed to be the only user; since it's bundled and built with the source code, it can use knowledge of mpv internal to render the information properly. See stats script description for some details.

video-bitrate, audio-bitrate, sub-bitrate

Bitrate values calculated on the packet level. This works by dividing the bit size of all packets between two keyframes by their presentation timestamp distance. (This uses the timestamps are stored in the file, so e.g. playback speed does not influence the returned values.) In particular, the video bitrate will update only per keyframe, and show the "past" bitrate. To make the property more UI friendly, updates to these properties are throttled in a certain way.

The unit is bits per second. OSD formatting turns these values in kilobits (or megabits, if appropriate), which can be prevented by using the raw property value, e.g. with ${=video-bitrate}.

Note that the accuracy of these properties is influenced by a few factors. If the underlying demuxer rewrites the packets on demuxing (done for some file formats), the bitrate might be slightly off. If timestamps are bad or jittery (like in Matroska), even constant bitrate streams might show fluctuating bitrate.

How exactly these values are calculated might change in the future.

In earlier versions of mpv, these properties returned a static (but bad) guess using a completely different method.

audio-device-list

The list of discovered audio devices. This is mostly for use with the client API, and reflects what --audio-device=help with the command line player returns.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each device entry)
        "name"          MPV_FORMAT_STRING
        "description"   MPV_FORMAT_STRING

The name is what is to be passed to the --audio-device option (and often a rather cryptic audio API-specific ID), while description is human readable free form text. The description is set to the device name (minus mpv-specific <driver>/ prefix) if no description is available or the description would have been an empty string.

The special entry with the name set to auto selects the default audio output driver and the default device.

The property can be watched with the property observation mechanism in the client API and in Lua scripts. (Technically, change notification is enabled the first time this property is read.)

audio-device (RW)

Set the audio device. This directly reads/writes the --audio-device option, but on write accesses, the audio output will be scheduled for reloading.

Writing this property while no audio output is active will not automatically enable audio. (This is also true in the case when audio was disabled due to reinitialization failure after a previous write access to audio-device.)

This property also doesn't tell you which audio device is actually in use.

How these details are handled may change in the future.

current-vo

Current video output driver (name as used with --vo).

current-gpu-context

Current GPU context of video output driver (name as used with --gpu-context). Valid for --vo=gpu and --vo=gpu-next.

current-ao

Current audio output driver (name as used with --ao).

user-data (RW)

This is a recursive key/value map of arbitrary nodes shared between clients for general use (i.e. scripts, IPC clients, host applications, etc). The player itself does not use any data in it (although some builtin scripts may). The property is not preserved across player restarts.

The following sub-paths are reserved for internal uses or have special semantics: user-data/osc, user-data/mpv. Unless noted otherwise, the semantics of any properties under these sub-paths can change at any time and may not be relied upon, and writing to these properties may prevent builtin scripts from working properly.

Currently, the following properties have defined special semantics:

user-data/osc/margins: This property is written by an OSC implementation to indicate the margins that it occupies. Its sub-properties l, r, t, and b should all be set to the left, right, top, and bottom margins respectively. Values are between 0.0 and 1.0, normalized to window width/height.

Sub-paths can be accessed directly; e.g. user-data/my-script/state/a can be read, written, or observed.

The top-level object itself cannot be written directly; write to sub-paths instead.

Converting this property or its sub-properties to strings will give a JSON representation. If converting a leaf-level object (i.e. not a map or array) and not using raw mode, the underlying content will be given (e.g. strings will be printed directly, rather than quoted and JSON-escaped).

user-data/mpv/ytdl

Data shared by the builtin ytdl hook script.

user-data/mpv/ytdl/path: Path to the ytdl executable, if found, or an empty string otherwise. The property is not set until the script attempts to find the ytdl executable, i.e. until an URL is being loaded by the script.
user-data/mpv/ytdl/json-subprocess-result: Result of executing ytdl to retrieve the JSON data of the URL being loaded. The format is the same as subprocess's result, capturing stdout and stderr.

menu-data (RW)

This property stores the raw menu definition. See `Context Menu`_ section for details.

type: Menu item type. Can be: separator, submenu, or empty.
title: Menu item title. Required if type is not separator.
cmd: Command to execute when the menu item is clicked.
shortcut: Menu item shortcut key which appears to the right of the menu item. A shortcut key does not have to be functional; it's just a visual hint.
state: Menu item state. Can be: checked, disabled, hidden, or empty.
submenu: Submenu items, which is required if type is submenu.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (menu item)
        "type"           MPV_FORMAT_STRING
        "title"          MPV_FORMAT_STRING
        "cmd"            MPV_FORMAT_STRING
        "shortcut"       MPV_FORMAT_STRING
        "state"          MPV_FORMAT_NODE_ARRAY[MPV_FORMAT_STRING]
        "submenu"        MPV_FORMAT_NODE_ARRAY[menu item]

Writing to this property with the client API using MPV_FORMAT_NODE or with Lua mp.set_property_native will trigger an immediate update of the menu if mpv video output is currently active. You may observe the current-vo property to check if this is the case.

working-directory

The working directory of the mpv process. Can be useful for JSON IPC users, because the command line player usually works with relative paths.

protocol-list

List of protocol prefixes potentially recognized by the player. They are returned without trailing :// suffix (which is still always required). In some cases, the protocol will not actually be supported (consider https if ffmpeg is not compiled with TLS support).

decoder-list

List of decoders supported. This lists decoders which can be passed to --vd and --ad.

codec: Canonical codec name, which identifies the format the decoder can handle.
driver: The name of the decoder itself. Often, this is the same as codec. Sometimes it can be different. It is used to distinguish multiple decoders for the same codec.
description: Human readable description of the decoder and codec.

When querying the property with the client API using MPV_FORMAT_NODE, or with Lua mp.get_property_native, this will return a mpv_node with the following contents:

MPV_FORMAT_NODE_ARRAY
    MPV_FORMAT_NODE_MAP (for each decoder entry)
        "codec"         MPV_FORMAT_STRING
        "driver"        MPV_FORMAT_STRING
        "description"   MPV_FORMAT_STRING

encoder-list

List of libavcodec encoders. This has the same format as decoder-list. The encoder names (driver entries) can be passed to --ovc and --oac (without the lavc: prefix required by --vd and --ad).

demuxer-lavf-list

List of available libavformat demuxers' names. This can be used to check for support for a specific format or use with --demuxer-lavf-format.

input-key-list

List of Key names, same as output by --input-keylist.

mpv-version

The mpv version/copyright string. Depending on how the binary was built, it might contain either a release version, or just a git hash.

mpv-configuration

The configuration arguments that were passed to the build system. If the meson version used to compile mpv is older than 1.1.0, then a hardcoded string of a few, arbitrary options is displayed instead.

ffmpeg-version

The contents of the av_version_info() API call. This is a string which identifies the build in some way, either through a release version number, or a git hash. This property is unavailable if mpv is linked against older FFmpeg versions.

libass-version

The value of ass_library_version(). This is an integer, encoded in a somewhat weird form (apparently "hex BCD"), indicating the release version of the libass library linked to mpv.

platform

Returns a string describing what target platform mpv was built for. The value of this is dependent on what the underlying build system detects. Some of the most common values are: windows, darwin (macos or ios), linux, android, and freebsd. Note that this is not a complete listing.

options/<name> (RW)

The value of option --<name>. Most options can be changed at runtime by writing to this property. Note that many options require reloading the file for changes to take effect. If there is an equivalent property, prefer setting the property instead.

There shouldn't be any reason to access options/<name> instead of <name>, except in situations in which the properties have different behavior or conflicting semantics.

file-local-options/<name> (RW)

Similar to options/<name>, but when setting an option through this property, the option is reset to its old value once the current file has stopped playing. Trying to write an option while no file is playing (or is being loaded) results in an error.

(Note that if an option is marked as file-local, even options/ will access the local value, and the old value, which will be restored on end of playback, cannot be read or written until end of playback.)

option-info/<name>

Additional per-option information.

This has a number of sub-properties. Replace <name> with the name of a top-level option. No guarantee of stability is given to any of these sub-properties - they may change radically in the feature.

option-info/<name>/name: The name of the option.
option-info/<name>/type: The name of the option type, like String or Integer. For many complex types, this isn't very accurate.
option-info/<name>/set-from-commandline: Whether the option was set from the mpv command line. What this is set to if the option is e.g. changed at runtime is left undefined (meaning it could change in the future).
option-info/<name>/set-locally: Whether the option was set per-file. This is the case with automatically loaded profiles, file-dir configs, and other cases. It means the option value will be restored to the value before playback start when playback ends.
option-info/<name>/expects-file: Whether the option takes file paths as arguments.
option-info/<name>/default-value: The default value of the option. May not always be available.
option-info/<name>/min, option-info/<name>/max: Integer minimum and maximum values allowed for the option. Only available if the options are numeric, and the minimum/maximum has been set internally. It's also possible that only one of these is set.
option-info/<name>/choices: If the option is a choice option, the possible choices. Choices that are integers may or may not be included (they can be implied by min and max). Note that options which behave like choice options, but are not actual choice options internally, may not have this info available.

property-list

The list of top-level properties.

profile-list

The list of profiles and their contents. This is highly implementation-specific, and may change any time. Currently, it returns an array of options for each profile. Each option has a name and a value, with the value currently always being a string. Note that the options array is not a map, as order matters and duplicate entries are possible. Recursive profiles are not expanded, and show up as special profile options.

The profile-restore field is currently missing if it holds the default value (either because it was not set, or set explicitly to default), but in the future it might hold the value default.

command-list

The list of input commands. This returns an array of maps, where each map node represents a command. This map currently only has a single entry: name for the name of the command. (This property is supposed to be a replacement for --input-cmdlist. The option dumps some more information, but it's a valid feature request to extend this property if needed.)

input-bindings

The list of current input key bindings. This returns an array of maps, where each map node represents a binding for a single key/command. This map has the following entries:

key: The key name. This is normalized and may look slightly different from how it was specified in the source (e.g. in input.conf).
cmd: The command mapped to the key. (Currently, this is exactly the same string as specified in the source, other than stripping whitespace and comments. It's possible that it will be normalized in the future.)
is_weak: If set to true, any existing and active user bindings will take priority.
owner: If this entry exists, the name of the script (or similar) which added this binding.
section: Name of the section this binding is part of. This is a rarely used mechanism. This entry may be removed or change meaning in the future.
priority: A number. Bindings with a higher value are preferred over bindings with a lower value. If the value is negative, this binding is inactive and will not be triggered by input. Note that mpv does not use this value internally, and matching of bindings may work slightly differently in some cases. In addition, this value is dynamic and can change around at runtime.
comment: If available, the comment following the command on the same line. (For example, the input.conf entry f cycle bla # toggle bla would result in an entry with comment = "toggle bla", cmd = "cycle bla".)

This property is read-only, and change notification is not supported.

Inconsistencies between options and properties

You can access (almost) all options as properties, though there are some caveats with some properties (due to historical reasons):

vid, aid, sid

While playback is active, these return the actually active tracks. For example, if you set aid=5, and the currently played file contains no audio track with ID 5, the aid property will return no.

Before mpv 0.31.0, you could set existing tracks at runtime only.

display-fps

This inconsistent behavior is deprecated. Post-deprecation, the reported value and the option value are cleanly separated (override-display-fps for the option value).

vf, af

If you set the properties during playback, and the filter chain fails to reinitialize, the option will be set, but the runtime filter chain does not change. On the other hand, the next video to be played will fail, because the initial filter chain cannot be created.

This behavior changed in mpv 0.31.0. Before this, the new value was rejected iff a video (for vf) or an audio (for af) track was active. If playback was not active, the behavior was the same as the current one.

playlist

The property is read-only and returns the current internal playlist. The option is for loading playlist during command line parsing. For client API uses, you should use the loadlist command instead.

profile, include

These are write-only, and will perform actions as they are written to, exactly as if they were used on the mpv CLI commandline. Their only use is when using libmpv before mpv_initialize(), which in turn is probably only useful in encoding mode. Normal libmpv users should use other mechanisms, such as the apply-profile command, and the mpv_load_config_file API function. Avoid these properties.

Property Expansion

All string arguments to input commands as well as certain options (like --term-playing-msg) are subject to property expansion. Note that property expansion does not work in places where e.g. numeric parameters are expected. (For example, the add command does not do property expansion. The set command is an exception and not a general rule.)

Example for input.conf

i show-text "Filename: ${filename}": shows the filename of the current file when pressing the i key

Whether property expansion is enabled by default depends on which API is used (see Flat command syntax, Commands specified as arrays and Named arguments), but it can always be enabled with the expand-properties prefix or disabled with the raw prefix, as described in Input Command Prefixes.

The following expansions are supported:

${NAME}: Expands to the value of the property NAME. If retrieving the property fails, expand to an error string. (Use ${NAME:} with a trailing : to expand to an empty string instead.) If NAME is prefixed with =, expand to the raw value of the property (see section below).
${NAME:STR}: Expands to the value of the property NAME, or STR if the property cannot be retrieved. STR is expanded recursively.
${?NAME:STR}: Expands to STR (recursively) if the property NAME is available.
${!NAME:STR}: Expands to STR (recursively) if the property NAME cannot be retrieved.
${?NAME==VALUE:STR}: Expands to STR (recursively) if the property NAME expands to a string equal to VALUE. You can prefix NAME with = in order to compare the raw value of a property (see section below). If the property is unavailable, or other errors happen when retrieving it, the value is never considered equal. Note that VALUE can't contain any of the characters : or }. Also, it is possible that escaping with " or % might be added in the future, should the need arise.
${!NAME==VALUE:STR}: Same as with the ? variant, but STR is expanded if the value is not equal. (Using the same semantics as with ?.)
$$: Expands to $.
$}: Expands to }. (To produce this character inside recursive expansion.)
$>: Disable property expansion and special handling of $ for the rest of the string.

In places where property expansion is allowed, C-style escapes are often accepted as well. Example:

\n becomes a newline character

\\ expands to \

Raw and Formatted Properties

Normally, properties are formatted as human-readable text, meant to be displayed on OSD or on the terminal. It is possible to retrieve an unformatted (raw) value from a property by prefixing its name with =. These raw values can be parsed by other programs and follow the same conventions as the options associated with the properties. Additionally, there is a > prefix to format human-readable text, with fixed precision for floating-point values. This is useful for printing values where a constant width is important.

Examples

${time-pos} expands to 00:14:23 (if playback position is at 14 minutes 23 seconds)
${=time-pos} expands to 863.4 (same time, plus 400 milliseconds - milliseconds are normally not shown in the formatted case)
${avsync} expands to +0.003
${>avsync} expands to +0.0030
${=avsync} expands to 0.003028

Sometimes, the difference in amount of information carried by raw and formatted property values can be rather big. In some cases, raw values have more information, like higher precision than seconds with time-pos. Sometimes it is the other way around, e.g. aid shows track title and language in the formatted case, but only the track number if it is raw.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

input.rst

input.rst

COMMAND INTERFACE

input.conf

input.conf syntax

Key names

Flat command syntax

Commands specified as arrays

Named arguments

List of Input Commands

Playback Control

Property Manipulation

Playlist Manipulation

Track Manipulation

Text Manipulation

Configuration Commands

OSD Commands

Input and Keybind Commands

Execution Commands

Scripting Commands

Screenshot Commands

Filter Commands

Miscellaneous Commands

List of events

Hooks

Input Command Prefixes

Synchronous vs. Asynchronous

Asynchronous command details

Input Sections

Properties

Property list

Inconsistencies between options and properties

Property Expansion

Raw and Formatted Properties

Files

input.rst

Latest commit

History

input.rst

File metadata and controls

COMMAND INTERFACE

input.conf

input.conf syntax

Key names

Flat command syntax

Commands specified as arrays

Named arguments

List of Input Commands

Playback Control

Property Manipulation

Playlist Manipulation

Track Manipulation

Text Manipulation

Configuration Commands

OSD Commands

Input and Keybind Commands

Execution Commands

Scripting Commands

Screenshot Commands

Filter Commands

Miscellaneous Commands

List of events

Hooks

Input Command Prefixes

Synchronous vs. Asynchronous

Asynchronous command details

Input Sections

Properties

Property list

Inconsistencies between options and properties

Property Expansion

Raw and Formatted Properties