ModernZ redraws the mpv on-screen controller as a Lua script

A fork of ModernX that keeps mpv's OSC contract

ModernZ is described as a sleek and modern OSC for mpv, and the README is precise about what it is in relation to the other project. This project is a fork of ModernX that enhances functionality by adding more features while preserving the core standards of mpv's OSC.

That last clause is the important one for anyone deciding whether to install it. An on-screen controller is not just a set of buttons, it is a protocol. mpv's OSC specification defines the message format, the command identifiers and the layout of the interface, and a script that ignores those conventions will work with itself and break with everything else that talks to mpv's OSC port, including the default OSC, the input.conf bindings and other scripts that expect the standard command names.

So the fork keeps the wire protocol and changes the surface. The repository top level listing shows what that means in practice. There is modernz.lua, which is the whole controller, modernz.conf, which is the configuration file, modernz-icons.ttf, which is the icon font, an icons/ directory, an extras/ directory for the extra scripts, a docs/ directory, and a .github/ directory.

A single Lua file plus a font plus a config is a very small artefact for what the feature list claims, and it says something about the approach. mpv's OSC is itself a Lua script, and the interface is drawn as an ASS subtitle overlay, so the entire controller is a Lua program that computes subtitle events. There is no separate window, no rendering library and no dependency beyond what mpv already has.

The project is LGPL-2.1 licensed, which is the licence family mpv itself uses, and that is a deliberate choice for something that is loaded into the player's process.

Four layouts, two icon themes and three icon styles

The customisation surface is where the fork's value becomes concrete, and it is organised as three independent axes.

The first is the layout, chosen with the layout option in your modernz.conf, and the accepted values are default, compact, mini and seekbar.

That is a meaningful spread. The default is the conventional arrangement, the compact and mini are for small windows or an embedded display, and seekbar is a layout where the seek bar carries the controls, which is the arrangement people use when the video is small and the overlay covers most of it.

The second is the icon theme, with the icon_theme option accepting fluent or material, described as matching your preferred style. Those are the two big icon sets, and the choice is not cosmetic in a forked project, because an icon font is a binary asset and shipping two of them doubles the size of the visual layer. The modernz-icons.ttf at the root is the font, and the icons/ directory holds the sources or the per-theme assets.

The third is the icon style, chosen with icon_style, and the values are mixed, filled and outline. Both the fluent and material themes have all three, so the two axes combine. Fluent in mixed style and material in outline style are different visual languages, not just different glyph shapes, and a user who switches themes usually wants to switch style with them.

The seek bar has its own sizing option, seekbar_height, with the values small, medium, large and xlarge, and the README explains the motivation simply, if you find the seek bar too thin or too thick you can easily adjust its size. A separate option for the seek bar height is a sign of how much of the screen the overlay takes up on a small window, which is where the compact and mini layouts exist too.

The README also mentions colour adjustments among the wider range of customisation options, and the configuration file at the repository root, modernz.conf, is the single place all of it lives.

The buttons, and the menus behind them

The features list names the controls and the menus separately, and the menus are the interesting half.

The buttons are listed as download, playlist, speed control, screenshot, pin, loop, shuffle, and more, with a link to docs/CONTROLS.md for the details. Download is a notable one for a player, since it turns the player into a way of fetching the file it is playing. Pin is the opposite, a control that keeps the overlay visible, which is what you want when you are using the interface rather than watching through it. Speed control and shuffle are not in mpv's default OSC at all.

The menus are listed as interactive menus for playlist, subtitles, chapters, audio tracks, and audio devices. That is the substantial addition over the default controller, and it changes what the overlay is for. A button row tells you what you can do; a menu lets you choose from a list, and for a film with thirty subtitle tracks or a TV series with forty chapters, a scrollable menu is the difference between usable and not.

The audio devices entry is worth a second look, because it implies the OSC can list what the system has rather than only cycling through it, which is what mpv's own controls do by default. And the docs directory has a dedicated file for it, docs/INTERACTIVE_MENUS.md, with an image showing the menu open over a menu button.

There is also an Image Viewer mode with zoom controls, documented separately at docs/IMAGE_VIEWER.md. That is a feature rather far outside the OSC idea, and it is the kind of thing a fork accumulates, since the base OSC draws a control overlay and a fork can draw anything into the same subtitle layer.

Two smaller features are worth noting. The hover behaviour is separated, with an independent hover zone for the top bar, the window controls bar, and the bottom bar, the OSC, so the two overlays do not appear at the same time and the window controls do not steal the hover from the media controls. And video thumbnail previews are supported through thumbfast, an external script, so the seek bar can show a frame from the target position rather than a bare progress line.

Locales are JSON, and the controls are configurable

Multi-language support is listed with JSON locale integration, and the Translations section of the README is the part that says how it works. The interface strings live in JSON files, so adding a language is a matter of adding a file rather than editing a Lua table, and a translator does not need to touch the code.

That matters for an OSC more than it might seem, because the interface is drawn as text in a subtitle overlay, so every label is a string the player has to render. A locale file is also a small, reviewable artefact, which is what makes community translation of a media player interface practical at all. The OSC Language section is listed in the navigation next to Configuration and Controls, so it is treated as a first class feature rather than an afterthought.

The controls are configurable too, with the Controls section in the navigation and a link to docs/CONTROLS.md. The word configurable here covers both the key bindings and the layout of the buttons themselves, and for an overlay that draws itself, the set of buttons is a configuration value rather than a code change.

The extras/ directory at the top of the repository is for the extra scripts, and the thumbnail previews depend on one of them being present, thumbfast, which is a separate project by po5. So the feature set of ModernZ is ModernZ plus whatever you install alongside it, which is the normal arrangement for mpv scripts, where each script is independent and the user assembles what they want.

The release history shows steady work on the fork, with v0.3.1 on 2026-03-19, v0.3.2 on 2026-04-19 and v0.3.3 on 2026-05-20, and the last push to main on 2026-06-04.

Where ModernZ is the wrong choice

The first wrong case is a user who wants the minimal OSC. mpv's built-in controller is small, it appears and disappears, and it never obscures the video. ModernZ is by design a large, featureful interface with menus, so a user who wants the default behaviour is choosing a different tool for no reason. The mini and compact layouts narrow the gap but do not close it.

The second wrong case is a setup where the script cannot run. This is a Lua script for mpv, and the README's own list of features, image viewer mode, interactive menus, thumbnail previews, all of them depend on the mpv scripting environment and on additional scripts being present. A minimal mpv build, or a platform where the Lua environment is not present, will not give you the whole feature set, and the thumbnail previews need thumbfast installed as well.

The third wrong case is a user who does not want a fork. A fork means the upstream project and this one can drift, and the two will diverge. If you intend to track upstream ModernX for its own sake, this is the wrong place to be. If you want the features and do not care about upstream, it is fine.

The fourth wrong case is a user on a small embedded display where the overlay covers the video, or a keyboard-only workflow where the interactive menus are extra navigation. The pin button and the independent hover zones mitigate the first, and the menu is optional in the second, but the general shape of the interface is a rich one.

How it differs from the stock mpv OSC

The comparison worth making is with the controller mpv ships, and the difference in approach is in how the two treat the surface area.

The stock OSC is a row of buttons in the bottom right, drawn as an ASS subtitle overlay, with the standard command identifiers so that input.conf bindings and other scripts can drive it. It is deliberately minimal, it appears on mouse movement and disappears, and it does exactly the things a player needs: play, pause, seek, volume, fullscreen, and the standard cycle commands for things like subtitles and audio tracks.

ModernZ takes the same foundation and extends it in three directions. The first is breadth of controls, adding download, screenshot, pin, speed and shuffle to the set, which are all one-shot commands that mpv exposes but the default OSC does not put on screen. The second is menus, which is the real change, because a menu is a different kind of interaction from a button, since a button applies a fixed action and a menu asks you to choose.

The third is presentation. Four layouts, two icon themes and three icon styles, and a separately adjustable seek bar height, is a theming system rather than a controller, and it is the part that a fork of a fork tends to accumulate, because each is a small change and the sum is a different product.

What both have in common is the constraint that makes the whole thing work. The interface is an ASS subtitle overlay, so it is drawn by the video renderer, it inherits the subtitle styling, and it can be scaled and positioned with the standard subtitle options. That is why an OSC can be themed and scripted at all, and it is also why an OSC is limited to what can be expressed as subtitle events, text and rectangles, which is why the interactive menus and the image viewer are the ambitious parts of this project rather than the buttons.

Editorial conclusion

ModernZ fits an mpv user on Linux or a small embedded screen who wants a controller with menus for subtitles, chapters and audio tracks rather than a row of buttons, and it fits a user who wants the same interface to work in several languages through the JSON locale files. It does not fit a user who wants the minimal mpv OSC, and it does not fit a Windows or macOS setup where the script needs a Lua environment mpv does not provide by default. Before installing it, read the fork relationship carefully, since it is a fork of ModernX and preserves mpv's core OSC standards, and note that the current release is v0.3.3 from 2026-05-20 with the last push on 2026-06-04.

Frequently asked questions

Official sources

1. Issues
2. License: LGPL-2.1
3. README
4. Releases
5. Samillion/ModernZ on GitHub