ModernZ - A Sleek Alternative OSC for mpv

A sleek and modern OSC for mpv, this project is a fork of ModernX designed to enhance functionality by adding more features, all while preserving the core standards of mpv's OSC.

Installation »
Configuration · Controls · Interactive Lists · OSC Language · Extra Scripts

Features

• 🎨 Modern, customizable interface [options]
• 🖼️ Video thumbnail previews on seek (with thumbfast)
• 📄 Interactive lists for playlist, subtitles, audio tracks, chapter and audio devices [preview]
• 🔽 Download button for web videos (with yt-dlp)
• 🌐 Multi-language support [locale]
• ⌨️ Configurable controls [details]

Customization Showcase

Don't like the default white buttons and text? ModernZ is fully customizable! Change colors and button layouts to match your style:

See the Color Customization section in the configuration guide for details on how to customize colors and buttons.

Installation

1. Disable Stock OSC

   • Add osc=no in your mpv.conf

2. Copy Files

   • Place modernz.lua in your mpv scripts directory
   • Place fluent-system-icons.ttf in your mpv fonts directory
   • (OPTIONAL) Place thumbfast.lua in your mpv scripts directory

3. Locations

   Linux:   ~/.config/mpv/
   Windows: C:/Users/%username%/AppData/Roaming/mpv/
   macOS:   ~/Library/Application Support/mpv/
   

4. Folder Structure [mpv manual]

   mpv/
   ├── fonts/
   │   └── fluent-system-icons.ttf
   ├── script-opts/
   │   └── modernz.conf
   └── scripts/
   	   ├── modernz.lua
   	   └── thumbfast.lua (optional)
   

Configuration

1. Create modernz.conf in the /script-opts folder to customize settings

   • Download default modernz.conf

2. Example short configuration:

   # Seekbar colors (Hex format)
   seekbarfg_color=#B7410E
   
   # Interface options
   showplaylist=no
   title=${media-title}
   scalewindowed=1.0
   windowcontrols=auto
   

For a full list of options, check out the detailed user options here.

Controls

Button Interactions

• Left click: Primary action
• Right click: Secondary action
• Middle click/Shift+Left click: Alternative action

Note

Middle clicking performs the same function as Shift+left mouse button, allowing for one handed use

For a full list of interactions, check out the Button Interactions Guide.

Keybinds

ModernZ doesn't set keybinds by default to avoid interfering with your current setup. You can add keybinds in input.conf if you prefer:

w   script-binding modernz/progress-toggle     # Toggle progress bar
x   script-message-to modernz osc-show         # Show OSC
y   script-message-to modernz osc-visibility   # Toggle visibility
z   script-message-to modernz osc-idlescreen   # Toggle idle screen

Interactive Lists

ModernZ supports mpv's built-in select.lua (v0.39+) for playlist and chapter navigation.

ModernZ_interactive_lists.mp4

Tip

If the font size for the interactive playlist is too small, you can add the following in your mpv.conf

# change font size for console and select
script-opts-append=console-font_size=25

Translations

ModernZ is currently available in English, but you can easily switch it to your preferred language! Here's how:

1. Download the locale pack:

Grab the modernz-locale.lua file from this repository. This file holds translations for various languages.

2. Add the locales to mpv:

Copy the downloaded modernz-locale.lua file to your mpv's /scripts folder.

3. Choose our language:

There are two ways to set your preferred language:

• Recommended: Use the modernz.conf file

  # Example configuration in modernz.conf
  language = "zh"  # Set language to Simplified Chinese

• Alternative: Edit the modernz.lua script

  Open modernz.lua and find the user_opts section near the beginning. Change the language value to your preferred code:

  local user_opts = {
      -- General
      language = "en",  -- Change this to your preferred language code
      ...
  }

Need More Info?

For a complete list of available languages, contribution guidelines, and in-depth translation documentation, head over to the TRANSLATIONS.md.

Extras

The following scripts are ones I wrote and maintain, feel free to use them if they're useful to you.

• Pause-Indicator-Lite - A simple script that displays an indicator on pause

• ytdlAutoFormat - A simple mpv script to automatically change ytdl-format (yt-dlp) for specified domains.

• BoxtoWide - A simple mpv script to change 4:3 aspect-ratio of video files/streams to 16:9 automatically.

For even more useful scripts, check out the mpv User Scripts Wiki. It offers a wide range of community-contributed scripts to enhance your mpv experience.

History

• Samillion/ModernZ
  • forked from zydezu/ModernX
  • forked from dexeonify/ModernX
    • forked from cyl0/ModernX
    • forked from maoiscat/mpv-osc-modern

Why fork yet again?

• To add many features in: Color Customization, Options and Locale Integration
• To integrate console and select into the osc, which inspired mpv to apply it in the stock osc. [ref #1, #2]
• To re-do the project entirely to match mpv's stock osc standards, to ensure compatibility
• To eliminate old bugs and redundancy within the code

In essence, to modernize and revive the Modern origin.

Having said that, ModernZ still uses parts of the old code, and every previous and current fork author and contributor deserve credit (including mpv's stock osc), that is why they're mentioned in detail.

Credits:

Fluent System Icons font was modified by Xurdejl for use on ModernZ, they also contributed with code, reports and tests. 😻