ulyssescaballes-mpv.config
||||⚓
Ulysses RS Caballes - MPV Cinema Config
A handcrafted cinema engine for MPV.
Uniting neural upscaling, HDR tone mapping, and immersive 3D spatial audio.
Built for precision. Tuned for immersion. Crafted for cinephiles.
Build & Capabilities
What This Configuration Delivers
✓ Vulkan (gpu-next) high-quality video rendering pipeline
✓ Advanced GLSL shader stack: CuNNy (CNN upscaling), SSimSuperRes, Adaptive Sharpen, Depth Reality Boost
✓ HDR tone mapping with contrast recovery (BT.2390)
✓ ICC color-managed playback
✓ Immersive 3D spatial audio
✓ Modular profiles for anime, realism, sports, and 8K content
Performance Notes
This handcrafted cinema engine for MPV is designed to scale smoothly across a wide range of GPU hardware.
The playback pipeline has been tried and tested on hardware as old as the NVIDIA GTX 650, establishing it as a practical baseline. A GTX 650-class GPU or newer is strongly recommended. The newer and more powerful the GPU, the better, with shader complexity, scaling, and output resolution adjusted to match the available GPU performance.
For older or lower-powered GPUs, lighter shader profiles are recommended, while more powerful GPUs can take advantage of higher resolutions, heavier shader chains, and the full processing pipeline.
The CuNNy-8x32-DS-Q shader profile is optimized for Windows 11 environments and may cause performance issues (lag or dropped frames) on Linux systems with AMD GPUs.
Recommended for Linux/AMD setups:
✓ FSRCNNX-x2_16-0-4-1 → lighter, stable, and cross-platform friendly
✓ CuNNy-4x32 or CuNNy-2x32 → reduced demand with good perceptual quality
✓ Hybrid stacks (FSRCNNX + Adaptive Sharpen / Depth Reality Boost) → balance between speed and sharpness
This ensures smoother playback while preserving visual detail and stability.
Table of Contents
- Overview
- Features
- Demo Clip
- Screenshots
- Shader Pipeline
- Audio Pipeline
- Profiles
- Video Keyboard Function Shortcuts
- Audio Keyboard Function Shortcuts
- Menu & Utility Shortcuts
- Script Suite
- Installation
- Common Toggles & Beginner Notes
- Optional Add-ons
- MPV + YouTube Integration
- Philosophy
- Repo Hygiene
- Final Word
- License
Overview
This MPV configuration is engineered for viewers who demand cinematic fidelity, pristine rendering, and uncompromising visual precision across everything from anime, films, and sports to 8K HDR.
Every component is meticulously tuned for clarity, depth, detail, and lifelike realism, driven by a custom shader pipeline and Lua automation that dynamically adapts to the content while preserving its cinematic intent.
For the ultimate cinematic experience with maximum visual impact, a powerful high-end GPU is strongly recommended.
Features
✓ Custom GLSL pipeline for super-resolution, sharpening, depth, and film emulation
✓ Vulkan-optimized rendering for high-performance playback
✓ Content-aware profiles (anime, realism, sports, 8K)
✓ Lua automation for dynamic shader control and recovery
✓ Clean, modular and remixable architecture
Demo Clip
This clip was rendered and played with this configuration, showcasing HEVC Main 10 playback, HDR tone mapping, and full shader fidelity.
Screenshots
Debanding and tone mapping - smooth gradients, lifelike contrast.
Styled subtitles and shader stack delivering cinematic realism.
Visual Improvements
| Without Config | With Ulysses RS Caballes - MPV Cinema Engine | How | |—————|————————|——————| | Flat colors | Cinematic tone mapping | BT.2390 HDR curve + GAMMA / Perceptual Linearity | | Aliasing artifacts | Neural upscaling | CuNNy-8x32-DS-Q | | Washed HDR | Contrast recovery | stucki + debanding | | Weak audio stage | 3D Spatial audio | Equalizers+ | —
Shader Pipeline
-
Debanding (fade‑aware, error diffusion dithering)
-
Tone Mapping (BT.2390 with contrast recovery)
-
Resampling - 26-tap separable kernel
-
Adaptive Sharpen - linear-light, curve height tuned, overshoot control
-
Depth Reality Boost - perceptual depth cues without halos
Audio Pipeline
- Immersive 3D Spatial Audio
- Virtualized audio rendering for realistic positioning and depth.
- Supports optional custom audio datasets via [main.lua].
- EQ Chain
- Bass reinforcement, midrange cleanup, treble clarity, and subharmonic depth.
- Dynamics Control
- Normalization, compression, and limiter for safe playback.
Profiles
This configuration includes multiple playback profiles tailored to different content types. Each profile adjusts shaders, scaling, tone mapping, and enhancement strength.
Realism Fidelity
- Balanced sharpen, depth boost, filmic grain, natural color
- Super‑resolution, minimal grain, precision tone mapping, GPU-efficient scaling
Anime Fidelity
- Line‑art‑safe sharpen, debanding, gentle vibrancy, light grain
Sports Fidelity
- Motion‑clarity‑oriented sharpen, reduced grain, highlight visibility, clean gradients
Video Keyboard Function Shortcuts
| Shortcut | Function Name | Description |
|---|---|---|
| Ctrl + 1 | realism_fidelity | Realism as in baseline configuration. |
| Ctrl + 2 | anime_fidelity | Anime HDR preset. |
| Ctrl + 3 | sports_fidelity | Sports preset. |
| Ctrl + 4 | debug | Debugging overlays. |
Audio Keyboard Function Shortcuts
| Shortcut | Function Name | Description |
|---|---|---|
| F + 9 | pure-mode | Pure Headset Reference Playback |
| F + 10 | cinema-mode | Cinema IMAX-inspired SenseSurround Mode |
| F + 11 | music-mode | Music Live Concert Mode |
| F + 12 | reset-filters | Filters Cleared |
Menu & Utility Shortcuts
| Key | Action |
|---|---|
| O | Open File |
| Y | YouTube Search |
| H | Playback History |
| K | Keybinds Menu |
| V | Video Settings |
| A | Audio Device Selector |
| S | Subtitle Settings |
| P | Screenshot Menu |
| Shift + S | Screenshot / Saved on Desktop |
Script Suite
-
shader-recover.lua
Reloads shaders if an error occurs. -
profile-auto.lua
Auto-selects profile based on resolution/framerate. -
stats-overlay.lua
Displays GPU load, tone mapping status, and active shaders. -
subtitle-style.lua
Cinematic subtitle styling. -
audio/main.lua
Custom Lua script for handling spatial audio effects and optional audio datasets.
Installation
Note: This configuration uses MPV in portable mode.
Settings, scripts, shaders, profiles, and related files are stored inside the portable_config directory alongside mpv.exe.
Requirements:
✓ MPV v0.41+
✓ Vulkan‑capable GPU
✓ Compatible 64-bit processor
✓ Windows 11 (recommended)
Download mpv-x86_64-v3 (Zhongfly builds):
mpv-x86_64-v3 (Zhongfly builds)
- Open File Explorer
- Enable: View → Show → Hidden items
- Navigate to %APPDATA%
- Create folder named MPV
- Extract the MPV Zhongfly build into this folder
- Open the installer folder then right-click updater.ps1 and select Run with Powershell
- Right-click mpv-register.bat and select Run as administrator
- Press Win + R and enter ms-settings:defaultapps
- Scroll down and select app mpv
- Set default file and link types to MPV
- Right-click updater.bat and select Run as administrator then follow the prompts
- Download or clone this repository and extract the
portable_configfolder - Place the “portable_config” folder here:
“C:/Users//AppData/Roaming/MPV/***portable_config***"
%APPDATA%\MPV\
│
├── mpv.exe
└── portable_config\
├── mpv.conf
├── input.conf
├── script-opts\
├── scripts\
│ └── main.lua\
│
└── shaders\
├── CuNNy-8x32-DS.glsl
├── SSim\
├── Adaptive_sharpen\
└── Depth_reality_boost\
- The configuration is designed around Vulkan rendering. Ensure MPV is configured to use Vulkan:
gpu-api=vulkan
- Double-click any media file and MPV will instantly play it, or play CDs, DVDs, and Blu-ray discs with maximum audio and video quality playback, each time, all the time. Sit back, relax, and enjoy a seamless viewing and listening experience.
- Regularly check for MPV updates by right-clicking updater.bat and selecting Run as administrator. If an update is available, it will be downloaded and installed automatically.
Common Toggles & Beginner Notes
| Option | Setting | Effect |
|---|---|---|
| Idle Behavior | idle=yes |
MPV stays open even with no file loaded (useful for drag‑and‑drop). |
idle=no |
MPV closes automatically after playback (traditional media player feel). | |
| On‑Screen Controller (OSC) | osc=no |
Disables the control bar for a cleaner, cinema‑style look. |
osc=yes |
Enables the familiar UI with playback controls. | |
| Window Border | border=no |
Removes title bar for a cinema‑style presentation. |
border=yes |
Restores standard window controls. | |
| Volume Max | volume-max=130 |
Allows boosting volume beyond 100% (use with care to avoid distortion). |
Optional Add-ons
| Add-on | Purpose/Benefit |
|---|---|
| Anime4K | Stylized upscaling for animation content |
| FSRCNNX | Neural network–based upscaling |
| RAVU | High‑precision scaling |
| SVP / Motion Interpolation | Smoother playback for sports and fast motion |
| External LUTs | Custom color grading for cinematic tone |
MPV + YouTube Integration
Instructions on how to enable MPV to directly open and play YouTube streams from a web browser (Applicable only to Firefox-based browsers or on any Firefox based variants):
- Download and install Firefox or one of its variants. For the best experience,
Floorpis highly recommended. - Install browser extension:
ff2mpv (for Windows)from Firefox Browser Add-ons. - Download:
ff2mpv-master.zip - Extract “ff2mpv-master.zip” inside [MPV] folder.
- Open “ff2mpv-master” folder, copy “ytdlProtocol.bat” then paste it outside “ff2mpv-master” folder to sit where “mpv.exe” is placed inside [MPV] folder, here:
“C:/Users//AppData/Roaming/MPV/***ytdlProtocol.bat***". - Right click “ytdlProtocol.bat”, then “Run as Administrator” once.
- Open YouTube in your Firefox-based browser, right-click on the video stream of your choice. From the context menu, scroll down and select “Play link in MPV”. If prompted, check the box labeled “Always allow this extension to open ytdl links” and then click “Open Link”. MPV will instantly play the selected YouTube video stream directly with the best audio and video quality playback. Sit back, relax, and enjoy a smooth, immersive viewing experience every time.
Philosophy
This configuration is guided on two core principles:
Precision
Every shader, parameter, and filter is chosen with intent - no bloat, no placebo settings.
Cinematic Realism
The complete configuration is optional by design.
You can:
✓ Use everything
✓ Replace individual shaders
✓ Reduce the processing workload
✓ Build your own profile
✓ Adopt only the audio configuration
✓ Adopt only the video configuration
✓ Reuse individual scripts
✓ Remix the entire architecture
The configuration is a foundation, not a restriction.
Adopt the full pipeline or integrate only the components you need.
Repo Hygiene
| Practice | Description |
|---|---|
| No cache files | Temporary and automatically generated cache files are excluded. |
| No platform clutter | Unnecessary operating-system metadata is avoided. |
| Clean folder structure | Configurations, shaders, scripts, and options remain organized. |
| Human‑readable configs | Config files are concise, documented, and easy to understand. |
| Commented shader chains | Each GLSL filter is annotated for clarity and maintainability. |
| Versioned updates | Clear changelogs accompany every update for transparency. |
| Commit intent | Every commit message documents purpose, no silent changes. |
Final Word
License
This project is licensed under the GNU General Public License v3.0. Feel free to fork, adapt, and share.
See the LICENSE file for details.