neulab/tldr huggingface dataset:
Don't forget to set the playback_only field if you want the command run while the player is in idle mode, or if you don't want that end of playback kills the command.
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.
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> Select the subtitle immediately (default).
<auto> Don't select the subtitle. (Or in some special situations, let the default stream selection mechanism decide.)
<cached> 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.
sub-seek <skip> <flags> Seek to the next (skip set to 1) or the previous (skip set to -1) subtitle.  This is similar to sub-step, except that it seeks video and audio instead of adjusting the subtitle delay.
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.
print-text <text> Print text to stdout. The string can contain properties (see Property Expansion). Take care to put the argument in quotes.
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.
<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).
expand-text <string> 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 <string> 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.
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.
show-progress Show the progress bar, the elapsed time and the total duration of the file on the OSD.
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.
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.
mouse <x> <y> [<button> [<mode>]] Send a mouse event with given coordinate (<x>, <y>).
<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> 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. 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> <command> Binds a key to an input command. command must be a complete command containing all the desired arguments and flags. Both name and command use the input.conf naming scheme. This is primarily useful for the client API.
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.
Input Commands that are Possibly Subject to Change 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.
<del>  Remove the given filters from the video chain. Unlike in the other cases, the second parameter is a comma separated list of filter names or integer indexes. 0 would denote the first filter. Negative indexes start from the last filter, and -1 denotes the last filter. Deprecated, use remove.
<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.
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).
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.
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.
overlay-add <id> <x> <y> <file> <offset> <fmt> <w> <h> <stride> 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.
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.)
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 commend 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.
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).
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 _.
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:
1. The string key-binding.
2. The name of the binding (as established above).
3. The key state as string (see below).
4. The key name (since mpv 0.15.0).
5. 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 2 characters:
1. 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).
2. Whether the event originates from the mouse, either m (mouse button) or - (something else).
Future versions can add more arguments and more key state characters to support more input peculiarities.
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.
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.
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.
vf-command <label> <command> <argument> Send a command to the filter with the given <label>. Use all to send it to all filters at once. The command and argument string is filter specific. Currently, this only works with the lavfi filter - see the libavfilter documentation for which commands a filter supports.
Note that the <label> is a mpv filter label, not a libavfilter filter name.
af-command <label> <command> <argument> Same as vf-command, but for audio filters.
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-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.
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.
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.
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 reencode 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-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.
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 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.
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.
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.
name   The name of the property.
data   The new value of the property.
The following events also happen, but are deprecated: tracks-changed, track-switched, pause, unpause, metadata-update, idle, tick, chapter-change. 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).
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.)
The property name is annotated with RW to indicate whether the property is generally writable.
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.
Property list NOTE: Most options can be set as 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 working-directory property.
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.)
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.
drop-frame-count is a deprecated alias.
frame-drop-count Frames dropped by VO (when using --framedrop=vo).
vo-drop-frame-count is a deprecated alias.
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.