Modern, Audiophile-Grade Subsonic & Navidrome Client for macOS and iOS
Features • Architecture • Prerequisites • Getting Started • Audio Engine • Shortcuts • Localization
mpvg is a native, beautifully crafted music player client designed specifically for Navidrome and Subsonic-compatible media servers. Built from the ground up with SwiftUI, it combines a refined, Apple Music-inspired visual design with a high-fidelity audiophile playback engine powered by mpv and CoreAudio on macOS, and an optimized AVFoundation engine on iOS.
Whether you're listening on studio monitors, high-end headphones, or an external USB DAC, mpvg delivers bit-perfect, uncompressed music streaming with zero compromises.
- CoreAudio Exclusive Mode (Hog Mode) (macOS): Takes direct hardware control of your output device (
--audio-exclusive=yes), bypassing the macOS system mixer and system alert sounds for pure bit-perfect transmission. - Dynamic Sample Rate Switching: Automatically reconfigures your DAC's hardware clock rate to match the incoming audio stream (e.g., 44.1 kHz, 48 kHz, 96 kHz, 192 kHz) without software resampling.
- Seamless Gapless Playback: Continuous playback between tracks without audible pauses—essential for classical music, live recordings, and concept albums.
- Hardware DAC Hotplug Detection: Real-time CoreAudio listener that detects when USB DACs or headphones are connected or disconnected, automatically warning you if your preferred DAC goes offline.
- Live Stream Inspector: Displays active sample rate, bit depth, format (FLAC, ALAC, WAV, MP3, etc.), channels, and exclusive mode status directly in the player bar.
- Full Library Browsing: Effortlessly explore your music collection by Albums, Artists, Playlists, and Genres.
- Discovery Sections: Dedicated views for Most Popular and Recently Added releases.
- Instant Search: Lightning-fast search across tracks, albums, and artists, accessible via header or sidebar with ⌘ F.
- Bi-directional Star Ratings: Rate songs directly in the player bar or track lists, synchronizing five-star ratings back to your Navidrome server.
- Scrobbling & Now Playing: Notifies your server of active playback and scrobbles completed tracks automatically.
- Configurable Queue Preload: Preload up to 10 upcoming tracks into memory and local storage to guarantee instant track changes with zero buffering lag.
- Disk Audio Cache (
AudioCacheManager): Stores played audio files locally to minimize network bandwidth and prevent playback stutter over unstable connections. - Disk Image Cache (
LibraryCacheManager): Ultra-fast asynchronous cover art rendering and persistent disk caching for smooth, jitter-free scrolling. - Cache Management: Transparent cache size monitoring in Settings with one-click cache clearing.
- Liquid Glass Player Bar: A floating, translucent frosted-glass player bar with real-time seek slider, volume control, time counters, and DAC HUD.
- Collapsible Sidebar: Apple Music-style sidebar with translucent vibrant materials, navigation shortcuts, and search.
- Grid & Table View Modes: Switch between high-resolution album grid cards and a dense, metadata-rich table view (showing track count, year, genre, and duration).
- Full Artist & Album Views: Deep-dive into artist profiles with discographies and top tracks, or inspect complete album tracklists.
- Interactive Queue Popover: Inspect, reorder, or jump between upcoming tracks in the playing queue.
- Toast Notification System: Subtle, non-intrusive on-screen toasts for audio engine reconnections, DAC events, and server status.
- Media Keys & Control Center: Full support for macOS media keys (Play, Pause, Next, Previous, Scrubber) via
MPRemoteCommandCenterandMPNowPlayingInfoCenter. - macOS Control Center & iOS Lock Screen: Displays rich artwork, artist, title, album, and scrubbing bar natively across system controls.
- Demo Mode: Includes a sample catalog loader to test and experience the interface without an active server connection.
mpvg utilizes a dual-engine architecture tailored to the host platform:
graph TD
subgraph UI ["SwiftUI Application Layer"]
MainView --> SidebarView
MainView --> BrowseView
MainView --> PlayerBarView
MainView --> SettingsView
PlayerViewModel --> NavidromeService
PlayerViewModel --> AudioCacheManager
PlayerViewModel --> LibraryCacheManager
end
subgraph macOSEngine ["macOS Backend"]
PlayerViewModel --> MPVProcessManager
MPVProcessManager -->|Unix Domain Socket /tmp/mpv_player.sock| MPVProcess[mpv binary]
MPVProcess -->|Exclusive Hog Mode| CoreAudio[CoreAudio HAL / USB DAC]
MediaKeyController -->|MPRemoteCommandCenter| PlayerViewModel
end
subgraph iOSEngine ["iOS Backend"]
PlayerViewModel --> IOSAudioEngine
IOSAudioEngine -->|AVPlayer & AVAudioSession| iOSCoreAudio[iOS Audio Session / Hi-Res DAC]
end
subgraph RemoteServer ["Backend Music Server"]
NavidromeService -->|Subsonic REST API v1.16+| Navidrome[Navidrome / Subsonic Server]
end
- Spawns and manages an independent
mpvprocess using IPC over a local Unix domain socket (/tmp/mpv_player.sock). - Automatically locates the Homebrew
mpvbinary (/opt/homebrew/bin/mpvor/usr/local/bin/mpv). - Communicates using JSON-IPC commands for millisecond-accurate seeking, volume changes, track transitions, and stream property observation.
- Employs CoreAudio HAL APIs (
kAudioHardwarePropertyDevices,kAudioDevicePropertyHogMode) to monitor audio devices and control DAC hardware formats.
- Utilizes
AVPlayerandAVAudioSessiontuned for bit-perfect audio delivery to external USB DACs (such as HiBy FC1 and other Lightning/Type-C dongles). - Integrates route change notifications and interruption handling for seamless transitions when connecting or disconnecting headphones.
- macOS 14.0 (Sonoma) or later.
- Xcode 15.0+ or Command Line Tools.
- mpv installed via Homebrew:
brew install mpv
- iOS 17.0 or later.
- Compatible iPhone or iPad with an active network connection to your Subsonic server.
git clone https://github.com/fabsanh/mpvg.git
cd mpvgOpen the Xcode project:
open mpvg.xcodeproj- Select the mpvg (macOS) or mpvg (iOS) scheme.
- Press ⌘ R to build and launch.
- Navigate to Settings in the sidebar.
- Enter your Server URL (e.g.,
https://music.yourdomain.com). - Enter your Username and Password (or API token).
- Click Save & Test Connection.
- Once connected, your library will automatically synchronize.
To enable bit-perfect audiophile playback on macOS:
- Open Settings → Audio Engine & Exclusive Mode.
- Select your connected Output Device (USB DAC or audio interface).
- Toggle CoreAudio Exclusive Mode to
ON:- mpvg will claim hardware hog mode on the device.
- macOS alerts and other applications will not mix into your music.
- Toggle Bit-Perfect Sample Rate to
ON:- When playing a 96 kHz or 192 kHz FLAC track, mpvg dynamically changes the physical DAC clock to 96,000 Hz or 192,000 Hz without digital resampling.
- Toggle Gapless Playback to
ONfor uninterrupted playback.
You can also toggle Exclusive Mode directly from the player bar's status badge.
| Shortcut | Action |
|---|---|
| Space | Play / Pause |
| ⌘ F | Focus Search Bar |
| Media Play/Pause | Play / Pause (System-wide) |
| Media Next | Next Track (System-wide) |
| Media Previous | Previous Track (System-wide) |
mpvg includes complete, native localization support powered by Apple String Catalogs (Localizable.xcstrings):
- 🇬🇧 English (Default)
- 🇪🇸 Spanish (Español)
The application automatically adheres to your system language preference.
Developed by Fabián Sanhueza (@fabsanh).
Powered by mpv and built for the Navidrome / Subsonic music community.