mpv-macWrapper

Wrap your Homebrew (or otherwise installed) mpv CLI as a native macOS .app — double-click to launch, pin to Dock, right-click files to open.

中文  · 

Why?

Homebrew and other package managers install/compile mpv as a command-line binary. It can't:

• Launch from Finder with a double-click
• Stay in the Dock
• Appear in "Open With" menus
• Show up in Launchpad

This project builds a ~1.2 MB .app bundle (wrapper v1.0.0, tested with mpv v0.41.0) that solves all of the above.

Quick Start

brew install --cask IstPlayer/tap/mpv-macwrapper

Without Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/IstPlayer/mpv-macWrapper/main/scripts/install.sh)"

Or download the latest DMG and drag mpv.app into /Applications/.

macOS Gatekeeper: the app is unsigned. On first launch, macOS will block it with a "cannot be opened because it is from an unidentified developer" dialog. Right-click (or Control-click) the app in Finder and choose Open, then confirm. You may also need to go to System Settings → Privacy & Security and scroll down to find the security prompt to allow it manually. Alternatively, make install strips the quarantine flag automatically, so Gatekeeper won't prompt on subsequent launches.

Tested on: macOS Tahoe 26.5 (Apple Silicon).

Usage

Action	Command / Gesture
Launch (idle window)	Double-click mpv.app
Open a file	open -a mpv video.mkv
Drag & drop	Drop a video onto the mpv window or Dock icon
Finder right-click	Right-click a video → Open With → mpv

How It Works

mpv.app/
└── Contents/
    ├── MacOS/mpv          ← native arm64 launcher (C, ~33 KB)
    ├── Resources/mpv.icns ← pre-generated app icon
    └── Info.plist         ← metadata + 20 format associations

The launcher locates mpv at runtime by checking, in order:

1. ~/.config/mpv-macWrapper/path.conf — saved from file picker

2. $MPV_PATH environment variable

3. /opt/homebrew/bin/mpv (Apple Silicon Homebrew)

4. /usr/local/bin/mpv (Intel Homebrew)

5. /opt/local/bin/mpv (MacPorts)

6. $PATH — searches every directory on your PATH for mpv

7. Native file picker — manual selection → saved to path.conf

• With arguments → passes them through to mpv.
• No arguments → launches mpv --idle=yes --force-window=yes (blank window, ready for drag & drop).

mpv updates require zero maintenance. The launcher always resolves to the current binary on your system.

Configuration

All mpv behaviour is controlled by your ~/.config/mpv/:

• mpv.conf — main configuration
• scripts/ — Lua scripts (ModernZ, thumbfast, playlistmanager, …)
• script-opts/ — script options

The launcher itself has zero configuration.

Dependencies

Dependency	Why	Install
mpv	The player itself	brew install mpv
clang	Compile the launcher	xcode-select --install
sips / iconutil	Icon packaging (pre-generated)	Built into macOS

Regenerating the icon from scratch is optional (it's pre-generated). It only requires curl, sips, and iconutil — all built into macOS. Run make icon. To use a custom icon, edit the URL variable in scripts/generate-icon to point to your own SVG before running.

Development

The .app is pre-built and committed. To rebuild (e.g. after modifying the launcher):

make          # Build mpv.app
make test     # Build + smoke tests
make clean    # Remove build artifacts
make icon     # Regenerate the icon from upstream

Custom mpv path

MPV_PATH=/opt/custom/bin/mpv make

FAQ

Do I need to reinstall after brew upgrade mpv?

No. The launcher automatically locates mpv at runtime following the lookup rules.

How do I uninstall?

brew uninstall --cask mpv-macwrapper
brew untap IstPlayer/tap  # optional: remove the tap

If installed from source: make uninstall.

License

GPLv2+ © 2026 IstPlayer.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

See LICENSE for the full text.