<h1 align="center">ModernZ - A Sleek Alternative OSC for mpv</h1>

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.

<img width="1715" height="966" alt="ModernZ" src="https://github.com/user-attachments/assets/a2c8081e-2909-4bd1-872d-c59c48e76302" /> <p align="center"> <a href="#installation"><strong>Installation »</strong></a><br> <a href="#configuration">Configuration</a> · <a href="#controls">Controls</a> · <a href="#translations">OSC Language</a> · <a href="#extras">Extra Scripts</a> </p>

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

<table> <thead> <tr> <th><code>modern</code></th> </tr> </thead> <tbody> <tr> <td><img width="1715" height="120" alt="modernz_modern_layout" src="https://github.com/user-attachments/assets/97791b5b-e7c8-47bc-8805-a286052762f6" /></td> </tr> </tbody> </table> <table> <thead> <tr> <th><code>modern-compact</code></th> </tr> </thead> <tbody> <tr> <td><img width="1715" height="150" alt="modernz_compact_layout" src="https://github.com/user-attachments/assets/b88f7823-b328-427e-8720-c2d4ab2c496a" /></td> </tr> </tbody> </table>

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.

<table> <thead> <tr> <th><code>fluent</code></th> </tr> </thead> <tbody> <tr> <td><img width="1715" height="120" alt="modernz_fluent_theme" src="https://github.com/user-attachments/assets/9c0172db-f959-4c95-a31f-aab55290f5ec" /></td> </tr> </tbody> </table> <table> <thead> <tr> <th><code>material</code></th> </tr> </thead> <tbody> <tr> <td><img width="1715" height="120" alt="modernz_material_theme" src="https://github.com/user-attachments/assets/cc532cd8-32aa-4dba-93eb-5f8f599ea654" /></td> </tr> </tbody> </table>

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.

<table> <thead> <tr> <th colspan="2"><code>fluent</code></th> </tr> <tr> <th>Style</th> <th>Preview</th> </tr> </thead> <tbody> <tr> <td><code>mixed</code></td> <td><img width="1715" height="120" alt="modernz_fluent_mixed" src="https://github.com/user-attachments/assets/58774224-1fd2-4939-8263-b14bba551be0" /></td> </tr> <tr> <td><code>filled</code></td> <td><img width="1715" height="120" alt="modernz_fluent_filled" src="https://github.com/user-attachments/assets/c0beee55-b6c8-4bef-a192-0b529c1ecea9" /></td> </tr> <tr> <td><code>outline</code></td> <td><img width="1715" height="120" alt="modernz_fluent_outline" src="https://github.com/user-attachments/assets/5c6af748-1f4e-46e6-b6b9-470954e93ef8" /></td> </tr> </tbody> </table> <table> <thead> <tr> <th colspan="2"><code>material</code></th> </tr> <tr> <th>Style</th> <th>Preview</th> </tr> </thead> <tbody> <tr> <td><code>mixed</code></td> <td><img width="1715" height="120" alt="modernz_material_mixed" src="https://github.com/user-attachments/assets/2518a9f6-8a07-499c-912d-a527535d6ff1" /></td> </tr> <tr> <td><code>filled</code></td> <td><img width="1715" height="120" alt="modernz_material_filled" src="https://github.com/user-attachments/assets/c14f94f3-0564-4ef8-b46a-6e1edb75556c" /></td> </tr> <tr> <td><code>outline</code></td> <td><img width="1715" height="120" alt="modernz_material_outline" src="https://github.com/user-attachments/assets/d1e12ff2-a4bb-4956-9049-821fe243ad93" /></td> </tr> </tbody> </table>

Colors

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

<table> <thead> <tr> <th>Colors</th> </tr> </thead> <tbody> <tr> <td><img width="1715" height="108" alt="modernz_colors_top" src="https://github.com/user-attachments/assets/b4f97def-df93-40ed-aa8e-d432e25c3230" /></td> </tr> <tr> <td><img width="1715" height="188" alt="modernz_colors_bottom" src="https://github.com/user-attachments/assets/4a40bb0b-7d4a-429c-add4-43a9c8aa511b" /></td> </tr> </tbody> </table>

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

Installation

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
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
Locations

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

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:

Download the locale pack

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

Add the locales to mpv

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

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 eve

ModernZ

Install / Use

README