uosc

Project Overview

uosc is a UI script for the mpv player, written in Lua, focused on minimalism and proximity-based interaction. Interface elements no longer pop up on every mouse move; instead they appear based on how close the cursor is to a control, giving you full control over when the UI shows and hides. It also offers a configurable controls bar, context menus, thumbnails, and subtitle downloads.

Let mpv's interface appear only when it should, quietly and efficiently.

Key Features

• Proximity-based display: elements show or hide by cursor proximity instead of popping up on every move
• Minimizing timeline: the timeline can shrink into a small progress bar when idle
• Custom menus: build nested context menus yourself in input.conf
• Configurable controls bar: adjust the buttons and layout as needed
• Thumbnail previews: integration with thumbfast for fast, efficient thumbnails
• Track selection UIs: screens for choosing subtitle, audio, and video tracks
• Subtitle download: download subtitles from OpenSubtitles, or load external subtitle files
• Stream quality: a UI for choosing streaming quality
• Directory and playlist navigation: quick jumps through directories and playlists
• Searchable menus: every menu supports typing to search instantly
• Contextual scroll wheel: the wheel seeks on the timeline and adjusts volume and speed on their bars
• Chapters as timeline ranges: map chapters into clickable timeline ranges

Target Audience

• Advanced users who want a cleaner mpv interface
• Users who like efficient keyboard and wheel control
• People who need online subtitles and thumbnail previews
• Tinkerers who customize menus and toolbars

Quick Start

1. On Windows run the PowerShell install command; on Linux and macOS run the Bash install script
2. Or manually download uosc.zip and uosc.conf and extract them into mpv's config directory and script-opts
3. Optionally disable osd-bar and the window border in mpv.conf for a more unified look
4. Install thumbfast for timeline thumbnails, which uosc integrates automatically
5. Edit input.conf to build your own menus and key bindings
6. See and adjust all options and their defaults in uosc.conf

Core Advantages

• Restrained interface: appears only when needed and never distracts from watching
• Efficient controls: menus are searchable and the wheel does different things per control
• Feature-complete: subtitle download, track selection, and thumbnails in one place
• Extensible: a third-party script API lets others reuse uosc to render their menus

System Requirements

Item	Requirement
Player	mpv 0.33 or later
Linux/macOS install	Requires curl and unzip
Optional dependency	thumbfast (timeline thumbnails)

Notes

• If the interface feels sluggish during playback, video-sync=display-resample helps somewhat but raises CPU and GPU load
• Tying UI rendering to frame rate is an mpv limitation; pausing makes it smoother
• The installer may trigger antivirus false positives, a common misreport