Skip to content
Guido Cella edited this page Jul 4, 2024 · 124 revisions

Table of Contents

Does mpv have an official GUI?

No. But there is the OSC (on-screen-controller), which lets you control playback with the mouse. Requires mpv to be compiled with Lua support.

There are some 3rd party GUI frontends listed here.

Tearing

Tearing is a very annoying artifact that makes it look like the video has a horizontal line across the video. The video isn’t properly joining on that line. The line can be fixed or moving. Sometimes it’s not a line, but a bunch of blocks. It can be unnoticeable if there is no movement, but very apparent if the camera moves e.g. at low speed.

Tearing is generally not something a video player can do anything about. It depends on the hardware, drivers, the video output selected in mpv (VO), and possibly the desktop environment/compositor.

Changing the compositor settings can sometimes help with tearing.

MacOS (OSX)

Never seen it tearing.

Windows

Windows uses the native d3d11 backend by default now. If you experience problems, try playing with any of the --d3d11-... options.

Use --d3d11-adapter=help to see the description name of all GPU in your system.

Example;
Available D3D11 adapters:
description: Intel(R) HD Graphics 630
description: NVIDIA GeForce GTX 1080 Ti
description: AMD Radeon RX 5700 XT
description: Radeon (TM) RX 470 Graphics
description: Microsoft Basic Render Driver
Windows always use IntelHD as default when you are using Intel with i-GPU Processor, you can try switching to another GPU for utilize D3D11 rendering, --vo=gpu, --gpu-api=d3d11, --angle-renderer=auto, --d3d11-adapter=..., --d3d11-sync-interval=1. Example; --d3d11-adapter=Radeon (TM) RX 470 Graphics.

You can try forcing other backends with --gpu-context=.... dxinterop seems to perform best generally (might be outdated), but it will crash randomly with some older buggy Intel drivers. The deprecated --vo=direct3d should roughly behave like --angle-renderer=d3d9, but may be faster due to using fixed-function legacy APIs (but does not support hardware decoding without copy-back).

X11/Nvidia

Nvidia should generally not tear. Sometimes, it tears in windowed mode, but not in fullscreen (solution unknown). There are additional problems with multimonitor systems.

  • Try enabling ForceFullCompositionPipeline.
  • Try with and without a compositor.
  • Try disabling the composite extension in xorg.conf:

    Section "Extensions"
        Option "Composite" "Disable"
    EndSection
  • Set the performance mode to maximum performance. Energy saving often interferes with proper vo_opengl operation, and sometimes even appears to cause tearing.
  • Try --vo=vdpau.

  • To fix tearing under KDE, create file /etc/profile.d/kwin.sh with content:

    export __GL_SYNC_TO_VBLANK=1
    export __GL_YIELD=USLEEP

X11/Nvidia with PRIME

If your Xorg-server is older than ABI version 23, or your kernel is older than version 4.5, or your Nvidia driver is not up to date, then you will inevitably get tearing due to the lack of PRIME buffer synchronization. You cannot fix this tearing with any of the other methods described on this page. Assume the fetal position and cry, or switch to using your Intel GPU instead.

X11/Intel

Intel tears out of the box. However, most of the time, tearing with the gpu vo (the default) can be fixed by enabling a compositor. If this doesn't apply to you, try the following options.

  • Try enabling SNA and the TearFree option.

    Unfortunately, this can cause stability issues - GL applications sometimes randomly crash. Somewhere, there’s a claim that adding i915.semaphores=1 to your kernel parameters fixes the crashes.
  • Try disabling SNA by using UXA (on older hardware).
  • Try --x11-bypass-compositor=no
  • Try --vo=xv --xv-adaptor=N, and try 0 or 1 for N. This may fix tearing if the other methods fail, but keep in mind that using Xv with mpv is strongly discouraged.
  • Try --vo=vaapi. Although this is Intel’s native video output method, it seems to fix tearing only very rarely. Do keep in mind though that the vaapi vo does not provide the high quality rendering that the gpu vo is capable of

  • Try --vo=sdl. This will likely use your 2d acceleration, which means that this won't fix tearing if you experience tearing with any of the non-gpu VOs. As with vo=vaapi, it doesn't offer the features that gpu offers.

  • If you are using Xorg's new "modesetting" driver and are not using a compositing window manager (for example, you are using a plain window manager such as Awesome without a desktop manager like Gnome or KDE), you might need to run a compositor during video play-back. Compton might solve the issue if started with its glx backend:
    1. Install Compton from a package manager or compile from source
    2. Start Compton in a terminal as follows: compton --backend=glx
    3. Start mpv
    This archived post explains the procedure in more details.

X11/AMD

  • The official drivers (AMDGPU-PRO/fglrx) are completely broken; so just avoid them altogether.
  • With amdgpu, you need to enable the TearFree option (either via xrandr --set TearFree on or via xorg.conf) to prevent tearing when not in fullscreen, unless you are using a compositor.
  • If you still get tearing in fullscreen mode when using vulkan, add option "EnablePageFlip" "off" to the Device section of your xorg.conf.
  • Unrelated, but if you have performance issues, try echo high > /sys/class/drm/card0/device/power_dpm_force_performance_level.

Recommended GPU hardware

Since mpv normally renders video with shaders rather than fixed-function video hardware (it does that for the sake of quality and consistency), the GPU hardware and the quality of its drivers is very important for mpv to function well.

We're only portraying the situation on Linux. The author doesn't know the situation on Windows. Apple is completely incompetent and evil in the graphics area, please don't buy their products. Most notably, mpv still uses portable APIs on macOS, which Apple has declared deprecated and which are seemingly only updated to continuously ruin performance.

amdgpu (open source)

These seem to work pretty well. There are some consistent issues, but there is hope. Their discrete GPUs are usually powerful enough to handle even advanced render settings at high resolutions and frame rates. Newer models (Vega and later) seem to cause more problems. Some stability problems in various kernel releases, because they ported bad Windows code to the Linux kernel (FPU usage and improper context management).

amdgpu-pro (closed source)

Unknown. Might work well, but may cause additional problems in theory. Since open-source amdgpu drivers work pretty well (and supposedly better than amdgpu-pro in some cases), it's possible that they only provide an additional source of problems.

In any case, you can switch to amdgpu drivers without losing much.

Intel

Their hardware is relatively weak, and their drivers are chaotic. If you manage to pick the right driver versions, things will probably work very well up to medium settings. However, there are frequent problems (some of them seemingly never being fixed), and it is known that driver release versions have bugs not present in git. Also, they always start new drivers instead of improving what they have, which will make your life as an Intel user stressful.

However, if your PC is a laptop, you might have to choose pure Intel over Hybrid Graphics, at least now it could only do on a windows system using --gpu-api=d3d11 then select hybrid graphics --d3d11-adapter=... or --gpu-api=vulkan with --vulkan-device=.... Not recommended enabling hybrid graphics while running on battery, it will drain fast

Nvidia

No. Their hardware may be pretty good, but their drivers are problematic. They are closed source and tend to replace system libraries at installation. In addition, they tend to be behind the open-source APIs (for example, there is still no presentation feedback at all in their GL implementation). Nvidia drivers also seem to cause frequent system stability problems. There are weird quirks like huge user-noticeable timeouts at initialization, which shouldn't exist at all.

While Nvidia used to be recommended in the past (at least by the author), it keeps getting worse.

Mobile

Why would you buy a device that was designed to spy on you for the purpose of making megacorps even richer? That's kind of stupid, you know.

Anyway, all mobile GPUs are bad, both in the hardware implementation, drivers, and the fact that mobile devices are not very powerful unless you're fine with them draining your battery in minutes. Mobile GPUs can be fairly efficient if you use their fixed-function video decoding & rendering pipeline, but mpv does not attempt to do so.

ARM/Linux

There are many "embedded" or "mini computer" boards with powerful ARM chips. Consumers usually run Linux on them. They are all trash in all aspects. Roughly as bad or worse than mobile devices.

Although mpv has some support for RPI and Rockchip devices, which may or may not work well for you.

I am using NVIDIA G-Sync on Windows and running mpv in fullscreen mode reduces the frame rate of other displays

This is likely caused by the way G-Sync interacts with Windows’ compositor. Using --opengl-backend=win should fix this because mpv gets an exclusive fullscreen window that way. The compositor unredirects exclusive fullscreen windows and is not forced to run at their frame rate.

I can’t see the OSC/OSD/GUI!

The OSC requires Lua support. Install either one of Lua 5.1, 5.2, or LuaJIT, including development headers, and rebuild mpv. mpv does not and is unlikely to ever support Lua 5.3 or newer.
If you didn’t build mpv yourself, ask the packager to enable Lua.

Also, note that the OSC is invisible by default but it should appear once you move the mouse over the mpv window.

I can't see the window when mpv plays audio files.

Use --force-window.

Help mpv doesn't disable the screensaver during playback

Apparently, some screensavers do not use standard APIs, and require weird mechanisms in ALL software that needs to inhibit the screensaver. I guess their thinking was, "there is a very popular way to inhibit the screensaver that we interoperate with well, so let's go out of our way to put a stop to that." These do not sound to me like people whose software you should trust on your computer.

See for example https://www.jwz.org/xscreensaver/faq.html#dvd

Joke (?) aside, if you need to run xscreensaver-command (for XScreenSaver) or xdg-screensaver (for GNOME?), you can write a Lua script to do so. See disable screensaver

Why don't I have any window decorations?

You are most likely using GNOME Wayland or possibly some other Wayland compositor that does not support the xdg-decoration protocol. Mutter has essentially zero plans to deviate from client-side decorations so this will not change. mpv draws pseudo-client side decorations via the osc by default, so the usual functionality is still available.

NVIDIA and Wayland

Since the NVIDIA 495.29.05 beta release, NVIDIA now supports GBM as well as VK_KHR_wayland_surface. In theory, mpv on Wayland can now work on NVIDIA if your drivers are new enough. At this stage, no mpv developer has tried it out, and so no one cannot speak to how well it works. In terms of the general desktop experience, we have seen reports that Sway works correctly, but both GNOME and KDE have hard coded driver detection1 that means they will still use EGLStreams despite the new GBM support. Until that changes, you will not see any improvement in the Wayland experience in those desktop environments. With respect to mpv specifically, it is possible to make GLES via the `--opengl-es=yes` option, and while Vulkan is claimed to be supported with new drivers from 470.63.01 onwards, this hasn't been independently verified. In any case, do not attempt to use any particular compositor's EGLStreams backend while testing this.

1. In Mutter 42.0+ and KWin 5.23.2+, the hardcoded EGLStreams detection has been dropped.

Should I use X11 or Wayland?

mpv will support X11 and Wayland until the end of civilization (well maybe there will be a new windowing system before then). Provided you have working drivers/hardware (i.e. not NVIDIA) and aren't using some broken window manager/compositor, the X11 and Wayland backends should perform equally well. Any advantages one has over the other one have to do with the windowing system itself. You can just pick whichever implementation you like better.

mpv does its best to be independent of specific desktop environments and compositors, so we only support upstream wayland-protocols and not other desktop-specific libraries or compositor-specific protocols. Certain wayland compositors only support certain wayland-protocols, so they may not have every feature the mpv wayland backend supports.

What's the difference between high-quality, gpu-hq etc.?

The VO (video output) using GPU shader-based rendering was renamed and updated a few times. Currently, the following things hold true:

  • --vo=gpu is essentially the default
  • --profile=high-quality is for selecting a preset with advanced scaling and so on (replaces --profile=gpu-hq)
  • --profile=fast is for selecting a preset with "dumb" rendering and lower quality options (meant for limited hardware)
  • GPU supports multiple backends, like `d3d...`, opengl, vulkan (they are used by default in that order); use --gpu-api=vulkan to force e.g. vulkan, use --gpu-context=... to select specific backends.

Hardware decoding doesn't work? it should be enabled by default right?

  • use --hwdec=auto or --hwdec=auto-safe or --hwdec=auto-copy or --hwdec=auto-copy-safe instead of anything else
  • make sure all hwdec backends are compiled in
  • make sure the file you're playing can be hardware decoded at all (this is for example not the case with 10-bit h264 video)
  • some codecs need to be explicitly enabled with --hwdec-codecs=...

Hardware decoding is not enabled by default, because it is typically an additional source of errors. It is worth using only if your CPU is too slow to decode a specific video.

I'm using vo=vaapi or vo=vdpau, but there are problems

First off: DO NOT USE THESE VOs. They are broken and old. There is no reason to use them. Just don't override the VO selection and use the default. Some users seem to think using these VOs is required for hardware decoding. This is not true. If you want hardware decoding, use --hwdec=auto, which may use some of these APIs for decoding. (On older Nvidia drivers, you may need --gpu-context=x11 in addition.)

These VOs use rather old video output APIs, which have been mostly abandoned by their vendors. In particular, vaapi is known to be thoroughly broken in most Intel drivers. It's not surprising to see major bugs and problems, and mpv can do nothing about it.

In some cases, using them might be justified for performance (they might use a hardware overlay, most often these are just emulated with shaders though).

Video on RPI doesn't work, or is too slow

It is recommended to build mpv with an ffmpeg fork that implements the v4l2-request API. See this page for more details.

(How) can I play YouTube playlists?

Pretty much like anything else, just pass the playlist URL to mpv. Note that you need a link to the actual playlist (https://www.youtube.com/playlist?list=...), NOT to a video in the playlist (https://www.youtube.com/watch?v=...&list=...&index=...). You can get that link by clicking on the title of the playlist on the right.

If I click mpv, nothing happens.

mpv is a command line program and doesn’t provide an actual GUI. You need to start it with a media file. On Windows, you can create a file association with the Open with… context menu. Also, if you start mpv.exe from explorer.exe, it will enter pseudo-gui mode. For Linux, a mpv.desktop file is provided.

You can also start mpv with mpv --player-operation-mode=pseudo-gui. You play files by dropping them on the window.

How can I change video quality on YouTube?

Check available format of video by youtube-dl:

youtube-dl --list-formats <link>
or
youtube-dl -F <link>

For example:

youtube-dl -F https://www.youtube.com/watch?v=SYM-RJwSGQ8
[info] Available formats for SYM-RJwSGQ8:
format code  extension  resolution note
...
251          webm       audio only DASH audio  149k , opus @160k, 4.29MiB
135          mp4        854x480    480p 1159k , avc1.4d401e, 25fps, video only, 16.02MiB
247          webm       1280x720   720p 1372k , vp9, 25fps, video only, 20.12MiB
136          mp4        1280x720   720p 2318k , avc1.4d401f, 25fps, video only, 30.37MiB
248          webm       1920x1080  1080p 2402k , vp9, 25fps, video only, 35.54MiB
137          mp4        1920x1080  1080p 3770k , avc1.640028, 25fps, video only, 55.70MiB
22           mp4        1280x720   hd720 , avc1.64001F,  mp4a.40.2@192k (best)
...
Choice format and type
mpv --ytdl-format [format code] https://www.youtube.com/watch?v=SYM-RJwSGQ8
For 1280x720:
mpv --ytdl-format 22 https://www.youtube.com/watch?v=SYM-RJwSGQ8
You can mix different video+audio:
mpv --ytdl-format [video format code] + [audio format code] link
For mp4 1080p video (3770k) and webm audio (149k, opus @160k):
mpv --ytdl-format 137+251 https://www.youtube.com/watch?v=SYM-RJwSGQ8

You can also use the special aliases bestvideo and bestaudio, and also use conditionals. (See youtube-dl --help for a full documentation). As an example, if you always want to use the best video stream but only up to 1440p - and falling back to the best single-file format when not playing DASH streams - you can use something like this:

ytdl-format=bestvideo[height<=?1440]+bestaudio/best

How can I find out the names and commands associated with each key?

Run mpv in input test mode:

mpv --input-test --force-window --idle

How can I make mpv the default application for opening movie files on macOS (OSX)?

  • Install mpv as an app with Homebrew:

    $ brew cask install mpv
  • If you need an alias in Applications/Launchpad, open a Finder window at /usr/local/Caskroom/mpv/your_mpv_version/. In there the mpv.app bundle has been generated. While holding Cmd+Alt, drag this .app into the Applications folder.

  • Use duti to associate files with the application:

    $ brew install duti
    $ duti -s io.mpv avi all
    $ duti -s io.mpv mkv all
    $ duti -s io.mpv mp4 all

For macOS Big Sur and later you can also use openwith.

I want the old PulseAudio volume control back on Linux

With mpv 0.18.1, volume control was forced to softvol, and the --softvol option was removed. PulseAudio volume control (as in changing the per-client volume in the server) is not used anymore. The following things change with this as perceived by users with default settings:

  • changing volume in mpv now affects only the current mpv instance
  • volume is not saved across all instances (though it will be saved for the current instance/media file if you use the watch-later feature)
  • volume is not limited to 100% anymore
  • you cannot use mpv volume controls to set the volume higher than your current PulseAudio volume settings

It is recommended that you use a separate, non-mpv key binding to control your global volume.

If you want the old behavior, you have to switch your key-bindings manually to the audio output volume controls:

  • open your input.conf (see here for default location)
  • add the following lines:
9 add ao-volume -2
0 add ao-volume 2
  • or replace any occurrences of volume with ao-volume
  • don’t forget that lines starting with # are commented (the default input.conf has all entries commented)
  • note that mpv 0.18.1 had a bug that made PulseAudio “stuck” if the step was 1 and not 2 - this has been fixed in later versions
  • options like --volume can never influence the server value
  • you can do the same with the mute key binding (mute -> ao-mute)

You can also grab all volume bindings from the default input.conf to change all volume bindings.

Note this also works on other audio outputs and platforms. Which kind of volume ao-volume controls depends entirely on the audio API. Some APIs make it the global system volume, some make it per-client or per-stream private volume.

For technically inclined people: there was also a branch adding change that would have allowed changing all key bindings with a single option, but it hasn’t proven popular so far.

I want the old OSC back

In mpv 0.21.0 the default OSC layout was changed to the bottom bar, along with other settings that worked better with it.

Create a script-opts/osc.conf text file inside mpv’s configuration directory and use the following settings:

layout=box
seekbarstyle=slider
deadzonesize=0
minmousemove=3
In mpv 0.22.0, bottombar and topbar layouts were enlarged to have the same size in scalewindowed=1 as before with scalewindowed=1.5.

If you were using those layouts already and want the scale back as it was before 0.22.0, calculate it with 𝑥/1.5 where 𝑥 is the old value. So if are looking for the equivalent to scalewindowed=1, use these script-opts/osc.conf:

scalewindowed=0.666
scalefullscreen=0.666
Other options are available.

How does youtube-dl work? Does it download the stream to disk?

The mpv youtube-dl wrapper script calls youtube-dl --dump-single-json, -J on URLs that begin with http(s). This returns a direct media link from which mpv streams directly. Nothing is downloaded to disk. Once playback starts, youtube-dl has exited and is not active anymore.

Why were some cache options removed or changed (stream cache)?

Starting with mpv 0.30.0, some cache options have been removed (--cache-default, --cache-initial, --cache-seek-min, --cache-backbuffer, --cache-file, --cache-file-size), or changed (--cache does not take a size in KB anymore). This is a consequence of removing the stream cache, which was a ringbuffer of input data between demuxer and network level.

Caching is now done on the demuxing layer (between demuxer and decoder), which is controlled by separate options: --cache-secs=..., --demuxer-readahead-secs=..., --demuxer-max-bytes=...(KiB/MiB), --demuxer-max-back-bytes=...(KiB/MiB). Instead of --cache-file, --cache-on-disk is available.

The reason for the stream cache removal was that it mainly wasted memory, reduced performance, increased code complexity, and tended to cause weird bugs due to the cache layer not reflecting some of the underlying stream's behavior exactly.

On Windows, why does mpv.exe not attach to the console and what does mpv.com do?

This is a limitation of the Windows platform. There are two so-called subsystems on Windows: the GUI subsystem and the CLI subsystem. A Windows executable can only use one of them. If a program uses the CLI subsystem, it can attach to the console, print messages there, and receive input. However, such a program will always open a console window of its own if it is not already being run from one. A program using the GUI subsystem on the other hand will not attach to the console it is being called from, and control will immediately return to the command prompt. To work around that limitation, mpv has a separate executable, called mpv.com, which uses the CLI subsystem and redirects input and output for mpv.exe. Since Windows looks for executables with the .com suffix first (by default; defined by the %PATHEXT% variable), just typing mpv without a suffix on the command prompt will run mpv.com and you will get console output as expected.

How do I automatically play the next file in the folder?

Either pass all files to mpv, e.g. run this in the directory with the files:

mpv *.*
Or use a script

Why does mpv not support Lua 5.3 or newer?

There are hundreds of mpv user scripts which target Lua 5.1/5.2/jit. Lua 5.3 is a different language from 5.1 or 5.2. Simply switching to Lua 5.3 or newer would probably break most user scripts. The changes that make 5.3 incompatible are larger and have a greater impact than the changes that were done from 5.1 to 5.2 (or between LuaJIT and 5.1/5.2). This is especially due to the introduction of the integer type. Moreover, this would mean dropping LuaJIT support, as LuaJIT supports the 5.1/5.2 language only.

This is _not_ a matter of porting mpv's Lua code to Lua 5.3 or newer. The problem is with the language the Lua interpreter accepts, and how it is incompatible with hundreds of 3rd party Lua scripts outside of the control of the mpv developers.

Supporting both languages for a time would be theoretically possible. But it would require separate backends, and significant effort to avoid the symbol conflicts between Lua 5.2 and 5.3 (maybe even impossible to do with distro-provided libs), so it won't be done.

What is the rar file format and why is it stupid?

RAR is an archive file format like zip. It is proprietary and there is not much code around that can handle it fully. Everyone should use the 7zip format instead - there is no reason to use rar. The time of proprietary file formats designed to sell software that handles it ought to be over. RAR is basically a relic of the past.

Multimedia related, it is unfortunately somewhat common to distribute large video files in uncompressed multi-volume RAR archives. This is almost the absolutely worst way to distribute media anyone could come up with. It's stupid because it requires support in every media player (limiting your choices), _will_ be inefficient in some ways, and is an absolutely unnecessary relic from the past, where it was stupid too. Apparently, the people creating these live in the past.

It is somewhat expected from media players to handle these. mpv currently does so through libarchive. Unfortunately, its support for multi-volume archives is not very good.

Please do not report bugs about this to mpv. Pester libarchive for better uncompressed/multi-volume RAR support instead.

mpv before release 0.30.0 had some special code for uncompressed RAR for this purpose. This code was lifted from VLC, but VLC removed this code years ago. This code used to work better, but was unacceptable to keep for maintenance reasons. It is unlikely that this code is readded.

Why is there no DVD/Bluray menu support? And DVD/BD support in general.

DVD menu support existed since early times but was removed because it was a maintenance nightmare. It affected unrelated parts of the player deeply and prevented improving more important features. In addition, it never worked well. Later, DVD menu support was added again using rewritten code (and then Bluray menu support). However, despite the rewrite, it still affected the player core (preventing improvements in other areas), and it still did not work well.

The opinion of the developers is that menu support is cursed, and not worth implementing anyway. In addition to the monumental effort required to make it work well, only very few users benefit from it. It is a fact that playing DVDs/BDs gives a much better user experienced when ripped to files, which precludes menu support.

As a consequence, mpv only has some fallback support for optical media discs. Please don't report issues to it, as there is little chance of any improvements done to it.

If you are a developer and want to improve DVD/BD support in mpv, you are welcome to do so. But please try to keep the code isolated, so it does not affect the playback core too much. Most code related to it must be isolated in a separate module (for example stream_blurray.c, although it's allowed to change the layer at which the module is implemented). Ask on the developer IRC.

HDR doesn't work on my monitor?

Use this if you dislike the wrong color gamut, wrong luminance, and ugly effect of HDR. Set target trc, target primary or override video parameter

# This (might) practice to HD-TV 8-bit or 8-bit+FRC (Fake 10-bit)
--vf=format=colormatrix=bt.709:colorlevels=limited:primaries=bt.709:light=709-1886:gamma=srgb
                                  # use colormatrix "bt.709" or "bt.601" or "auto"
                                  # use primaries "bt.709" or "bt.601-625" or "bt.601-525" or "adobe" or "dci-p3" or "auto"
                                  # use colorlevels "limited" or "auto"
                                  # use light "709-1886" or "hlg" or "gamma1.2" or "display" or "auto"
                                  # use gamma "bt.1886" or "srgb" or "pq" or "gamma1.8" or "gamma2.0" or "gamma2.2" or "linear" or "auto"

--video-output-levels=limited     # Limited range [(16-235 per component), TV and studio levels]
--target-trc=srgb             # Use "pq" or "srgb" or "bt.1886"
--target-prim=auto
--dither-depth=8               # Use "auto" or "8"/"10" depending on your display bitdepth

# For PC just change "colorlevels=full or auto" and "--video-output-levels=full or limited or auto"
# This (might) practice to SD-TV
--vf=format=colormatrix=bt.601:colorlevels=limited:primaries=bt.601-525:light=auto:gamma=srgb
                                  # use colormatrix "bt.709" or "bt.601" or "auto"
                                  # use primaries "bt.709" or "bt.601-625" or "bt.601-525" or "adobe" or "dci-p3" or "auto"
                                  # use colorlevels "limited" or "auto"
                                  # use light "709-1886" or "hlg" or "gamma1.2" or "display" or "auto"
                                  # use gamma "bt.1886" or "srgb" or "pq" or "gamma1.8" or "gamma2.0" or "gamma2.2" or "linear" or "auto"

--video-output-levels=limited     # Limited range [(16-235 per component), TV and studio levels]
--target-trc=srgb              # Use "pq" or "srgb" or "bt.1886"
--target-prim=auto
--dither-depth=8               # Use "auto" or "8" depending on your display bitdepth

# For PC just change "colorlevels=full or auto" and "--video-output-levels=full or limited or auto"
# This (should) apply to UHD-TV
--vf=format=colormatrix=bt.2020-ncl:colorlevels=limited:primaries=bt.2020:light=709-1886:gamma=bt.1886
                                  # use colormatrix "bt.2020-cl" or "bt.2020-ncl" or "bt.709" or "smpte-240m" or "auto"
                                  # use primaries "bt.2020" or "bt.709" or "adobe" or "dci-p3" or "auto"
                                  # use colorlevels "limited" or "auto"
                                  # use light "709-1886" or "hlg" or "gamma1.2" or "display" or "auto"
                                  # use gamma "bt.1886" or "srgb" or "pq" or "gamma1.8" or "gamma2.0" or "gamma2.2" or "linear" or "auto"

--video-output-levels=limited     # Limited range [(16-235 per component), TV and studio levels]
--target-trc=pq                   # Use "pq" or "srgb" or "bt.1886"
--target-prim=auto                # Use "bt.2020" or "bt.709" or "adobe" or "dci-p3" or "auto"
--dither-depth=auto               # Use "auto" or "8"/"10"/"12"/"14"/"16" depending on your display bitdepth

# For PC just change "colorlevels=full or auto" and "--video-output-levels=full or limited or auto"

# This (might) practice to Apple TV
--vf=format=colormatrix=bt.709:colorlevels=limited:primaries=apple:light=709-1886:gamma=1.8
                                  # use colormatrix "bt.709" or "bt.2020-cl" or "bt.2020-ncl" or "bt.709" or "smpte-240m" or "auto"
                                  # use primaries "bt.601-625" or "bt.601-525" or "bt.709" or "bt.2020" or "adobe" or "dci-p3" or "linear" or "auto"
                                  # use colorlevels "limited" or "auto"
                                  # use light "709-1886" or "hlg" or "gamma1.2" or "display" or "auto"
                                  # use gamma "gamma1.8" or "gamma2.0" or "gamma2.2" or "linear" or "bt.1886" or "srgb" or "pq" or "auto"

--video-output-levels=limited     # Limited range [(16-235 per component), TV and studio levels]
--gamma-auto                      # Automatically corrects the gamma value depending on ambient lighting conditions
--target-prim=apple               # Use "apple" or "bt.601-625" or "bt.601-525" or "bt.709" or "bt.2020" or "adobe" or "dci-p3" or "auto"
--dither-depth=auto               # Use "auto" or "8"/"10"/"12"/"14"/"16" and bla..bla..bla.. depending on your display bitdepth

# For Monitor just change "colorlevels=full or auto" and "--video-output-levels=full or limited or auto"

# You can try force transfer characteristics (gamma) of the display just disable/remove "#--gamma-auto" and enable "--target trc=".
#--target-trc=gamma1.8             # Use "gamma1.8" or "gamma2.0" or "gamma2.2" or "linear" or "bt.1886" or "srgb" or "pq" or "auto"

For better display effects, you can use a tone mapping image 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).

Choose one;                        # use "mobius" or "reinhard" or "hable" or "bt.2390" or "linear" or "clip" or "gamma"
--tone-mapping=mobius
--tone-mapping-param=0.3
--tone-mapping-max-boost=1.0       # Value 1.0 Up to 10.0
--gamut-clipping

--tone-mapping=reinhard
--tone-mapping-param=0.5
--tone-mapping-max-boost=1.0
--gamut-clipping

--tone-mapping=linear
--tone-mapping-param=1.0
--tone-mapping-max-boost=1.0
--gamut-clipping

--tone-mapping=clip
--tone-mapping-param=1.0
--tone-mapping-max-boost=1.0
--gamut-clipping

--tone-mapping=gamma
--tone-mapping-param=1.8
--tone-mapping-max-boost=1.0
--gamut-clipping

--tone-mapping=bt.2390
--gamut-clipping
# Perceptual tone mapping curve (EETF) specified in ITU-R Report BT.2390. This is the default MPV, curve to use for typical HDR-mastered content

--tone-mapping=hable
--gamut-clipping
# 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.
You can change the parameter by yourself.

Trying set --d3d11-output-format=... and --d3d11-output-csp=... might help (*Windows).

Player freezing when switching to fullscreen?

Try add line --angle-flip=no or --d3d11-flip=no for D3D11 backend.

How is mpv related to MPlayer?

The relation between the two projects is mostly historic. They should be considered two separate projects. mpv and MPlayer are different software, incompatible to each other. There is no overlap in developers and other project members between MPlayer and mpv. mpv is not a drop-in replacement for MPlayer, and the command line switches and behavior are different.

MPlayer users should not expect that mpv is in any way similar to it. Both are CLI video players and have common roots, but in some areas, there are radical differences. An Old and outdated summary of changes

mpv is based on MPlayer's code. At first, there was the mplayer2 project, which forked away from MPlayer roughly in 2008, and went different ways from it. (It was renamed to mplayer2 only a few years later, causing general confusion.) In 2012, some newer developers, who joined mplayer2 development around 2011, forked mplayer2 again. This second fork was then renamed to mpv.

The reason for this fork was disagreement over the direction of development. While MPlayer focuses on maintenance and not breaking old code and features, mpv wanted to go into the other direction, modernization. This included merciless removal of code/features that were not considered worth maintaining due to being obscure and unused or rewriting existing code to clean it up and to reduce bugs. Reducing maintenance burden by replacing MPlayer code with FFmpeg mechanisms was also a priority. mplayer2 was stuck between those positions - first going for mpv's direction, but then remaining stagnant with slow development. The mplayer2 project soon went inactive after the mpv fork, and is completely gone today.

We consider mpv's radical approach successful, making the code easier to work with, removing bugs, and making it easier to add new features. We added modern features wanted by users in exchange for removing large amounts of features barely anyone used anymore.

One result is that mpv development has nothing to do with MPlayer development anymore. They are completely separate projects. The mplayer2 period might have contributed to the relative isolation between the two projects. After all these years of going in separate directions, merging MPlayer and mpv back into one project wouldn't make sense.

How do I create a Conditional auto profile that applies to all videos (or all audio)?

As per the mpv manual, you can create auto-profiles that will automatically apply specific options if specific conditions are met.

The following profiles (added to your config file) automatically apply to all videos files and all audio files, respectively:

# This applies to all videos
[video]
profile-cond=p["current-tracks/video/albumart"] == false
# Replace this line with the options you want to apply
# This applies to all audio
[audio]
profile-cond=not vid and not vo_configured or p["current-tracks/video/albumart"]
# Replace this line with the options you want to apply

Note that you only need to check not vo_configured if you use --lavfi-complex with videos, which makes vid false.

How do I rotate videos?

Cycle through video-rotate values in 90° steps. Example for input.conf:

r cycle-values video-rotate 270 180 90 0
t cycle-values video-rotate 90 180 270 0

How do I apply a profile only once with Auto Profiles?

Using input commands and the user-data interface.

[some_profile]
profile-cond = not p["user-data/some-profile-applied"]
input-commands = no-osd set user-data/some-profile-applied 1
Clone this wiki locally