neulab/tldr huggingface dataset:
force  use terminal OSD even if video output active
The auto mode also enables terminal OSD if --video-osd=no was set.
--term-osd-bar, --no-term-osd-bar Enable printing a progress bar under the status line on the terminal.  (Disabled by default.)
--term-osd-bar-chars=<string> Customize the --term-osd-bar feature. The string is expected to consist of 5 characters (start, left space, position indicator, right space, end). You can use Unicode characters, but note that double- width characters will not be treated correctly.
Default: [-+-].
--term-playing-msg=<string> Print out a string after starting playback. The string is expanded for properties, e.g. --term-playing-msg='file: ${filename}' will print the string file: followed by a space and the currently played filename.
--term-status-msg=<string> Print out a custom string during playback instead of the standard status line. Expands properties. See Property Expansion.
--term-title=<string> Set the terminal title. Currently, this simply concatenates the escape sequence setting the window title with the provided (property expanded) string. This will mess up if the expanded string contain bytes that end the escape sequence, or if the terminal does not understand the sequence. The latter probably includes the regrettable win32.
Expands properties. See Property Expansion.
--msg-module Prepend module name to each console message.
--msg-time Prepend timing information to each console message. The time is in seconds since the player process was started (technically, slightly later actually), using a monotonic time source depending on the OS. This is CLOCK_MONOTONIC on sane UNIX variants.
Cache --cache=<yes|no|auto> Decide whether to use network cache settings (default: auto).
If enabled, use up to --cache-secs for the cache size (but still limited to --demuxer-max-bytes), and make the cached data seekable (if possible).  If disabled, --cache-pause and related are implicitly disabled.
The auto choice enables this depending on whether the stream is thought to involve network accesses or other slow media (this is an imperfect heuristic).
Before mpv 0.30.0, this used to accept a number, which specified the size of the cache in kilobytes. Use e.g. --cache --demuxer-max-bytes=123k instead.
--no-cache Turn off input stream caching. See --cache.
--cache-secs=<seconds> How many seconds of audio/video to prefetch if the cache is active. This overrides the --demuxer-readahead-secs option if and only if the cache is enabled and the value is larger. The default value is set to something very high, so the actually achieved readahead will usually be limited by the value of the --demuxer-max-bytes option. Setting this option is usually only useful for limiting readahead.
--cache-on-disk=<yes|no> Write packet data to a temporary file, instead of keeping them in memory.  This makes sense only with --cache. If the normal cache is disabled, this option is ignored.
You need to set --cache-dir to use this.
The cache file is append-only. Even if the player appears to prune data, the file space freed by it is not reused. The cache file is deleted when playback is closed.
Note that packet metadata is still kept in memory. --demuxer-max-bytes and related options are applied to metadata only. The size of this metadata  varies, but 50 MB per hour of media is typical. The cache statistics will report this metadats size, instead of the size of the cache file. If the metadata hits the size limits, the metadata is pruned (but not the cache file).
When the media is closed, the cache file is deleted. A cache file is generally worthless after the media is closed, and it's hard to retrieve any media data from it (it's not supported by design).
If the option is enabled at runtime, the cache file is created, but old data will remain in the memory cache. If the option is disabled at runtime, old data remains in the disk cache, and the cache file is not closed until the media is closed. If the option is disabled and enabled again, it will continue to use the cache file that was opened first.
--cache-dir=<path> Directory where to create temporary files (default: none).
Currently, this is used for --cache-on-disk only.
--cache-pause=<yes|no> Whether the player should automatically pause when the cache runs out of data and stalls decoding/playback (default: yes). If enabled, it will pause and unpause once more data is available, aka "buffering".
--cache-pause-wait=<seconds> Number of seconds the packet cache should have buffered before starting playback again if "buffering" was entered (default: 1). This can be used to control how long the player rebuffers if --cache-pause is enabled, and the demuxer underruns. If the given time is higher than the maximum set with --cache-secs or --demuxer-readahead-secs, or prefetching ends before that for some other reason (like file end or maximum configured cache size reached), playback resumes earlier.
--cache-pause-initial=<yes|no> Enter "buffering" mode before starting playback (default: no). This can be used to ensure playback starts smoothly, in exchange for waiting some time to prefetch network data (as controlled by --cache-pause-wait). For example, some common behavior is that playback starts, but network caches immediately underrun when trying to decode more data as playback progresses.
Another thing that can happen is that the network prefetching is so CPU demanding (due to demuxing in the background) that playback drops frames at first. In these cases, it helps enabling this option, and setting --cache-secs and --cache-pause-wait to roughly the same value.
This option also triggers when playback is restarted after seeking.
--cache-unlink-files=<immediate|whendone|no> Whether or when to unlink cache files (default: immediate). This affects cache files which are inherently temporary, and which make no sense to remain on disk after the player terminates. This is a debugging option.
immediate Unlink cache file after they were created. The cache files won't be visible anymore, even though they're in use. This ensures they are guaranteed to be removed from disk when the player terminates, even if it crashes.
whendone Delete cache files after they are closed.
no     Don't delete cache files. They will consume disk space without having a use.
--stream-buffer-size=<bytesize> Size of the low level stream byte buffer (default: 128KB). This is used as buffer between demuxer and low level I/O (e.g. sockets). Generally, this can be very small, and the main purpose is similar to the internal buffer FILE in the C standard library will have.
Half of the buffer is always used for guaranteed seek back, which is important for unseekable input.
There are known cases where this can help performance to set a large buffer:
1. mp4 files. libavformat may trigger many small seeks in both directions, depending on how the file was muxed.
2. Certain network filesystems, which do not have a cache, and where small reads can be inefficient.
In other cases, setting this to a large value can reduce performance.
Usually, read accesses are at half the buffer size, but it may happen that accesses are done alternating with smaller and larger sizes (this is due to the internal ring buffer wrap-around).
--vd-queue-enable=<yes|no>, --ad-queue-enable Enable running the video/audio decoder on a separate thread (default: no).  If enabled, the decoder is run on a separate thread, and a frame queue is put between decoder and higher level playback logic. The size of the frame queue is defined by the other options below.
This is probably quite pointless. libavcodec already has multithreaded decoding (enabled by default), which makes this largely unnecessary. It might help in some corner cases with high bandwidth video that is slow to decode (in these cases libavcodec would block the playback logic, while using a decoding thread would distribute the decoding time evenly without affecting the playback logic). In other situations, it will simply make seeking slower and use significantly more memory.
The queue size is restricted by the other --vd-queue-... options. The final queue size is the minimum as indicated by the option with the lowest limit. Each decoder/track has its own queue that may use the full configured queue size.
Most queue options can be changed at runtime. --vd-queue-enable itself (and the audio equivalent) update only if decoding is completely reinitialized. However, setting --vd-queue-max-samples=1 should almost lead to the same behavior as --vd-queue-enable=no, so that value can be used for effectively runtime enabling/disabling the queue.
This should not be used with hardware decoding. It is possible to enable this for audio, but it makes even less sense.
--vd-queue-max-bytes=<bytesize>, --ad-queue-max-bytes Maximum approximate allowed size of the queue. If exceeded, decoding will be stopped. The maximum size can be exceeded by about 1 frame.
--vd-queue-max-samples=<int>, --ad-queue-max-samples Maximum number of frames (video) or samples (audio) of the queue. The audio size may be exceeded by about 1 frame.
--vd-queue-max-secs=<seconds>, --ad-queue-max-secs Maximum number of seconds of media in the queue. The special value 0 means no limit is set. The queue size may be exceeded by about 2 frames. Timestamp resets may lead to random queue size usage.
Network --user-agent=<string> Use <string> as user agent for HTTP streaming.
--cookies, --no-cookies Support cookies when making HTTP requests. Disabled by default.
--cookies-file=<filename> Read HTTP cookies from <filename>. The file is assumed to be in Netscape format.
--http-header-fields=<field1,field2> Set custom HTTP fields when accessing HTTP stream.
mpv --http-header-fields='Field1: value1','Field2: value2' \ http://localhost:1234
Will generate HTTP request:
GET / HTTP/1.0 Host: localhost:1234 User-Agent: MPlayer Icy-MetaData: 1 Field1: value1 Field2: value2 Connection: close
--http-proxy=<proxy> URL of the HTTP/HTTPS proxy. If this is set, the http_proxy environment is ignored. The no_proxy environment variable is still respected. This option is silently ignored if it does not start with http://. Proxies are not used for https URLs. Setting this option does not try to make the ytdl script use the proxy.
--tls-ca-file=<filename> Certificate authority database file for use with TLS. (Silently fails with older FFmpeg or Libav versions.)
--tls-verify Verify peer certificates when using TLS (e.g. with https://...). (Silently fails with older FFmpeg or Libav versions.)
--tls-cert-file A file containing a certificate to use in the handshake with the peer.
--tls-key-file A file containing the private key for the certificate.
--referrer=<string> Specify a referrer path or URL for HTTP requests.
--network-timeout=<seconds> Specify the network timeout in seconds (default: 60 seconds). This affects at least HTTP. The special value 0 uses the FFmpeg/Libav defaults. If a protocol is used which does not support timeouts, this option is silently ignored.
WARNING: This breaks the RTSP protocol, because of inconsistent FFmpeg API regarding its internal timeout option. Not only does the RTSP timeout option accept different units (seconds instead of microseconds, causing mpv to pass it huge values), it will also overflow FFmpeg internal calculations. The worst is that merely setting the option will put RTSP into listening mode, which breaks any client uses. At time of this writing, the fix was not made effective yet. For this reason, this option is ignored (or should be ignored) on RTSP URLs. You can still set the timeout option directly with --demuxer-lavf-o.
--rtsp-transport=<lavf|udp|udp_multicast|tcp|http> Select RTSP transport method (default: tcp). This selects the underlying network transport when playing rtsp://... URLs. The value lavf leaves the decision to libavformat.
--hls-bitrate=<no|min|max|<rate>> If HLS streams are played, this option controls what streams are selected by default. The option allows the following parameters:
no     Don't do anything special. Typically, this will simply pick the first audio/video streams it can find.
min    Pick the streams with the lowest bitrate.
max    Same, but highest bitrate. (Default.)
Additionally, if the option is a number, the stream with the highest rate equal or below the option value is selected.
The bitrate as used is sent by the server, and there's no guarantee it's actually meaningful.
DVB --dvbin-prog=<string> This defines the program to tune to. Usually, you may specify this by using a stream URI like "dvb://ZDF HD", but you can tune to a different channel by writing to this property at runtime.  Also see dvbin-channel-switch-offset for more useful channel switching functionality.
--dvbin-card=<0-15> Specifies using card number 0-15 (default: 0).
--dvbin-file=<filename> Instructs mpv to read the channels list from <filename>. The default is in the mpv configuration directory (usually ~/.config/mpv) with the filename channels.conf.{sat,ter,cbl,atsc} (based on your card type) or channels.conf as a last resort.  For DVB-S/2 cards, a VDR 1.7.x format channel list is recommended as it allows tuning to DVB-S2 channels, enabling subtitles and decoding the PMT (which largely improves the demuxing).  Classic mplayer format channel lists are still supported (without these improvements), and for other card types, only limited VDR format channel list support is implemented (patches welcome).  For channels with dynamic PID switching or incomplete channels.conf, --dvbin-full-transponder or the magic PID 8192 are recommended.
--dvbin-timeout=<1-30> Maximum number of seconds to wait when trying to tune a frequency before giving up (default: 30).
--dvbin-full-transponder=<yes|no> Apply no filters on program PIDs, only tune to frequency and pass full transponder to demuxer.  The player frontend selects the streams from the full TS in this case, so the program which is shown initially may not match the chosen channel.  Switching between the programs is possible by cycling the program property. This is useful to record multiple programs on a single transponder, or to work around issues in the channels.conf.  It is also recommended to use this for channels which switch PIDs on-the-fly, e.g. for regional news.
Default: no
--dvbin-channel-switch-offset=<integer> This value is not meant for setting via configuration, but used in channel switching. An input.conf can cycle this value up and down to perform channel switching. This number effectively gives the offset to the initially tuned to channel in the channel list.
An example input.conf could contain: H cycle dvbin-channel-switch-offset up, K cycle dvbin-channel-switch-offset down
ALSA audio output options --alsa-device=<device> Deprecated, use --audio-device (requires alsa/ prefix).
--alsa-resample=yes Enable ALSA resampling plugin. (This is disabled by default, because some drivers report incorrect audio delay in some cases.)
--alsa-mixer-device=<device> Set the mixer device used with ao-volume (default: default).
--alsa-mixer-name=<name> Set the name of the mixer element (default: Master). This is for example PCM or Master.
--alsa-mixer-index=<number> Set the index of the mixer channel (default: 0). Consider the output of "amixer scontrols", then the index is the number that follows the name of the element.
--alsa-non-interleaved Allow output of non-interleaved formats (if the audio decoder uses this format). Currently disabled by default, because some popular ALSA plugins are utterly broken with non-interleaved formats.
--alsa-ignore-chmap Don't read or set the channel map of the ALSA device - only request the required number of channels, and then pass the audio as-is to it. This option most likely should not be used. It can be useful for debugging, or for static setups with a specially engineered ALSA configuration (in this case you should always force the same layout with --audio-channels, or it will work only for files which use the layout implicit to your ALSA device).
--alsa-buffer-time=<microseconds> Set the requested buffer time in microseconds. A value of 0 skips requesting anything from the ALSA API. This and the --alsa-periods option uses the ALSA near functions to set the requested parameters. If doing so results in an empty configuration set, setting these parameters is skipped.
Both options control the buffer size. A low buffer size can lead to higher CPU usage and audio dropouts, while a high buffer size can lead to higher latency in volume changes and other filtering.
--alsa-periods=<number> Number of periods requested from the ALSA API. See --alsa-buffer-time for further remarks.
GPU renderer options The following video options are currently all specific to --vo=gpu and --vo=libmpv only, which are the only VOs that implement them.
--scale=<filter> The filter function to use when upscaling video.
bilinear Bilinear hardware texture filtering (fastest, very low quality). This is the default for compatibility reasons.
spline36 Mid quality and speed. This is the default when using gpu-hq.
lanczos Lanczos scaling. Provides mid quality and speed. Generally worse than spline36, but it results in a slightly sharper image which is good for some content types. The number of taps can be controlled with scale-radius, but is best left unchanged.
(This filter is an alias for sinc-windowed sinc)
ewa_lanczos Elliptic weighted average Lanczos scaling. Also known as Jinc.  Relatively slow, but very good quality. The radius can be controlled with scale-radius. Increasing the radius makes the filter sharper but adds more ringing.
(This filter is an alias for jinc-windowed jinc)
ewa_lanczossharp A slightly sharpened version of ewa_lanczos, preconfigured to use an ideal radius and parameter. If your hardware can run it, this is probably what you should use by default.
mitchell Mitchell-Netravali. The B and C parameters can be set with --scale-param1 and --scale-param2. This filter is very good at downscaling (see --dscale).
oversample A version of nearest neighbour that (naively) oversamples pixels, so that pixels overlapping edges get linearly interpolated instead of rounded. This essentially removes the small imperfections and judder artifacts caused by nearest-neighbour interpolation, in exchange for adding some blur. This filter is good at temporal interpolation, and also known as "smoothmotion" (see --tscale).
linear A --tscale filter.
There are some more filters, but most are not as useful. For a complete list, pass help as value, e.g.:
mpv --scale=help
--cscale=<filter> As --scale, but for interpolating chroma information. If the image is not subsampled, this option is ignored entirely.
--dscale=<filter> Like --scale, but apply these filters on downscaling instead. If this option is unset, the filter implied by --scale will be applied.
--tscale=<filter> The filter used for interpolating the temporal axis (frames). This is only used if --interpolation is enabled. The only valid choices for --tscale are separable convolution filters (use --tscale=help to get a list). The default is mitchell.
Common --tscale choices include oversample, linear, catmull_rom, mitchell, gaussian, or bicubic. These are listed in increasing order of smoothness/blurriness, with bicubic being the smoothest/blurriest and oversample being the sharpest/least smooth.
--scale-param1=<value>, --scale-param2=<value>, --cscale-param1=<value>, --cscale-param2=<value>, --dscale-param1=<value>, --dscale-param2=<value>, --tscale-param1=<value>, --tscale-param2=<value> Set filter parameters. By default, these are set to the special string default, which maps to a scaler-specific default value. Ignored if the filter is not tunable. Currently, this affects the following filter parameters:
bcspline Spline parameters (B and C). Defaults to 0.5 for both.
gaussian Scale parameter (t). Increasing this makes the result blurrier.  Defaults to 1.
oversample Minimum distance to an edge before interpolation is used. Setting this to 0 will always interpolate edges, whereas setting it to 0.5 will never interpolate, thus behaving as if the regular nearest neighbour algorithm was used. Defaults to 0.0.
--scale-blur=<value>, --scale-wblur=<value>, --cscale-blur=<value>, --cscale-wblur=<value>, --dscale-blur=<value>, --dscale-wblur=<value>, --tscale-blur=<value>, --tscale-wblur=<value> Kernel/window scaling factor (also known as a blur factor). Decreasing this makes the result sharper, increasing it makes it blurrier (default 0). If set to 0, the kernel's preferred blur factor is used. Note that setting this too low (eg. 0.5) leads to bad results. It's generally recommended to stick to values between 0.8 and 1.2.
--scale-clamp=<0.0-1.0>, --cscale-clamp, --dscale-clamp, --tscale-clamp Specifies a weight bias to multiply into negative coefficients. Specifying --scale-clamp=1 has the effect of removing negative weights completely, thus effectively clamping the value range to [0-1]. Values between 0.0 and 1.0 can be specified to apply only a moderate diminishment of negative weights. This is especially useful for --tscale, where it reduces excessive ringing artifacts in the temporal domain (which typically manifest themselves as short flashes or fringes of black, mostly around moving edges) in exchange for potentially adding more blur. The default for --tscale-clamp is 1.0, the others default to 0.0.
--scale-cutoff=<value>, --cscale-cutoff=<value>, --dscale-cutoff=<value> Cut off the filter kernel prematurely once the value range drops below this threshold. Doing so allows more aggressive pruning of skippable coefficients by disregarding parts of the LUT which are effectively zeroed out by the window function. Only affects polar (EWA) filters. The default is 0.001 for each, which is perceptually transparent but provides a 10%-20% speedup, depending on the exact radius and filter kernel chosen.
--scale-taper=<value>, --scale-wtaper=<value>, --dscale-taper=<value>, --dscale-wtaper=<value>, --cscale-taper=<value>, --cscale-wtaper=<value>, --tscale-taper=<value>, --tscale-wtaper=<value> Kernel/window taper factor. Increasing this flattens the filter function.  Value range is 0 to 1. A value of 0 (the default) means no flattening, a value of 1 makes the filter completely flat (equivalent to a box function).  Values in between mean that some portion will be flat and the actual filter function will be squeezed into the space in between.
--scale-radius=<value>, --cscale-radius=<value>, --dscale-radius=<value>, --tscale-radius=<value> Set radius for tunable filters, must be a float number between 0.5 and 16.0. Defaults to the filter's preferred radius if not specified. Doesn't work for every scaler and VO combination.
Note that depending on filter implementation details and video scaling ratio, the radius that actually being used might be different (most likely being increased a bit).
--scale-antiring=<value>, --cscale-antiring=<value>, --dscale-antiring=<value>, --tscale-antiring=<value> Set the antiringing strength. This tries to eliminate ringing, but can introduce other artifacts in the process. Must be a float number between 0.0 and 1.0. The default value of 0.0 disables antiringing entirely.
Note that this doesn't affect the special filters bilinear and bicubic_fast, nor does it affect any polar (EWA) scalers.
--scale-window=<window>, --cscale-window=<window>, --dscale-window=<window>, --tscale-window=<window> (Advanced users only) Choose a custom windowing function for the kernel.  Defaults to the filter's preferred window if unset. Use --scale-window=help to get a list of supported windowing functions.
--scale-wparam=<window>, --cscale-wparam=<window>, --cscale-wparam=<window>, --tscale-wparam=<window> (Advanced users only) Configure the parameter for the window function given by --scale-window etc. By default, these are set to the special string default, which maps to a window-specific default value. Ignored if the window is not tunable. Currently, this affects the following window parameters:
kaiser Window parameter (alpha). Defaults to 6.33.
blackman Window parameter (alpha). Defaults to 0.16.
gaussian Scale parameter (t). Increasing this makes the window wider. Defaults to 1.
--scaler-lut-size=<4..10> Set the size of the lookup texture for scaler kernels (default: 6). The actual size of the texture is 2^N for an option value of N. So the lookup texture with the default setting uses 64 samples.
All weights are linearly interpolated from those samples, so increasing the size of lookup table might improve the accuracy of scaler.
--scaler-resizes-only Disable the scaler if the video image is not resized. In that case, bilinear is used instead of whatever is set with --scale. Bilinear will reproduce the source image perfectly if no scaling is performed.  Enabled by default. Note that this option never affects --cscale.
--correct-downscaling When using convolution based filters, extend the filter size when downscaling. Increases quality, but reduces performance while downscaling.
This will perform slightly sub-optimally for anamorphic video (but still better than without it) since it will extend the size to match only the milder of the scale factors between the axes.
Note: this option is ignored when using bilinear downscaling (the default).
--linear-downscaling Scale in linear light when downscaling. It should only be used with a --fbo-format that has at least 16 bit precision. This option has no effect on HDR content.
--linear-upscaling Scale in linear light when upscaling. Like --linear-downscaling, it should only be used with a --fbo-format that has at least 16 bits precisions. This is not usually recommended except for testing/specific purposes. Users are advised to either enable --sigmoid-upscaling or keep both options disabled (i.e. scaling in gamma light).
--sigmoid-upscaling When upscaling, use a sigmoidal color transform to avoid emphasizing ringing artifacts. This is incompatible with and replaces --linear-upscaling. (Note that sigmoidization also requires linearization, so the LINEAR rendering step fires in both cases)
--sigmoid-center The center of the sigmoid curve used for --sigmoid-upscaling, must be a float between 0.0 and 1.0. Defaults to 0.75 if not specified.
--sigmoid-slope The slope of the sigmoid curve used for --sigmoid-upscaling, must be a float between 1.0 and 20.0. Defaults to 6.5 if not specified.
--interpolation Reduce stuttering caused by mismatches in the video fps and display refresh rate (also known as judder).
WARNING: This requires setting the --video-sync option to one of the display- modes, or it will be silently disabled.  This was not required before mpv 0.14.0.
This essentially attempts to interpolate the missing frames by convoluting the video along the temporal axis. The filter used can be controlled using the --tscale setting.
--interpolation-threshold=<0..1,-1> Threshold below which frame ratio interpolation gets disabled (default: 0.01). This is calculated as abs(disphz/vfps - 1) < threshold, where vfps is the speed-adjusted video FPS, and disphz the display refresh rate. (The speed-adjusted video FPS is roughly equal to the normal video FPS, but with slowdown and speedup applied. This matters if you use --video-sync=display-resample to make video run synchronously to the display FPS, or if you change the speed property.)
The default is intended to enable interpolation in scenarios where retiming with the --video-sync=display-* cannot adjust the speed of the video sufficiently for smooth playback. For example if a video is 60.00 FPS and your display refresh rate is 59.94 Hz, interpolation will never be activated, since the mismatch is within 1% of the refresh rate. The default also handles the scenario when mpv cannot determine the container FPS, such as during certain live streams, and may dynamically toggle interpolation on and off. In this scenario, the default would be to not use interpolation but rather to allow --video-sync=display-* to retime the video to match display refresh rate. See --video-sync-max-video-change for more information about how mpv will retime video.
Also note that if you use e.g. --video-sync=display-vdrop, small deviations in the rate can disable interpolation and introduce a discontinuity every other minute.
Set this to -1 to disable this logic.
--opengl-pbo Enable use of PBOs. On some drivers this can be faster, especially if the source video size is huge (e.g. so called "4K" video). On other drivers it might be slower or cause latency issues.
--dither-depth=<N|no|auto> Set dither target depth to N. Default: no.
no     Disable any dithering done by mpv.
auto   Automatic selection. If output bit depth cannot be detected, 8 bits per component are assumed.
8      Dither to 8 bit output.
Note that the depth of the connected video display device cannot be detected. Often, LCD panels will do dithering on their own, which conflicts with this option and leads to ugly output.
--dither-size-fruit=<2-8> Set the size of the dither matrix (default: 6). The actual size of the matrix is (2^N) x (2^N) for an option value of N, so a value of 6 gives a size of 64x64. The matrix is generated at startup time, and a large matrix can take rather long to compute (seconds).
Used in --dither=fruit mode only.
--dither=<fruit|ordered|error-diffusion|no> Select dithering algorithm (default: fruit). (Normally, the --dither-depth option controls whether dithering is enabled.)
The error-diffusion option requires compute shader support. It also requires large amount of shared memory to run, the size of which depends on both the kernel (see --error-diffusion option below) and the height of video window. It will fallback to fruit dithering if there is no enough shared memory to run the shader.
--temporal-dither Enable temporal dithering. (Only active if dithering is enabled in general.) This changes between 8 different dithering patterns on each frame by changing the orientation of the tiled dithering matrix. Unfortunately, this can lead to flicker on LCD displays, since these have a high reaction time.
--temporal-dither-period=<1-128> Determines how often the dithering pattern is updated when --temporal-dither is in use. 1 (the default) will update on every video frame, 2 on every other frame, etc.
--error-diffusion=<kernel> The error diffusion kernel to use when --dither=error-diffusion is set.
simple Propagate error to only two adjacent pixels. Fastest but low quality.
sierra-lite Fast with reasonable quality. This is the default.
floyd-steinberg Most notable error diffusion kernel.
atkinson Looks different from other kernels because only fraction of errors will be propagated during dithering. A typical use case of this kernel is saving dithered screenshot (in window mode). This kernel produces slightly smaller file, with still reasonable dithering quality.
There are other kernels (use --error-diffusion=help to list) but most of them are much slower and demanding even larger amount of shared memory.  Among these kernels, burkes achieves a good balance between performance and quality, and probably is the one you want to try first.
--gpu-debug Enables GPU debugging. What this means depends on the API type. For OpenGL, it calls glGetError(), and requests a debug context. For Vulkan, it enables validation layers.
--opengl-swapinterval=<n> Interval in displayed frames between two buffer swaps. 1 is equivalent to enable VSYNC, 0 to disable VSYNC. Defaults to 1 if not specified.
Note that this depends on proper OpenGL vsync support. On some platforms and drivers, this only works reliably when in fullscreen mode. It may also require driver-specific hacks if using multiple monitors, to ensure mpv syncs to the right one. Compositing window managers can also lead to bad results, as can missing or incorrect display FPS information (see --override-display-fps).
--vulkan-device=<device name> The name of the Vulkan device to use for rendering and presentation. Use --vulkan-device=help to see the list of available devices and their names. If left unspecified, the first enumerated hardware Vulkan device will be used.
--vulkan-swap-mode=<mode> Controls the presentation mode of the vulkan swapchain. This is similar to the --opengl-swapinterval option.
auto   Use the preferred swapchain mode for the vulkan context. (Default)
fifo   Non-tearing, vsync blocked. Similar to "VSync on".
fifo-relaxed Tearing, vsync blocked. Late frames will tear instead of stuttering.
mailbox Non-tearing, not vsync blocked. Similar to "triple buffering".
immediate Tearing, not vsync blocked. Similar to "VSync off".
--vulkan-queue-count=<1..8> Controls the number of VkQueues used for rendering (limited by how many your device supports). In theory, using more queues could enable some parallelism between frames (when using a --swapchain-depth higher than 1), but it can also slow things down on hardware where there's no true parallelism between queues. (Default: 1)
--vulkan-async-transfer Enables the use of async transfer queues on supported vulkan devices. Using them allows transfer operations like texture uploads and blits to happen concurrently with the actual rendering, thus improving overall throughput and power consumption. Enabled by default, and should be relatively safe.
--vulkan-async-compute Enables the use of async compute queues on supported vulkan devices. Using this, in theory, allows out-of-order scheduling of compute shaders with graphics shaders, thus enabling the hardware to do more effective work while waiting for pipeline bubbles and memory operations. Not beneficial on all GPUs. It's worth noting that if async compute is enabled, and the device supports more compute queues than graphics queues (bound by the restrictions set by --vulkan-queue-count), mpv will internally try and prefer the use of compute shaders over fragment shaders wherever possible. Enabled by default, although Nvidia users may want to disable it.
--vulkan-disable-events Disable the use of VkEvents, for debugging purposes or for compatibility with some older drivers / vulkan portability layers that don't provide working VkEvent support.
--vulkan-display-display=<n> The index of the display, on the selected Vulkan device, to present on when using the displayvk GPU context. Use --vulkan-display-display=help to see the list of available displays. If left unspecified, the first enumerated display will be used.
--vulkan-display-mode=<n> The index of the display mode, of the selected Vulkan display, to use when using the displayvk GPU context. Use --vulkan-display-mode=help to see the list of available modes. If left unspecified, the first enumerated mode will be used.
--vulkan-display-plane=<n> The index of the plane, on the selected Vulkan device, to present on when using the displayvk GPU context. Use --vulkan-display-plane=help to see the list of available planes. If left unspecified, the first enumerated plane will be used.
--d3d11-exclusive-fs=<yes|no> Switches the D3D11 swap chain fullscreen state to 'fullscreen' when fullscreen video is requested. Also known as "exclusive fullscreen" or "D3D fullscreen" in other applications. Gives mpv full control of rendering on the swap chain's screen. Off by default.
--d3d11-warp=<yes|no|auto> Use WARP (Windows Advanced Rasterization Platform) with the D3D11 GPU backend (default: auto). This is a high performance software renderer. By default, it is only used when the system has no hardware adapters that support D3D11. While the extended GPU features will work with WARP, they can be very slow.
--d3d11-feature-level=<12_1|12_0|11_1|11_0|10_1|10_0|9_3|9_2|9_1> Select a specific feature level when using the D3D11 GPU backend. 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.  Most extended GPU features will not work at 9_x feature levels.
--d3d11-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.
--d3d11-sync-interval=<0..4> Schedule each frame to be presented for this number of VBlank intervals.  (default: 1) Setting to 1 will enable VSync, setting to 0 will disable it.
--d3d11-adapter=<adapter name|help> Select a specific D3D11 adapter to utilize for D3D11 rendering. Will pick the default adapter if unset. Alternatives are listed when the name "help" is given.
Checks for matches based on the start of the string, case insensitive. Thus, if the description of the adapter starts with the vendor name, that can be utilized as the selection parameter.
Hardware decoders utilizing the D3D11 rendering abstraction's helper functionality to receive a device, such as D3D11VA or DXVA2's DXGI mode, will be affected by this choice.
--d3d11-output-format=<auto|rgba8|bgra8|rgb10_a2|rgba16f> Select a specific D3D11 output format to utilize for D3D11 rendering.  "auto" is the default, which will pick either rgba8 or rgb10_a2 depending on the configured desktop bit depth. rgba16f and bgra8 are left out of the autodetection logic, and are available for manual testing.
NOTE: Desktop bit depth querying is only available from an API available from Windows 10. Thus on older systems it will only automatically utilize the rgba8 output format.
--d3d11-output-csp=<auto|srgb|linear|pq|bt.2020> Select a specific D3D11 output color space to utilize for D3D11 rendering.  "auto" is the default, which will select the color space of the desktop on which the swap chain is located.
Values other than "srgb" and "pq" have had issues in testing, so they are mostly available for manual testing.
NOTE: Swap chain color space configuration is only available from an API available from Windows 10. Thus on older systems it will not work.
--d3d11va-zero-copy=<yes|no> By default, when using hardware decoding with --gpu-api=d3d11, the video image will be copied (GPU-to-GPU) from the decoder surface to a shader resource. Set this option to avoid that copy by sampling directly from the decoder image. This may increase performance and reduce power usage, but can cause the image to be sampled incorrectly on the bottom and right edges due to padding, and may invoke driver bugs, since Direct3D 11 technically does not allow sampling from a decoder surface (though most drivers support it.)
Currently only relevant for --gpu-api=d3d11.
--wayland-app-id=<string> Set the client app id for Wayland-based video output methods (default: mpv).
--wayland-disable-vsync=<yes|no> Disable vsync for the wayland contexts (default: no). Useful for benchmarking the wayland context when combined with video-sync=display-desync, --no-audio, and --untimed=yes. Only works with --gpu-context=wayland and --gpu-context=waylandvk.
--wayland-edge-pixels-pointer=<value> Defines the size of an edge border (default: 10) to initiate client side resize events in the wayland contexts with the mouse. This is only active if there are no server side decorations from the compositor.
--wayland-edge-pixels-touch=<value> Defines the size of an edge border (default: 32) to initiate client side resizes events in the wayland contexts with touch events.
--spirv-compiler=<compiler> Controls which compiler is used to translate GLSL to SPIR-V. This is (currently) only relevant for --gpu-api=vulkan and --gpu-api=d3d11.  The possible choices are currently only:
auto   Use the first available compiler. (Default)
shaderc Use libshaderc, which is an API wrapper around glslang. This is generally the most preferred, if available.
NOTE: This option is deprecated, since there is only one reasonable value.  It may be removed in the future.
--glsl-shader=<file>, --glsl-shaders=<file-list> Custom GLSL hooks. These are a flexible way to add custom fragment shaders, which can be injected at almost arbitrary points in the rendering pipeline, and access all previous intermediate textures.
Each use of the --glsl-shader option will add another file to the internal list of shaders, while --glsl-shaders takes a list of files, and overwrites the internal list with it. The latter is a path list option (see List Options for details).
The syntax is not stable yet and may change any time.
The general syntax of a user shader looks like this:
//!METADATA ARGS... //!METADATA ARGS...
vec4 hook() { ... return something; }
Each section of metadata, along with the non-metadata lines after it, defines a single block. There are currently two types of blocks, HOOKs and TEXTUREs.
A TEXTURE block can set the following options:
TEXTURE <name> (required) The name of this texture. Hooks can then bind the texture under this name using BIND. This must be the first option of the texture block.
SIZE <width> [<height>] [<depth>] (required) The dimensions of the texture. The height and depth are optional. The type of texture (1D, 2D or 3D) depends on the number of components specified.
FORMAT <name> (required) The texture format for the samples. Supported texture formats are listed in debug logging when the gpu VO is initialized (look for Texture formats:). Usually, this follows OpenGL naming conventions.  For example, rgb16 provides 3 channels with normalized 16 bit components. One oddity are float formats: for example, rgba16f has 16 bit internal precision, but the texture data is provided as 32 bit floats, and the driver converts the data on texture upload.
Although format names follow a common naming convention, not all of them are available on all hardware, drivers, GL versions, and so on.
FILTER <LINEAR|NEAREST> The min/magnification filter used when sampling from this texture.
BORDER <CLAMP|REPEAT|MIRROR> The border wrapping mode used when sampling from this texture.
Following the metadata is a string of bytes in hexadecimal notation that define the raw texture data, corresponding to the format specified by FORMAT, on a single line with no extra whitespace.
A HOOK block can set the following options:
HOOK <name> (required) The texture which to hook into. May occur multiple times within a metadata block, up to a predetermined limit. See below for a list of hookable textures.
DESC <title> User-friendly description of the pass. This is the name used when representing this shader in the list of passes for property vo-passes.
BIND <name> Loads a texture (either coming from mpv or from a TEXTURE block) and makes it available to the pass. When binding textures from mpv, this will also set up macros to facilitate accessing it properly. See below for a list. By default, no textures are bound. The special name HOOKED can be used to refer to the texture that triggered this pass.
SAVE <name> Gives the name of the texture to save the result of this pass into. By default, this is set to the special name HOOKED which has the effect of overwriting the hooked texture.
WIDTH <szexpr>, HEIGHT <szexpr> Specifies the size of the resulting texture for this pass. szexpr refers to an expression in RPN (reverse polish notation), using the operators + - * / > < !, floating point literals, and references to sizes of existing texture (such as MAIN.width or CHROMA.height), OUTPUT, or NATIVE_CROPPED (size of an input texture cropped after pan-and-scan, video-align-x/y, video-pan-x/y, etc. and possibly prescaled). By default, these are set to HOOKED.w and HOOKED.h, espectively.
WHEN <szexpr> Specifies a condition that needs to be true (non-zero) for the shader stage to be evaluated. If it fails, it will silently be omitted. (Note that a shader stage like this which has a dependency on an optional hook point can still cause that hook point to be saved, which has some minor overhead)
OFFSET <ox oy | ALIGN> Indicates a pixel shift (offset) introduced by this pass. These pixel offsets will be accumulated and corrected during the next scaling pass (cscale or scale). The default values are 0 0 which correspond to no shift. Note that offsets are ignored when not overwriting the hooked texture.
A special value of ALIGN will attempt to fix existing offset of HOOKED by align it with reference. It requires HOOKED to be resizable (see below). It works transparently with fragment shader. For compute shader, the predefined texmap macro is required to handle coordinate mapping.
COMPONENTS <n> Specifies how many components of this pass's output are relevant and should be stored in the texture, up to 4 (rgba). By default, this value is equal to the number of components in HOOKED.
COMPUTE <bw> <bh> [<tw> <th>] Specifies that this shader should be treated as a compute shader, with the block size bw and bh. The compute shader will be dispatched with however many blocks are necessary to completely tile over the output.  Within each block, there will be tw*th threads, forming a single work group. In other words: tw and th specify the work group size, which can be different from the block size. So for example, a compute shader with bw, bh = 32 and tw, th = 8 running on a 500x500 texture would dispatch 16x16 blocks (rounded up), each with 8x8 threads.
Compute shaders in mpv are treated a bit different from fragment shaders. Instead of defining a vec4 hook that produces an output sample, you directly define void hook which writes to a fixed writeonly image unit named out_image (this is bound by mpv) using imageStore. To help translate texture coordinates in the absence of vertices, mpv provides a special function NAME_map(id) to map from the texel space of the output image to the texture coordinates for all bound textures. In particular, NAME_pos is equivalent to NAME_map(gl_GlobalInvocationID), although using this only really makes sense if (tw,th) == (bw,bh).
Each bound mpv texture (via BIND) will make available the following definitions to that shader pass, where NAME is the name of the bound texture:
vec4 NAME_tex(vec2 pos) The sampling function to use to access the texture at a certain spot (in texture coordinate space, range [0,1]). This takes care of any necessary normalization conversions.
vec4 NAME_texOff(vec2 offset) Sample the texture at a certain offset in pixels. This works like NAME_tex but additionally takes care of necessary rotations, so that sampling at e.g. vec2(-1,0) is always one pixel to the left.
vec2 NAME_pos The local texture coordinate of that texture, range [0,1].
vec2 NAME_size The (rotated) size in pixels of the texture.
mat2 NAME_rot The rotation matrix associated with this texture. (Rotates pixel space to texture coordinates)
vec2 NAME_pt The (unrotated) size of a single pixel, range [0,1].
float NAME_mul The coefficient that needs to be multiplied into the texture contents in order to normalize it to the range [0,1].
sampler NAME_raw The raw bound texture itself. The use of this should be avoided unless absolutely necessary.
Normally, users should use either NAME_tex or NAME_texOff to read from the texture. For some shaders however , it can be better for performance to do custom sampling from NAME_raw, in which case care needs to be taken to respect NAME_mul and NAME_rot.
In addition to these parameters, the following uniforms are also globally available:
float random A random number in the range [0-1], different per frame.
int frame A simple count of frames rendered, increases by one per frame and never resets (regardless of seeks).
vec2 input_size The size in pixels of the input image (possibly cropped and prescaled).
vec2 target_size The size in pixels of the visible part of the scaled (and possibly cropped) image.
vec2 tex_offset Texture offset introduced by user shaders or options like panscan, video-align-x/y, video-pan-x/y.
Internally, vo_gpu may generate any number of the following textures.  Whenever a texture is rendered and saved by vo_gpu, all of the passes that have hooked into it will run, in the order they were added by the user. This is a list of the legal hook points:
RGB, LUMA, CHROMA, ALPHA, XYZ (resizable) Source planes (raw). Which of these fire depends on the image format of the source.
CHROMA_SCALED, ALPHA_SCALED (fixed) Source planes (upscaled). These only fire on subsampled content.
NATIVE (resizable) The combined image, in the source colorspace, before conversion to RGB.
MAINPRESUB (resizable) The image, after conversion to RGB, but before --blend-subtitles=video is applied.
MAIN (resizable) The main image, after conversion to RGB but before upscaling.
LINEAR (fixed) Linear light image, before scaling. This only fires when --linear-upscaling, --linear-downscaling or --sigmoid-upscaling is in effect.
SIGMOID (fixed) Sigmoidized light, before scaling. This only fires when --sigmoid-upscaling is in effect.
PREKERNEL (fixed) The image immediately before the scaler kernel runs.
POSTKERNEL (fixed) The image immediately after the scaler kernel runs.
SCALED (fixed) The final upscaled image, before color management.