Skip to content
Ingmar Ellenberger edited this page Mar 24, 2019 · 46 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 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.


Never seen it tearing.


Whether tearing happens with OpenGL may depend on the backend and how it interacts with the GPU and the compositor via the swap chain. Try with playing the --angle- options, which configure the d3d swapchain. You can also try various with --opengl-backend=NAME, where NAME is the name of the backend. dxinterop seems to perform best generally, but it will crash randomly with some older buggy Intel drivers. The deprecated --vo=direct3d should roughly behave like --angle-renderer=d3d9.


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

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

    Section "Extensions"
        Option "Composite" "Disable"
  • 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/ 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 synchronisation. You cannot fix this tearing with any of the other methods described on this page. Assume fetal position and cry, or switch to using your Intel GPU instead.


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 post explains the procedure in more details.


  • 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.

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.
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.

What's the difference between opengl-hq, 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 (replaces --vo=opengl)
  • --profile=gpu-hq is for selecting a preset with advanced scaling and so on (replaces --vo=opengl-hq and --profile=opengl-hq)
  • 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.

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

You need to build FFmpeg with mmal support - this is not enabled by default in FFmpeg. mpv also needs to be compiled with mmal, and the Broadcom firmware libEGL. Otherwise hardware decoding and scaling cannot be enabled.

You can check whether the FFmpeg (libavcodec) linked to mpv is built with mmal with mpv --hwdec=help|grep mmal. Before mpv 0,.28, this might have been called rpi instead of mmal, and the hwdec help output does not indicate whether FFmpeg actually was built with support. If the output is empty, FFmpeg was not correctly built. You can check whether mpv was built with mmal with mpv --vo=help|grep rpi.

It's rather complicated to get this to build correctly because RPI userland is a mess. Don't ask us for help, because we don't know your specific system. Keep in mind that the firmware libEGL and Mesa's libEGL (as often shipped by distros) are incompatible.

Once all this is done, run mpv with mpv --hwdec=rpi --vo=rpi file.mkv. Otherwise mpv might use software decoding, which tends to be too slow.

If you get the error mmal: mmal_vc_port_enable: failed to enable port ENOMEM, try increasing gpu_mem in /boot/config.txt.

(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 (, NOT to a video in the playlist ( 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>
youtube-dl -F <link>

For example:

youtube-dl -F
[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]
For 1280x720:
mpv --ytdl-format 22
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

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:


How can I change volume using the mouse wheel?

By default, volume is changed by scrolling horizontally. If you want to use vertical scrolling for that (rather than seeking), put this in your input.conf:

AXIS_UP    add volume 2
AXIS_DOWN  add volume -2

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

Is FFmpeg or Libav preferred for use with mpv?

Generally FFmpeg, simply because it has more features. Don't expect subtitles to work on Libav.

How can I make mpv the default application to open movie files on MacOS (OSX)?

  • Install mpv as an app with Homebrew:

    $ brew install mpv --with-bundle
  • If you need alias in Applications/Launchpad, open Finder window at /usr/local/Cellar/mpv/your_mpv_version/. In there the bundle was generated. While holding Cmd+Alt drag this .app onto Applications folder.

  • Use duti to associate files with application:

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


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 you 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 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 to change 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 bottombar, along with other settings that worked better with it.

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

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 lua-settings/osc.conf:

Other options are available in the manual.

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

The mpv youtube-dl wrapper script calls youtube-dl -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.

See the manual for available options:

Why does the cache not work for Twitch (HLS sites) and some youtube links?

Twitch uses HLS, some youtube links use segmented DASH. These are both segmented streaming protocols, for which no single, monolithic stream exists. The classic stream cache works only for unsegmented input, so it can't cache these sites.

This is not an issue for the demuxer packet cache introduced in mpv 0.28.0. This extends the memory cache for demuxed packets and makes it seekable (in exchange for some wasted memory and CPU). It can be controlled with and .

On Windows, why does mpv.exe not attach to the console and what does 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, 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 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 like .

Why does mpv not support Lua 5.3?

Lua 5.3 is a different language from 5.1 or 5.2, so it won't be supported to avoid breaking all user scripts. Lua 5.1, Lua 5.2, and LuaJIT are also different, but the differences are relatively minor.

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.

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.

mpv went on, radically minimizing its code base, as seen here:

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 separate directions, merging MPlayer and mpv back into one project wouldn't make sense.

You can’t perform that action at this time.