Config files for https://mpv.io/ | See my modernX fork here: https://github.com/zydezu/modernX
Lua
113
383 commits
updated Sep 11, 2026
My personal mpv config.
[!NOTE] Releases of the modernx script are in a seperate repository - see here https://github.com/zydezu/ModernX/releases.
Use git clone https://github.com/zydezu/mpvconfig mpv, and place it in the relevant directory. This will be typically located at \%APPDATA%\mpv\ on Windows and ~/.config/mpv/ on Linux/MacOS.
For the clipboard functionality use in copypaste.lua, you many need to install the xclip or wl-clipboard package, depending on your session type.
Use mkdir -p ~/.var/app/io.mpv.Mpv/config to make the mpv configuration directory for the first time
cd ~/.var/app/io.mpv.Mpv/config
git clone https://github.com/zydezu/mpvconfig mpv to clone the config files as mpv/
flatpak override --user io.mpv.Mpv --filesystem=host, needed for mpv flatpak to access host filesystem, so screenshots and lyric downloads can be saved
See the Files section in mpv's manual for more information.
For files with 5.1 or 7.1 surround sound, you may need to set
Audio enhancements to Off in the windows sound settings to hear all the audio channels properly.
Please note that many of these scripts have been slightly modified from their initial repositories. Compare the scripts to find the modifications.
| Script and description | Keybinds |
|---|---|
| autoloop loops files by default that are smaller than a set duration | None |
| autolyrics tries to download lyrics and display them for said file | Alt+m - Request lyrics from musixmatch then netease if that fails Alt+n - Request lyrics only from netease Alt+o - Set lyrics start point to the current timestamp (if lyrics need to be synced) |
| copypaste Copy and paste file paths, URLs and timestamps | Ctrl+c - Copy file path or URL to clipboard Ctrl+v - Paste file path or URL and play it o - Open file location or URL in browser |
| detectdualsubs Detects if there are two existing subtitles, one being an original script and the other being a translation (eg: English and Japanese subtitles) and displays them both on screen | Ctrl+x - Toggle dual subs on or off |
| loadaudiotracks Allows multiple audio tracks to be selected and played together | Ctrl+z - Toggle another audio track |
| modernx a modern OSC for mpv with many additional features | z - Cycle through audio tracks x - Cycle through subtitle tracks p - Pin or unpin the window Tab - Show chapter list Ctrl+s - Shuffle the current playlist For more: See repository |
| mpvcut allows clipping a segment of a video | z - Mark start segment z (again) - Clip the video Shift+z - Cancel the clip a - Change mode (copy, encode, compress) |
| screenshotfolder saves screenshots to a designated folder | s - Take a screenshot |
| selectformat allows you to change the quality of internet videos on the fly | Ctrl+f - Open format menu Use up and down to choose a resolution, and fold and unfold selections with the arrow keys to see more codec options |
| sponsorblock a fully-featured port of SponsorBlock for mpv | See repository |
| thumbfast show thumbnails when hovering the progress bar | None |
| unpauseonplaylistchange automatically resumes playback when moving to another item in the playlist while paused | None |
| input.conf an input configuration file | - - Decrease subtitle font size + - Increase subtitle font size Scroll wheel - Change volume |
mpvcut.lua copying the resulting filempvcut.luaretryonerror.lua triggerst now shows the subtitle transcriptionunpauseonplaylistchange.lua, which resumes playback when moving to another playlist item while pausedytsub.luaadd_sponsorblock_chapters = false not being respected on YouTube videos without chapters alreadychapter_marker_color and chapter_marker_current_color) instead of inheriting the seekbar's progress colorchapter_marker_style option to modernx.lua to change the shape of chapter markers, supporting triangle, bar, single-bar and gapchapter_hover_subtitle option to modernx.lua to show the hovered chapter's name in the chapter title text below the seekbar instead of the main title (this option only applies when thumbfast isn't available)modernx.luampv.conf to fix GPU memory issues with 8K videosmpvcut.luaselectformat.lua are now consistentselectformat.luaselect.lua menus for selecting audio/subtitle tracks and changing audio outputshift+z/shift+c key bindings to select audio/subtitle tracks, add TAB key binding to select chaptersmpv.confhr-seek=no to mpv.conf to fix various delays and errors upon startup when the video progress was saved at a non-keyframe positionmodernx.lua and make some option descriptions clearerselectformat.lua configuration, add icons for dropdownsdetectdualsubs.lua as it was rarely usedscreenshot-high-bit-depth=no to mpv.conf to stop huge screenshots being taken (we can add it back in 10 years when HDR screenshots are supported on social media platforms)screen-name instead of screen in mpv.confmodernx.luamodernx.luampvcut.luamodernx.luaautolyrics.lua show a message if lyrics not foundmodernx.luampvcut.luampvcut.luampvcut.luainput.confscreenshot-sw from mpv.confmodernX.luashow_skip_message, to sponsorblock.luamodernx.luamodernx.luatable.unpack() instead of unpack() in screenshotfolder.luascreenshotfolder.luashow_message is false in screenshotfolder.luaautolyrics.lua crashing if no lyrics are foundautolyrics.lua by using lrclib.net~~desktop to ~/Picturesmpvcut.lualivechat.luaunc2url.lua and make various changes to playing network filesdisablehwforp010.luadisablehwforp010.luampvcut.luaav1_animated_crf as an option in mpvcut.lua that controls the quality for animated avif clipsmpvcut.lua now encodes/compresses the right audio track, and no longer compresses it.gif or .avif in mpvcut.lua, you can choose which with the gif_encoding_type optionscreenshotfolder.luampvcut.luampvcut.lua not respecting the encoding_type option when encoding a clipsponsorblock.luaautolyrics.luathumbfast.lua throwing errorsshow_top_mark and show_bottom_mark to modernx.lualivechat.luathumbfast.lua looking weirdthumbfast.lua to upstreamupdatechecker.lua, you can disable it by changing the update_checker optionencoding_type as an option to mpvcut.lua, the supported options are h264, h265 and av1. h265 is the defaultmpvcut.lua to encode/compress files as .mp4Ctrl+x now toggles dual subtitles in detectdualsubs.lua instead of only forcing them onmpvcut.lua now uses a to select cuts, Shift+a to cycle cut modes and Ctrl+a to cancelmodernx.lua now uses z and x to cycle through audio and subtitle tracks respectivelyloadaudiotracks.lua to allow multiple audio tracks to be played at the same timecopy_youtube_timestamp as an option to copypaste.lua, that copies YouTube links with the current timestamp to be pastedmodernx.lua, you can now shuffle a playlist with Ctrl+s or by right-clicking the play/pause buttonautolyrics.lua and mpvcut.lua failing to create directories on linuxmodernx.lua, splitting CJK characters in the clickable description properlymodernx.luaosc_keep_with_cursor, seekbar_between_timers and seekbar_height as options in modernx.luasave_location, time_stamp_format and save_based_on_chapter_name as options in screenshotfolder.luafade_transparency_strength and window_fade_transparency_strength as options to modernx, this also removes the option titlebarboxremoveuuid to sponsorblock.luaautolyrics.lua as it seems to be unreliablemp.input in autolyrics.lua and fix filenamesmodernx.luamodernx.luaautolyrics.lua and modernx.luamodernx.luascreenshotfolder.luasub-use-marginsmodernx.luaautolyrics.luadetectdualsubs.luamodernx.lua - NOTE: requires a custom version of sponsorblock.lua https://github.com/zydezu/mpvconfig/blob/main/scripts/sponsorblock.luashow_sponsorblock_segments, add_sponsorblock_chapters, sponsorblock_sponsor_color, sponsorblock_intro_color, sponsorblock_outro_color, sponsorblock_interaction_color, sponsorblock_selfpromo_color and sponsorblock_filler_colorseekbar_cache_color to modernx.luaprogress_bar_height to modernx.luamodernx.lua now sets the tick rate to the monitors refresh rateselectformat.lua up-to-date with https://github.com/koonix/mpv-selectformatdetectdualsubs.lua that detects if there are two existing subtitles, one being an original script and the other being a translation (eg: English and Japanese subtitles) and displays them both on screenkey_bindings in modernx.luastrip_artists and chinese_to_kanji_path options to autolyrics.luaautoloop.lua into copypaste.luampvcut.luaautoload.lua as autocreate-playlist in mpv.conf replicates it's functionalitycompresssize value in mpvcut.lua to 9.50MBmpvcut.lua default compress size target to 9.00MB (THANKS DISCORD >~<0)AOTFShinGoProMedium.otf to the fonts folder as it is used in mpv.confmodernx.lua to prevent a crashmodernx.lua
MERRY XMAS!!
mpv.confmpvcut.lua to describe the option bettermpv.conf's ytdl-format option if setselectformat.lua by bitratemodernx.lua fixes to comment parsingmodernx.lua new iconsdynamictimeformat option to modernx.luaautolyrics.luamodernx.lua https://github.com/zydezu/ModernX/pull/40screenshotfolder.lua to not include file extensions in folder directoriesmodernx.luampvcut.luampvcut.lua breaking when 'compressing' audio filesselectformat.lua, allowing you to change the quality of internet videos on the flympvcut.lua now stops overwriting previously cut filesautoloop not staying disabled over a playlist of filesshift+left click on the seekbar now scrubs to the exact position, whilst left click now scrubs to the keyframe position (faster)modernx.luaautolyrics.luaautolyrics.luaautolyrics.luamodernx.lua album artists and artists (from the file metadata) and now displayed separately, instead of where previously 'artist' would override 'album artist'https://www.youtube.com/watch?v=Pbb40i1khlc&list=WL&index=3?=autoloop.lua to open the file location or url in web browserautoload.lua adding out of order playlists when directly accessing a file pathdontsaveonaudio to autoloop.lua, which doesn't save the current position on audio filesdescriptionfontsize to modernxnetwork option)| New font v2 | New font | Old font |
|---|---|---|
dynamictitle in ModernX to be cleanerautomatickeyframemode and automatickeyframelimit to modernx, resolving https://github.com/zydezu/ModernX/issues/23cacheloading on autolyrics.luab key, if persistentprogresstoggle is enabledmodernxmodernxkeybindings to modernxshowfilesize, fixing https://github.com/zydezu/ModernX/issues/7modernx more seamless, instantly clearing the descriptionmodernxdownloadpath in modernx, fixing https://github.com/zydezu/ModernX/issues/4modernx and screenshotting in screenshotfolder.lua when viewing YouTube short 'share' links, along with the dynamictitle optionytdlpQualityupdatetitleyoutubestats option in modernx.lua, which when enabled, updates the window/OSC title bar with YouTube video stats (views, likes, dislikes)persistentprogressheight option to modernx.lua, as part of this issuepersistentprogress and persistentbuffer in modernx.lua
cacheloadingsavedirectorydownloadforall is disableddontsaveduration option to autoloop.lua, which doesn't save the position of videos under the specified length, but also doesn't loop them - perfect for short videos under a minute or soautolyrics.lua functionality for YouTube videos, and .lrc files can now be saved to a specified pathautolyrics.lua on unix systemsif (not (state.paused and user_opts.donttimeoutonpause)) then
hide_osc()
end
raisesubswithosc optionuser_opts.dynamictitle in modernx.lua not properly updating the title when switching video in a playlistoptions.downloadforall featuredonttimeoutonpause option, which when enabled, doesn't hide the osc whilst hovering over it, when paused.user_opts.title function properlysave-position-on-quit, so always play from the start, this option can be configured in script-opts/autoloop.conf as playfromstart=false (to disable)user_opts.dateformat

P will now pin the windowdynamictitle setting as it now incorporates file metadatamodernx.luascreenshotfolder.lua, saving screenshots in ~~desktop/mpv/[filename]input.conf, and added the quality menu to itsponsorblock.pyLua
97.8%
Python
2.2%
Config files for https://mpv.io/ | See my modernX fork here: https://github.com/zydezu/modernX
Lua
113
383 commits
updated Sep 11, 2026
My personal mpv config.
[!NOTE] Releases of the modernx script are in a seperate repository - see here https://github.com/zydezu/ModernX/releases.
Use git clone https://github.com/zydezu/mpvconfig mpv, and place it in the relevant directory. This will be typically located at \%APPDATA%\mpv\ on Windows and ~/.config/mpv/ on Linux/MacOS.
For the clipboard functionality use in copypaste.lua, you many need to install the xclip or wl-clipboard package, depending on your session type.
Use mkdir -p ~/.var/app/io.mpv.Mpv/config to make the mpv configuration directory for the first time
cd ~/.var/app/io.mpv.Mpv/config
git clone https://github.com/zydezu/mpvconfig mpv to clone the config files as mpv/
flatpak override --user io.mpv.Mpv --filesystem=host, needed for mpv flatpak to access host filesystem, so screenshots and lyric downloads can be saved
See the Files section in mpv's manual for more information.
For files with 5.1 or 7.1 surround sound, you may need to set
Audio enhancements to Off in the windows sound settings to hear all the audio channels properly.
Please note that many of these scripts have been slightly modified from their initial repositories. Compare the scripts to find the modifications.
| Script and description | Keybinds |
|---|---|
| autoloop loops files by default that are smaller than a set duration | None |
| autolyrics tries to download lyrics and display them for said file | Alt+m - Request lyrics from musixmatch then netease if that fails Alt+n - Request lyrics only from netease Alt+o - Set lyrics start point to the current timestamp (if lyrics need to be synced) |
| copypaste Copy and paste file paths, URLs and timestamps | Ctrl+c - Copy file path or URL to clipboard Ctrl+v - Paste file path or URL and play it o - Open file location or URL in browser |
| detectdualsubs Detects if there are two existing subtitles, one being an original script and the other being a translation (eg: English and Japanese subtitles) and displays them both on screen | Ctrl+x - Toggle dual subs on or off |
| loadaudiotracks Allows multiple audio tracks to be selected and played together | Ctrl+z - Toggle another audio track |
| modernx a modern OSC for mpv with many additional features | z - Cycle through audio tracks x - Cycle through subtitle tracks p - Pin or unpin the window Tab - Show chapter list Ctrl+s - Shuffle the current playlist For more: See repository |
| mpvcut allows clipping a segment of a video | z - Mark start segment z (again) - Clip the video Shift+z - Cancel the clip a - Change mode (copy, encode, compress) |
| screenshotfolder saves screenshots to a designated folder | s - Take a screenshot |
| selectformat allows you to change the quality of internet videos on the fly | Ctrl+f - Open format menu Use up and down to choose a resolution, and fold and unfold selections with the arrow keys to see more codec options |
| sponsorblock a fully-featured port of SponsorBlock for mpv | See repository |
| thumbfast show thumbnails when hovering the progress bar | None |
| unpauseonplaylistchange automatically resumes playback when moving to another item in the playlist while paused | None |
| input.conf an input configuration file | - - Decrease subtitle font size + - Increase subtitle font size Scroll wheel - Change volume |
mpvcut.lua copying the resulting filempvcut.luaretryonerror.lua triggerst now shows the subtitle transcriptionunpauseonplaylistchange.lua, which resumes playback when moving to another playlist item while pausedytsub.luaadd_sponsorblock_chapters = false not being respected on YouTube videos without chapters alreadychapter_marker_color and chapter_marker_current_color) instead of inheriting the seekbar's progress colorchapter_marker_style option to modernx.lua to change the shape of chapter markers, supporting triangle, bar, single-bar and gapchapter_hover_subtitle option to modernx.lua to show the hovered chapter's name in the chapter title text below the seekbar instead of the main title (this option only applies when thumbfast isn't available)modernx.luampv.conf to fix GPU memory issues with 8K videosmpvcut.luaselectformat.lua are now consistentselectformat.luaselect.lua menus for selecting audio/subtitle tracks and changing audio outputshift+z/shift+c key bindings to select audio/subtitle tracks, add TAB key binding to select chaptersmpv.confhr-seek=no to mpv.conf to fix various delays and errors upon startup when the video progress was saved at a non-keyframe positionmodernx.lua and make some option descriptions clearerselectformat.lua configuration, add icons for dropdownsdetectdualsubs.lua as it was rarely usedscreenshot-high-bit-depth=no to mpv.conf to stop huge screenshots being taken (we can add it back in 10 years when HDR screenshots are supported on social media platforms)screen-name instead of screen in mpv.confmodernx.luamodernx.luampvcut.luamodernx.luaautolyrics.lua show a message if lyrics not foundmodernx.luampvcut.luampvcut.luampvcut.luainput.confscreenshot-sw from mpv.confmodernX.luashow_skip_message, to sponsorblock.luamodernx.luamodernx.luatable.unpack() instead of unpack() in screenshotfolder.luascreenshotfolder.luashow_message is false in screenshotfolder.luaautolyrics.lua crashing if no lyrics are foundautolyrics.lua by using lrclib.net~~desktop to ~/Picturesmpvcut.lualivechat.luaunc2url.lua and make various changes to playing network filesdisablehwforp010.luadisablehwforp010.luampvcut.luaav1_animated_crf as an option in mpvcut.lua that controls the quality for animated avif clipsmpvcut.lua now encodes/compresses the right audio track, and no longer compresses it.gif or .avif in mpvcut.lua, you can choose which with the gif_encoding_type optionscreenshotfolder.luampvcut.luampvcut.lua not respecting the encoding_type option when encoding a clipsponsorblock.luaautolyrics.luathumbfast.lua throwing errorsshow_top_mark and show_bottom_mark to modernx.lualivechat.luathumbfast.lua looking weirdthumbfast.lua to upstreamupdatechecker.lua, you can disable it by changing the update_checker optionencoding_type as an option to mpvcut.lua, the supported options are h264, h265 and av1. h265 is the defaultmpvcut.lua to encode/compress files as .mp4Ctrl+x now toggles dual subtitles in detectdualsubs.lua instead of only forcing them onmpvcut.lua now uses a to select cuts, Shift+a to cycle cut modes and Ctrl+a to cancelmodernx.lua now uses z and x to cycle through audio and subtitle tracks respectivelyloadaudiotracks.lua to allow multiple audio tracks to be played at the same timecopy_youtube_timestamp as an option to copypaste.lua, that copies YouTube links with the current timestamp to be pastedmodernx.lua, you can now shuffle a playlist with Ctrl+s or by right-clicking the play/pause buttonautolyrics.lua and mpvcut.lua failing to create directories on linuxmodernx.lua, splitting CJK characters in the clickable description properlymodernx.luaosc_keep_with_cursor, seekbar_between_timers and seekbar_height as options in modernx.luasave_location, time_stamp_format and save_based_on_chapter_name as options in screenshotfolder.luafade_transparency_strength and window_fade_transparency_strength as options to modernx, this also removes the option titlebarboxremoveuuid to sponsorblock.luaautolyrics.lua as it seems to be unreliablemp.input in autolyrics.lua and fix filenamesmodernx.luamodernx.luaautolyrics.lua and modernx.luamodernx.luascreenshotfolder.luasub-use-marginsmodernx.luaautolyrics.luadetectdualsubs.luamodernx.lua - NOTE: requires a custom version of sponsorblock.lua https://github.com/zydezu/mpvconfig/blob/main/scripts/sponsorblock.luashow_sponsorblock_segments, add_sponsorblock_chapters, sponsorblock_sponsor_color, sponsorblock_intro_color, sponsorblock_outro_color, sponsorblock_interaction_color, sponsorblock_selfpromo_color and sponsorblock_filler_colorseekbar_cache_color to modernx.luaprogress_bar_height to modernx.luamodernx.lua now sets the tick rate to the monitors refresh rateselectformat.lua up-to-date with https://github.com/koonix/mpv-selectformatdetectdualsubs.lua that detects if there are two existing subtitles, one being an original script and the other being a translation (eg: English and Japanese subtitles) and displays them both on screenkey_bindings in modernx.luastrip_artists and chinese_to_kanji_path options to autolyrics.luaautoloop.lua into copypaste.luampvcut.luaautoload.lua as autocreate-playlist in mpv.conf replicates it's functionalitycompresssize value in mpvcut.lua to 9.50MBmpvcut.lua default compress size target to 9.00MB (THANKS DISCORD >~<0)AOTFShinGoProMedium.otf to the fonts folder as it is used in mpv.confmodernx.lua to prevent a crashmodernx.lua
MERRY XMAS!!
mpv.confmpvcut.lua to describe the option bettermpv.conf's ytdl-format option if setselectformat.lua by bitratemodernx.lua fixes to comment parsingmodernx.lua new iconsdynamictimeformat option to modernx.luaautolyrics.luamodernx.lua https://github.com/zydezu/ModernX/pull/40screenshotfolder.lua to not include file extensions in folder directoriesmodernx.luampvcut.luampvcut.lua breaking when 'compressing' audio filesselectformat.lua, allowing you to change the quality of internet videos on the flympvcut.lua now stops overwriting previously cut filesautoloop not staying disabled over a playlist of filesshift+left click on the seekbar now scrubs to the exact position, whilst left click now scrubs to the keyframe position (faster)modernx.luaautolyrics.luaautolyrics.luaautolyrics.luamodernx.lua album artists and artists (from the file metadata) and now displayed separately, instead of where previously 'artist' would override 'album artist'https://www.youtube.com/watch?v=Pbb40i1khlc&list=WL&index=3?=autoloop.lua to open the file location or url in web browserautoload.lua adding out of order playlists when directly accessing a file pathdontsaveonaudio to autoloop.lua, which doesn't save the current position on audio filesdescriptionfontsize to modernxnetwork option)| New font v2 | New font | Old font |
|---|---|---|
dynamictitle in ModernX to be cleanerautomatickeyframemode and automatickeyframelimit to modernx, resolving https://github.com/zydezu/ModernX/issues/23cacheloading on autolyrics.luab key, if persistentprogresstoggle is enabledmodernxmodernxkeybindings to modernxshowfilesize, fixing https://github.com/zydezu/ModernX/issues/7modernx more seamless, instantly clearing the descriptionmodernxdownloadpath in modernx, fixing https://github.com/zydezu/ModernX/issues/4modernx and screenshotting in screenshotfolder.lua when viewing YouTube short 'share' links, along with the dynamictitle optionytdlpQualityupdatetitleyoutubestats option in modernx.lua, which when enabled, updates the window/OSC title bar with YouTube video stats (views, likes, dislikes)persistentprogressheight option to modernx.lua, as part of this issuepersistentprogress and persistentbuffer in modernx.lua
cacheloadingsavedirectorydownloadforall is disableddontsaveduration option to autoloop.lua, which doesn't save the position of videos under the specified length, but also doesn't loop them - perfect for short videos under a minute or soautolyrics.lua functionality for YouTube videos, and .lrc files can now be saved to a specified pathautolyrics.lua on unix systemsif (not (state.paused and user_opts.donttimeoutonpause)) then
hide_osc()
end
raisesubswithosc optionuser_opts.dynamictitle in modernx.lua not properly updating the title when switching video in a playlistoptions.downloadforall featuredonttimeoutonpause option, which when enabled, doesn't hide the osc whilst hovering over it, when paused.user_opts.title function properlysave-position-on-quit, so always play from the start, this option can be configured in script-opts/autoloop.conf as playfromstart=false (to disable)user_opts.dateformat

P will now pin the windowdynamictitle setting as it now incorporates file metadatamodernx.luascreenshotfolder.lua, saving screenshots in ~~desktop/mpv/[filename]input.conf, and added the quality menu to itsponsorblock.pyLua
97.8%
Python
2.2%