ModernZ - A Sleek Alternative OSC for mpv

A sleek and modern OSC for mpv. This project is a fork of ModernX that enhances functionality by adding more features while preserving the core standards of mpv's OSC.

Installation »
Configuration · Controls · OSC Language · Extra Scripts

Features

• 🎨 Modern, customizable interface with multiple layouts, themes, and icon styles [options]
• 🖱️ Independent hover zone for top bar (window controls) and bottom bar (OSC)
• 📷 Image Viewer mode with zoom controls [details]
• 🎛️ Buttons: download, playlist, speed control, screenshot, pin, loop, cache, and more. [details]
• 📄 Interactive menus for playlist, subtitles, chapters, audio tracks, and audio devices
• 🌐 Multi-language support with JSON locale integration
• ⌨️ Configurable controls [details]
• 🖼️ Video thumbnail previews with thumbfast

Customization

Choose the layout that suits your preference (modern or modern-compact) using the layout option in your modernz.conf.

Layouts

modern

modern-compact

Themes

You can also change the icon theme to fluent or material to match your preferred style by using the icon_theme option in your modernz.conf.

fluent

material

Theme Styles

Both fluent and material themes have different styles as well. By using the icon_style option, you can choose mixed, filled, or outline.

fluent
Style	Preview
mixed
filled
outline

material
Style	Preview
mixed
filled
outline

Colors

Not a fan of white buttons and text? You have complete control to customize colors to perfectly reflect your style.

Colors

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
   • (OPTIONAL) Add title-bar=no in your mpv.conf for a clean look without the native operating system top bar

2. Copy Files

   • Place modernz.lua in your mpv scripts directory
   • Place modernz-icons.ttf in your mpv fonts directory
   • (OPTIONAL) Place modernz-locale.json in your mpv script-opts 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/
│   └── 📄 modernz-icons.ttf
├── 📁 script-opts/
│   ├── 📄 modernz.conf
│   └── 📄 modernz-locale.json (optional)
└── 📁 scripts/
    ├── 📄 modernz.lua
    └── 📄 thumbfast.lua (optional)

Configuration

• Place modernz.conf in the /script-opts folder to customize settings

  • Download modernz.conf with all default options

• Alternatively, you can create a short configuration of the options you want changed only:

# Short configuration example
# Seekbar color (hex format)
seekbarfg_color=#B7410E

# Interface options
speed_button=yes
title=${media-title}
icon_theme=fluent
icon_style=outline

For a full list of options, check out the detailed list 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:

v   script-binding modernz/visibility                # Cycle visibility modes
V   script-message-to modernz osc-visibility cycle   # Set a visibility mode (cycle, auto, always, never)
w   script-binding modernz/progress-toggle           # Toggle progress bar
x   script-message-to modernz osc-show               # Show OSC
y   script-message-to modernz osc-hide               # Hide OSC
z   script-message-to modernz osc-idlescreen         # Toggle idle screen

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.json file from this repository. This file holds translations for various languages.

2. Add the locales to mpv

Copy the downloaded modernz-locale.json file to your mpv /script-opts folder.

3. Choose your language

Adjust or add the language option in your modernz.conf to your preferred language.

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

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 maintained by me. Feel free to use them if they're useful to you.

• Pause-Indicator-Lite - A simple script that displays an indicator on pause
• PiP-Lite - Add a PiP mode (Picture-in-Picture) via the ModernZ pin button or when ontop is enabled
• ytdlAutoFormat - A simple mpv script to automatically change ytdl-format (yt-dlp) for specified domains
• BoxtoWide - A simple mpv script to change the aspect-ratio of video files/streams to a specific target ratio 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 dexeonify/ModernX
    • forked from cyl0/ModernX
      • forked from maoiscat/mpv-osc-modern

Why fork yet again?

• Add extensive feature support, including color customization, advanced options, and locale integration
• Integrate mpv's console and select functionality to OSC
  • An approach that later inspired adoption in mpv’s stock OSC (#1, #2)
• Introduce a dedicated layout optimized for image viewing. details
• Add modern and modern-compact layouts and icon themes support
• Refactor the project to align with mpv’s stock OSC standards, ensuring long-term compatibility
• Remove legacy bugs and redundant code to improve maintainability and stability
  • This enables other Modern forks to build on ModernZ as a foundation
    • Such as zydezu/ModernX (reference)

In essence, to maintain and revive the modern-osc origin.

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

Credits:

• Material Symbols by Google — Apache 2.0
• Fluent System Icons by Microsoft — MIT (some icons modified or created to suit the OSC's needs)
• mpv and their osc.lua, as ModernZ osc was re-based on the stock osc standards and applies updates from it
• All modern osc origin and their forks as mentioned in history
• All contributors, testers and users that helped directly or indirectly with ModernZ osc ❤️