neulab/tldr huggingface dataset:
--profile=<profile1,profile2,...> Use the given profile(s), --profile=help displays a list of the defined profiles.
--reset-on-next-file=<all|option1,option2,...> Normally, mpv will try to keep all settings when playing the next file on the playlist, even if they were changed by the user during playback. (This behavior is the opposite of MPlayer's, which tries to reset all settings when starting next file.)
Default: Do not reset anything.
This can be changed with this option. It accepts a list of options, and mpv will reset the value of these options on playback start to the initial value. The initial value is either the default value, or as set by the config file or command line.
In some cases, this might not work as expected. For example, --volume will only be reset if it is explicitly set in the config file or the command line.
The special name all resets as many options as possible.
• --reset-on-next-file=pause Reset pause mode when switching to the next file.
• --reset-on-next-file=fullscreen,speed Reset fullscreen and playback speed settings if they were changed during playback.
• --reset-on-next-file=all Try to reset all settings that were changed during playback.
--watch-later-options=option1,option2,... The options that are saved in "watch later" files if they have been changed since when mpv started. These values will be restored the next time the files are played. The playback position is always saved as start, so adding start to this list has no effect.
When removing options, existing watch later data won't be modified and will still be applied fully, but new watch later data won't contain these options.
• --watch-later-options-remove=fullscreen The fullscreen state won't be saved to watch later files.
• --watch-later-options-remove=volume --watch-later-options-remove=mute The volume and mute state won't be saved to watch later files.
• --watch-later-options-clr No option will be saved to watch later files except the starting position.
--write-filename-in-watch-later-config Prepend the watch later config files with the name of the file they refer to. This is simply written as comment on the top of the file.
WARNING: This option may expose privacy-sensitive information and is thus disabled by default.
--ignore-path-in-watch-later-config Ignore path (i.e. use filename only) when using watch later feature.  (Default: disabled)
--show-profile=<profile> Show the description and content of a profile. Lists all profiles if no parameter is provided.
--use-filedir-conf Look for a file-specific configuration file in the same directory as the file that is being played. See File-specific Configuration Files.
WARNING: May be dangerous if playing from untrusted media.
--ytdl, --no-ytdl Enable the youtube-dl hook-script. It will look at the input URL, and will play the video located on the website. This works with many streaming sites, not just the one that the script is named after. This requires a recent version of youtube-dl to be installed on the system. (Enabled by default.)
If the script can't do anything with an URL, it will do nothing.
This accepts a set of options, which can be passed to it with the --script-opts option (using ytdl_hook- as prefix):
try_ytdl_first=<yes|no> If 'yes' will try parsing the URL with youtube-dl first, instead of the default where it's only after mpv failed to open it. This mostly depends on whether most of your URLs need youtube-dl parsing.
exclude=<URL1|URL2|... A |-separated list of URL patterns which mpv should not use with youtube-dl. The patterns are matched after the http(s):// part of the URL.
^ matches the beginning of the URL, $ matches its end, and you should use % before any of the characters ^$()%|,.[]*+-? to match that character.
• --script-opts=ytdl_hook-exclude='^youtube%.com' will exclude any URL that starts with http://youtube.com or https://youtube.com.
• --script-opts=ytdl_hook-exclude='%.mkv$|%.mp4$' will exclude any URL that ends with .mkv or .mp4.
See more lua patterns here: https://www.lua.org/manual/5.1/manual.html#5.4.1
all_formats=<yes|no> If 'yes' will attempt to add all formats found reported by youtube-dl (default: no). Each format is added as a separate track. In addition, they are delay-loaded, and actually opened only when a track is selected (this should keep load times as low as without this option).
It adds average bitrate metadata, if available, which means you can use --hls-bitrate to decide which track to select. (HLS used to be the only format whose alternative quality streams were exposed in a similar way, thus the option name.)
Tracks which represent formats that were selected by youtube-dl as default will have the default flag set. This means mpv should generally still select formats chosen with --ytdl-format by default.
Although this mechanism makes it possible to switch streams at runtime, it's not suitable for this purpose for various technical reasons. (It's slow, which can't be really fixed.) In general, this option is not useful, and was only added to show that it's possible.
There are two cases that must be considered when doing quality/bandwidth selection:
1. Completely separate audio and video streams (DASH-like). Each of these streams contain either only audio or video, so you can mix and combine audio/video bandwidths without restriction. This intuitively matches best with the concept of selecting quality by track (what all_formats is supposed to do).
2. Separate sets of muxed audio and video streams. Each version of the media contains both an audio and video stream, and they are interleaved. In order not to waste bandwidth, you should only select one of these versions (if, for example, you select an audio stream, then video will be downloaded, even if you selected video from a different stream).
mpv will still represent them as separate tracks, but will set the title of each track to muxed-N, where N is replaced with the youtube-dl format ID of the originating stream.
Some sites will mix 1. and 2., but we assume that they do so for compatibility reasons, and there is no reason to use them at all.
force_all_formats=<yes|no> If set to 'yes', and all_formats is also set to 'yes', this will try to represent all youtube-dl reported formats as tracks, even if mpv would normally use the direct URL reported by it (default: yes).
It appears this normally makes a difference if youtube-dl works on a master HLS playlist.
If this is set to 'no', this specific kind of stream is treated like all_formats is set to 'no', and the stream selection as done by youtube-dl (via --ytdl-format) is used.
use_manifests=<yes|no> Make mpv use the master manifest URL for formats like HLS and DASH, if available, allowing for video/audio selection in runtime (default: no). It's disabled ("no") by default for performance reasons.
ytdl_path=youtube-dl Configure paths to youtube-dl's executable or a compatible fork's. The paths should be separated by : on Unix and ; on Windows. mpv looks in order for the configured paths in PATH and in mpv's config directory.  The defaults are "yt-dlp", "yt-dlp_x86" and "youtube-dl". On Windows the suffix extension ".exe" is always appended.
Why do the option names mix _ and -?
--ytdl-format=<ytdl|best|worst|mp4|webm|...> Video format/quality that is directly passed to youtube-dl. The possible values are specific to the website and the video, for a given url the available formats can be found with the command youtube-dl --list-formats URL. See youtube-dl's documentation for available aliases.  (Default: bestvideo+bestaudio/best)
The ytdl value does not pass a --format option to youtube-dl at all, and thus does not override its default. Note that sometimes youtube-dl returns a format that mpv cannot use, and in these cases the mpv default may work better.
--ytdl-raw-options=<key>=<value>[,<key>=<value>[,...]] Pass arbitrary options to youtube-dl. Parameter and argument should be passed as a key-value pair. Options without argument must include =.
There is no sanity checking so it's possible to break things (i.e. passing invalid parameters to youtube-dl).
A proxy URL can be passed for youtube-dl to use it in parsing the website.  This is useful for geo-restricted URLs. After youtube-dl parsing, some URLs also require a proxy for playback, so this can pass that proxy information to mpv. Take note that SOCKS proxies aren't supported and https URLs also bypass the proxy. This is a limitation in FFmpeg.
• --ytdl-raw-options=username=user,password=pass
• --ytdl-raw-options=force-ipv6=
• --ytdl-raw-options=proxy=[http://127.0.0.1:3128]
• --ytdl-raw-options-append=proxy=http://127.0.0.1:3128
--load-stats-overlay=<yes|no> Enable the builtin script that shows useful playback information on a key binding (default: yes). By default, the i key is used (I to make the overlay permanent).
--load-osd-console=<yes|no> Enable the builtin script that shows a console on a key binding and lets you enter commands (default: yes). By default,. The ´ key is used to show the console, and ESC to hide it again. (This is based on  a user script called repl.lua.)
--load-auto-profiles=<yes|no|auto> Enable the builtin script that does auto profiles (default: auto). See Conditional auto profiles for details. auto will load the script, but immediately unload it if there are no conditional profiles.
--player-operation-mode=<cplayer|pseudo-gui> For enabling "pseudo GUI mode", which means that the defaults for some options are changed. This option should not normally be used directly, but only by mpv internally, or mpv-provided scripts, config files, or .desktop files. See PSEUDO GUI MODE for details.
Video --vo=<driver> Specify the video output backend to be used. See VIDEO OUTPUT DRIVERS for details and descriptions of available drivers.
--vd=<...> Specify a priority list of video decoders to be used, according to their family and name. See --ad for further details. Both of these options use the same syntax and semantics; the only difference is that they operate on different codec lists.
NOTE: See --vd=help for a full list of available decoders.
--vf=<filter1[=parameter1:parameter2:...],filter2,...> Specify a list of video filters to apply to the video stream. See VIDEO FILTERS for details and descriptions of the available filters.  The option variants --vf-add, --vf-pre, --vf-del and --vf-clr exist to modify a previously specified list, but you should not need these for typical use.
--untimed Do not sleep when outputting video frames. Useful for benchmarks when used with --no-audio.
--framedrop=<mode> Skip displaying some frames to maintain A/V sync on slow systems, or playing high framerate video on video outputs that have an upper framerate limit.
The argument selects the drop methods, and can be one of the following:
<no>   Disable any frame dropping. Not recommended, for testing only.
<vo>   Drop late frames on video output (default). This still decodes and filters all frames, but doesn't render them on the VO. Drops are indicated in the terminal status line as Dropped: field.
In audio sync. mode, this drops frames that are outdated at the time of display. If the decoder is too slow, in theory all frames would have to be dropped (because all frames are too late) - to avoid this, frame dropping stops  if the effective framerate is below 10 FPS.
In display-sync. modes (see --video-sync), this affects only how A/V drops or repeats frames. If this mode is disabled, A/V desync will in theory not affect video scheduling anymore (much like the display-resample-desync mode). However, even if disabled, frames will still be skipped (i.e. dropped) according to the ratio between video and display frequencies.
This is the recommended mode, and the default.
<decoder> Old, decoder-based framedrop mode. (This is the same as --framedrop=yes in mpv 0.5.x and before.) This tells the decoder to skip frames (unless they are needed to decode future frames). May help with slow systems, but can produce unwatchable choppy output, or even freeze the display completely.
This uses a heuristic which may not make sense, and in general cannot achieve good results, because the decoder's frame dropping cannot be controlled in a predictable manner. Not recommended.
Even if you want to use this, prefer decoder+vo for better results.
The --vd-lavc-framedrop option controls what frames to drop.
<decoder+vo> Enable both modes. Not recommended. Better than just decoder mode.
NOTE: --vo=vdpau has its own code for the vo framedrop mode. Slight differences to other VOs are possible.
--video-latency-hacks=<yes|no> Enable some things which tend to reduce video latency by 1 or 2 frames (default: no). Note that this option might be removed without notice once the player's timing code does not inherently need to do these things anymore.
This does:
• Use the demuxer reported FPS for frame dropping. This avoids the player needing to decode 1 frame in advance, lowering total latency in effect. This also means that if the demuxer reported FPS is wrong, or the video filter chain changes FPS (e.g. deinterlacing), then it could drop too many or not enough frames.
• Disable waiting for the first video frame. Normally the player waits for the first video frame to be fully rendered before starting playback properly. Some VOs will lazily initialize stuff when rendering the first frame, so if this is not done, there is some likeliness that the VO has to drop some frames if rendering the first frame takes longer than needed.
--override-display-fps=<fps> Set the display FPS used with the --video-sync=display-* modes. By default, a detected value is used. Keep in mind that setting an incorrect value (even if slightly incorrect) can ruin video playback. On multi-monitor systems, there is a chance that the detected value is from the wrong monitor.
Set this option only if you have reason to believe the automatically determined value is wrong.
--display-fps=<fps> Deprecated alias for --override-display-fps.
--hwdec=<api> Specify the hardware video decoding API that should be used if possible.  Whether hardware decoding is actually done depends on the video codec. If hardware decoding is not possible, mpv will fall back on software decoding.
Hardware decoding is not enabled by default, because it is typically an additional source of errors. It is worth using only if your CPU is too slow to decode a specific video.
NOTE: Use the Ctrl+h shortcut to toggle hardware decoding at runtime. It toggles this option between auto and no.
Always enabling HW decoding by putting it into the config file is discouraged. If you use the Ubuntu package, delete /etc/mpv/mpv.conf, as the package tries to enable HW decoding by default by setting hwdec=vaapi (which is less than ideal, and may even cause sub-optimal wrappers to be used). Or at least change it to hwdec=auto-safe.
Use one of the auto modes if you want to enable hardware decoding. Explicitly selecting the mode is mostly meant for testing and debugging.  It's a bad idea to put explicit selection into the config file if you want thing to just keep working after updates and so on.
NOTE: Even if enabled, hardware decoding is still only white-listed for some codecs. See --hwdec-codecs to enable hardware decoding in more cases.
Which method to choose?
• If you only want to enable hardware decoding at runtime, don't set the parameter, or put hwdec=no into your mpv.conf (relevant on distros which force-enable it by default, such as on Ubuntu). Use the Ctrl+h default binding to enable it at runtime.
• If you're not sure, but want hardware decoding always enabled by default, put hwdec=auto-safe into your mpv.conf, and acknowledge that this use case is not "really" supported and may cause problems.
• If you want to test available hardware decoding methods, pass --hwdec=auto --hwdec-codecs=all and look at the terminal output.
• If you're a developer, or want to perform elaborate tests, you may need any of the other possible option values.
<api> can be one of the following:
no     always use software decoding (default)
auto   forcibly enable any hw decoder found (see below)
yes    exactly the same as auto
auto-safe enable any whitelisted hw decoder (see below)
auto-copy enable best hw decoder with copy-back (see below)
vdpau  requires --vo=gpu with X11, or --vo=vdpau (Linux only)
vdpau-copy copies video back into system RAM (Linux with some GPUs only)
vaapi  requires --vo=gpu or --vo=vaapi (Linux only)
vaapi-copy copies video back into system RAM (Linux with some GPUs only)
videotoolbox requires --vo=gpu (macOS 10.8 and up), or --vo=libmpv (iOS 9.0 and up)
videotoolbox-copy copies video back into system RAM (macOS 10.8 or iOS 9.0 and up)
dxva2  requires --vo=gpu with --gpu-context=d3d11, --gpu-context=angle or --gpu-context=dxinterop (Windows only)
dxva2-copy copies video back to system RAM (Windows only)
d3d11va requires --vo=gpu with --gpu-context=d3d11 or --gpu-context=angle (Windows 8+ only)
d3d11va-copy copies video back to system RAM (Windows 8+ only)
mediacodec requires --vo=mediacodec_embed (Android only)
mediacodec-copy copies video back to system RAM (Android only)
mmal   requires --vo=gpu (Raspberry Pi only - default if available)
mmal-copy copies video back to system RAM (Raspberry Pi only)
nvdec  requires --vo=gpu (Any platform CUDA is available)
nvdec-copy copies video back to system RAM (Any platform CUDA is available)
cuda   requires --vo=gpu (Any platform CUDA is available)
cuda-copy copies video back to system RAM (Any platform CUDA is available)
crystalhd copies video back to system RAM (Any platform supported by hardware)
rkmpp  requires --vo=gpu (some RockChip devices only)
auto tries to automatically enable hardware decoding using the first available method. This still depends what VO you are using. For example, if you are not using --vo=gpu or --vo=vdpau, vdpau decoding will never be enabled. Also note that if the first found method doesn't actually work, it will always fall back to software decoding, instead of trying the next method (might matter on some Linux systems).
auto-safe is similar to auto, but allows only whitelisted methods that are considered "safe". This is supposed to be a reasonable way to enable hardware decdoding by default in a config file (even though you shouldn't do that anyway; prefer runtime enabling with Ctrl+h). Unlike auto, this will not try to enable unknown or known-to-be-bad methods. In addition, this may disable hardware decoding in other situations when it's known to cause problems, but currently this mechanism is quite primitive.  (As an example for something that still causes problems: certain combinations of HEVC and Intel chips on Windows tend to cause mpv to crash, most likely due to driver bugs.)
auto-copy-safe selects the union of methods selected with auto-safe and auto-copy.
auto-copy selects only modes that copy the video data back to system memory after decoding. This selects modes like vaapi-copy (and so on).  If none of these work, hardware decoding is disabled. This mode is usually guaranteed to incur no additional quality loss compared to software decoding (assuming modern codecs and an error free video stream), and will allow CPU processing with video filters. This mode works with all video filters and VOs.
Because these copy the decoded video back to system RAM, they're often less efficient than the direct modes, and may not help too much over software decoding.
NOTE: Most non-copy methods only work with the OpenGL GPU backend. Currently, only the vaapi, nvdec and cuda methods work with Vulkan.
The vaapi mode, if used with --vo=gpu, requires Mesa 11, and most likely works with Intel and AMD GPUs only. It also requires the opengl EGL backend.
nvdec and nvdec-copy are the newest, and recommended method to do hardware decoding on Nvidia GPUs.
cuda and cuda-copy are an older implementation of hardware decoding on Nvidia GPUs that uses Nvidia's bitstream parsers rather than FFmpeg's.  This can lead to feature deficiencies, such as incorrect playback of HDR content, and nvdec/nvdec-copy should always be preferred unless you specifically need Nvidia's deinterlacing algorithms. To use this deinterlacing you must pass the option: vd-lavc-o=deint=[weave|bob|adaptive].  Pass weave (or leave the option unset) to not attempt any deinterlacing.
Quality reduction with hardware decoding
In theory, hardware decoding does not reduce video quality (at least for the codecs h264 and HEVC). However, due to restrictions in video output APIs, as well as bugs in the actual hardware decoders, there can be some loss, or even blatantly incorrect results.
In some cases, RGB conversion is forced, which means the RGB conversion is performed by the hardware decoding API, instead of the shaders used by --vo=gpu. This means certain colorspaces may not display correctly, and certain filtering (such as debanding) cannot be applied in an ideal way. This will also usually force the use of low quality chroma scalers instead of the one specified by --cscale. In other cases, hardware decoding can also reduce the bit depth of the decoded image, which can introduce banding or precision loss for 10-bit files.
vdpau always does RGB conversion in hardware, which does not support newer colorspaces like BT.2020 correctly. However, vdpau doesn't support 10 bit or HDR encodings, so these limitations are unlikely to be relevant.
vaapi and d3d11va are safe. Enabling deinterlacing (or simply their respective post-processing filters) will possibly at least reduce color quality by converting the output to a 8 bit format.
dxva2 is not safe. It appears to always use BT.601 for forced RGB conversion, but actual behavior depends on the GPU drivers. Some drivers appear to convert to limited range RGB, which gives a faded appearance.  In addition to driver-specific behavior, global system settings might affect this additionally. This can give incorrect results even with completely ordinary video sources.
rpi always uses the hardware overlay renderer, even with --vo=gpu.
cuda should usually be safe, but depending on how a file/stream has been mixed, it has been reported to corrupt the timestamps causing glitched, flashing frames. It can also sometimes cause massive framedrops for unknown reasons. Caution is advised, and nvdec should always be preferred.
crystalhd is not safe. It always converts to 4:2:2 YUV, which may be lossy, depending on how chroma sub-sampling is done during conversion. It also discards the top left pixel of each frame for some reason.
All other methods, in particular the copy-back methods (like dxva2-copy etc.) should hopefully be safe, although they can still cause random decoding issues. At the very least, they shouldn't affect the colors of the image.
In particular, auto-copy will only select "safe" modes (although potentially slower than other methods), but there's still no guarantee the chosen hardware decoder will actually work correctly.
In general, it's very strongly advised to avoid hardware decoding unless absolutely necessary, i.e. if your CPU is insufficient to decode the file in questions. If you run into any weird decoding issues, frame glitches or discoloration, and you have --hwdec turned on, the first thing you should try is disabling it.
--gpu-hwdec-interop=<auto|all|no|name> This option is for troubleshooting hwdec interop issues. Since it's a debugging option, its semantics may change at any time.
This is useful for the gpu and libmpv VOs for selecting which hwdec interop context to use exactly. Effectively it also can be used to block loading of certain backends.
If set to auto (default), the behavior depends on the VO: for gpu, it does nothing, and the interop context is loaded on demand (when the decoder probes for --hwdec support). For libmpv, which has has no on-demand loading, this is equivalent to all.
The empty string is equivalent to auto.
If set to all, it attempts to load all interop contexts at GL context creation time.
Other than that, a specific backend can be set, and the list of them can be queried with help (mpv CLI only).
Runtime changes to this are ignored (the current option value is used whenever the renderer is created).
The old aliases --opengl-hwdec-interop and --hwdec-preload are barely related to this anymore, but will be somewhat compatible in some cases.
--hwdec-extra-frames=<N> Number of GPU frames hardware decoding should preallocate (default: see --list-options output). If this is too low, frame allocation may fail during decoding, and video frames might get dropped and/or corrupted.  Setting it too high simply wastes GPU memory and has no advantages.
This value is used only for hardware decoding APIs which require preallocating surfaces (known examples include d3d11va and vaapi). For other APIs, frames are allocated as needed. The details depend on the libavcodec implementations of the hardware decoders.
The required number of surfaces depends on dynamic runtime situations. The default is a fixed value that is thought to be sufficient for most uses. But in certain situations, it may not be enough.
--hwdec-image-format=<name> Set the internal pixel format used by hardware decoding via --hwdec (default no). The special value no selects an implementation specific standard format. Most decoder implementations support only one format, and will fail to initialize if the format is not supported.
Some implementations might support multiple formats. In particular, videotoolbox is known to require uyvy422 for good performance on some older hardware. d3d11va can always use yuv420p, which uses an opaque format, with likely no advantages.
--cuda-decode-device=<auto|0..> Choose the GPU device used for decoding when using the cuda or nvdec hwdecs with the OpenGL GPU backend, and with the cuda-copy or nvdec-copy hwdecs in all cases.
For the OpenGL GPU backend, the default device used for decoding is the one being used to provide gpu output (and in the vast majority of cases, only one GPU will be present).
For the copy hwdecs, the default device will be the first device enumerated by the CUDA libraries - however that is done.
For the Vulkan GPU backend, decoding must always happen on the display device, and this option has no effect.
--vaapi-device=<device file> Choose the DRM device for vaapi-copy. This should be the path to a DRM device file. (Default: /dev/dri/renderD128)
--panscan=<0.0-1.0> Enables pan-and-scan functionality (cropping the sides of e.g. a 16:9 video to make it fit a 4:3 display without black bands). The range controls how much of the image is cropped. May not work with all video output drivers.
This option has no effect if --video-unscaled option is used.
--video-aspect-override=<ratio|no> Override video aspect ratio, in case aspect information is incorrect or missing in the file being played.
These values have special meaning:
0      disable aspect ratio handling, pretend the video has square pixels
no     same as 0
-1     use the video stream or container aspect (default)
But note that handling of these special values might change in the future.
• --video-aspect-override=4:3  or --video-aspect-override=1.3333
• --video-aspect-override=16:9 or --video-aspect-override=1.7777
• --no-video-aspect-override or --video-aspect-override=no
--video-aspect-method=<bitstream|container> This sets the default video aspect determination method (if the aspect is _not_ overridden by the user with --video-aspect-override or others).
container Strictly prefer the container aspect ratio. This is apparently the default behavior with VLC, at least with Matroska. Note that if the container has no aspect ratio set, the behavior is the same as with bitstream.
bitstream Strictly prefer the bitstream aspect ratio, unless the bitstream aspect ratio is not set. This is apparently the default behavior with XBMC/kodi, at least with Matroska.
The current default for mpv is container.
Normally you should not set this. Try the various choices if you encounter video that has the wrong aspect ratio in mpv, but seems to be correct in other players.
--video-unscaled=<no|yes|downscale-big> Disable scaling of the video. If the window is larger than the video, black bars are added. Otherwise, the video is cropped, unless the option is set to downscale-big, in which case the video is fit to window. The video still can be influenced by the other --video-... options. This option disables the effect of --panscan.
Note that the scaler algorithm may still be used, even if the video isn't scaled. For example, this can influence chroma conversion. The video will also still be scaled in one dimension if the source uses non-square pixels (e.g. anamorphic widescreen DVDs).
This option is disabled if the --no-keepaspect option is used.
--video-pan-x=<value>, --video-pan-y=<value> Moves the displayed video rectangle by the given value in the X or Y direction. The unit is in fractions of the size of the scaled video (the full size, even if parts of the video are not visible due to panscan or other options).
For example, displaying a 1280x720 video fullscreen on a 1680x1050 screen with --video-pan-x=-0.1 would move the video 168 pixels to the left (making 128 pixels of the source video invisible).
--video-rotate=<0-359|no> Rotate the video clockwise, in degrees. If no is given, the video is never rotated, even if the file has rotation metadata. (The rotation value is added to the rotation metadata, which means the value 0 would rotate the video according to the rotation metadata.)
When using hardware decoding without copy-back, only 90° steps work, while software decoding and hardware decoding methods that copy the video back to system memory support all values between 0 and 359.
--video-zoom=<value> Adjust the video display scale factor by the given value. The parameter is given log 2. For example, --video-zoom=0 is unscaled, --video-zoom=1 is twice the size, --video-zoom=-2 is one fourth of the size, and so on.
--video-scale-x=<value>, --video-scale-y=<value> Multiply the video display size with the given value (default: 1.0). If a non-default value is used, this will be different from the window size, so video will be either cut off, or black bars are added.
This value is multiplied with the value derived from --video-zoom and the normal video aspect aspect ratio. This option is disabled if the --no-keepaspect option is used.
--video-align-x=<-1-1>, --video-align-y=<-1-1> Moves the video rectangle within the black borders, which are usually added to pad the video to screen if video and screen aspect ratios are different.  --video-align-y=-1 would move the video to the top of the screen (leaving a border only on the bottom), a value of 0 centers it (default), and a value of 1 would put the video at the bottom of the screen.
If video and screen aspect match perfectly, these options do nothing.
--video-margin-ratio-left=<val>, --video-margin-ratio-right=<val>, --video-margin-ratio-top=<val>, --video-margin-ratio-bottom=<val> Set extra video margins on each border (default: 0). Each value is a ratio of the window size, using a range 0.0-1.0. For example, setting the option --video-margin-ratio-right=0.2 at a window size of 1000 pixels will add a 200 pixels border on the right side of the window.
The video is "boxed" by these margins. The window size is not changed. In particular it does not enlarge the window, and the margins will cause the video to be downscaled by default. This may or may not change in the future.
The margins are applied after 90° video rotation, but before any other video transformations.
Subtitles still may use the margins, depending on --sub-use-margins and similar options.
These options were created for the OSC. Some odd decisions, such as making the margin values a ratio (instead of pixels), were made for the sake of the OSC. It's possible that these options may be replaced by ones that are more generally useful. The behavior of these options may change to fit OSC requirements better, too.
--correct-pts, --no-correct-pts --no-correct-pts switches mpv to a mode where video timing is determined using a fixed framerate value (either using the --fps option, or using file information). Sometimes, files with very broken timestamps can be played somewhat well in this mode. Note that video filters, subtitle rendering, seeking (including hr-seeks and backstepping), and audio synchronization can be completely broken in this mode.
--fps=<float> Override video framerate. Useful if the original value is wrong or missing.
NOTE: Works in --no-correct-pts mode only.
--deinterlace=<yes|no> Enable or disable interlacing (default: no).  Interlaced video shows ugly comb-like artifacts, which are visible on fast movement. Enabling this typically inserts the yadif video filter in order to deinterlace the video, or lets the video output apply deinterlacing if supported.
This behaves exactly like the deinterlace input property (usually mapped to d).
Keep in mind that this will conflict with manually inserted deinterlacing filters, unless you take care. (Since mpv 0.27.0, even the hardware deinterlace filters will conflict. Also since that version, --deinterlace=auto was removed, which used to mean that the default interlacing option of possibly inserted video filters was used.)
Note that this will make video look worse if it's not actually interlaced.
--frames=<number> Play/convert only first <number> video frames, then quit.
--frames=0 loads the file, but immediately quits before initializing playback. (Might be useful for scripts which just want to determine some file properties.)
For audio-only playback, any value greater than 0 will quit playback immediately after initialization. The value 0 works as with video.
--video-output-levels=<outputlevels> RGB color levels used with YUV to RGB conversion. Normally, output devices such as PC monitors use full range color levels. However, some TVs and video monitors expect studio RGB levels. Providing full range output to a device expecting studio level input results in crushed blacks and whites, the reverse in dim gray blacks and dim whites.
Not all VOs support this option. Some will silently ignore it.
Available color ranges are:
auto   automatic selection (equals to full range) (default)
limited limited range (16-235 per component), studio levels
full   full range (0-255 per component), PC levels
NOTE: It is advisable to use your graphics driver's color range option instead, if available.
--hwdec-codecs=<codec1,codec2,...|all> Allow hardware decoding for a given list of codecs only. The special value all always allows all codecs.
You can get the list of allowed codecs with mpv --vd=help. Remove the prefix, e.g. instead of lavc:h264 use h264.
By default, this is set to h264,vc1,hevc,vp8,vp9,av1. Note that the hardware acceleration special codecs like h264_vdpau are not relevant anymore, and in fact have been removed from Libav in this form.
This is usually only needed with broken GPUs, where a codec is reported as supported, but decoding causes more problems than it solves.
mpv --hwdec=vdpau --vo=vdpau --hwdec-codecs=h264,mpeg2video Enable vdpau decoding for h264 and mpeg2 only.
--vd-lavc-check-hw-profile=<yes|no> Check hardware decoder profile (default: yes). If no is set, the highest profile of the hardware decoder is unconditionally selected, and decoding is forced even if the profile of the video is higher than that.  The result is most likely broken decoding, but may also help if the detected or reported profiles are somehow incorrect.
--vd-lavc-software-fallback=<yes|no|N> Fallback to software decoding if the hardware-accelerated decoder fails (default: 3). If this is a number, then fallback will be triggered if N frames fail to decode in a row. 1 is equivalent to yes.
Setting this to a higher number might break the playback start fallback: if a fallback happens, parts of the file will be skipped, approximately by to the number of packets that could not be decoded. Values below an unspecified count will not have this problem, because mpv retains the packets.
--vd-lavc-dr=<yes|no> Enable direct rendering (default: yes). If this is set to yes, the video will be decoded directly to GPU video memory (or staging buffers).  This can speed up video upload, and may help with large resolutions or slow hardware. This works only with the following VOs:
• gpu: requires at least OpenGL 4.4 or Vulkan.
(In particular, this can't be made work with opengl-cb, but the libmpv render API has optional support.)
Using video filters of any kind that write to the image data (or output newly allocated frames) will silently disable the DR code path.
--vd-lavc-bitexact Only use bit-exact algorithms in all decoding steps (for codec testing).
--vd-lavc-fast (MPEG-2, MPEG-4, and H.264 only) Enable optimizations which do not comply with the format specification and potentially cause problems, like simpler dequantization, simpler motion compensation, assuming use of the default quantization matrix, assuming YUV 4:2:0 and skipping a few checks to detect damaged bitstreams.
--vd-lavc-o=<key>=<value>[,<key>=<value>[,...]] Pass AVOptions to libavcodec decoder. Note, a patch to make the o= unneeded and pass all unknown options through the AVOption system is welcome. A full list of AVOptions can be found in the FFmpeg manual.
Some options which used to be direct options can be set with this mechanism, like bug, gray, idct, ec, vismv, skip_top (was st), skip_bottom (was sb), debug.
--vd-lavc-o=debug=pict
--vd-lavc-show-all=<yes|no> Show even broken/corrupt frames (default: no). If this option is set to no, libavcodec won't output frames that were either decoded before an initial keyframe was decoded, or frames that are recognized as corrupted.
--vd-lavc-skiploopfilter=<skipvalue> (H.264 only) Skips the loop filter (AKA deblocking) during H.264 decoding. Since the filtered frame is supposed to be used as reference for decoding dependent frames, this has a worse effect on quality than not doing deblocking on e.g. MPEG-2 video. But at least for high bitrate HDTV, this provides a big speedup with little visible quality loss.
<skipvalue> can be one of the following:
none   Never skip.
default Skip useless processing steps (e.g. 0 size packets in AVI).
nonref Skip frames that are not referenced (i.e. not used for decoding other frames, the error cannot "build up").
bidir  Skip B-Frames.
nonkey Skip all frames except keyframes.
all    Skip all frames.
--vd-lavc-skipidct=<skipvalue> (MPEG-1/2 only) Skips the IDCT step. This degrades quality a lot in almost all cases (see skiploopfilter for available skip values).
--vd-lavc-skipframe=<skipvalue> Skips decoding of frames completely. Big speedup, but jerky motion and sometimes bad artifacts (see skiploopfilter for available skip values).
--vd-lavc-framedrop=<skipvalue> Set framedropping mode used with --framedrop (see skiploopfilter for available skip values).
--vd-lavc-threads=<N> Number of threads to use for decoding. Whether threading is actually supported depends on codec (default: 0). 0 means autodetect number of cores on the machine and use that, up to the maximum of 16. You can set more than 16 threads manually.
--vd-lavc-assume-old-x264=<yes|no> Assume the video was encoded by an old, buggy x264 version (default: no).  Normally, this is autodetected by libavcodec. But if the bitstream contains no x264 version info (or it was somehow skipped), and the stream was in fact encoded by an old x264 version (build 150 or earlier), and if the stream uses 4:4:4 chroma, then libavcodec will by default show corrupted video. This option sets the libavcodec x264_build option to 150, which means that if the stream contains no version info, or was not encoded by x264 at all, it assumes it was encoded by the old version. Enabling this option is pretty safe if you want your broken files to work, but in theory this can break on streams not encoded by x264, or if a stream encoded by a newer x264 version contains no version info.
--swapchain-depth=<N> Allow up to N in-flight frames. This essentially controls the frame latency. Increasing the swapchain depth can improve pipelining and prevent missed vsyncs, but increases visible latency. This option only mandates an upper limit, the implementation can use a lower latency than requested internally. A setting of 1 means that the VO will wait for every frame to become visible before starting to render the next frame. (Default: 3)
Audio --audio-pitch-correction=<yes|no> If this is enabled (default), playing with a speed different from normal automatically inserts the scaletempo2 audio filter. For details, see audio filter section.
--audio-device=<name> Use the given audio device. This consists of the audio output name, e.g.  alsa, followed by /, followed by the audio output specific device name. The default value for this option is auto, which tries every audio output in preference order with the default device.
You can list audio devices with --audio-device=help. This outputs the device name in quotes, followed by a description. The device name is what you have to pass to the --audio-device option. The list of audio devices can be retrieved by API by using the audio-device-list property.
While the option normally takes one of the strings as indicated by the methods above, you can also force the device for most AOs by building it manually. For example name/foobar forces the AO name to use the device foobar. However, the --ao option will strictly force a specific AO. To avoid confusion, don't use --ao and --audio-device together.
Example for ALSA
MPlayer and mplayer2 required you to replace any ',' with '.' and any ':' with '=' in the ALSA device name. For example, to use the device named dmix:default, you had to do: -ao alsa:device=dmix=default
In mpv you could instead use: --audio-device=alsa/dmix:default
--audio-exclusive=<yes|no> Enable exclusive output mode. In this mode, the system is usually locked out, and only mpv will be able to output audio.
This only works for some audio outputs, such as wasapi and coreaudio. Other audio outputs silently ignore this options. They either have no concept of exclusive mode, or the mpv side of the implementation is missing.
--audio-fallback-to-null=<yes|no> If no audio device can be opened, behave as if --ao=null was given. This is useful in combination with --audio-device: instead of causing an error if the selected device does not exist, the client API user (or a Lua script) could let playback continue normally, and check the current-ao and audio-device-list properties to make high-level decisions about how to continue.
--ao=<driver> Specify the audio output drivers to be used. See AUDIO OUTPUT DRIVERS for details and descriptions of available drivers.
--af=<filter1[=parameter1:parameter2:...],filter2,...> Specify a list of audio filters to apply to the audio stream. See AUDIO FILTERS for details and descriptions of the available filters.  The option variants --af-add, --af-pre, --af-del and --af-clr exist to modify a previously specified list, but you should not need these for typical use.
--audio-spdif=<codecs> List of codecs for which compressed audio passthrough should be used. This works for both classic S/PDIF and HDMI.
Possible codecs are ac3, dts, dts-hd, eac3, truehd.  Multiple codecs can be specified by separating them with ,. dts refers to low bitrate DTS core, while dts-hd refers to DTS MA (receiver and OS support varies). If both dts and dts-hd are specified, it behaves equivalent to specifying dts-hd only.
In earlier mpv versions you could use --ad to force the spdif wrapper.  This does not work anymore.
There is not much reason to use this. HDMI supports uncompressed multichannel PCM, and mpv supports lossless DTS-HD decoding via FFmpeg's new DCA decoder (based on libdcadec).
--ad=<decoder1,decoder2,...[-]> Specify a priority list of audio decoders to be used, according to their decoder name. When determining which decoder to use, the first decoder that matches the audio format is selected. If that is unavailable, the next decoder is used. Finally, it tries all other decoders that are not explicitly selected or rejected by the option.
- at the end of the list suppresses fallback on other available decoders not on the --ad list. + in front of an entry forces the decoder. Both of these should not normally be used, because they break normal decoder auto-selection! Both of these methods are deprecated.
--ad=mp3float Prefer the FFmpeg/Libav mp3float decoder over all other MP3 decoders.
--ad=help List all available decoders.
Enabling compressed audio passthrough (AC3 and DTS via SPDIF/HDMI) with this option is not possible. Use --audio-spdif instead.
--volume=<value> Set the startup volume. 0 means silence, 100 means no volume reduction or amplification. Negative values can be passed for compatibility, but are treated as 0.
Since mpv 0.18.1, this always controls the internal mixer (aka "softvol").
--replaygain=<no|track|album> Adjust volume gain according to replaygain values stored in the file metadata. With --replaygain=no (the default), perform no adjustment.  With --replaygain=track, apply track gain. With --replaygain=album, apply album gain if present and fall back to track gain otherwise.
--replaygain-preamp=<db> Pre-amplification gain in dB to apply to the selected replaygain gain (default: 0).
--replaygain-clip=<yes|no> Prevent clipping caused by replaygain by automatically lowering the gain (default). Use --replaygain-clip=no to disable this.
--replaygain-fallback=<db> Gain in dB to apply if the file has no replay gain tags. This option is always applied if the replaygain logic is somehow inactive. If this is applied, no other replaygain options are applied.
--audio-delay=<sec> Audio delay in seconds (positive or negative float value). Positive values delay the audio, and negative values delay the video.
--mute=<yes|no|auto> Set startup audio mute status (default: no).
auto is a deprecated possible value that is equivalent to no.
See also: --volume.
--softvol=<no|yes|auto> Deprecated/unfunctional. Before mpv 0.18.1, this used to control whether to use the volume controls of the audio output driver or the internal mpv volume filter.
The current behavior is that softvol is always enabled, i.e. as if this option is set to yes. The other behaviors are not available anymore, although auto almost matches current behavior in most cases.
The no behavior is still partially available through the ao-volume and ao-mute properties. But there are no options to reset these.
--audio-demuxer=<[+]name> Use this audio demuxer type when using --audio-file. Use a '+' before the name to force it; this will skip some checks. Give the demuxer name as printed by --audio-demuxer=help.
--ad-lavc-ac3drc=<level> Select the Dynamic Range Compression level for AC-3 audio streams. <level> is a float value ranging from 0 to 1, where 0 means no compression (which is the default) and 1 means full compression (make loud passages more silent and vice versa). Values up to 6 are also accepted, but are purely experimental. This option only shows an effect if the AC-3 stream contains the required range compression information.
The standard mandates that DRC is enabled by default, but mpv (and some other players) ignore this for the sake of better audio quality.
--ad-lavc-downmix=<yes|no> Whether to request audio channel downmixing from the decoder (default: no).  Some decoders, like AC-3, AAC and DTS, can remix audio on decoding. The requested number of output channels is set with the --audio-channels option.  Useful for playing surround audio on a stereo system.
--ad-lavc-threads=<0-16> Number of threads to use for decoding. Whether threading is actually supported depends on codec. As of this writing, it's supported for some lossless codecs only. 0 means autodetect number of cores on the machine and use that, up to the maximum of 16 (default: 1).
--ad-lavc-o=<key>=<value>[,<key>=<value>[,...]] Pass AVOptions to libavcodec decoder. Note, a patch to make the o= unneeded and pass all unknown options through the AVOption system is welcome. A full list of AVOptions can be found in the FFmpeg manual.
--ad-spdif-dtshd=<yes|no>, --dtshd, --no-dtshd If DTS is passed through, use DTS-HD.
This and enabling passthrough via --ad are deprecated in favor of using --audio-spdif=dts-hd.
--audio-channels=<auto-safe|auto|layouts> Control which audio channels are output (e.g. surround vs. stereo). There are the following possibilities:
--audio-channels=auto-safe Use the system's preferred channel layout. If there is none (such as when accessing a hardware device instead of the system mixer), force stereo. Some audio outputs might simply accept any layout and do downmixing on their own.
--audio-channels=auto Send the audio device whatever it accepts, preferring the audio's original channel layout. Can cause issues with HDMI (see the warning below).