neulab/tldr huggingface dataset:
OUTPUT (fixed) The final output image, after color management but before dithering and drawing to screen.
Only the textures labelled with resizable may be transformed by the pass. When overwriting a texture marked fixed, the WIDTH, HEIGHT and OFFSET must be left at their default values.
--glsl-shader=<file> CLI/config file only alias for --glsl-shaders-append.
--deband Enable the debanding algorithm. This greatly reduces the amount of visible banding, blocking and other quantization artifacts, at the expense of very slightly blurring some of the finest details. In practice, it's virtually always an improvement - the only reason to disable it would be for performance.
--deband-iterations=<1..16> The number of debanding steps to perform per sample. Each step reduces a bit more banding, but takes time to compute. Note that the strength of each step falls off very quickly, so high numbers (>4) are practically useless.  (Default 1)
--deband-threshold=<0..4096> The debanding filter's cut-off threshold. Higher numbers increase the debanding strength dramatically but progressively diminish image details.  (Default 32)
--deband-range=<1..64> The debanding filter's initial radius. The radius increases linearly for each iteration. A higher radius will find more gradients, but a lower radius will smooth more aggressively. (Default 16)
If you increase the --deband-iterations, you should probably decrease this to compensate.
--deband-grain=<0..4096> Add some extra noise to the image. This significantly helps cover up remaining quantization artifacts. Higher numbers add more noise. (Default 48)
--sharpen=<value> If set to a value other than 0, enable an unsharp masking filter. Positive values will sharpen the image (but add more ringing and aliasing). Negative values will blur the image. If your GPU is powerful enough, consider alternatives like the ewa_lanczossharp scale filter, or the --scale-blur option.
--opengl-glfinish Call glFinish() before swapping buffers (default: disabled). Slower, but might improve results when doing framedropping. Can completely ruin performance. The details depend entirely on the OpenGL driver.
--opengl-waitvsync Call glXWaitVideoSyncSGI after each buffer swap (default: disabled).  This may or may not help with video timing accuracy and frame drop. It's possible that this makes video output slower, or has no effect at all.
X11/GLX only.
--opengl-dwmflush=<no|windowed|yes|auto> Calls DwmFlush after swapping buffers on Windows (default: auto). It also sets SwapInterval(0) to ignore the OpenGL timing. Values are: no (disabled), windowed (only in windowed mode), yes (also in full screen).
The value auto will try to determine whether the compositor is active, and calls DwmFlush only if it seems to be.
This may help to get more consistent frame intervals, especially with high-fps clips - which might also reduce dropped frames. Typically, a value of windowed should be enough, since full screen may bypass the DWM.
--angle-d3d11-feature-level=<11_0|10_1|10_0|9_3> Selects a specific feature level when using the ANGLE backend with D3D11.  By default, the highest available feature level is used. This option can be used to select a lower feature level, which is mainly useful for debugging.  Note that OpenGL ES 3.0 is only supported at feature level 10_1 or higher.  Most extended OpenGL features will not work at lower feature levels (similar to --gpu-dumb-mode).
Windows with ANGLE only.
--angle-d3d11-warp=<yes|no|auto> Use WARP (Windows Advanced Rasterization Platform) when using the ANGLE backend with D3D11 (default: auto). This is a high performance software renderer. By default, it is used when the Direct3D hardware does not support Direct3D 11 feature level 9_3. While the extended OpenGL features will work with WARP, they can be very slow.
--angle-egl-windowing=<yes|no|auto> Use ANGLE's built in EGL windowing functions to create a swap chain (default: auto). If this is set to no and the D3D11 renderer is in use, ANGLE's built in swap chain will not be used and a custom swap chain that is optimized for video rendering will be created instead. If set to auto, a custom swap chain will be used for D3D11 and the built in swap chain will be used for D3D9. This option is mainly for debugging purposes, in case the custom swap chain has poor performance or does not work.
If set to yes, the --angle-max-frame-latency, --angle-swapchain-length and --angle-flip options will have no effect.
--angle-flip=<yes|no> Enable flip-model presentation, which avoids unnecessarily copying the backbuffer by sharing surfaces with the DWM (default: yes). This may cause performance issues with older drivers. If flip-model presentation is not supported (for example, on Windows 7 without the platform update), mpv will automatically fall back to the older bitblt presentation model.
If set to no, the --angle-swapchain-length option will have no effect.
--angle-renderer=<d3d9|d3d11|auto> Forces a specific renderer when using the ANGLE backend (default: auto). In auto mode this will pick D3D11 for systems that support Direct3D 11 feature level 9_3 or higher, and D3D9 otherwise. This option is mainly for debugging purposes. Normally there is no reason to force a specific renderer, though --angle-renderer=d3d9 may give slightly better performance on old hardware. Note that the D3D9 renderer only supports OpenGL ES 2.0, so most extended OpenGL features will not work if this renderer is selected (similar to --gpu-dumb-mode).
--macos-force-dedicated-gpu=<yes|no> Deactivates the automatic graphics switching and forces the dedicated GPU.  (default: no)
macOS only.
--cocoa-cb-sw-renderer=<yes|no|auto> Use the Apple Software Renderer when using cocoa-cb (default: auto). If set to no the software renderer is never used and instead fails when a the usual pixel format could not be created, yes will always only use the software renderer, and auto only falls back to the software renderer when the usual pixel format couldn't be created.
--cocoa-cb-10bit-context=<yes|no> Creates a 10bit capable pixel format for the context creation (default: yes).  Instead of 8bit integer framebuffer a 16bit half-float framebuffer is requested.
--macos-title-bar-appearance=<appearance> Sets the appearance of the title bar (default: auto). Not all combinations of appearances and --macos-title-bar-material materials make sense or are unique. Appearances that are not supported by you current macOS version fall back to the default value.  macOS and cocoa-cb only
<appearance> can be one of the following:
auto   Detects the system settings and sets the title bar appearance appropriately. On macOS 10.14 it also detects run time changes.
aqua   The standard macOS Light appearance.
darkAqua The standard macOS Dark appearance. (macOS 10.14+)
vibrantLight Light vibrancy appearance with.
vibrantDark Dark vibrancy appearance with.
aquaHighContrast Light Accessibility appearance. (macOS 10.14+)
darkAquaHighContrast Dark Accessibility appearance. (macOS 10.14+)
vibrantLightHighContrast Light vibrancy Accessibility appearance.  (macOS 10.14+)
vibrantDarkHighContrast Dark vibrancy Accessibility appearance.  (macOS 10.14+)
--macos-title-bar-material=<material> Sets the material of the title bar (default: titlebar). All deprecated materials should not be used on macOS 10.14+ because their functionality is not guaranteed. Not all combinations of materials and --macos-title-bar-appearance appearances make sense or are unique.  Materials that are not supported by you current macOS version fall back to the default value.  macOS and cocoa-cb only
<material> can be one of the following:
titlebar The standard macOS titel bar material.
selection The standard macOS selection material.
menu   The standard macOS menu material. (macOS 10.11+)
popover The standard macOS popover material. (macOS 10.11+)
sidebar The standard macOS sidebar material. (macOS 10.11+)
headerView The standard macOS header view material.  (macOS 10.14+)
sheet  The standard macOS sheet material. (macOS 10.14+)
windowBackground The standard macOS window background material.  (macOS 10.14+)
hudWindow The standard macOS hudWindow material. (macOS 10.14+)
fullScreen The standard macOS full screen material.  (macOS 10.14+)
toolTip The standard macOS tool tip material. (macOS 10.14+)
contentBackground The standard macOS content background material.  (macOS 10.14+)
underWindowBackground The standard macOS under window background material. (macOS 10.14+)
underPageBackground The standard macOS under page background material. (deprecated in macOS 10.14+)
dark   The standard macOS dark material.  (deprecated in macOS 10.14+)
light  The standard macOS light material.  (macOS 10.14+)
mediumLight The standard macOS mediumLight material.  (macOS 10.11+, deprecated in macOS 10.14+)
ultraDark The standard macOS ultraDark material.  (macOS 10.11+ deprecated in macOS 10.14+)
--macos-title-bar-color=<color> Sets the color of the title bar (default: completely transparent). Is influenced by --macos-title-bar-appearance and --macos-title-bar-material.  See --sub-color for color syntax.
--macos-fs-animation-duration=<default|0-1000> Sets the fullscreen resize animation duration in ms (default: default).  The default value is slightly less than the system's animation duration (500ms) to prevent some problems when the end of an async animation happens at the same time as the end of the system wide fullscreen animation. Setting anything higher than 500ms will only prematurely cancel the resize animation after the system wide animation ended. The upper limit is still set at 1000ms since it's possible that Apple or the user changes the system defaults. Anything higher than 1000ms though seems too long and shouldn't be set anyway.  (macOS and cocoa-cb only)
--macos-app-activation-policy=<regular|accessory|prohibited> Changes the App activation policy. With accessory the mpv icon in the Dock can be hidden. (default: regular)
--macos-geometry-calculation=<visible|whole> This changes the rectangle which is used to calculate the screen position and size of the window (default: visible). visible takes the the menu bar and Dock into account and the window is only positioned/sized within the visible screen frame rectangle, whole takes the whole screen frame rectangle and ignores the menu bar and Dock. Other previous restrictions still apply, like the window can't be placed on top of the menu bar etc.
--android-surface-size=<WxH> Set dimensions of the rendering surface used by the Android gpu context.  Needs to be set by the embedding application if the dimensions change during runtime (i.e. if the device is rotated), via the surfaceChanged callback.
Android with --gpu-context=android only.
--gpu-sw Continue even if a software renderer is detected.
--gpu-context=<sys> The value auto (the default) selects the GPU context. You can also pass help to get a complete list of compiled in backends (sorted by autoprobe order).
auto   auto-select (default)
cocoa  Cocoa/macOS (deprecated, use --vo=libmpv instead)
win    Win32/WGL
winvk  VK_KHR_win32_surface
angle  Direct3D11 through the OpenGL ES translation layer ANGLE. This supports almost everything the win backend does (if the ANGLE build is new enough).
dxinterop (experimental) Win32, using WGL for rendering and Direct3D 9Ex for presentation. Works on Nvidia and AMD. Newer Intel chips with the latest drivers may also work.
d3d11  Win32, with native Direct3D 11 rendering.
x11    X11/GLX
x11vk  VK_KHR_xlib_surface
wayland Wayland/EGL
waylandvk VK_KHR_wayland_surface
drm    DRM/EGL
displayvk VK_KHR_display. This backend is roughly the Vukan equivalent of DRM/EGL, allowing for direct rendering via Vulkan without a display manager.
x11egl X11/EGL
android Android/EGL. Requires --wid be set to an android.view.Surface.
--gpu-api=<type> Controls which type of graphics APIs will be accepted:
auto   Use any available API (default)
opengl Allow only OpenGL (requires OpenGL 2.1+ or GLES 2.0+)
vulkan Allow only Vulkan (requires a valid/working --spirv-compiler)
d3d11  Allow only --gpu-context=d3d11
--opengl-es=<mode> Controls which type of OpenGL context will be accepted:
auto   Allow all types of OpenGL (default)
yes    Only allow GLES
no     Only allow desktop/core GL
--fbo-format=<fmt> Selects the internal format of textures used for FBOs. The format can influence performance and quality of the video output. fmt can be one of: rgb8, rgb10, rgb10_a2, rgb16, rgb16f, rgb32f, rgba12, rgba16, rgba16f, rgba16hf, rgba32f.
Default: auto, which first attempts to utilize 16bit float (rgba16f, rgba16hf), and falls back to rgba16 if those are not available.  Finally, attempts to utilize rgb10_a2 or rgba8 if all of the previous formats are not available.
--gamma-factor=<0.1..2.0> Set an additional raw gamma factor (default: 1.0). If gamma is adjusted in other ways (like with the --gamma option or key bindings and the gamma property), the value is multiplied with the other gamma value.
Recommended values based on the environmental brightness:
1.0    Pitch black or dimly lit room (default)
1.1    Moderately lit room, home
1.2    Brightly illuminated room, office
NOTE: This is based around the assumptions of typical movie content, which contains an implicit end-to-end of about 0.8 from scene to display. For bright environments it can be useful to cancel that out.
--gamma-auto Automatically corrects the gamma value depending on ambient lighting conditions (adding a gamma boost for bright rooms).
With ambient illuminance of 16 lux, mpv will pick the 1.0 gamma value (no boost), and slightly increase the boost up until 1.2 for 256 lux.
NOTE: Only implemented on macOS.
--target-prim=<value> Specifies the primaries of the display. Video colors will be adapted to this colorspace when ICC color management is not being used. Valid values are:
auto   Disable any adaptation, except for atypical color spaces. Specifically, wide/unusual gamuts get automatically adapted to BT.709, while standard gamut (i.e. BT.601 and BT.709) content is not touched. (default)
bt.470m ITU-R BT.470 M
bt.601-525 ITU-R BT.601 (525-line SD systems, eg. NTSC), SMPTE 170M/240M
bt.601-625 ITU-R BT.601 (625-line SD systems, eg. PAL/SECAM), ITU-R BT.470 B/G
bt.709 ITU-R BT.709 (HD), IEC 61966-2-4 (sRGB), SMPTE RP177 Annex B
bt.2020 ITU-R BT.2020 (UHD)
apple  Apple RGB
adobe  Adobe RGB (1998)
prophoto ProPhoto RGB (ROMM)
cie1931 CIE 1931 RGB (not to be confused with CIE XYZ)
dci-p3 DCI-P3 (Digital Cinema Colorspace), SMPTE RP431-2
v-gamut Panasonic V-Gamut (VARICAM) primaries
s-gamut Sony S-Gamut (S-Log) primaries
--target-trc=<value> Specifies the transfer characteristics (gamma) of the display. Video colors will be adjusted to this curve when ICC color management is not being used.  Valid values are:
auto   Disable any adaptation, except for atypical transfers. Specifically, HDR or linear light source material gets automatically converted to gamma 2.2, while SDR content is not touched. (default)
bt.1886 ITU-R BT.1886 curve (assuming infinite contrast)
srgb   IEC 61966-2-4 (sRGB)
linear Linear light output
gamma1.8 Pure power curve (gamma 1.8), also used for Apple RGB
gamma2.0 Pure power curve (gamma 2.0)
gamma2.2 Pure power curve (gamma 2.2)
gamma2.4 Pure power curve (gamma 2.4)
gamma2.6 Pure power curve (gamma 2.6)
gamma2.8 Pure power curve (gamma 2.8), also used for BT.470-BG
pq     ITU-R BT.2100 PQ (Perceptual quantizer) curve, aka SMPTE ST2084
hlg    ITU-R BT.2100 HLG (Hybrid Log-gamma) curve, aka ARIB STD-B67
v-log  Panasonic V-Log (VARICAM) curve
s-log1 Sony S-Log1 curve
s-log2 Sony S-Log2 curve
NOTE: When using HDR output formats, mpv will encode to the specified curve but it will not set any HDMI flags or other signalling that might be required for the target device to correctly display the HDR signal.  The user should independently guarantee this before using these signal formats for display.
--target-peak=<auto|nits> Specifies the measured peak brightness of the output display, in cd/m^2 (AKA nits). The interpretation of this brightness depends on the configured --target-trc. In all cases, it imposes a limit on the signal values that will be sent to the display. If the source exceeds this brightness level, a tone mapping filter will be inserted. For HLG, it has the additional effect of parametrizing the inverse OOTF, in order to get colorimetrically consistent results with the mastering display. For SDR, or when using an ICC (profile (--icc-profile), setting this to a value above 203 essentially causes the display to be treated as if it were an HDR display in disguise. (See the note below)
In auto mode (the default), the chosen peak is an appropriate value based on the TRC in use. For SDR curves, it uses 203. For HDR curves, it uses 203 * the transfer function's nominal peak.
NOTE: When using an SDR transfer function, this is normally not needed, and setting it may lead to very unexpected results. The one time it is useful is if you want to calibrate a HDR display using traditional transfer functions and calibration equipment. In such cases, you can set your HDR display to a high brightness such as 800 cd/m^2, and then calibrate it to a standard curve like gamma2.8. Setting this value to 800 would then instruct mpv to essentially treat it as an HDR display with the given peak. This may be a good alternative in environments where PQ or HLG input to the display is not possible, and makes it possible to use HDR displays with mpv regardless of operating system support for HDMI HDR metadata.
In such a configuration, we highly recommend setting --tone-mapping to mobius or even clip.
--tone-mapping=<value> Specifies the algorithm used for tone-mapping images onto the target display. This is relevant for both HDR->SDR conversion as well as gamut reduction (e.g. playing back BT.2020 content on a standard gamut display).  Valid values are:
clip   Hard-clip any out-of-range values. Use this when you care about perfect color accuracy for in-range values at the cost of completely distorting out-of-range values. Not generally recommended.
mobius Generalization of Reinhard to a Möbius transform with linear section.  Smoothly maps out-of-range values while retaining contrast and colors for in-range material as much as possible. Use this when you care about color accuracy more than detail preservation. This is somewhere in between clip and reinhard, depending on the value of --tone-mapping-param.
reinhard Reinhard tone mapping algorithm. Very simple continuous curve.  Preserves overall image brightness but uses nonlinear contrast, which results in flattening of details and degradation in color accuracy.
hable  Similar to reinhard but preserves both dark and bright details better (slightly sigmoidal), at the cost of slightly darkening / desaturating everything. Developed by John Hable for use in video games. Use this when you care about detail preservation more than color/brightness accuracy. This is roughly equivalent to --tone-mapping=reinhard --tone-mapping-param=0.24. If possible, you should also enable --hdr-compute-peak for the best results.
bt.2390 Perceptual tone mapping curve (EETF) specified in ITU-R Report BT.2390.  This is the recommended curve to use for typical HDR-mastered content.  (Default)
gamma  Fits a logarithmic transfer between the tone curves.
linear Linearly stretches the entire reference gamut to (a linear multiple of) the display.
--tone-mapping-param=<value> Set tone mapping parameters. By default, this is set to the special string default, which maps to an algorithm-specific default value. Ignored if the tone mapping algorithm is not tunable. This affects the following tone mapping algorithms:
clip   Specifies an extra linear coefficient to multiply into the signal before clipping. Defaults to 1.0.
mobius Specifies the transition point from linear to mobius transform. Every value below this point is guaranteed to be mapped 1:1. The higher the value, the more accurate the result will be, at the cost of losing bright details. Defaults to 0.3, which due to the steep initial slope still preserves in-range colors fairly accurately.
reinhard Specifies the local contrast coefficient at the display peak. Defaults to 0.5, which means that in-gamut values will be about half as bright as when clipping.
gamma  Specifies the exponent of the function. Defaults to 1.8.
linear Specifies the scale factor to use while stretching. Defaults to 1.0.
--tone-mapping-max-boost=<1.0..10.0> Upper limit for how much the tone mapping algorithm is allowed to boost the average brightness by over-exposing the image. The default value of 1.0 allows no additional brightness boost. A value of 2.0 would allow over-exposing by a factor of 2, and so on. Raising this setting can help reveal details that would otherwise be hidden in dark scenes, but raising it too high will make dark scenes appear unnaturally bright.
--hdr-compute-peak=<auto|yes|no> Compute the HDR peak and frame average brightness per-frame instead of relying on tagged metadata. These values are averaged over local regions as well as over several frames to prevent the value from jittering around too much. This option basically gives you dynamic, per-scene tone mapping.  Requires compute shaders, which is a fairly recent OpenGL feature, and will probably also perform horribly on some drivers, so enable at your own risk.  The special value auto (default) will enable HDR peak computation automatically if compute shaders and SSBOs are supported.
--hdr-peak-decay-rate=<1.0..1000.0> The decay rate used for the HDR peak detection algorithm (default: 100.0).  This is only relevant when --hdr-compute-peak is enabled. Higher values make the peak decay more slowly, leading to more stable values at the cost of more "eye adaptation"-like effects (although this is mitigated somewhat by --hdr-scene-threshold). A value of 1.0 (the lowest possible) disables all averaging, meaning each frame's value is used directly as measured, but doing this is not recommended for "noisy" sources since it may lead to excessive flicker. (In signal theory terms, this controls the time constant "tau" of an IIR low pass filter)
--hdr-scene-threshold-low=<0.0..100.0>, --hdr-scene-threshold-high=<0.0..100.0> The lower and upper thresholds (in dB) for a brightness difference to be considered a scene change (default: 5.5 low, 10.0 high). This is only relevant when --hdr-compute-peak is enabled. Normally, small fluctuations in the frame brightness are compensated for by the peak averaging mechanism, but for large jumps in the brightness this can result in the frame remaining too bright or too dark for up to several seconds, depending on the value of --hdr-peak-decay-rate. To counteract this, when the brightness between the running average and the current frame exceeds the low threshold, mpv will make the averaging filter more aggressive, up to the limit of the high threshold (at which point the filter becomes instant).
--tone-mapping-desaturate=<0.0..1.0> Apply desaturation for highlights (default: 0.75). The parameter controls the strength of the desaturation curve. A value of 0.0 completely disables it, while a value of 1.0 means that overly bright colors will tend towards white. (This is not always the case, especially not for highlights that are near primary colors)
Values in between apply progressively more/less aggressive desaturation.  This setting helps prevent unnaturally oversaturated colors for super-highlights, by (smoothly) turning them into less saturated (per channel tone mapped) colors instead. This makes images feel more natural, at the cost of chromatic distortions for out-of-range colors. The default value of 0.75 provides a good balance. Setting this to 0.0 preserves the chromatic accuracy of the tone mapping process.
--tone-mapping-desaturate-exponent=<0.0..20.0> This setting controls the exponent of the desaturation curve, which controls how bright a color needs to be in order to start being desaturated. The default of 1.5 provides a reasonable balance.  Decreasing this exponent makes the curve more aggressive.
--gamut-warning If enabled, mpv will mark all clipped/out-of-gamut pixels that exceed a given threshold (currently hard-coded to 101%). The affected pixels will be inverted to make them stand out. Note: This option applies after the effects of all of mpv's color space transformation / tone mapping options, so it's a good idea to combine this with --tone-mapping=clip and use --target-prim to set the gamut to simulate. For example, --target-prim=bt.709 would make mpv highlight all pixels that exceed the gamut of a standard gamut (sRGB) display. This option also does not work well with ICC profiles, since the 3DLUTs are always generated against the source color space and have chromatically-accurate clipping built in.
--gamut-clipping If enabled (default: yes), mpv will colorimetrically clip out-of-gamut colors by desaturating them (preserving luma), rather than hard-clipping each component individually. This should make playback of wide gamut content on typical (standard gamut) monitors look much more aesthetically pleasing and less blown-out.
--use-embedded-icc-profile Load the embedded ICC profile contained in media files such as PNG images.  (Default: yes). Note that this option only works when also using a display ICC profile (--icc-profile or --icc-profile-auto), and also requires LittleCMS 2 support.
--icc-profile=<file> Load an ICC profile and use it to transform video RGB to screen output.  Needs LittleCMS 2 support compiled in. This option overrides the --target-prim, --target-trc and --icc-profile-auto options.
--icc-profile-auto Automatically select the ICC display profile currently specified by the display settings of the operating system.
NOTE: On Windows, the default profile must be an ICC profile. WCS profiles are not supported.
Applications using libmpv with the render API need to provide the ICC profile via MPV_RENDER_PARAM_ICC_PROFILE.
--icc-cache-dir=<dirname> Store and load the 3D LUTs created from the ICC profile in this directory.  This can be used to speed up loading, since LittleCMS 2 can take a while to create a 3D LUT. Note that these files contain uncompressed LUTs. Their size depends on the --icc-3dlut-size, and can be very big.
NOTE: This is not cleaned automatically, so old, unused cache files may stick around indefinitely.
--icc-intent=<value> Specifies the ICC intent used for the color transformation (when using --icc-profile).
0      perceptual
1      relative colorimetric (default)
2      saturation
3      absolute colorimetric
--icc-3dlut-size=<r>x<g>x<b> Size of the 3D LUT generated from the ICC profile in each dimension.  Default is 64x64x64. Sizes may range from 2 to 512.
--icc-force-contrast=<no|0-1000000|inf> Override the target device's detected contrast ratio by a specific value.  This is detected automatically from the profile if possible, but for some profiles it might be missing, causing the contrast to be assumed as infinite. As a result, video may appear darker than intended. If this is the case, setting this option might help. This only affects BT.1886 content. The default of no means to use the profile values. The special value inf causes the BT.1886 curve to be treated as a pure power gamma 2.4 function.
--blend-subtitles=<yes|video|no> Blend subtitles directly onto upscaled video frames, before interpolation and/or color management (default: no). Enabling this causes subtitles to be affected by --icc-profile, --target-prim, --target-trc, --interpolation, --gamma-factor and --glsl-shaders. It also increases subtitle performance when using --interpolation.
The downside of enabling this is that it restricts subtitles to the visible portion of the video, so you can't have subtitles exist in the black margins below a video (for example).
If video is selected, the behavior is similar to yes, but subs are drawn at the video's native resolution, and scaled along with the video.
WARNING: This changes the way subtitle colors are handled. Normally, subtitle colors are assumed to be in sRGB and color managed as such. Enabling this makes them treated as being in the video's color space instead. This is good if you want things like softsubbed ASS signs to match the video colors, but may cause SRT subtitles or similar to look slightly off.
--alpha=<blend-tiles|blend|yes|no> Decides what to do if the input has an alpha component.
blend-tiles Blend the frame against a 16x16 gray/white tiles background (default).
blend  Blend the frame against the background color (--background, normally black).
yes    Try to create a framebuffer with alpha component. This only makes sense if the video contains alpha information (which is extremely rare) or if you make the background color transparent. May not be supported on all platforms. If alpha framebuffers are unavailable, it silently falls back on a normal framebuffer. Note that if you set the --fbo-format option to a non-default value, a format with alpha must be specified, or this won't work. Whether this really works depends on the windowing system and desktop environment.
no     Ignore alpha component.
--opengl-rectangle-textures Force use of rectangle textures (default: no). Normally this shouldn't have any advantages over normal textures. Note that hardware decoding overrides this flag. Could be removed any time.
--background=<color> Color used to draw parts of the mpv window not covered by video. See the --sub-color option for how colors are defined.
--gpu-tex-pad-x, --gpu-tex-pad-y Enlarge the video source textures by this many pixels. For debugging only (normally textures are sized exactly, but due to hardware decoding interop we may have to deal with additional padding, which can be tested with these options). Could be removed any time.
--opengl-early-flush=<yes|no|auto> Call glFlush() after rendering a frame and before attempting to display it (default: auto). Can fix stuttering in some cases, in other cases probably causes it. The auto mode will call glFlush() only if the renderer is going to wait for a while after rendering, instead of flipping GL front and backbuffers immediately (i.e. it doesn't call it in display-sync mode).
On macOS this is always deactivated because it only causes performance problems and other regressions.
--gpu-dumb-mode=<yes|no|auto> This mode is extremely restricted, and will disable most extended features. That includes high quality scalers and custom shaders!
It is intended for hardware that does not support FBOs (including GLES, which supports it insufficiently), or to get some more performance out of bad or old hardware.
This mode is forced automatically if needed, and this option is mostly useful for debugging. The default of auto will enable it automatically if nothing uses features which require FBOs.
This option might be silently removed in the future.
--gpu-shader-cache-dir=<dirname> Store and load compiled GLSL shaders in this directory. Normally, shader compilation is very fast, so this is usually not needed. It mostly matters for GPU APIs that require internally recompiling shaders to other languages, for example anything based on ANGLE or Vulkan. Enabling this can improve startup performance on these platforms.
Miscellaneous --display-tags=tag1,tags2,... Set the list of tags that should be displayed on the terminal. Tags that are in the list, but are not present in the played file, will not be shown.  If a value ends with *, all tags are matched by prefix (though there is no general globbing). Just passing * essentially filtering.
The default includes a common list of tags, call mpv with --list-options to see it.
--mc=<seconds/frame> Maximum A-V sync correction per frame (in seconds)
--autosync=<factor> Gradually adjusts the A/V sync based on audio delay measurements. Specifying --autosync=0, the default, will cause frame timing to be based entirely on audio delay measurements. Specifying --autosync=1 will do the same, but will subtly change the A/V correction algorithm. An uneven video framerate in a video which plays fine with --no-audio can often be helped by setting this to an integer value greater than 1. The higher the value, the closer the timing will be to --no-audio. Try --autosync=30 to smooth out problems with sound drivers which do not implement a perfect audio delay measurement. With this value, if large A/V sync offsets occur, they will only take about 1 or 2 seconds to settle out. This delay in reaction time to sudden A/V offsets should be the only side effect of turning this option on, for all sound drivers.
--video-timing-offset=<seconds> Control how long before video display target time the frame should be rendered (default: 0.050). If a video frame should be displayed at a certain time, the VO will start rendering the frame earlier, and then will perform a blocking wait until the display time, and only then "swap" the frame to display. The rendering cannot start before the previous frame is displayed, so this value is implicitly limited by the video framerate. With normal video frame rates, the default value will ensure that rendering is always immediately started after the previous frame was displayed. On the other hand, setting a too high value can reduce responsiveness with low FPS value.
For client API users using the render API (or the deprecated opengl-cb API), this option is interesting, because you can stop the render API from limiting your FPS (see mpv_render_context_render() documentation).
This applies only to audio timing modes (e.g. --video-sync=audio). In other modes (--video-sync=display-...), video timing relies on vsync blocking, and this option is not used.
--video-sync=<audio|...> How the player synchronizes audio and video.
If you use this option, you usually want to set it to display-resample to enable a timing mode that tries to not skip or repeat frames when for example playing 24fps video on a 24Hz screen.
The modes starting with display- try to output video frames completely synchronously to the display, using the detected display vertical refresh rate as a hint how fast frames will be displayed on average. These modes change video speed slightly to match the display. See --video-sync-...  options for fine tuning. The robustness of this mode is further reduced by making a some idealized assumptions, which may not always apply in reality. Behavior can depend on the VO and the system's video and audio drivers.  Media files must use constant framerate. Section-wise VFR might work as well with some container formats (but not e.g. mkv).
Under some circumstances, the player automatically reverts to audio mode for some time or permanently. This can happen on very low framerate video, or if the framerate cannot be detected.
Also in display-sync modes it can happen that interruptions to video playback (such as toggling fullscreen mode, or simply resizing the window) will skip the video frames that should have been displayed, while audio mode will display them after the renderer has resumed (typically resulting in a short A/V desync and the video "catching up").
Before mpv 0.30.0, there was a fallback to audio mode on severe A/V desync. This was changed for the sake of not sporadically stopping. Now, display-desync does what it promises and may desync with audio by an arbitrary amount, until it is manually fixed with a seek.
These modes also require a vsync blocked presentation mode. For OpenGL, this translates to --opengl-swapinterval=1. For Vulkan, it translates to --vulkan-swap-mode=fifo (or fifo-relaxed).
The modes with desync in their names do not attempt to keep audio/video in sync. They will slowly (or quickly) desync, until e.g. the next seek happens. These modes are meant for testing, not serious use.
audio  Time video frames to audio. This is the most robust mode, because the player doesn't have to assume anything about how the display behaves. The disadvantage is that it can lead to occasional frame drops or repeats. If audio is disabled, this uses the system clock. This is the default mode.
display-resample Resample audio to match the video. This mode will also try to adjust audio speed to compensate for other drift.  (This means it will play the audio at a different speed every once in a while to reduce the A/V difference.)
display-resample-vdrop Resample audio to match the video. Drop video frames to compensate for drift.
display-resample-desync Like the previous mode, but no A/V compensation.
display-vdrop Drop or repeat video frames to compensate desyncing video. (Although it should have the same effects as audio, the implementation is very different.)
display-adrop Drop or repeat audio data to compensate desyncing video. This mode will cause severe audio artifacts if the real monitor refresh rate is too different from the reported or forced rate. Since mpv 0.33.0, this acts on entire audio frames, instead of single samples.
display-desync Sync video to display, and let audio play on its own.
desync Sync video according to system clock, and let audio play on its own.
--video-sync-max-factor=<value> Maximum multiple for which to try to fit the video's FPS to the display's FPS (default: 5).
For example, if this is set to 1, the video FPS is forced to an integer multiple of the display FPS, as long as the speed change does not exceed the value set by --video-sync-max-video-change.
See --interpolation-threshold for how this option affects interpolation.
This is mostly for testing, and the option may be randomly changed in the future without notice.
--video-sync-max-video-change=<value> Maximum speed difference in percent that is applied to video with --video-sync=display-... (default: 1). Display sync mode will be disabled if the monitor and video refresh way do not match within the given range. It tries multiples as well: playing 30 fps video on a 60 Hz screen will duplicate every second frame. Playing 24 fps video on a 60 Hz screen will play video in a 2-3-2-3-... pattern.
The default settings are not loose enough to speed up 23.976 fps video to 25 fps. We consider the pitch change too extreme to allow this behavior by default. Set this option to a value of 5 to enable it.
Note that in the --video-sync=display-resample mode, audio speed will additionally be changed by a small amount if necessary for A/V sync. See --video-sync-max-audio-change.
--video-sync-max-audio-change=<value> Maximum additional speed difference in percent that is applied to audio with --video-sync=display-... (default: 0.125). Normally, the player plays the audio at the speed of the video. But if the difference between audio and video position is too high, e.g. due to drift or other timing errors, it will attempt to speed up or slow down audio by this additional factor. Too low values could lead to video frame dropping or repeating if the A/V desync cannot be compensated, too high values could lead to chaotic frame dropping due to the audio "overshooting" and skipping multiple video frames before the sync logic can react.
--mf-fps=<value> Framerate used when decoding from multiple PNG or JPEG files with mf:// (default: 1).
--mf-type=<value> Input file type for mf:// (available: jpeg, png, tga, sgi). By default, this is guessed from the file extension.
--stream-dump=<destination-filename> Instead of playing a file, read its byte stream and write it to the given destination file. The destination is overwritten. Can be useful to test network-related behavior.
--stream-lavf-o=opt1=value1,opt2=value2,... Set AVOptions on streams opened with libavformat. Unknown or misspelled options are silently ignored. (They are mentioned in the terminal output in verbose mode, i.e. --v. In general we can't print errors, because other options such as e.g. user agent are not available with all protocols, and printing errors for unknown options would end up being too noisy.)
--vo-mmcss-profile=<name> (Windows only.)  Set the MMCSS profile for the video renderer thread (default: Playback).
--priority=<prio> (Windows only.)  Set process priority for mpv according to the predefined priorities available under Windows.
Possible values of <prio>: idle|belownormal|normal|abovenormal|high|realtime
--force-media-title=<string> Force the contents of the media-title property to this value. Useful for scripts which want to set a title, without overriding the user's setting in --title.
--external-files=<file-list> Load a file and add all of its tracks. This is useful to play different files together (for example audio from one file, video from another), or for advanced --lavfi-complex used (like playing two video files at the same time).
Unlike --sub-files and --audio-files, this includes all tracks, and does not cause default stream selection over the "proper" file. This makes it slightly less intrusive. (In mpv 0.28.0 and before, this was not quite strictly enforced.)
--external-file=<file> CLI/config file only alias for --external-files-append. Each use of this option will add a new external file.
--cover-art-files=<file-list> Use an external file as cover art while playing audio. This makes it appear on the track list and subject to automatic track selection. Options like --audio-display control whether such tracks are supposed to be selected.
(The difference to loading a file with --external-files is that video tracks will be marked as being pictures, which affects the auto-selection method. If the passed file is a video, only the first frame will be decoded and displayed. Enabling the cover art track during playback may show a random frame if the source file is a video. Normally you're not supposed to pass videos to this option, so this paragraph describes the behavior coincidentally resulting from implementation details.)
--cover-art-file=<file> CLI/config file only alias for --cover-art-files-append. Each use of this option will add a new external file.
--cover-art-auto=<no|exact|fuzzy|all> Whether to load _external_ cover art automatically. Similar to --sub-auto and --audio-file-auto. If a video already has tracks (which are not marked as cover art), external cover art will not be loaded.
no     Don't automatically load cover art.
exact  Load the media filename with an image file extension.
fuzzy  Load all cover art containing the media filename and filenames in an internal whitelist, such as cover.jpg (default).
all    Load all images in the current directory.
See --cover-art-files for details about what constitutes cover art.
See --audio-display how to control display of cover art (this can be used to disable cover art that is part of the file).
--autoload-files=<yes|no> Automatically load/select external files (default: yes).
If set to no, then do not automatically load external files as specified by --sub-auto, --audio-file-auto and --cover-art-auto. If external files are forcibly added (like with --sub-files), they will not be auto-selected.
This does not affect playlist expansion, redirection, or other loading of referenced files like with ordered chapters.
--record-file=<file> Deprecated, use --stream-record, or the dump-cache command.
Record the current stream to the given target file. The target file will always be overwritten without asking.
This was deprecated because it isn't very nice to use. For one, seeking while this is enabled will be directly reflected in the output, which was not useful and annoying.
--stream-record=<file> Write received/read data from the demuxer to the given output file. The output file will always be overwritten without asking. The output format is determined by the extension of the output file.
Switching streams or seeking during recording might result in recording being stopped and/or broken files. Use with care.
Seeking outside of the demuxer cache will result in "skips" in the output file, but seeking within  the demuxer cache should not affect recording. One exception is when you seek back far enough to exceed the forward buffering size, in which case the cache stops actively reading. This will return in dropped data if it's a live stream.
If this is set at runtime, the old file is closed, and the new file is opened. Note that this will write only data that is appended at the end of the cache, and the already cached data cannot be written. You can try the dump-cache command as an alternative.
External files (--audio-file etc.) are ignored by this, it works on the "main" file only. Using this with files using ordered chapters or EDL files will also not work correctly in general.
There are some glitches with this because it uses FFmpeg's libavformat for writing the output file. For example, it's typical that it will only work if the output format is the same as the input format. This is the case even if it works with the ffmpeg tool. One reason for this is that ffmpeg and its libraries contain certain hacks and workarounds for these issues, that are unavailable to outside users.
This replaces --record-file. It is similar to the ancient/removed --stream-capture/-capture options, and provides better behavior in most cases (i.e. actually works).
--lavfi-complex=<string> Set a "complex" libavfilter filter, which means a single filter graph can take input from multiple source audio and video tracks. The graph can result in a single audio or video output (or both).
Currently, the filter graph labels are used to select the participating input tracks and audio/video output. The following rules apply:
• A label of the form aidN selects audio track N as input (e.g. aid1).
• A label of the form vidN selects video track N as input.
• A label named ao will be connected to the audio output.
• A label named vo will be connected to the video output.
Each label can be used only once. If you want to use e.g. an audio stream for multiple filters, you need to use the asplit filter. Multiple video or audio outputs are not possible, but you can use filters to merge them into one.
It's not possible to change the tracks connected to the filter at runtime, unless you explicitly change the lavfi-complex property and set new track assignments. When the graph is changed, the track selection is changed according to the used labels as well.
Other tracks, as long as they're not connected to the filter, and the corresponding output is not connected to the filter, can still be freely changed with the normal methods.
Note that the normal filter chains (--af, --vf) are applied between the complex graphs (e.g. ao label) and the actual output.
• --lavfi-complex='[aid1] [aid2] amix [ao]' Play audio track 1 and 2 at the same time.
• --lavfi-complex='[vid1] [vid2] vstack [vo]' Stack video track 1 and 2 and play them at the same time. Note that both tracks need to have the same width, or filter initialization will fail (you can add scale filters before the vstack filter to fix the size).  To load a video track from another file, you can use --external-file=other.mkv.
• --lavfi-complex='[aid1] asplit [t1] [ao] ; [t1] showvolume [t2] ; [vid1] [t2] overlay [vo]' Play audio track 1, and overlay the measured volume for each speaker over video track 1.
• null:// --lavfi-complex='life [vo]' A libavfilter source-only filter (Conways' Life Game).
See the FFmpeg libavfilter documentation for details on the available filters.
--metadata-codepage=<codepage> Codepage for various input metadata (default: utf-8). This affects how file tags, chapter titles, etc. are interpreted. You can for example set this to auto to enable autodetection of the codepage. (This is not the default because non-UTF-8 codepages are an obscure fringe use-case.)
See --sub-codepage option on how codepages are specified and further details regarding autodetection and codepage conversion. (The underlying code is the same.)
Conversion is not applied to metadata that is updated at runtime.
Debugging --unittest=<name> Run an internal unit test. There are multiple, and the name specifies which.
The special value all-simple runs all tests which do not need further setup (other arguments and such). Some tests may need additional arguments to do anything useful.
On success, the player binary exits with exit status 0, otherwise it returns with an undefined non-0 exit status (it may crash or abort itself on test failures).
This is only enabled if built with --enable-tests, and should normally be enabled and used by developers only.
Audio output drivers are interfaces to different audio output facilities. The syntax is:
--ao=<driver1,driver2,...[,]> Specify a priority list of audio output drivers to be used.
If the list has a trailing ',', mpv will fall back on drivers not contained in the list.
NOTE: See --ao=help for a list of compiled-in audio output drivers. The driver --ao=alsa is preferred. --ao=pulse is preferred on systems where PulseAudio is used. On BSD systems, --ao=oss is preferred.
alsa (Linux only) ALSA audio output driver
See ALSA audio output options for options specific to this AO.