# tomasklaen/uosc: a proximity-based UI for mpv

> uosc replaces mpv's on-screen controller with elements that appear only when the cursor approaches them. It requires mpv 0.33 or newer, ships installers for Windows and Unix, and is licensed LGPL-2.1.

**tomasklaen/uosc** — Feature-rich minimalist proximity-based UI for MPV player.

- Repository: https://github.com/tomasklaen/uosc
- Stars: 3,431 · Forks: 111
- Language: Lua
- License: LGPL-2.1
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/tomasklaen-uosc

## The problem uosc solves for mpv users

mpv ships with an on-screen controller, usually shortened to osc, that appears whenever the mouse moves and disappears on a timer. On a large screen that timer is either too short, so the controls vanish while you are still reaching for them, or too long, so they sit over the picture. uosc takes a different position: visibility is tied to cursor proximity rather than to mouse movement. The README describes the intent directly, saying UI elements "hide and show based on their proximity to cursor instead of every time mouse moves", which it frames as giving the viewer control over when the UI is visible. The audience is people who watch video in mpv rather than people who write mpv scripts, though the project also publishes an API on its wiki for third-party scripts that want to render menus through uosc. The feature list is long and mostly practical: track selection, subtitle download from Open Subtitles, external subtitle loading, stream quality selection, directory and playlist navigation, and a timeline that can shrink into a small progress bar when it is not in use.

## How proximity, the timeline and the menus fit together

The mechanism is a Lua script loaded by mpv. uosc draws its own elements and decides their visibility from cursor position, so the UI layer is separate from mpv's built-in osc. The timeline is the clearest example of the design: when it goes unused it minimizes itself into a small discrete progress bar rather than staying at full height. Chapters can be turned into timeline ranges, which the README shows as the red portion of the timeline in the preview. The mouse wheel is context-sensitive: over the timeline it seeks by timeline_step seconds per scroll, over the volume bar it changes volume by volume_step, over the speed bar it changes speed by speed_step, and over bare video with no widget under the cursor it falls back to whatever wheel bindings you set in input.conf. Right-clicking the volume or speed element resets it. Menus are the other half. They are all searchable, and the README says you can simply start typing; menu_type_to_search controls whether typing goes straight into search or whether ctrl+f or backslash is needed. Navigation inside menus uses up, down, enter, backspace for the parent menu, esc to close, and the usual page keys, with shift+del reserved for a menu's own del action when search is active. The context menu is built by editing input.conf with nesting support, which means the menu structure lives in your mpv configuration rather than inside the script.

## Installing uosc and opening the main menu

uosc requires mpv 0.33 and higher. The README gives three install paths: a PowerShell one-liner on Windows, a curl-based shell script on Linux and macOS, and a manual extraction of uosc.zip into your mpv config directory. On Windows, the installer may need the execution policy relaxed for the current user before the remote script can run.

```powershell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm https://raw.githubusercontent.com/tomasklaen/uosc/HEAD/installers/windows.ps1 | iex
```

If that command is run from an mpv installation directory that contains portable_config, the README states it installs there instead of into AppData. The Unix installer needs curl and unzip.

```sh
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/tomasklaen/uosc/HEAD/installers/unix.sh)"
```

On Linux the installer tries to detect which config location your package variant uses, with the order of precedence being the flatpak path ~/.var/app/io.mpv.Mpv, then ~/snap/mpv, then ~/snap/mpv-wayland, then ~/.config/mpv. To force a lower-priority location, the higher ones must not exist. The manual route is to extract uosc.zip into the mpv config directory and, if you do not already have one, place uosc.conf into script-opts inside that directory; the file contains every option with its default value and documentation. For a first real use, install as above, start mpv, and move the cursor toward the bottom of the window. The controls bar should appear on approach rather than on any mouse movement. Open a menu and type a few letters to filter it; uosc searches menus as you type. If you want the seek and volume indicators uosc provides, add the two lines the README suggests to mpv.conf.

```config
osd-bar=no
border=no
```

The first disables mpv's own bar because uosc draws its own indicators through the flash-timeline and flash-volume commands. The second lets uosc draw window controls and a border when the native border is off.

## The sluggish-UI trade-off and other limits

The README is unusually candid about a performance problem. During playback the UI rendering frequency is chained to the video frame rate, so the interface can feel sluggish; pausing the video switches the refresh rate closer to or matching the monitor and the UI should feel smoother. The suggested remedy is video-sync=display-resample in mpv.conf, with the acknowledged cost of somewhat higher CPU and GPU load. That is a real trade-off, not a footnote: on a low-powered machine you are choosing between a UI that lags the frame rate and a sync mode that costs more to run. The README attributes the underlying limitation to mpv rather than to uosc. Two smaller constraints are worth knowing before you install. First, the Windows installer downloads a remote script and the README warns that the downloaded archive might trigger false positives in some antiviruses, with an FAQ entry devoted to it. Second, uosc is not a standalone player. It is a script for mpv, so it inherits mpv's configuration model and its config directory locations; if you want a player with a settings window, this is the wrong layer to look at. The project also carries a Go utility binary called ziggy, built with a tools/build script that requires Go, and the repository includes a go.mod listing dependencies such as clipboard and browser packages. Nothing in the README explains what ziggy does at runtime, so treat it as an implementation detail rather than a feature you configure.

## uosc against mpv's built-in osc and ModernX

The closest comparison is mpv's own osc, which uosc replaces. The built-in controller shows on mouse movement and hides on a timer; uosc shows on cursor proximity instead, and adds a searchable menu system, a configurable controls bar, subtitle download from Open Subtitles, stream quality selection and thumbfast thumbnail integration that the stock osc does not provide. If all you want is a seek bar that appears when the mouse moves, the built-in osc is already installed and needs no script. ModernX is the other mpv UI people commonly mention alongside uosc. Both are Lua scripts layered on mpv, so the practical difference is in the interaction model and the configuration surface rather than in what mpv itself can play. uosc's distinguishing choices are proximity-based visibility and a context menu defined in input.conf with nesting; a project that instead emphasises a fixed control layout will feel different in daily use even though both sit on the same player. On the thumbnail side, thumbfast is not an alternative to uosc but a companion: the README states that installing thumbfast is the only step needed for timeline thumbnails, because uosc integrates with it. The comparison to make is therefore not uosc versus thumbfast but uosc versus whatever controller you use today.

## Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-30. Release 5.13.0 is dated 2026-08-03, following 5.12.0 in September 2025 and 5.11.0 in August 2025, so the project has a release history spanning multiple years with a recent tag. Upgrades are cheap by design. Both installers are described as installing or updating uosc, and the default uosc.conf is only written if it does not already exist, which means your edited options survive a reinstall. The manual path is the same idea: extract the new uosc.zip over the old one. The cost of upgrading is therefore mostly the cost of reading the changelog on the releases page, since options can change between versions and your uosc.conf is yours to maintain. The licence is LGPL-2.1, with the licence file stored as LICENSE.LGPL at the repository root. For most users this is a non-issue because you are installing and running the script rather than modifying and redistributing it. If you fork uosc or ship it inside a product, the LGPL terms apply to that distribution, and the specifics are for a lawyer rather than for this article. The Go binary adds a second licence surface if you build and redistribute ziggy yourself.

## Conclusion

Adopt uosc if you already live in mpv and want the on-screen controller to stop covering the frame: the proximity behaviour, the searchable menus and the input.conf-driven context menu are the reasons to switch. Skip it if you want a player you configure once through a graphical settings dialog, or if you are pinned to an mpv older than 0.33. Before committing, open uosc.conf and read the option list, confirm your mpv build reports 0.33 or higher, and decide whether you want osd-bar disabled as the README suggests, because that is the setting uosc's own seek and volume indicators replace.

## FAQ

### What version of mpv does uosc require?

The README states that uosc requires mpv 0.33 and higher. Installing it on an older build is not covered by the documentation.

### How do I install uosc on Linux or macOS?

The README gives a single shell command that pipes the unix installer from the repository into bash, and notes that it requires curl and unzip. The installer detects which config location your package variant uses, preferring the flatpak path, then snap, then ~/.config/mpv.

### Why does the uosc UI feel slow while a video is playing?

The README explains that during playback the UI rendering frequency is chained to the video frame rate, which it calls an mpv limitation. It suggests video-sync=display-resample in mpv.conf as a partial remedy, at the cost of somewhat higher CPU and GPU load.

### Does uosc need thumbfast for timeline thumbnails?

Thumbnails are optional. The README says that installing thumbfast is the only step required, because uosc integrates with it and no further configuration is needed.

### Will upgrading uosc overwrite my configuration?

The README describes the installers as installing or updating uosc and placing a default uosc.conf into script-opts only if it does not already exist. An existing configuration is therefore left in place.

## Sources

- [Issues](https://github.com/tomasklaen/uosc/issues)
- [License: LGPL-2.1](https://github.com/tomasklaen/uosc/blob/main/LICENSE)
- [README](https://github.com/tomasklaen/uosc/blob/main/README.md)
- [Releases](https://github.com/tomasklaen/uosc/releases)
- [tomasklaen/uosc on GitHub](https://github.com/tomasklaen/uosc)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tomasklaen-uosc