Important
This script is updated most frequently at mpvconfig, stable builds are released here in the releases tab.
A fork of mpvX (based on mpv-osc-modern), that aims to mirror the functionality of MPV's stock OSC while with a more modern-looking interface.
Note
This script is included in my mpvconfig, check that repository for a full mpv configuration
This fork changes the following:
- Adds compact mode and reorganises some features
- Added loop and pin window buttons
- Adds a download button for web videos
- Displays descriptions, likes and dislike counts from web videos
- Added shift+left clicking and shift+right clicking the audio/subtitles button for a list of tracks are shown and traversed through
- Pressing TAB shows a list of chapters
- Added dynamic title changing depending on the file/source being played
- Many more configurable options
- Various bug fixes
Locate your MPV folder. It is typically located at \%APPDATA%\mpv\
on Windows and ~/.config/mpv/
on Linux/MacOS. See the Files section in mpv's manual for more info.
Note
Create these folders if you don't have them already
Place modernx.lua
into your mpv scripts/
folder, remove any previous OSC scripts.
Then place the two fonts in the fonts/
folder. Material-Design-Iconic-Font.ttf (click the link to download) and also Material-Design-Iconic-Round.ttf.
Add the following lines to your mpv.conf
file.
Note
Please note that in .conf
files use yes/no in place of true/false
osc=no
border=no #optional - if you don't want to see the OS border
This is what disabling and enabling the border looks like:
Border Enabled | Border Disabled |
---|---|
Note
This option may vary depending on your system.
Create an modernx.conf
file and place it in the script-opts/
folder (create the folder if you haven't already). A plethora of options can be changed, so please refer to the table of configurable user_opts
parameters below for detailed explanations of settings.
Here is an example of a configuration file, which would be placed in script-opts/modernx.conf
:
compactmode=no
showinfo=yes
titlefontsize=20
seekbarhandlesize=0
Option | Description |
---|---|
language | The language of the osc, mostly messages that are shown in the top left of the screen |
welcomescreen | Whether to show the mpv 'Drop files or URLs to play here.' screen |
windowcontrols | Whether to show OSC window controls, 'auto' will only show them in fullscreen or when borderless, 'yes' always shows them and 'no' never shows them |
keybindings | If to register keybindings i.e. chapter scrubbing, pinning window |
showwindowed | Whether to show the OSC when windowed |
showfullscreen | Whether to show the OSC when in fullscreen |
noxmas | Disable showing the santa hat in December |
keybindings | Whether the script should register keybindings for things like chapter scrubbing |
vidscale | Whether the OSC scales with the window's size |
scalewindowed | The scaling of the OSC when windowed |
scalefullscreen | The scaling of the OSC when in fullscreen |
scaleforcedwindow | The scaling when rendered on a forced window (like an audio file) |
hidetimeout | Duration in ms until the OSC hides when there is no mouse movement |
fadeduration | Duration in ms of the fade effect the OSC exihibts |
minmousemove | The minimum amount of pixels the mouse has to move for the OSC to show |
scrollingSpeed | The speed of scrolling text in menus |
showonpause | Whether to disable the hide timeout on pause (when enabled, pausing will show the OSC instantly) |
donttimeoutonpause | Whether to disable the hide timeout on pause |
bottomhover | If the osc should only display when hovering over UI elements at the bottom of the window (includes the window control buttons at the top if visible) On: Off: |
raisesubswithosc | Whether to raise any subtitles being shown, if the OSC is being shown |
thumbnailborder | The width of outline of the thumbnail border |
persistentprogress | Whether to always show a small progress line at the bottom of the screen |
persistentprogressheight | The height of the persistentprogress bar |
persistentbuffer | Whether, on web videos to show the buffer on the persistent progress line |
persistentprogresstoggle | Whether to enable toggling the persistentprogress bar |
showtitle | Whether to show the title in the OSC |
showdescription | Whether to show video description on web videos, clicking it will show an on-screen box of the full description |
showwindowtitle | Whether to show to window title, when the window is borderless/fullscreened (this will match whatever is set in your mpv.conf file) |
showfilesize | Whether to show the current file's size in the description |
titleBarStrip | Whether to make the title bar a singular bar, instead of a black fade at the top of the screen |
title | What title is shown in the OSC, see the mpv manual for more properties - turn off dynamictitle for this option to be respected |
dynamictitle | Changed what title information is shown depending on if the filename and media-title properties differ, seen most in audio files and playing urls |
updatetitleyoutubestats | Whether to update the window/OSC title bar with YouTube video stats (views, likes, dislikes) |
font | The font of the OSC, by default matches the font set in mpv.conf |
titlefontsize | The size of the title text |
chapterformat | The format of the chapter text when hovering over the seekbar. Use 'no' to disable |
dateformat | how dates should be formatted, when read from metadata (uses standard lua date formatting) |
osc_color | The colour of the OSC and title bar |
OSCfadealpha | Alpha of the background box for the OSC |
boxalpha | Alpha of the fade box effect, 0 (opaque) to 255 (fully transparent) |
descriptionBoxAlpha | Alpha of the description background box |
seekbarfg_color | Colour of current seekbar progress and the handle |
seekbarbg_color | Colour of the remaining seekbar |
seekbarkeyframes | Whether to use keyframes when dragging the seekbar |
automatickeyframemode | Whether to set seekbarkeyframes based on video length to prevent laggy scrubbing on long videos |
automatickeyframelimit | Videos of above this length (in seconds) will have seekbarkeyframes on |
seekbarhandlesize | How big the seek bar handle appears, from 0 to 1 |
seekrange | Whether to show the buffer range on the seekbar |
seekrangealpha | The transparency of seekranges |
iconstyle | Whether the icons are normal or round varients - thanks to cyl0#55 |
hovereffect | Whether buttons emit a glowing effect when hovered over |
timetotal | Whether to display the total time instead of remaining time |
timems | Whether to display time in milliseconds |
timefontsize | The font size of the time |
jumpamount | How many seconds the jump buttons jump by |
jumpiconnumber | Whether to show 5, 10 or 30 in the jump icons if the jumpamount are any of those values |
jumpmode | What kind of seeking mode is used for the jump buttons |
volumecontrol | Whether to show the mute button and volume slider |
volumecontroltype | Whether to use linear or logarithmic volume scale |
showjump | Whether to show the jump forward/backward buttons |
showskip | Whether to show the chapter buttons |
compactmode | Remove the 'jump' buttons and embed that functionality in the 'chapter' buttons, see compact mode for more information |
showloop | Whether to show the loop button |
loopinpause | Whether to activate looping by right clicking pause |
showontop | Whether to show the pin window on top button |
showinfo | Whether to show the info button |
downloadbutton | Whether to show download button for web videos |
downloadpath | The download path for videos |
showyoutubecomments | EXPERIMENTAL - not ready, show YouTube comments below the clickable description |
commentsdownloadpath | The download path for the comment JSON file |
ytdlpQuality | What quality of video the download button uses (a max quality mp4 by is downloaded by default) |
The default options are shown below:
-- Parameters
-- default user option values
-- Change them using osc.conf
local user_opts = {
-- general settings --
language = 'en', -- en:English, chs:Chinese, pl:Polish, jp:Japanese
welcomescreen = true, -- show the mpv 'play files' screen upon open
windowcontrols = 'auto', -- whether to show OSC window controls, 'auto', 'yes' or 'no'
showwindowed = true, -- show OSC when windowed?
showfullscreen = true, -- show OSC when fullscreen?
noxmas = false, -- disable santa hat in December
keybindings = true, -- register keybindings i.e. chapter scrubbing, pinning window
-- scaling settings --
vidscale = false, -- whether to scale the controller with the video
scalewindowed = 1.0, -- scaling of the controller when windowed
scalefullscreen = 1.0, -- scaling of the controller when fullscreen
scaleforcedwindow = 1.0, -- scaling when rendered on a forced window
-- interface settings --
hidetimeout = 2000, -- duration in ms until OSC hides if no mouse movement
fadeduration = 150, -- duration of fade out in ms, 0 = no fade
minmousemove = 0, -- amount of pixels the mouse has to move for OSC to show
scrollingSpeed = 40, -- the speed of scrolling text in menus
showonpause = true, -- whether to show to osc when paused
donttimeoutonpause = false, -- whether to disable the hide timeout on pause
bottomhover = true, -- if the osc should only display when hovering at the bottom
raisesubswithosc = true, -- whether to raise subtitles above the osc when it's shown
thumbnailborder = 2, -- the width of the thumbnail border
persistentprogress = false, -- always show a small progress line at the bottom of the screen
persistentprogressheight = 17, -- the height of the persistentprogress bar
persistentbuffer = false, -- on web videos, show the buffer on the persistent progress line
persistentprogresstoggle = true,-- enable toggling the persistentprogress bar
-- title and chapter settings --
showtitle = true, -- show title in OSC
showdescription = true, -- show video description on web videos
showwindowtitle = true, -- show window title in borderless/fullscreen mode
showfilesize = true, -- show the current file's size in the description
titleBarStrip = true, -- whether to make the title bar a singular bar instead of a black fade
title = '${media-title}', -- title shown on OSC - turn off dynamictitle for this option to apply
dynamictitle = true, -- change the title depending on if {media-title} and {filename}
-- differ (like with playing urls, audio or some media)
updatetitleyoutubestats = true, -- update the window/OSC title bar with YouTube video stats (views, likes, dislikes)
font = 'mpv-osd-symbols', -- mpv-osd-symbols = default osc font (or the one set in mpv.conf)
-- to be shown as OSC title
titlefontsize = 28, -- the font size of the title text
chapterformat = 'Chapter: %s', -- chapter print format for seekbar-hover. "no" to disable
dateformat = "%Y-%m-%d", -- how dates should be formatted, when read from metadata (uses standard lua date formatting)
osc_color = '000000', -- accent of the OSC and the title bar
OSCfadealpha = 150, -- alpha of the background box for the OSC
boxalpha = 75, -- alpha of the window title bar
descriptionBoxAlpha = 100, -- alpha of the description background box
-- seekbar settings --
seekbarfg_color = 'E39C42', -- color of the seekbar progress and handle
seekbarbg_color = 'FFFFFF', -- color of the remaining seekbar
seekbarkeyframes = false, -- use keyframes when dragging the seekbar
automatickeyframemode = true, -- set seekbarkeyframes based on video length to prevent laggy scrubbing on long videos
automatickeyframelimit = 600, -- videos of above this length (in seconds) will have seekbarkeyframes on
seekbarhandlesize = 0.8, -- size ratio of the slider handle, range 0 ~ 1
seekrange = true, -- show seekrange overlay
seekrangealpha = 150, -- transparency of seekranges
iconstyle = 'round', -- icon style, 'solid' or 'round'
hovereffect = true, -- whether buttons have a glowing effect when hovered over
-- button settings --
timetotal = true, -- display total time instead of remaining time by default
timems = false, -- show time as milliseconds by default
timefontsize = 18, -- the font size of the time
jumpamount = 5, -- change the jump amount (in seconds by default)
jumpiconnumber = true, -- show different icon when jumpamount is 5, 10, or 30
jumpmode = 'relative', -- seek mode for jump buttons - https://mpv.io/manual/stable/#command-interface-seek-%3Ctarget%3E-[%3Cflags%3E]
volumecontrol = true, -- whether to show mute button and volume slider
volumecontroltype = 'linear', -- use 'linear' or 'log' (logarithmic) volume scale
showjump = true, -- show "jump forward/backward 5 seconds" buttons
showskip = true, -- show the skip back and forward (chapter) buttons
compactmode = true, -- replace the jump buttons with the chapter buttons, clicking the
-- buttons will act as jumping, and shift clicking will act as
-- skipping a chapter
showloop = true, -- show the loop button
loopinpause = true, -- activate looping by right clicking pause
showontop = true, -- show window on top button
showinfo = false, -- show the info button
downloadbutton = true, -- show download button for web videos
downloadpath = "~~desktop/mpv/downloads", -- the download path for videos
showyoutubecomments = false, -- EXPERIMENTAL - not ready
commentsdownloadpath = "~~desktop/mpv/downloads/comments", -- the download path for the comment JSON file
ytdlpQuality = '-f bestvideo[vcodec^=avc][ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best' -- what quality of video the download button uses (max quality mp4 by default)
}
Compact mode is a setting you can enable in the configuration, it removes the skip buttons, and places that functionality within the chapter buttons, allowing for more space in the interface. Clicking the buttons will act as jumping, and shift clicking will act as skipping a chapter
Compact Mode Enabled | Compact Mode Disabled |
---|---|
![]() |
![]() |
Important
This changes the actions of the chapter back/forward buttons in the following way:
Left mouse button
jumps forwards/backwards by 5 seconds, or by the amount set inuser_opts
Right mouse button
play previous/next chapter and show the chapter listShift + Left mouse button
jumps forwards/backwards by 1 minuteShift + Right mouse button
show playlist Please note that this option will override theshowjump
option.
To enable thumbnails on the seekbar, install thumbfast. No other step necessary.
Like the built-in script, some buttons may accept multiple mouse actions, here is a list:
Note
Middle clicking performs the same function as Shift+left mouse button
, allowing for one handed use
Left mouse button
show the full media titleRight mouse button
show the full filename
Left mouse button
show the full description, useup arrow
,down arrow
orscroll wheel
to scroll through it
Left mouse button
seek to chosen position (using keyframes)Shift+left mouse button
seek to the exact positionRight mouse button
seek to the head of chosen chapter
Left mouse button
display time in milliseconds
Left mouse button
display total time instead of remaining time
Left mouse button
play previous/next fileRight mouse button
show playlistShift+left mouse button
play previous/next file and show playlistShift+right mouse button
show playlist
Left mouse button
go to previous/next chapterRight mouse button
show chapter listShift+left mouse button
go to previous/next chapter and show playlistShift+right mouse button
show chapter list
Left mouse button
jumps forwards/backwards by 5 seconds, or by the amount set inuser_opts
Right mouse button
jumps forwards/backwards by 1 minuteShift+left mouse button
skips to the previous/next frame
Left mouse button/right mouse button
cycle to next/previous trackShift+left mouse button
cycle to next/previous track and show track listShift+right mouse button
show track list
Left mouse button
toggle pinning (and removing video border)Right mouse button
toggle pinning without changing the border
Left mouse button
mute/unmute videoScroll wheel
change volume
x
cycle through audio tracksc
cycle through subtitle tracksp
pin or unpin the windowTab
show chapter listShift+left
go to the previous chapterShift+right
go to the next chapterCtrl+left
go to the previous file (in playlist)Ctrl+right
go to the next file (in playlist)b
toggle the persistent progress bar ifpersistentprogresstoggle
is enabled