neulab/tldr huggingface dataset:
<primaries> RGB primaries the source file was encoded with. Normally this should be set in the file header, but when playing broken or mistagged files this can be used to override the setting.
This option only affects video output drivers that perform color management, for example gpu with the target-prim or icc-profile suboptions set.
If this option is set to auto (which is the default), the video's primaries flag will be used. If that flag is unset, the color space will be selected automatically, using the following heuristics: If the <colormatrix> is set or determined as BT.2020 or BT.709, the corresponding primaries are used. Otherwise, if the video height is exactly 576 (PAL), BT.601-625 is used. If it's exactly 480 or 486 (NTSC), BT.601-525 is used. If the video resolution is anything else, BT.709 is used.
Available primaries are:
bt.601-525 ITU-R BT.601 (SD) 525-line systems (NTSC, SMPTE-C)
bt.601-625 ITU-R BT.601 (SD) 625-line systems (PAL, SECAM)
bt.709 ITU-R BT.709 (HD) (same primaries as sRGB)
cie1931 CIE 1931 RGB
dci-p3 DCI-P3 (Digital Cinema)
v-gamut Panasonic V-Gamut primaries
<gamma> Gamma function the source file was encoded with. Normally this should be set in the file header, but when playing broken or mistagged files this can be used to override the setting.
This option only affects video output drivers that perform color management.
If this option is set to auto (which is the default), the gamma will be set to BT.1886 for YCbCr content, sRGB for RGB content and Linear for XYZ content.
Available gamma functions are:
bt.1886 ITU-R BT.1886 (EOTF corresponding to BT.601/BT.709/BT.2020)
linear Linear light
gamma1.8 Pure power curve (gamma 1.8)
gamma2.8 Pure power curve (gamma 2.8)
prophoto ProPhoto RGB (ROMM) curve
pq     ITU-R BT.2100 PQ (Perceptual quantizer) curve
hlg    ITU-R BT.2100 HLG (Hybrid Log-gamma) curve
v-log  Panasonic V-Log transfer curve
s-log1 Sony S-Log1 transfer curve
s-log2 Sony S-Log2 transfer curve
<sig-peak> Reference peak illumination for the video file, relative to the signal's reference white level. This is mostly interesting for HDR, but it can also be used tone map SDR content to simulate a different exposure. Normally inferred from tags such as MaxCLL or mastering metadata.
The default of 0.0 will default to the source's nominal peak luminance.
<light> Light type of the scene. This is mostly correctly inferred based on the gamma function, but it can be useful to override this when viewing raw camera footage (e.g. V-Log), which is normally scene-referred instead of display-referred.
Available light types are:
auto   Automatic selection (default)
display Display-referred light (most content)
hlg    Scene-referred using the HLG OOTF (e.g. HLG content)
709-1886 Scene-referred using the BT709+BT1886 interaction
gamma1.2 Scene-referred using a pure power OOTF (gamma=1.2)
<stereo-in> Set the stereo mode the video is assumed to be encoded in. Use --vf=format:stereo-in=help to list all available modes. Check with the stereo3d filter documentation to see what the names mean.
<stereo-out> Set the stereo mode the video should be displayed as. Takes the same values as the stereo-in option.
<rotate> Set the rotation the video is assumed to be encoded with in degrees.  The special value -1 uses the input format.
<w>, <h> If not 0, perform conversion to the given size. Ignored if convert=yes is not set.
<dw>, <dh> Set the display size. Note that setting the display size such that the video is scaled in both directions instead of just changing the aspect ratio is an implementation detail, and might change later.
<dar>  Set the display aspect ratio of the video frame. This is a float, but values such as [16:9] can be passed too ([...] for quoting to prevent the option parser from interpreting the : character).
<force-scaler=auto|zimg|sws> Force a specific scaler backend, if applicable. This is a debug option and could go away any time.
<alpha=auto|straight|premul> Set the kind of alpha the video uses. Undefined effect if the image format has no alpha channel (could be ignored or cause an error, depending on how mpv internals evolve). Setting this may or may not cause downstream image processing to treat alpha differently, depending on support. With convert and zimg used, this will convert the alpha.  libswscale and other FFmpeg components completely ignore this.
lavfi=graph[:sws-flags[:o=opts]] Filter video using FFmpeg's libavfilter.
<graph> The libavfilter graph string. The filter must have a single video input pad and a single video output pad.
See https://ffmpeg.org/ffmpeg-filters.html for syntax and available filters.
WARNING: If you want to use the full filter syntax with this option, you have to quote the filter graph in order to prevent mpv's syntax and the filter graph syntax from clashing. To prevent a quoting and escaping mess, consider using --lavfi-complex if you know which video track you want to use from the input file. (There is only one video track for nearly all video files anyway.)
--vf=lavfi=[gradfun=20:30,vflip] gradfun filter with nonsense parameters, followed by a vflip filter. (This demonstrates how libavfilter takes a graph and not just a single filter.) The filter graph string is quoted with [ and ]. This requires no additional quoting or escaping with some shells (like bash), while others (like zsh) require additional " quotes around the option string.
'--vf=lavfi="gradfun=20:30,vflip"' Same as before, but uses quoting that should be safe with all shells. The outer ' quotes make sure that the shell does not remove the " quotes needed by mpv.
'--vf=lavfi=graph="gradfun=radius=30:strength=20,vflip"' Same as before, but uses named parameters for everything.
<sws-flags> If libavfilter inserts filters for pixel format conversion, this option gives the flags which should be passed to libswscale. This option is numeric and takes a bit-wise combination of SWS_ flags.
See https://git.videolan.org/?p=ffmpeg.git;a=blob;f=libswscale/swscale.h.
<o>    Set AVFilterGraph options. These should be documented by FFmpeg.
'--vf=lavfi=yadif:o="threads=2,thread_type=slice"' forces a specific threading configuration.
sub=[=bottom-margin:top-margin] Moves subtitle rendering to an arbitrary point in the filter chain, or force subtitle rendering in the video filter as opposed to using video output OSD support.
<bottom-margin> Adds a black band at the bottom of the frame. The SSA/ASS renderer can place subtitles there (with --sub-use-margins).
<top-margin> Black band on the top for toptitles  (with --sub-use-margins).
--vf=sub,eq Moves sub rendering before the eq filter. This will put both subtitle colors and video under the influence of the video equalizer settings.
vapoursynth=file:buffered-frames:concurrent-frames Loads a VapourSynth filter script. This is intended for streamed processing: mpv actually provides a source filter, instead of using a native VapourSynth video source. The mpv source will answer frame requests only within a small window of frames (the size of this window is controlled with the buffered-frames parameter), and requests outside of that will return errors. As such, you can't use the full power of VapourSynth, but you can use certain filters.
WARNING: Do not use this filter, unless you have expert knowledge in VapourSynth, and know how to fix bugs in the mpv VapourSynth wrapper code.
If you just want to play video generated by VapourSynth (i.e. using a native VapourSynth video source), it's better to use vspipe and a pipe or FIFO to feed the video to mpv. The same applies if the filter script requires random frame access (see buffered-frames parameter).
file   Filename of the script source. Currently, this is always a python script (.vpy in VapourSynth convention).
The variable video_in is set to the mpv video source, and it is expected that the script reads video from it. (Otherwise, mpv will decode no video, and the video packet queue will overflow, eventually leading to only audio playing, or worse.)
The filter graph created by the script is also expected to pass through timestamps using the _DurationNum and _DurationDen frame properties.
See the end of the option list for a full list of script variables defined by mpv.
import vapoursynth as vs core = vs.get_core() core.std.AddBorders(video_in, 10, 10, 20, 20).set_output()
WARNING: The script will be reloaded on every seek. This is done to reset the filter properly on discontinuities.
buffered-frames Maximum number of decoded video frames that should be buffered before the filter (default: 4). This specifies the maximum number of frames the script can request in backward direction.
E.g. if buffered-frames=5, and the script just requested frame 15, it can still request frame 10, but frame 9 is not available anymore.  If it requests frame 30, mpv will decode 15 more frames, and keep only frames 25-30.
The only reason why this buffer exists is to serve the random access requests the VapourSynth filter can make.
The VapourSynth API has a getFrameAsync function, which takes an absolute frame number. Source filters must respond to all requests. For example, a source filter can request frame 2432, and then frame 3.  Source filters  typically implement this by pre-indexing the entire file.
mpv on the other hand is stream oriented, and does not allow filters to seek. (And it would not make sense to allow it, because it would ruin performance.) Filters get frames sequentially in playback direction, and cannot request them out of order.
To compensate for this mismatch, mpv allows the filter to access frames within a certain window. buffered-frames controls the size of this window. Most VapourSynth filters happen to work with this, because mpv requests frames sequentially increasing from it, and most filters only require frames "close" to the requested frame.
If the filter requests a frame that has a higher frame number than the highest buffered frame, new frames will be decoded until the requested frame number is reached. Excessive frames will be flushed out in a FIFO manner (there are only at most buffered-frames in this buffer).
If the filter requests a frame that has a lower frame number than the lowest buffered frame, the request cannot be satisfied, and an error is returned to the filter. This kind of error is not supposed to happen in a "proper" VapourSynth environment. What exactly happens depends on the filters involved.
Increasing this buffer will not improve performance. Rather, it will waste memory, and slow down seeks (when enough frames to fill the buffer need to be decoded at once). It is only needed to prevent the error described in the previous paragraph.
How many frames a filter requires depends on filter implementation details, and mpv has no way of knowing. A scale filter might need only 1 frame, an interpolation filter may require a small number of frames, and the Reverse filter will require an infinite number of frames.
If you want reliable operation to the full extend VapourSynth is capable, use vspipe.
The actual number of buffered frames also depends on the value of the concurrent-frames option. Currently, both option values are multiplied to get the final buffer size.
concurrent-frames Number of frames that should be requested in parallel. The level of concurrency depends on the filter and how quickly mpv can decode video to feed the filter. This value should probably be proportional to the number of cores on your machine. Most time, making it higher than the number of cores can actually make it slower.
Technically, mpv will call the VapourSynth getFrameAsync function in a loop, until there are concurrent-frames frames that have not been returned by the filter yet. This also assumes that the rest of the mpv filter chain reads the output of the vapoursynth filter quickly enough. (For example, if you pause the player, filtering will stop very soon, because the filtered frames are waiting in a queue.)
Actual concurrency depends on many other factors.
By default, this uses the special value auto, which sets the option to the number of detected logical CPU cores.
The following .vpy script variables are defined by mpv:
video_in The mpv video source as vapoursynth clip. Note that this has an incorrect (very high) length set, which confuses many filters. This is necessary, because the true number of frames is unknown. You can use the Trim filter on the clip to reduce the length.
video_in_dw, video_in_dh Display size of the video. Can be different from video size if the video does not use square pixels (e.g. DVD).
container_fps FPS value as reported by file headers. This value can be wrong or completely broken (e.g. 0 or NaN). Even if the value is correct, if another filter changes the real FPS (by dropping or inserting frames), the value of this variable will not be useful. Note that the --fps command line option overrides this value.
Useful for some filters which insist on having a FPS.
display_fps Refresh rate of the current display. Note that this value can be 0.
vavpp  VA-API video post processing. Requires the system to support VA-API, i.e. Linux/BSD only. Works with --vo=vaapi and --vo=gpu only.  Currently deinterlaces. This filter is automatically inserted if deinterlacing is requested (either using the d key, by default mapped to the command cycle deinterlace, or the --deinterlace option).
deint=<method> Select the deinterlacing algorithm.
no     Don't perform deinterlacing.
auto   Select the best quality deinterlacing algorithm (default). This goes by the order of the options as documented, with motion-compensated being considered best quality.
bob    bob deinterlacing.
weave, motion-adaptive, motion-compensated Advanced deinterlacing algorithms. Whether these actually work depends on the GPU hardware, the GPU drivers, driver bugs, and mpv bugs.
<interlaced-only>
no     Deinterlace all frames (default).
yes    Only deinterlace frames marked as interlaced.
reversal-bug=<yes|no>
no     Use the API as it was interpreted by older Mesa drivers. While this interpretation was more obvious and intuitive, it was apparently wrong, and not shared by Intel driver developers.
yes    Use Intel interpretation of surface forward and backwards references (default). This is what Intel drivers and newer Mesa drivers expect. Matters only for the advanced deinterlacing algorithms.
vdpaupp VDPAU video post processing. Works with --vo=vdpau and --vo=gpu only. This filter is automatically inserted if deinterlacing is requested (either using the d key, by default mapped to the command cycle deinterlace, or the --deinterlace option). When enabling deinterlacing, it is always preferred over software deinterlacer filters if the vdpau VO is used, and also if gpu is used and hardware decoding was activated at least once (i.e. vdpau was loaded).
sharpen=<-1-1> For positive values, apply a sharpening algorithm to the video, for negative values a blurring algorithm (default: 0).
denoise=<0-1> Apply a noise reduction algorithm to the video (default: 0; no noise reduction).
deint=<yes|no> Whether deinterlacing is enabled (default: no). If enabled, it will use the mode selected with deint-mode.
deint-mode=<first-field|bob|temporal|temporal-spatial> Select deinterlacing mode (default: temporal).
Note that there's currently a mechanism that allows the vdpau VO to change the deint-mode of auto-inserted vdpaupp filters. To avoid confusion, it's recommended not to use the --vo=vdpau suboptions related to filtering.
bob    Bob deinterlacing.
temporal Motion-adaptive temporal deinterlacing. May lead to A/V desync with slow video hardware and/or high resolution.
temporal-spatial Motion-adaptive temporal deinterlacing with edge-guided spatial interpolation. Needs fast video hardware.
chroma-deint Makes temporal deinterlacers operate both on luma and chroma (default).  Use no-chroma-deint to solely use luma and speed up advanced deinterlacing. Useful with slow video memory.
pullup Try to apply inverse telecine, needs motion adaptive temporal deinterlacing.
interlaced-only=<yes|no> If yes, only deinterlace frames marked as interlaced (default: no).
hqscaling=<0-9>
d3d11vpp Direct3D 11 video post processing. Currently requires D3D11 hardware decoding for use.
deint=<yes|no> Whether deinterlacing is enabled (default: no).
mode=<blend|bob|adaptive|mocomp|ivctc|none> Tries to select a video processor with the given processing capability.  If a video processor supports multiple capabilities, it is not clear which algorithm is actually selected. none always falls back. On most if not all hardware, this option will probably do nothing, because a video processor usually supports all modes or none.
fingerprint=... Compute video frame fingerprints and provide them as metadata. Actually, it currently barely deserved to be called fingerprint, because it does not compute "proper" fingerprints, only tiny downscaled images (but which can be used to compute image hashes or for similarity matching).
The main purpose of this filter is to support the skip-logo.lua script.  If this script is dropped, or mpv ever gains a way to load user-defined filters (other than VapourSynth), this filter will be removed. Due to the "special" nature of this filter, it will be removed without warning.
The intended way to read from the filter is using vf-metadata (also see clear-on-query filter parameter). The property will return a list of key/value pairs as follows:
fp0.pts = 1.2345 fp0.hex = 1234abcdef...bcde fp1.pts = 1.4567 fp1.hex = abcdef1234...6789 ... fpN.pts = ... fpN.hex = ... type = gray-hex-16x16
Each fp<N> entry is for a frame. The pts entry specifies the timestamp of the frame (within the filter chain; in simple cases this is the same as the display timestamp). The hex field is the hex encoded fingerprint, whose size and meaning depend on the type filter option.  The type field has the same value as the option the filter was created with.
This returns the frames that were filtered since the last query of the property. If clear-on-query=no was set, a query doesn't reset the list of frames. In both cases, a maximum of 10 frames is returned. If there are more frames, the oldest frames are discarded. Frames are returned in filter order.
(This doesn't return a structured list for the per-frame details because the internals of the vf-metadata mechanism suck. The returned format may change in the future.)
This filter uses zimg for speed and profit. However, it will fallback to libswscale in a number of situations: lesser pixel formats, unaligned data pointers or strides, or if zimg fails to initialize for unknown reasons. In these cases, the filter will use more CPU. Also, it will output different fingerprints, because libswscale cannot perform the full range expansion we normally request from zimg. As a consequence, the filter may be slower and not work correctly in random situations.
type=... What fingerprint to compute. Available types are:
gray-hex-8x8 grayscale, 8 bit, 8x8 size
gray-hex-16x16 grayscale, 8 bit, 16x16 size (default)
Both types simply remove all colors, downscale the image, concatenate all pixel values to a byte array, and convert the array to a hex string.
clear-on-query=yes|no Clear the list of frame fingerprints if the vf-metadata property for this filter is queried (default: yes). This requires some care by the user. Some types of accesses might query the filter multiple times, which leads to lost frames.
print=yes|no Print computed fingerprints to the terminal (default: no). This is mostly for testing and such. Scripts should use vf-metadata to read information from this filter instead.
gpu=... Convert video to RGB using the OpenGL renderer normally used with --vo=gpu. This requires that the EGL implementation supports off-screen rendering on the default display. (This is the case with Mesa.)
Sub-options:
w=<pixels>, h=<pixels> Size of the output in pixels (default: 0). If not positive, this will use the size of the first filtered input frame.
WARNING: This is highly experimental. Performance is bad, and it will not work everywhere in the first place. Some features are not supported.
WARNING: This does not do OSD rendering. If you see OSD, then it has been rendered by the VO backend. (Subtitles are rendered by the gpu filter, if possible.)
WARNING: If you use this with encoding mode, keep in mind that encoding mode will convert the RGB filter's output back to yuv420p in software, using the configured software scaler. Using zimg might improve this, but in any case it might go against your goals when using this filter.
WARNING: Do not use this with --vo=gpu. It will apply filtering twice, since most --vo=gpu options are unconditionally applied to the gpu filter. There is no mechanism in mpv to prevent this.
You can encode files from one format/codec to another using this facility.
--o=<filename> Enables encoding mode and specifies the output file name.
--of=<format> Specifies the output format (overrides autodetection by the file name extension of the file specified by -o). See --of=help for a full list of supported formats.
--ofopts=<options> Specifies the output format options for libavformat.  See --ofopts=help for a full list of supported options.
--ofopts-add=<option> Appends the option given as an argument to the options list. (Passing multiple options is currently still possible, but deprecated.)
--ofopts="" Completely empties the options list.
--oac=<codec> Specifies the output audio codec. See --oac=help for a full list of supported codecs.
--oaoffset=<value> Shifts audio data by the given time (in seconds) by adding/removing samples at the start. Deprecated.
--oacopts=<options> Specifies the output audio codec options for libavcodec.  See --oacopts=help for a full list of supported options.
--oac=libmp3lame --oacopts=b=128000 selects 128 kbps MP3 encoding.
--oacopts-add=<option> Appends the option given as an argument to the options list. (Passing multiple options is currently still possible, but deprecated.)
--oacopts="" Completely empties the options list.
--oafirst Force the audio stream to become the first stream in the output. By default, the order is unspecified. Deprecated.
--ovc=<codec> Specifies the output video codec. See --ovc=help for a full list of supported codecs.
--ovoffset=<value> Shifts video data by the given time (in seconds) by shifting the pts values. Deprecated.
--ovcopts=<options> Specifies the output video codec options for libavcodec.  See --ovcopts=help for a full list of supported options.
"--ovc=mpeg4 --ovcopts=qscale=5" selects constant quantizer scale 5 for MPEG-4 encoding.
"--ovc=libx264 --ovcopts=crf=23" selects VBR quality factor 23 for H.264 encoding.
--ovcopts-add=<option> Appends the option given as an argument to the options list. (Passing multiple options is currently still possible, but deprecated.)
--ovcopts="" Completely empties the options list.
--ovfirst Force the video stream to become the first stream in the output. By default, the order is unspecified. Deprecated.
--orawts Copies input pts to the output video (not supported by some output container formats, e.g. AVI). In this mode, discontinuities are not fixed and all pts are passed through as-is. Never seek backwards or use multiple input files in this mode!
--no-ocopy-metadata Turns off copying of metadata from input files to output files when encoding (which is enabled by default).
--oset-metadata=<metadata-tag[,metadata-tag,...]> Specifies metadata to include in the output file.  Supported keys vary between output formats. For example, Matroska (MKV) and FLAC allow almost arbitrary keys, while support in MP4 and MP3 is more limited.
--oset-metadata=title= Output title",comment="Another tag"" adds a title and a comment to the output file.
--oremove-metadata=<metadata-tag[,metadata-tag,...]> Specifies metadata to exclude from the output file when copying from the input file.
--oremove-metadata=comment,genre excludes copying of the the comment and genre tags to the output file.
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. The option --no-input-right-alt-gr changes this behavior.
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 occurance 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.
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).
ignore Use this to "block" keys that should be unbound, and do nothing. Useful for disabling default bindings, without disabling all bindings with --no-input-default-bindings.
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.
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.
set <name> <value> Set the given property or option to the given value.
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.
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).
multiply <name> <value> Similar to add, but multiplies the property or option with the numeric value.
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, and if no support is available, this will act like video.
<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.)
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.
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.
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-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 comm and 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> [<options>]] Load the given file or URL and play it. Technically, this is just a playlist manipulation command (which either replaces the playlist or appends 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.)
The third 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).
loadlist <url> [<flags>] Load the given playlist file or URL (like --playlist).
<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.)
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.
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.
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 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 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 NANME=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) The raw exit status of the process. It will be negative on error. 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 exits gracefully, 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 exited gracefully. 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.
In all cases, the subprocess will be terminated on player exit. Also see Asynchronous command details. Only the run command can start processes in a truly detached way.