How to Configure and Use MPV Video Player

September 16, 2023

MPV is a versatile video player that transcends operating system boundaries, running seamlessly on Linux, Windows, BSD, Android, and MacOS. Despite its minimalist design, MPV offers an array of configuration options, allowing users to tailor their viewing experience to perfection. Moreover, MPV's extensibility is a standout feature, enabling users to enhance its functionality through scripts written in Lua and JavaScript. In this guide, we'll explore how to configure and harness the power of MPV, making it your go-to video player for all platforms.

mpv with default configuration

figure 1: mpv with default configuration

Installation

Arch Linux/Manjaro

sudo pacman -S mpv

Debian/Ubuntu/Kali Linux/Raspbian

sudo apt install mpv

Windows
First, install and enable Chocolatey.

choco install mpv

For the installation of MPV on other systems, refer to this page.

How to Customize MPV

In Unix-based systems, configuration files are located in the directory /etc/mpv (system-wide) and ~/.config/mpv or $XDG_CONFIG_HOME/mpv (user-wide).

For Windows, they are in the directory C:\Users\<username>\AppData\Roaming\mpv. Please note that in Windows, backslashes are used instead of forward slashes for directories.

You can explore these system-wide directories for default shortcut keys and configurations. Then, modify them to make them your own.

The files/directories include:

  • mpv.conf: It is the main configuration file.

  • input.conf: All the keybindings are located here. A sample input.conf is available in the /usr/share/doc/mpv/ directory or this official mpv github page.

  • watch_later: When you enable the configuration related to --save-position-on-quit, MPV saves the position where you were watching the video into the files in this directory. The next time you play this video, it starts from the same time.

  • scripts: This directory stores all your scripts. When you install MPV, MPV saves some scripts in the directory /usr/share/mpv/scripts/. These are not enabled by default. To enable them, you need to copy or symlink them into your configuration's scripts directory. To learn about symlinks and how to create them in Linux, refer to this link.

  • script-modules and script-opts are two directories that store extra modules and options for scripts. You don't need to create them unless asked by the script's man page. Please note that a file script-opts/console.conf stores configuration related to MPV consoles.

MPV's console launched by pressing the backquote key located below the Esc key on a US keyboard

figure 2: console launched by pressing the backquote key located below the Esc key on a US keyboard

Here is a short but useful configuration for the console's fonts. Uncomment and modify it to make it your own.

[ajay@legion ~]$ nvim ~/.config/mpv/script-opts/console.conf
# scale=1
# font=monospace
font_size=25

How to Customize the Keybindings in MPV

To get the list of all keybindings in your MPV video player, press 'i' followed by '4'. Now, you can use the up and down arrow keys to browse through them.

 finding keybindings in mpv: press i then 4

figure 3: finding keybindings

To modify them, the simplest way is to copy the sample input.conf mentioned above to the user-wide input.conf. Now, uncomment and change them according to your needs.

To find the name of the key, run the following MPV command with the --input-test flag with any video:

[ajay@legion ~]$ mpv --input-test <any_mpv>

figure 4: mpv --input-test displays the keys you press

You can also use the command mpv --input-keylist to print some keys on your terminal.

Syntax for the input.conf:

<keys> <MPV_command>

These MPV commands can be run either from MPV's console or using shortcut keys. You can first try any complicated command using MPV's console and then bind them to your keys.

Here are my keybindings, similar to Vim keybindings:

Volume Keys in MPV

For volume control, to use mouse wheels, append the following:

WHEEL_UP      add volume -2
WHEEL_DOWN    add volume +2

But for controlling volumes using Vim keys, use:

j add volume -2
k add volume +2

You can add both if you wish.

Skipping in MPV Videos

If you don't like a scene in your video, you can skip the scene using the seek command. To bind it similar to Vim key bindings, use:

l seek  1
h seek -1
L seek  60
H seek -60

If the above seek keybindings move too fast, you can advance slowly (frame by frame). It is useful when you want to take a screenshot at a precise location.

> frame-step  # advance one frame and pause
< frame-back-step  # go back by one frame and pause

Taking Screenshot in MPV Video

For taking screenshots of important images, the following are the default keys. Modify them by uncommenting them.

#s screenshot  # take a screenshot
#S screenshot video  # ...without subtitles
#Ctrl+s screenshot window  # ...with subtitles and OSD, and scaled
#Alt+s screenshot each-frame  # automatically screenshot every frame

Subtitles in MPV

Sometimes, subtitles are not synchronized with the videos. In that case, to synchronize the subtitles, use:

Alt+h sub-step -1
Alt+l sub-step 1

📔 Note: To add subtitles in an MPV video, make sure the video name and subtitle names are the same except for the file extension.

subtitles in the mpv should have same name as that of video

figure 5: subtitles should have same name as that of video

Sometimes, subtitles are obfuscating an important scene, and you want to shift their position. Use T (top) and R (reverse the path):

T add sub-pos -1  # move subtitles up
R add sub-pos +1  # down

If a video has multiple subtitles (multilingual subtitles), use c to cycle through subtitles:

c cycle sub  # cycle through subtitles

Chapters in MPV

In YouTube, you can interact with chapters. Chapters are useful for long video lectures. In MPV, you can also interact with chapters. Use:

PGDWN add chapter 1  # skip to the next chapter
PGUP add chapter -1  # skip to the previous chapter

For example, this is how the following YouTube video with chapters looks like in the mpv:

chapters in mpv - notice the chapter name and dots in the bottom bar

figure 6: chapters in mpv - notice the chapter name and dots in the bottom bar

Video Playback Speed

Sometimes, videos are boring, and sometimes they are too fast to understand. Control the speed of a video using:

#[ multiply speed 1/1.1
#] multiply speed 1.1

#{ multiply speed 0.5
#} multiply speed 2.0
#BS set speed 1.0  # reset speed to normal
= set speed 1.0  # reset speed to normal

The commented lines are the default keys. Change them if you want.

If you are playing a boring video in a playlist and want to skip to the next/previous video in the playlist, use the following:

. playlist-next  # skip to the next file
, playlist-prev  # skip to the previous file
/ playlist-shuffle  # shuffle the playlist

Video Information

You might want to see video information like its size, frames per second, resolution, and encoding. Use:

i script-binding stats/display-stats-toggle

figure 7: display stats of the video in mpv

figure 7: display stats of the video

Start from the Beginning in the Video

Sometimes, if you have enabled the flag --save-position-on-quit and restart any video, it starts in the middle, and you want to start from the beginning. Use (I for 'initial'):

I seek 0 absolute

Keybindings for Audios in Multiple Languages

For videos with multilingual audio, cycle through them using a:

a cycle audio

Keybindings for Setting Loops in MPV

Loop in Videos: Using the following configuration, if you press 'r', your video will loop infinitely, which is good for short videos (like GIF files) that you want to watch again and again to understand them. You can also loop between two points in a video. Just press 'R' to set point a and then press 'R' again to set point b. Now, your video will loop between these two points, A and B.

R ab-loop
r cycle-values loop-file "inf" "no"

You can also bind your scripts. To learn more, refer to the script's manual. Here is how I have done it. You need to use script-binding as shown below:

C script-binding contact-sheet-toggle

How to Configure MPV

As mentioned earlier, MPV is configured in the file mpv.conf. A sample mpv.conf is available in the /usr/share/doc/mpv/ directory or this official github page. Copy and paste what you like.

Some flags/configurations that I find useful are described below.

All the flags passed to MPV in the command line can be written in the mpv.conf too, omitting the need to pass these flags each time you run MPV. For example, --save-position-on-quit becomes:

save-position-on-quit

Loop Videos/Images in MPV

When a video is finished, MPV closes the window. I hate this since most of the time, I use MPV for study/office-related videos and hence want to analyze the video by skipping. I also use MPV to open my images. So, I want images to be displayed continuously unless I quit. So, run the videos in an infinite loop:

loop-file=inf

Volume

Setting a volume of 100% is sensible:

volume=100

This will be applied when you start MPV.

MPV's Screenshot Directory

I want MPV to save its screenshots to my computer's screenshot directory. You can set it using screenshot-directory:

screenshot-directory=~/Pictures/screenshots

Many times, I use MPV to watch YouTube videos. To set YouTube's audio and subtitle language, use:

slang="en,eng,en-US,en-GB"
alang=en

Now, the subtitle will be applied and turned on over all YouTube URLs.

OSD (On Screen Display)

MPV uses OSD to display any notification. For example, when you press the key 'o' while playing any video, you will see the following info:

osd (on screen display) in mpv

figure 8: osd (on screen display)

Another good example is the notification shown while taking a screenshot.

It is too big for me. So, to set the font size and its location, uncomment and modify the following snippet:

osd-font-size=14
# available option: left|center|right
osd-align-x=left
# available option: top|center|bottom
osd-align-y=top
osd-margin-x=0
osd-margin-y=0

Controlling MPV Using IPC Protocol

You can also send commands to the MPV window from scripts written in any language (bash, python, etc.). This is very cool since I don't know JavaScript and Lua but know bash and python. Using this, I wrote many bash scripts for MPV 😎.

For this, first set an input-ipc-server:

input-ipc-server=/tmp/mpv_socket

Now, for example, the following bash command asks the video player for the current subtitle printed on the screen. You can use other bash commands in MPV's output. I used it when learning the English language. This way, I noted down the words I did not know and the movie's subtitle as a sentence.

[ajay@legion ~]$ echo '{ "command": ["get_property", "sub-text"] }' | socat - "/tmp/mpv_socket"

Profiles in MPV

In MPV, you can create various profiles. In each profile, you can set a different set of configurations.

You can list all the available profiles using the flag --profile=help:

figure 9: listing profiles in mpv using --profile=help

figure 9: listing profiles in mpv

There are some built-in profiles such as those for 'HP Slate 7' and '3GP for Nokia 6300,' and some you can create.

For example, I have created two profiles named "360p" and "720p." The first plays YouTube videos in 360p, and the other in 720p; otherwise, MPV plays the videos in their maximum resolution and hogs my whole internet.

To play a video using a profile in MPV, use the --profile flag:

[ajay@legion ~]$ mpv --profile=360p 'https://www.youtube.com/watch?v=t5Sd5c4o9UM

Now, the configurations in the profile will be applied as well.

Syntax:

<profile_configuration>
...
...
profile-desc="any string explaining the profile goes here."

The profile-desc is used for a description displayed in the mpv --profile=help command's output. The description is also used in bash and zsh's autocompletion.

Now, here is how the profile 360p looks like:

ytdl-raw-options='format-sort="res:360,+size",sub-lang="en",write-auto-sub=,yes-playlist='
demuxer-max-bytes=1024KiB
demuxer-max-back-bytes=2048MiB
profile-desc="YouTube in 360p"

📔 Note: ytdl-raw-options is used while playing YouTube videos - resolution of 360p, subtitle language of English, and others are applied. demuxer-max-back-bytes and demuxer-max-bytes ensure that only the given MiB/KiB of videos are downloaded; otherwise, MPV hogs the whole bandwidth to download the complete videos.

Some profiles are automatically applied when you launch MPV. You don't need any --profile, for example, those related to extension.

[extension.mp3]
no-resume-playback

The configuration snippet ensures that each time any file with the extension mp3 is opened, it doesn't honor the save-position-on-quit flag and instead starts from the beginning.

Playlist in MPV

MPV can also work with playlists. You can launch a YouTube playlist (for example) by passing its URL.

[ajay@legion ~]$ mpv 'https://www.youtube.com/watch?v=t5Sd5c4o9UM&list=RDt5Sd5c4o9UM&start_radio=1&rv=t5Sd5c4o9UM'

After videos are loaded into your playlist, you can press the keys configured above to skip to the next/previous videos.

A script that I find quite useful is autoload.lua, which automatically loads playlist entries before and after the currently played file. It does so by scanning the directory a file is located in when starting playback.

Way Ahead

Now that you know about MPV's keybindings and configuration, how about learning new scripts and customizing it further? I am planning to make a new article about this. So stay tuned to my blog for that. Thanks. If you have any queries or suggestions, put them in the comment section below.