Skip to content

README.md

Latest commit

 

History

History
276 lines (179 loc) · 10.9 KB

README.md

File metadata and controls

276 lines (179 loc) · 10.9 KB

mpv-config

A personal mpv configuration focused on high-quality playback, streaming support, and a clean customizable interface — suitable for both local files and YouTube/web video.

Screenshot 1 Screenshot 2

Highlights

  • Automatic shader profiles — shaders are applied based on source resolution without any manual switching. HD content, SD content, and 4K downscaling each get their own optimal pipeline.
  • Vulkan renderer — uses gpu-next with Vulkan for the best performance and quality on modern hardware.
  • Streaming ready — quality-menu for on-the-fly stream selection, SponsorBlock integration, YouTube subtitle support, and stream reload for stuck playback.
  • Extensive shader library — includes CuNNy, ArtCNN, FSRCNNX, NNEDI3, RAVU, Anime4K, ACNet/ARNet, and more, all accessible from the uosc menu. Every shader is documented inline in input.conf.
  • Surround downmix — 5.1 and 7.1 audio is automatically downmixed to stereo. Disable if you have a surround system.
  • Cross-platform — works on Windows, Linux, and macOS.

Table of Contents

Installation

Windows

1. Download mpv

Download the latest 64-bit Windows build from the Shinchiro builds page:

Download mpv for Windows

  • mpv-x86_64-*.7z — recommended for most systems
  • mpv-x86_64-v3-*.7z — for newer CPUs (Ryzen 5000+, Intel 12th gen+)

Extract the archive somewhere permanent. This folder will be your main mpv folder — do not move it after installation.

2. Install File Associations

Inside the mpv folder, open the installer folder, right-click mpv-install.bat, and select Run as administrator.

After it finishes, Windows may prompt you to set mpv as the default media player in Control Panel.

3. Install This Configuration

Download this repository as a ZIP, extract it, and copy the portable_config folder into your mpv folder — next to mpv.exe.

Your mpv folder should look like this:

Folder structure

4. Update mpv / Install yt-dlp + ffmpeg

Right-click updater.bat and select Run as administrator. The updater lets you update mpv and optionally install yt-dlp and ffmpeg, which enables streaming from YouTube and hundreds of other sites.

Supported sites

5. Updating the config

To update the configuration, delete the old portable_config then redo step 3 of the installtion to download the latest version.

Linux / macOS

1. Install mpv

Ubuntu / Debian

sudo apt install mpv

Arch Linux

sudo pacman -S mpv
# or for the git version:
yay -S mpv-git

macOS

brew install mpv

2. Option 1: Install the Configuration manually

Download this repository as a ZIP, extract it, and copy the contents of portable_config into ~/.config/mpv/ (create the folder if it doesn't exist).

3. Option 2: Install with Git instead

git clone https://github.com/HongYue1/mpv-config.git && mkdir -p ~/.config/mpv && cp -r ./mpv-config/portable_config/. ~/.config/mpv/ && rm -rf mpv-config

Settings You May Want to Change

For full option documentation, see the mpv manual (use Ctrl+F to search).

GPU API and Hardware Decoding

This config defaults to Vulkan. If your GPU doesn't support Vulkan or you have playback issues:

mpv.conf

gpu-api=vulkan      # change to: auto, d3d11, or opengl
hwdec=vulkan        # change to: auto, auto-copy, or auto-safe

Default Shader for HD Content

The default shader for 720p–1080p content is CuNNy, which requires Vulkan and is tuned for anime:

profiles.conf

glsl-shader="~~/shaders/CuNNy/ds/dp4a/CuNNy-4x16-DS-Q.glsl"

Note: If you primarily watch live-action content or aren't using Vulkan, delete or replace this line with a shader that suits your content.

Dither Depth

Set this to match your display's bit depth:

mpv.conf

dither-depth=10   # change to 8 for 8-bit displays, or auto if using d3d11

On Windows, check your display bit depth under Settings → System → Display → Advanced display.

YouTube Playback Quality

Default is 1080p. Change the number to set a different cap:

mpv.conf

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

Audio Downmixing

By default, 5.1 and 7.1 audio is downmixed to stereo. If you have a surround system, remove or comment out the Downmix_Audio_5_1 and Downmix_Audio_7_1 profiles in profiles.conf.

ICC Color Profile

icc-profile-auto is disabled by default because it can cause gamma issues on some systems. Enable it in mpv.conf if you have a calibrated ICC profile and want mpv to use it.

Video Output Range

mpv.conf

video-output-levels=full   # change to limited for TVs, or auto

Windows-Only Options

Only enable these if you are on Windows with gpu-api=d3d11:

d3d11-exclusive-fs=yes
dither-depth=auto

Important Notes

First Launch May Be Slow

When launching mpv for the first time with this configuration, or when a shader is used for the first time, mpv may freeze for a few seconds while it compiles and caches the shader. This only happens once per shader — subsequent launches are fast.

Sluggish UI During Playback

If the uosc interface feels slow during playback, add this to mpv.conf:

video-sync=display-resample

This slightly increases CPU/GPU usage but makes the UI feel more responsive. The root cause is that mpv ties UI rendering frequency to the video frame rate during playback — pausing the video will reveal the difference.

Toggle the UI

Press Tab to toggle uosc between always-visible and auto-hide mode.

Shaders

The uosc right-click menu exposes the full shader library, grouped by type. All shader variants are documented inline in input.conf. To clear all active shaders: Ctrl+Alt+C. To show all active shaders: Ctrl+Alt+S.

Included Scripts

Script Description
uosc Minimalist, highly customizable GUI
evafast Hold-to-fast-forward with adaptive speed ramp
thumbfast High-performance on-the-fly thumbnail generation
memo Recent files/history menu with uosc integration
quality-menu Change stream quality (video/audio format) on the fly
mpv-reload Reload stuck or slow streams automatically
mpv-ytsub Load YouTube auto-generated captions
mpv_sponsorblock_minimal Skip SponsorBlock-tagged segments

Included Shaders

Shaders are organized by category in portable_config/shaders/. All are accessible and documented in input.conf.

Luma Upscalers

Shader Best for
CuNNy Anime — fast CNN upscaler with multiple quality tiers and dp4a acceleration
ArtCNN General content — modern CNN upscaler with denoising and downscaling variants
Ani4Kv2 / AniSD Anime — Ani4Kv2 for HD/BD, AniSD for sub-720p sources
FSRCNNX Live-action — high quality prescaler, x2 8-0-4-1 and 16-0-4-1 variants
NNEDI3 High-quality prescaling, slower than FSRCNNX
RAVU Fast prescaling — Lite, Zoom, and Antiringing variants
Anime4K Anime upscaling and restoration — full shader set included
ACNet / ARNet Lightweight anime upscalers from Anime4KCPP with denoising variants
AMD CAS, FSR, NVScaler, NVSharpen GPU vendor upscalers and sharpeners

Chroma Upscalers

Shader Notes
CfL Prediction Default — uses luma information to reconstruct chroma detail
KrigBilateral Alternative chroma upscaler
JointBilateral / FastBilateral Bilateral filter-based chroma upscalers

Downscalers / Sharpeners / Other

Shader Notes
SSimDownscaler Perceptually better downscaling, used automatically for 4K+ sources
SSimSuperRes An accurate sharpener + antiringing shader
nlmeans Non-local means denoiser
hdeband Shader-based debanding
adaptive-sharpen Content-aware sharpening
Film Grain Adds synthetic film grain (normal and smooth variants)

References

Repositories used as references while building this configuration: