On-Screen Controller

mpv’s built-in mouse-controlled GUI overlay — layout, controls, and configuration

The On-Screen Controller (OSC) is a minimal built-in GUI integrated into mpv that provides mouse-controllable playback controls. It is designed to make mpv accessible to new users and to enable precise direct seeking with a mouse.

The OSC requires Lua support at compile time. It is enabled by default in all official mpv builds.

Enabling and disabling

mpv --osc=yes file.mkv    # enabled (default)
mpv --osc=no file.mkv     # disabled

You can also disable it in your config file:

# ~/.config/mpv/mpv.conf
osc=no

How the OSC appears

By default, the OSC appears whenever you move the mouse inside the player window and hides after 0.5 seconds of mouse inactivity, or when the mouse leaves the window. Press del to cycle between auto (mouse-triggered), always visible, and never visible.

Interface layout

+------+---------+---------+-----------------------------------------------+
| menu | pl prev | pl next | title                                   cache |
+------+------+------+---------+-----------+------+-------+-----+-----+----+
| play | skip | skip | time    |  seekbar  | time | audio | sub | vol | fs |
|      | back | frwd | elapsed |           | left |       |     |     |    |
+------+------+------+---------+-----------+------+-------+-----+-----+----+

Control reference

menu

Action	Result
Left-click	Open the context menu

pl prev / pl next

Action	Result
Left-click	Play previous / next file in playlist
Shift+left-click	Show the playlist
Middle-click	Show the playlist
Right-click	Open the playlist menu

title

Displays the current playlist position and media title, filename, or custom title. While hovering the seekbar, shows the target chapter name instead.

Action	Result
Left-click	Show file and track info
Shift+left-click	Show the file path
Middle-click	Show the file path
Right-click	Open the history menu

cache

Shows the current cache fill status.

play (play/pause button)

Action	Result
Left-click	Toggle play/pause
Shift+left-click	Toggle infinite playlist looping
Middle-click	Toggle infinite playlist looping
Right-click	Toggle infinite looping of the current file

skip back / skip frwd

Action	Result
Left-click (skip back)	Go to start of current chapter / previous chapter
Left-click (skip frwd)	Go to next chapter
Shift+left-click	Show chapter list
Middle-click	Show chapter list
Right-click	Open the chapter menu

time elapsed / time left

Action	Result
Left-click (time elapsed)	Toggle millisecond display
Left-click (time left)	Toggle between total and remaining time

seekbar

Indicates current playback position and shows chapter markers.

Action	Result
Left-click	Seek to clicked position
Right-click	Seek to nearest chapter
Mouse wheel	Seek forward / backward

audio / sub track selectors

Shows the selected track and the total number of available tracks.

Action	Result
Left-click	Cycle tracks forward
Shift+left-click	Cycle tracks backward
Middle-click	Cycle tracks backward
Right-click	Open the track selection menu
Mouse wheel	Cycle tracks forward / backward

vol (volume)

Action	Result
Left-click	Toggle mute
Right-click	Open audio device menu
Mouse wheel	Volume up / down

fs (fullscreen)

Action	Result
Left-click	Toggle fullscreen
Right-click	Toggle window maximized state

Key bindings

Key	Action
del	Cycle OSC visibility: auto (mouse) → always → never

Configuration

The OSC is configured through a config file or via --script-opts on the command line.

Config file: ~/.config/mpv/script-opts/osc.conf

Command line:

mpv --script-opts=osc-layout=bottombar,osc-seekbarstyle=knob file.mkv

All option names must be prefixed with osc- on the command line.

Layout options

layout · string · default: "bottombar"

The overall OSC layout. Available layouts:

• bottombar — horizontal bar at the bottom (default)
• topbar — horizontal bar at the top
• slimbottombar — thinner version of bottombar
• slimtopbar — thinner version of topbar
• box — compact floating box
• slimbox — slimmer floating box
• floating — compact floating window controls

# script-opts/osc.conf
layout=topbar

seekbarstyle · bar|diamond|knob · default: "bar"

Style of the playback position marker on the seekbar.

seekbarhandlesize · float · default: "0.6"

Size of the seek handle when seekbarstyle is diamond or knob. Relative to the full seekbar height.

seekbarkeyframes · yes|no · default: "yes"

Use keyframe-based seeking when dragging the seekbar. Set to no for exact seeking on drag (may be slower).

seekrangestyle · inverted|bar|line|slider|none · default: "inverted"

Display style for seekable (cached) ranges on the seekbar.

Visibility and scaling

visibility · auto|never|always · default: "auto"

Controls when the OSC is visible:

• auto — show on mouse movement, hide after inactivity
• always — always visible
• never — always hidden

scalewindowed · float · default: "1.0"

Scale factor for the OSC when the player is in windowed mode.

scalefullscreen · float · default: "1.0"

Scale factor for the OSC when the player is in fullscreen mode.

vidscale · auto|yes|no · default: "auto"

Whether to scale the OSC with the video:

• auto — scale with OSD (respects --osd-scale-by-window)
• no — keep OSC size constant as the window resizes

showwindowed · yes|no · default: "yes"

Show the OSC in windowed mode.

showfullscreen · yes|no · default: "yes"

Show the OSC in fullscreen mode.

Timing and appearance

hidetimeout · integer (ms) · default: "500"

Milliseconds of mouse inactivity before the OSC hides. Must not be negative.

fadeduration · integer (ms) · default: "200"

Duration of the fade-in and fade-out animations. Set to 0 to disable fading.

timems · yes|no · default: "no"

Display timecodes with millisecond precision.

timetotal · yes|no · default: "no"

Show total duration instead of time remaining in the right timecode display.

title · string

Template string for the OSC title. Supports property expansion. Default: ${!playlist-count==1:[${playlist-pos-1}/${playlist-count}] }${media-title}

boxalpha · integer (0–255) · default: "80"

Background box transparency for box and slimbox layouts. 0 is opaque, 255 is fully transparent.

deadzonesize · float (0.0–1.0) · default: "0.75"

Size of the deadzone — an area where mouse movement does not trigger the OSC. The deadzone spans this fraction of the window, starting from the edge opposite the OSC. 0 means the OSC appears anywhere in the window; 1 means only hovering the OSC itself shows it.

Colors

All color values use #RRGGBB format.

background_color · color · default: "#000000"

Background color of the OSC.

timecode_color · color · default: "#FFFFFF"

Color of timecodes and the seekbar.

title_color · color · default: "#FFFFFF"

Color of the title text.

buttons_color · color · default: "#FFFFFF"

Color of the main playback buttons.

Window controls

windowcontrols · auto|left|right|no · default: "auto"

Whether to show window management controls (minimize, maximize, quit) over the video. Useful when the window has no system title bar.

auto shows controls when there is no system title bar.

windowcontrols_alignment · left|right · default: "right"

Which side to place window controls on.

Custom buttons

You can add up to several custom buttons in bottombar and topbar layouts. Each button is configured with a set of custom_button_N_* options:

# script-opts/osc.conf

custom_button_1_content=🔁
custom_button_1_mbtn_left_command=cycle-values loop-file inf no
custom_button_1_mbtn_right_command=cycle-values loop-playlist inf no

custom_button_2_content=🔀
custom_button_2_mbtn_left_command=playlist-shuffle

custom_button_3_content=⏱
custom_button_3_mbtn_left_command=add speed 1
custom_button_3_mbtn_right_command=set speed 1
custom_button_3_wheel_up_command=add speed 0.25
custom_button_3_wheel_down_command=add speed -0.25

Script commands

Other scripts and input.conf bindings can send commands to the OSC:

Command	Effect
osc-visibility never	Hide the OSC
osc-visibility auto	Set to mouse-triggered mode
osc-visibility always	Always show the OSC
osc-visibility cycle	Cycle through visibility modes
osc-show	Trigger the OSC to appear (as if the mouse moved)
osc-hide	Hide the OSC (when in auto mode)
osc-idlescreen yes/no/cycle	Control the mpv logo idle screen

Example input.conf:

a script-message osc-visibility never
b script-message osc-visibility auto

Example configuration

# ~/.config/mpv/script-opts/osc.conf

layout=bottombar
seekbarstyle=knob
timems=no
timetotal=no
scalewindowed=1.2
scalefullscreen=1.0
vidscale=auto
hidetimeout=1000
fadeduration=150
visibility=auto
boxalpha=100
background_color=#111111
title_color=#FFFFFF