How to customize the mpv OSC appearance?

The on-screen controller (OSC) in mpv can be customized easily by modifying the player’s configuration files, allowing you to change its layout, scale, and behavior without editing complex code. While mpv looks minimal by default, it includes several built-in interface styles and scaling options that can be managed either directly within your main configuration or via a dedicated script options file. This article covers how to change the OSC layout, adjust its size for different window modes, and apply these settings to your player.

Method 1: Using the main mpv.conf File

You can pass configuration options directly to the OSC script using the script-opts property inside your main mpv.conf file.

To change the layout and size, locate your mpv.conf file and add the following lines:

# Choose a built-in layout (options: box, slimbox, bottombar, topbar)
script-opts=osc-layout=bottombar

# Adjust the interface scale for windowed and fullscreen modes
script-opts-add=osc-scalewindowed=1.0
script-opts-add=osc-scalefullscreen=1.2

Method 2: Using a Dedicated osc.conf File

For a cleaner configuration setup, you can create a standalone file dedicated entirely to the controller options. This removes the need to prefix every option with osc-.

1. Navigate to your mpv configuration directory.
2. Inside the folder, look for or create a subfolder named script-opts.
3. Create a new text file inside script-opts and name it osc.conf.
4. Add your preferred appearance variables directly to this file:

layout=slimbox
seekbarstyle=bar
deadzonesize=0.5
scalewindowed=0.8
scalefullscreen=1.0

Common OSC Customization Options

You can mix and match several built-in parameters to fine-tune how the player interface responds to your mouse and screen resolution:

• layout: Changes the overall design template. The bottombar option offers a modern, full-width progress bar, while box creates an overlapping floating window look.
• seekbarstyle: Sets the style of the timeline. Options include bar (a solid block) or slider (a thin line with a knob).
• deadzonesize: Controls how close the mouse cursor must be to the bottom screen edge before the controller appears. Setting this to 0 makes it show up only when moving the mouse directly over the interface.
• minmousemove: Defines the minimum number of pixels the mouse must move before revealing the controller, preventing accidental triggers from shaky surfaces.