Custom mpv Configuration

Custom mpv Configuration (Windows, Linux, and Android)

This is a power user feature, and playback works fine without it. If you want custom shaders, video scaling algorithms, or tone mapping, Moonfin can load your own mpv.conf file.

It applies only to the platforms that run libmpv: Windows, Linux, and Android phones and tablets when the mpv playback engine is selected. It doesn't apply to iOS, Apple TV, or macOS, which play through AetherEngine, and Android TV doesn't offer the setting. See Playback and Codecs for which backend each platform uses.

Setup

1. Go to Settings > Playback & SyncPlay > Advanced Options, find the MPV configuration section, and turn on Enable Custom mpv.conf.
2. Click Custom mpv.conf Path and point it at your mpv.conf file.
   • On Android, the easiest flow is to keep mpv.conf in a normal user folder (for example Downloads) and select it with the picker.
   • If no path is set, Moonfin checks the application support directory and the current working directory automatically.

Typical file locations:

• Linux: ~/.local/share/org.moonfin.linux/mpv.conf
• Windows: C:\Users\YourName\AppData\Roaming\org.moonfin\Moonfin\mpv.conf
• Android: a normal user folder, selected via Custom mpv.conf Path

Those first two are Moonfin's application support folder, which is the directory it checks when no path is set. Where Your Data Is Stored lists it for every platform.

Files over 256 KB are rejected.

Example configuration

# Scaling and rendering
scale=lanczos
deband=yes
tone-mapping=bt.2390

# Video sync and interpolation
video-sync=display-resample
interpolation=yes

# Shaders (see the Shaders section below for the rules)
# glsl-shaders=/home/you/mpv-shaders/first.glsl:/home/you/mpv-shaders/second.glsl

# Color adjustments
gamma=1.1
saturation=1.05

How Moonfin reads your file

Moonfin doesn't hand your file to mpv to load. It reads it line by line and sets each option on the player, so a few things work differently from standalone mpv:

• No quotes around values. Write scale=ewa_lanczossharp, not scale="ewa_lanczossharp". The quotes are passed through as part of the value, and mpv either rejects it or looks for a file with quotes in its name.
• Profiles are ignored. A [profile] header is skipped, but the lines under it still apply, all the time. Move anything you want applied out of profile blocks, and delete what you don't.
• Later lines win. If the same option shows up twice, the last one is the one you get.
• Changes apply the next time you start playing something, not to a video that's already playing.

Shaders

Shaders work, but only in one form. Put all of them on a single glsl-shaders= line:

glsl-shaders=/home/you/.config/mpv/shaders/FSRCNNX_x2_8-0-4-1.glsl:/home/you/.config/mpv/shaders/KrigBilateral.glsl

• Use glsl-shaders= only. glsl-shaders-append= and glsl-shader= are silently skipped, so a conf that adds shaders one per line loads none of them.
• Separate multiple shaders with : on Linux and Android, and ; on Windows.
• Use full paths. ~~/ doesn't point at your mpv config folder in Moonfin, so ~~/shaders/... won't be found. On Linux, ~/ for your home folder works.
• No quotes around the paths.
• glsl-shader-opts= works too, if a shader takes parameters.

If you installed Moonfin as a snap, it can't read hidden folders like ~/.config, and ~/ points inside the snap's own folder. Copy your shaders to a normal folder such as ~/Documents/mpv-shaders and use the full /home/you/... path.

Where scaling and shaders apply

mpv only scales the picture to your screen when it draws into its own window, which happens on Windows (see HDR on Windows). On Linux, and on Windows when video plays inside the app's own video view, mpv draws at the video's own resolution and Moonfin stretches the result to fit. There, scale, dscale, sigmoid-upscaling and upscaling shaders such as FSRCNNX, Anime4K or NVScaler won't make the picture any sharper. Chroma scaling, deband, dither, tone mapping and the color adjustments still apply.

Allowed and blocked options

Allowed options (basic and advanced scaling, rendering):

• Scaling: scale, cscale, dscale, and the scale-*, cscale-* and dscale-* options
• Rendering: sigmoid-upscaling, deband, deband-*, interpolation, tscale, video-sync, dither, dither-depth
• Color and tone: tone-mapping, tone-mapping-param, tone-mapping-mode, gamut-mapping-mode, brightness, contrast, saturation, gamma, sharpen
• HDR output: target-trc, target-prim, target-peak, target-contrast, target-colorspace-hint, target-colorspace-hint-mode, hdr-compute-peak, target-inverse-tone-mapping
• Audio: audio-spdif, audio-channels, audio-normalize-downmix, volume-gain, volume-max, replaygain, replaygain-preamp, replaygain-clip, replaygain-fallback
• Effects: deinterlace, keep-open
• GLSL shaders: glsl-shaders and glsl-shader-opts (see Shaders)

On Windows and Linux, Moonfin starts mpv with dither=fruit, scale=spline36, dscale=mitchell, cscale=spline36, sigmoid-upscaling=yes, tone-mapping=bt.2390 and hdr-compute-peak=yes. Your file is applied after these, so anything you set wins.

The HDR output keys matter most on Windows with Native HDR output turned on (see Playback and Codecs). target-colorspace-hint only does something where mpv owns its own window, so on the normal texture path it's harmless but has no effect.

Protected options affect core playback and are ignored:

• aid, sid, vid (track selection)
• sub-visibility, sub-ass, sub-ass-override (subtitle rendering)
• sub-delay, audio-delay (sync controls)
• network-timeout, sub-fonts-dir, sub-font (core behavior)

Blocked options are rejected for security:

• script, scripts, script-opts, load-scripts, and anything starting with script- (script execution)
• anything starting with ipc-
• include, profile, input-conf (config file manipulation)

Anything not on the allowed list is skipped too, unless unsafe advanced mode below unlocks it.

Advanced: unsafe advanced mode

Enable Unsafe Advanced mpv Options to unlock lower-level settings:

• vo (video output driver)
• gpu-api, gpu-context (GPU backend selection, a wrong value here blacks out all playback)
• hwdec (hardware decoding mode)
• audio-exclusive (request exclusive output mode)
• vf, af (custom video and audio filters)
• input-ipc-server (IPC socket endpoint)
• vd-lavc-* (decoder options)
• demuxer-* and cache-* (stream behavior)

Warning: these options can break playback or cause instability if misconfigured.

Checking that your settings took effect

On Windows, mpv's statistics overlay shows what mpv is actually doing: the decoder, the scaler, the output format and so on. Press Shift+I during playback, or open the playback information (I) and use the button there. It's the quickest way to confirm a line in your mpv.conf was applied.

Linux has no statistics overlay. With unsafe advanced mode on, add input-ipc-server=/run/user/1000/mpv.sock to your file (use your own user id in place of 1000), start playing something, and ask mpv directly:

echo '{"command":["get_property","scale"]}' | socat - /run/user/1000/mpv.sock

SVP (Smooth Video Project) on Windows

Moonfin ships a minimal libmpv-2.dll for a smaller download. Normal playback works fine with it. If you use SVP for frame interpolation, replace it with a full build that includes vapoursynth support:

1. Download the latest libmpv-2.dll from shinchiro/mpv-winbuild-cmake (the ~115 MB x86_64-v3 build).
2. Replace libmpv-2.dll in your Moonfin installation folder (default C:\Program Files\Moonfin\).
3. Launch SVP Manager before starting playback in Moonfin.