Custom mpv Configuration

Custom mpv Configuration (Desktop + Android)

Moonfin allows power users to fine-tune playback behavior using a custom mpv.conf file. This enables advanced options like custom shaders, video scaling algorithms, tone mapping, and more.

This applies to the platforms that play through libmpv. See Playback and Codecs for which backend each platform uses.

Setup

1. Enable Custom mpv.conf: Go to Settings > Playback > Advanced mpv and toggle Enable Custom mpv.conf to on.

2. Specify File Location: Provide a path to your mpv.conf file:

   • Click Custom mpv.conf Path to browse or enter the path manually.
   • On Android, the easiest flow is to create/store mpv.conf in a user-accessible folder (for example Downloads) and select it with the picker.
   • Moonfin will automatically check for mpv.conf in standard locations if not specified:
     • Application support directory (recommended)
     • Current working directory

3. Example File Locations

   • Linux: ~/.config/Moonfin/mpv.conf or /home/user/.local/share/Moonfin/mpv.conf
   • macOS: ~/Library/Application Support/Moonfin/mpv.conf
   • Windows: C:\Users\YourName\AppData\Local\Moonfin\mpv.conf
   • Android: Keep mpv.conf in a normal user folder (for example Downloads) and select it via Custom mpv.conf Path

File Size Limit

Configuration files must not exceed 256 KB. Larger files are rejected.

Allowed and Blocked Options

Protected Options: These affect core playback and are not configurable:

• aid, sid, vid (audio/subtitle/video 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: These are blocked for security:

• script, scripts, script-opts, load-scripts (script execution)
• include, profile, input-conf (config file manipulation)

Allowed Options (Basic & Advanced scaling, rendering):

• Scaling: scale, cscale, dscale, scale-* options
• Rendering: sigmoid-upscaling, deband, deband-*, interpolation, tscale, video-sync
• Color & tone: tone-mapping, tone-mapping-param, target-trc, brightness, contrast, saturation, gamma, sharpen
• Audio: audio-spdif, audio-channels, audio-normalize-downmix
• Effects: deinterlace, keep-open
• GLSL shaders: glsl-shader* (loading custom shaders)

Unsafe Advanced Mode

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

• vo (video output driver)
• gpu-context (GPU backend selection)
• hwdec (hardware decoding mode)
• audio-exclusive (request exclusive output mode)
• vf, af (custom video/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.

Example Configuration

# Scaling and rendering
scale=lanczos
deband=yes
tone-mapping=hdr

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

# Shaders (if using unsafe advanced)
# glsl-shader=/path/to/shader.glsl

# Color adjustments
gamma=1.1
saturation=1.05

SVP (Smooth Video Project) on Windows

Moonfin ships a minimal libmpv-2.dll for a smaller download size. If you use SVP for frame interpolation, you need to 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.

Normal playback works fine with the included DLL, this swap is only needed for SVP.