# mpv

mpv is a versatile and lightweight media player with extensive customizability. It is used and recommended by most enthusiasts as it supports a wide range of video, audio, and subtitle formats. Additionally, it offers many advanced features and is available on multiple platforms.

# Installation

# Windows

  1. Download the latest Windows build of mpv from mpv-winbuild. For most users, this should be mpv-x86_64-YYYYMMDD-git-abcxyz.7z
  2. Once downloaded, extract the archive's contents to your specified location
  1. Navigate to the installer folder and run mpv-install.bat. Follow the on-screen instructions to complete installation

Installing mpv-winbuild

Scoop is a command line package manager for Windows. Unlike other installation methods, Scoop downloads and manages packages in a portable way, keeping them neatly isolated in %userprofile%/scoop and automatically adding them to your PATH.

Scoop can be installed using their install script in a PowerShell window:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

Then, install mpv using scoop:

scoop bucket add extras
scoop install extras/mpv-git
scoop update mpv-git
scoop uninstall mpv-git

mpv can also be found in the various forks below:

If you don't want to setup mpv yourself, a portable build of mpv is available below. This is pre-configured to have the settings described in the Basic Config and Advanced Config and is automatically updated daily. The portable_config folder can also be downloaded separately if you wish to add it to your existing mpv installation.

mpv
mpv
portable_config
portable_config.7z

If you want to access mpv from the command line, you will need to add it to Windows PATH:

  1. In Windows Settings -> System -> About, locate Advanced System Settings. Head to Advanced and click on Environment Variables...
  2. Under System Variables, select Path and click on Edit...
  3. Click New and point the variable to the folder where mpv.exe is located/installed
  4. Launch a new terminal window. mpv can be accessed from the command line using mpv

Adding mpv to PATH
Adding mpv to PATH

# macOS

Download the latest macOS build of mpv: Stable Nightly

Install Homebrew. Then, run the following command in your terminal:

brew install mpv

# Linux

The following packages are not maintained by official mpv developers:

# Config Overview

By default, mpv's config can be found under %APPDATA%/mpv/. However, a folder named portable_config next to where mpv.exe is stored can override this location as the config folder.

.
└── mpv/
    ├── fonts/
    ├── script-opts/
    ├── scripts/
    ├── shaders/
    ├── input.conf
    └── mpv.conf
.
├── mpv.exe
└── portable_config/
    ├── fonts/
    ├── script-opts/
    ├── scripts/
    ├── shaders/
    ├── input.conf
    └── mpv.conf
.
└── portable_config/
    ├── fonts/
    ├── script-opts/
    ├── scripts/
    ├── shaders/
    ├── input.conf
    └── mpv.conf
File Meaning
fonts/ Directory for custom font files. These are typically used for subtitles
scripts/ Directory for custom scripts. These are usually .lua scripts
shaders/ Directory for custom shaders used in scaling, filtering, etc.
script-opts/ Directory used by custom scripts to store additional options/configs
mpv.conf General user configuration for mpv
input.conf Keybind settings for mpv

Some folders may not be present by default and will need to be created.

For more details, see mpv's documentation on files.

# Basic Config

mpv is a great player out-of-the-box which can be extensively customized to your liking.

We recommend taking your time to create your own config. If you want to get up and running quickly, we suggest using the generic mpv.conf config below:

## Video
profile=high-quality
vo=gpu-next
scale-antiring=0.6

# Dither
# This must be set to match your monitor's bit depth
dither-depth = 8

## Behavior (personal preference)
keep-open=yes
save-position-on-quit

## Screenshots
screenshot-format=png
screenshot-dir="~/Pictures/mpv"
screenshot-template="%F-%p-%n"
screenshot-high-bit-depth=no

## Language Priority
## Sub
## Add enm before eng for honorifics
slang=eng,en
alang=jpn,ja

## Dub
#slang=zxx,eng,en
#alang=eng,en
#subs-with-matching-audio=forced
Option Meaning
profile The profile to be used by mpv. This should be left at the top of your file avoid conflict with other settings.
vo The output driver to be used by mpv. gpu-next is recommended for most modern hardware.
scale-antiring Sets the strength of the antiringing filter. We recommend not setting too high of a value to prevent unwanted artifacts.
dither-depth Sets the dither depth. This should be set to your monitor's bit depth to prevent banding.
keep-open Whether to close or leave the player open after the file finishes playing. Use no if you want the player to close.
save-position-on-quit Save the current playback position on quit. When the file is reopened, mpv will resume from where it left off. Remove this option if you do not want the player to save your position.
screenshot-format File format used for screenshots. png is recommended for lossless quality.
screenshot-dir The directory where screenshots will be saved. Currently set to your default pictures folder (Pictures/mpv).
screenshot-template The naming scheme for screenshots. %F-%p translates to filename-timestamp.
slang Priority list of subtitle languages to use when there are multiple tracks.
alang Priority list of audio languages to use when there are multiple tracks.
subs-with-matching-audio Determines whether the subtitle and audio track must match their language.

# Advanced Config

mpv can be fine-tuned to meet your specific needs, from tweaking playback behavior to customizing video, audio, and subtitle settings. This section outlines the common options that can improve your experience.

# Debanding

Color banding is a visual artifact that is typically seen in gradients, where the colors can be easily differentiated by the human eye. See Tom Scott's video explaining color banding.

Banding (left) vs. No banding (right)

Banding (left) vs. No banding (right)

Newer versions of mpv now ship with debanding capabilities, so no additional configuration is required. You can enable debanding anytime during playback by pressing b (default keybind).

For sources where the default debanding isn't effective enough, you can apply more aggressive debanding profiles such as:

[BrazzersDeband]
deband=yes
deband-iterations=4
deband-threshold=64
deband-range=20
deband-grain=32
[HiroshimaDeband]
deband-iterations=4
deband-threshold=100
deband-range=8
deband-grain=32

# Scaling

Scaling is the process of taking content that does not match your screen resolution and resizing it to fit your display. See the Playback Guide for more information.

mpv has a built-in profile called high-quality which enables better upscaling using ewa_lanczossharp. By default, mpv uses lanczos and hermite. This option is necessary to enable even if you use an external shader, as it can act as a fallback.

Scalers only work when the resolution of your video does not match your display. They do not activate if the content resolution already matches your display resolution.

If you use high-end hardware, we recommend using the following shaders:

Download both the shader files and place them in your shaders folder.

Next, add the following to your input.conf, replacing g with the bind of your choice, if necessary (case-sensitive):

g cycle-values glsl-shaders "~~/shaders/nnedi3-nns128-win8x4.hook" "~~/shaders/ArtCNN_C4F32.glsl" ""

To toggle the shader, press g during playback to select the suitable shader.

If you use mid-range hardware, we recommend sticking to mpv's built-in high-quality profile.

To use the profile, add the following to the top of your mpv.conf:

## Video
profile=high-quality
vo=gpu-next
scale-antiring=0.6

This is included in the Basic Config.

If you use low-end hardware, we recommend sticking to mpv's default profile, which aims for a balance between quality and performance. No other changes need to be made as it is used by default.

If you use very low-end hardware, we recommend sticking to mpv's fast profile, which prioritizes performance over quality.

To use the profile, add the following to the top of your mpv.conf:

profile=fast

# Dither

Dither is an intentionally applied noise filter that aims to help eliminate various visual artifacts, such as color banding during playback.

By default, mpv uses dithering to match the content bit depth to your display's bit depth. However, in some instances, it may fail to detect the correct bit depth of your display automatically, causing the wrong bit depth to be used and adding banding during playback.

To avoid introducing banding during playback, we recommend explicitly defining your display's bit depth. Most modern displays use the 8-bit color depth, however you can manually check this:

  • For Windows, this can be found in Settings -> Display -> Advanced display settings -> Display information -> Bit depth

Then, set your display's bit depth in your mpv.conf:

dither-depth = 8

# Subtitle Restyling

Most releases will use their own font for .ass subtitles. These can be manually overridden by mpv, which can help improve readability or match personal preferences.

Below are a couple of commonly used styles:

Gandhi Sans
Gandhi Sans

Download this font here or use the button below:

Gandhi Sans

Run the .otf font file to install it system-wide or put it in your fonts folder. Add the following to your mpv.conf:

# Set sub-ass-override to "no" as we only need to enable it for specific cases
sub-ass-override=no
sub-ass-style-overrides=playresx=1920,playresy=1080
sub-font="Gandhi Sans"
sub-font-size=50
sub-color="#FFFFFF"
sub-border-size=2.4
sub-border-color="#FF000000"
sub-shadow-color="#A0000000"
sub-shadow-offset=0.75
sub-bold=yes
sub-ass-style-overrides=Kerning=yes

Cabin
Cabin

Download this font here or use the button below:

Cabin

Run the .ttf font file to install it system-wide or put it in your fonts folder. Add the following to your mpv.conf:

## Restyle Subtitles
# Set sub-ass-override to "no" as we only need to enable it for specific cases
sub-ass-override=no
sub-ass-style-overrides=playresx=1920,playresy=1080
sub-font="Cabin"
sub-font-size=50
sub-color="#FFFFFFFF"
sub-border-size=2.4
sub-border-color="#FF000000"
sub-shadow-color="#A0000000"
sub-shadow-offset=0.8
sub-ass-style-overrides=Kerning=yes

Cabin F
Cabin F

Download this font using the button below:

Cabin F

Run the .ttf font file to install it system-wide or put it in your fonts folder. Add the following to your mpv.conf:

## Restyle Subtitles
# Set sub-ass-override to "no" as we only need to enable it for specific cases
sub-ass-override=no
sub-ass-style-overrides=playresx=1920,playresy=1080
sub-font="Cabin F"
sub-font-size=50
sub-color="#FFFFFFFF"
sub-border-size=2.4
sub-border-color="#FF000000"
sub-shadow-color="#A0000000"
sub-shadow-offset=0.8
sub-ass-style-overrides=Kerning=yes

To activate it with a key, add the following to your input.conf, replacing k with the bind of your choice, if necessary (case-sensitive):

k cycle_values sub-ass-override "force" "no"

# Auto Profiles

Auto profiles allow users to automate actions based on certain conditions. Tasks such as debanding and subtitle restyling can be applied automatically when these conditions are met, such as file names.

For instance, some seasonal releases may exhibit banding issues and use subjectively less-appealing subtitle fonts. To address this, we can create a simulcast auto profile, which automatically applies debanding and subtitle restyling when playing releases uploaded by SubsPlease, Erai-raws, Tsundere-Raws, VARYG, or HorribleSubs.

Add the following to the end of your mpv.conf:

[crunchyroll]
profile-cond=filename:match("SubsPlease") or filename:match("Erai%-raws") or filename:match("HorribleSubs")
profile-restore=copy
sub-ass-use-video-data=aspect-ratio

[simulcast]
profile-cond=(function(a)for b,c in ipairs(a)do if filename:match(c)then return true end end end)({"SubsPlease","Erai%-raws","Tsundere%-Raws","%-VARYG","HorribleSubs","SubsPlus%+", "Yameii"})
profile-restore=copy
deband=yes

# Custom Scripts

mpv supports loading custom scripts, allowing you to further expand the player's functionality.

Below is a list of some popular scripts:

  • autocrop - Automatically crop the video by using lavfi's cropdetect filter to detect black bars
  • autoload - Automatically adds all files present in the folder to a playlist
  • change-refresh - Script to automatically change the refresh rate of the display to reflect the current video
  • mpv-playlistmanager - Script to create and manage playlists
  • mpv-webm - WebM maker for mpv
  • pause-when-minimize - Pauses playback when minimizing the window, and resumes playback when brought back
  • thumbfast - Display thumbnails when scrubbing video (may be needed for some Skins)
  • trackselect - Select tracks based on their title
  1. Navigate to your mpv config directory
  2. Locate the scripts folder. You may need to create this folder if it doesn't exist
  3. Drag your script file(s) (e.g. .lua) into the folder

Your scripts are automatically loaded when you launch mpv. If mpv is currently open, you will need to relaunch it in order for your script(s) to take effect.

# Skins

You can customize how mpv looks using skins. These are subject to personal preference, so find what works best for you.

Below is a list of some popular skins: