A native macOS media player built with SwiftUI and powered by libmpv.
Single-window, single-player design with video-first controls, a compact mini-player mode, MKV support, subtitles, audio tracks, per-video resume state, and an MCP server for AI agent control.
- Native SwiftUI macOS app
- mpv playback through
libmpv - Single window, single player — one main player window and one playback session
- Opening another video replaces the current file (resume state is saved first)
- Single app instance — a second launch activates the running Valen instead of starting another player
- MKV, WebM, MP4, MOV, AVI, FLAC, OGG, WAV, and common media extension support
- Open files with
Command-O, Finder, or drag and drop - Compact QuickTime-style translucent overlay controls
- Responsive compact mode for small windows (single-row layout, 480×280 minimum)
- Overlay auto-hides during playback when the pointer is idle
- Cursor hides when playback controls hide
- Display sleep is prevented while media is actively playing
- Fullscreen support through shortcut, double-click, or macOS window controls
- Audio track selector
- Subtitle track selector
- External subtitle files (
.srt,.ass,.ssa,.vtt, and more) via menu, drag-and-drop, or auto-load whenMovie.srtsits besideMovie.mkv - Native Settings window (separate from the player window)
- Per-video saved state:
- resume position
- resume state is flushed when Valen quits
- selected audio track
- selected subtitle track
- subtitles off/on state
- volume
- MCP server (stdio + Unix socket) for AI agent control — ships inside the app bundle
Valen is intentionally not a multi-window or multi-instance player.
| Action | Result |
|---|---|
| Open / drop a new media file | Replaces the current file in the same window |
| Open while Valen is already running | Activates the existing instance and loads there |
| Open several files at once | Plays the first supported media file |
| Drop a subtitle while a video is open | Loads that subtitle on the current file |
| Dock click with no visible window | Brings the existing player window forward |
MCP open_file |
Loads into the same single player and focuses its window |
There is no “open in new window” path. Settings is the only extra app window, and it does not create a second player.
| Shortcut | Action |
|---|---|
Command-O |
Open file |
Space |
Play / pause |
Left Arrow |
Seek backward |
Right Arrow |
Seek forward |
Control-Command-F |
Enter / exit fullscreen |
Escape |
Exit fullscreen |
| Double-click video | Enter / exit fullscreen |
The seek distance is configurable in Valen > Settings.
Install mpv through Homebrew:
brew install mpvYou also need Xcode or Xcode Command Line Tools with Swift 6.
swift run valenThis is the fastest development path.
Open the native app target:
open Valen.xcodeprojOr build from the command line:
xcodebuild -project Valen.xcodeproj -scheme Valen -configuration Debug buildThe Xcode target uses the same Swift source files as the Swift Package target. It links against Homebrew libmpv.
Run the unit and layout-contract tests:
swift testThe tests cover time formatting, media track labels, supported media extensions, saved playback state, preference defaults, overlay behavior policy, single-player open intent, MCP protocol encoding, release metadata, app bundle metadata (including single-instance), and stable UI copy/icons/metrics for the empty state and playback overlay.
See Docs/Testing.md for the test map and guidance on when to add more tests.
Scripts/build-app.shThis creates:
dist/Valen.appdist/Valen-0.2.1-macos-arm64.zip
The generated app bundle includes libmpv and Homebrew runtime dylib dependencies under Contents/Frameworks.
By default, the bundle is ad-hoc signed for local use.
Sparkle update scaffolding is included, but Sparkle is not fully embedded yet.
Current files:
Packaging/Sources/mpvdesk/SparkleUpdater.swiftPackaging/appcast.example.xml
To include a Sparkle feed URL in the generated bundle:
SPARKLE_FEED_URL="https://your-domain.com/valen/appcast.xml" Scripts/build-app.shBefore shipping auto-updates:
- embed Sparkle in the Xcode app target
- host a real
appcast.xml - replace the example feed URL
- sign release zips with Sparkle's EdDSA signing tool
Valen currently uses NSOpenGLView because mpv exposes a stable OpenGL render API. Apple deprecated OpenGL, so the long-term plan is to investigate a Metal-backed rendering surface.
See Docs/Rendering.md for the rendering roadmap and Metal investigation checklist.
See Docs/Roadmap.md for the subtitle-focused and AI-assisted playback TODO list.
Valen ships with an embedded Model Context Protocol server so AI agents (Claude Code, Claude Desktop, etc.) can drive the player.
The valen-mcp executable reads JSON-RPC over stdio and forwards calls to the running GUI through a Unix domain socket. The GUI listens on $TMPDIR/valen-control.sock whenever the app is running.
| Tool | Args | Description |
|---|---|---|
play |
- | Resume playback |
pause |
- | Pause playback |
toggle_play_pause |
- | Toggle play/pause |
open_file |
path (string, absolute) |
Open a local file in the single player (replaces current media); path must start with / |
seek |
seconds (number), relative (boolean, optional) |
Seek to an absolute time, or by a signed offset when relative is true |
set_volume |
value (0–150) |
Set volume; 100 is unity gain |
set_speed |
speed (0.25–4.0) |
Set playback speed multiplier |
get_state |
- | Read full player state (see below) |
list_audio_tracks |
- | List audio tracks for the current file |
list_subtitle_tracks |
- | List subtitle tracks for the current file |
select_audio_track |
id (integer) |
Select an audio track by mpv track id |
select_subtitle_track |
id (integer) |
Select a subtitle track by mpv track id |
subtitles_off |
- | Turn subtitles off |
list_audio_tracks and list_subtitle_tracks return { "tracks": [...] }. Each track includes id, kind, title, language, codec, isDefault, isForced, isSelected, and displayName.
get_state returns control protocol version 2 fields:
protocolVersion,currentFile,isPaused,position,duration,volume,speedselectedAudioID,selectedSubtitleID,subtitlesVisible,activeSubtitleTextaudioTracks,subtitleTracks(same shape as the list tools)
swift buildThe binaries land in .build/debug/valen and .build/debug/valen-mcp.
Start the GUI once so the socket exists, then pipe JSON-RPC through the MCP binary:
.build/debug/valen &
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_state","arguments":{}}}' \
| .build/debug/valen-mcpvalen-mcp ships inside the app bundle at Valen.app/Contents/MacOS/valen-mcp. Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"valen": {
"command": "/Applications/Valen.app/Contents/MacOS/valen-mcp"
}
}
}Launch Claude Desktop while the Valen app is running and the thirteen tools appear in the tools menu.
- OpenGL rendering works but produces deprecation warnings.
- Sparkle update code is scaffolded, but the framework still needs to be embedded in the Xcode target.
- Multi-window / multi-player is intentionally unsupported; open another file to replace the current one.
Valen source code is licensed under the MIT License.
Valen depends on libmpv and other bundled runtime libraries, which are distributed under their own licenses. Add THIRD_PARTY_NOTICES.md before a public binary release.