shirkeharsh/mooziac

Mooziac is an ultra-lightweight, 100% native Swift & AppKit player for YouTube Videos, YouTube Music, and local audio built specifically for macOS.
The native alternative to YouTube Music Desktop, Spotify, and Electron players — combining a menu bar music player with a 4K hardware-accelerated YouTube video window, an invisible trackpad edge volume slider, real-time synchronized lyrics HUD, and zero battery-draining Chromium bloat.

See Mooziac in Action

_{Interactive player preferences, themes, live audio waveforms, and native macOS menu bar playback controls.}

Why Mooziac?

Most desktop music players are heavy Electron wrappers that bundle a full Chromium browser, devouring system resources and draining laptop battery life. Mooziac was built from scratch in pure native Swift and AppKit with zero third-party runtime dependencies.

Feature	Mooziac	Official YTM Web / Desktop	Electron Wrappers
Technology	100% Native Swift & AppKit	Chromium / Web App	Heavy Chromium + Node.js
YouTube Video Player	Native 4K GPU Decode (Apple VideoToolbox)	High CPU in Browser	Heavy Electron / Lags
Distraction-Free Playback	Built-in clean styling & SponsorBlock	No	Third-party plugins
Trackpad Edge Volume	Yes (with haptic feedback)	No	No
Synchronized Lyrics HUD	Line-by-line LRC	Basic / Unsynced	No
Local Offline Audio	FLAC, MP3, WAV, AAC, M4A	Cloud only	No
Background Media Keys	Native macOS integration	Browser permissions	Inconsistent
Discord Rich Presence	Native Unix socket (0 deps)	No	Third-party plugins
Telemetry & Privacy	100% Local (Zero tracking)	Extensive Google telemetry	Varies

Native macOS Features: YouTube Video Player, Trackpad Gestures & Audio Engine

4K YouTube Video Player & Hardware Acceleration

Watch full YouTube videos in a dedicated native window with zero battery-draining CPU churn.

VideoToolbox GPU Decode: Hardware-accelerated VP9 and H.264 video decoding directly via Apple Silicon and Intel Metal GPUs.
Distraction-Free Viewing: Built-in clutter filtering, distraction-free focus mode, and automatic SponsorBlock segment skipping directly inside the native engine.
Native Fullscreen: Seamless edge-to-edge macOS fullscreen toggle via F key, double-click, or native window controls.

Invisible Trackpad Volume Slider

Turn the rightmost 1mm border of your MacBook trackpad into an invisible hardware volume dial.

1mm Border Edge: Slide along the outer bezel for fine-grained system volume adjustment across music and video.
Tactile Taptic Engine: Real physical haptic ticks as volume levels increment or decrement.
Continuous Level Tracking: Lift finger and resume adjusting smoothly from current level without snapping back.

Floating Synchronized Lyrics HUD

Sing along with real-time, line-by-line synchronized LRC lyrics right beneath your menu bar.

Line-by-Line LRC: Powered by LRCLib and native YouTube Music synced endpoints.
Non-Intrusive HUD: Floats discreetly without taking window focus or blocking your workspace.
Instant Local Cache: Stored in SQLite for zero-latency retrieval on repeat listens.

Dual Audio Engine (Cloud + Local Hi-Res)

Stream your cloud favorites or play lossless offline libraries in one seamless unified queue.

YouTube Music Bridge: Direct access to your cloud playlists, liked songs, and history.
Lossless Hi-Res: Pure AVFoundation playback supporting FLAC, ALAC, WAV, MP3, AAC, and M4A.
Built-in Downloader: Integrated yt-dlp pipeline with automatic tag and artwork embedding.

Interactive Waveform & Adaptive Glow

Dynamic ambient interface that harmonizes with your music and desktop wallpaper.

Live Audio Visualizer: Interactive waveform scrub bar with real-time seeking.
Adaptive Palette: Real-time color sampling from active album artwork.
Curated Themes: OLED Pitch Black, Crystal Glass, and Liquid Fluid visual styles.

Native Discord Rich Presence

Broadcast your now-playing status without third-party bloat or background daemons.

Native Unix Socket IPC: Direct connection with zero Node.js or Python runtime overhead.
Rich Status Card: Displays active song title, artist, album art, and live elapsed timestamps.
Auto-Pause Sync: Updates status in real time when playback is paused or resumed.

100% Local & Privacy-First

Architected with strict privacy principles — your listening data and video activity remain strictly on your Mac.

Zero Telemetry: No analytics SDKs, trackers, beacons, or crash reporters phoning home.
Local SQLite3: History, likes, and cached playlists stay entirely in your local storage.
Sandboxed WebKit: Credentials remain safely inside Apple's official WKWebsiteDataStore.

Gestures & Shortcuts

Trackpad MultiTouch Gestures

Gesture	Trackpad Region	Action
Edge Slide	Far-right 1mm border	Smooth volume adjustment with tactile haptics
Double Tap	Bottom-right corner	Next Track
Triple Tap	Bottom-right corner	Previous Track
Double Tap	Bottom-left corner	Play / Pause Toggle
Scroll	Over Menu Bar Icon	Fast Volume Stepping

Keyboard Shortcuts

Music Player Mode

Shortcut	Action
`Space`	Play / Pause
`Cmd + Right Arrow`	Next Track
`Cmd + Left Arrow`	Previous Track
`L`	Like / Unlike Song
`Cmd + R`	Reload Web Engine
`Cmd + Q`	Quit Mooziac

YouTube Video Mode

Shortcut	Action
`F`	Toggle macOS Native Fullscreen
`Space` / `K`	Play / Pause Video
`J` / `L`	Seek 10s Backward / Forward
`M`	Mute / Unmute Audio
`C`	Toggle Closed Captions / Subtitles
`[` / `]`	Decrease / Increase Playback Speed
`Cmd + Shift + F`	Toggle Distraction-Free Focus Mode
`Cmd + Shift + S`	Toggle SponsorBlock Auto-Skip
`Cmd + Shift + C`	Copy Video URL with Timestamp
`Esc`	Exit Fullscreen

Installation

Option 1: Homebrew (Recommended)

Install directly via the official Homebrew tap:

brew install shirkeharsh/tap/mooziac

To update in the future:

brew upgrade --cask mooziac

Option 2: Direct Download

Download Mooziac.dmg or Mooziac.zip.
Open Mooziac.dmg and drag Mooziac into your Applications folder.
Launch Mooziac from Spotlight (Cmd + Space) or Launchpad.

Note

macOS Gatekeeper: Because Mooziac is distributed directly outside the Mac App Store:

If macOS prompts that the app cannot be verified, go to System Settings > Privacy & Security and click Open Anyway.
Or run this one-line command in Terminal:
```
xattr -cr /Applications/Mooziac.app
```

Building from Source

Prerequisites

macOS 13.0 (Ventura) or later
Xcode 15+ or Xcode Command Line Tools (xcode-select --install)
Swift 5.9+ toolchain

# Clone repository
git clone https://github.com/shirkeharsh/mooziac.git
cd mooziac

# Run unit tests
swift test --parallel

# Build and launch debug app locally
./build_app.sh

# Build universal release binary & DMG package
./build_app.sh --release-only

Architecture and Project Structure

Mooziac is architected into modular Swift components using native macOS system frameworks:

Mooziac/
├── Package.swift                         # SPM manifest (macOS 13+, Swift 5.9)
├── Mooziac.entitlements                  # Hardened Runtime security entitlements
├── build_app.sh                          # Universal build & packaging pipeline
├── Sources/Mooziac/                      # Main application target
│   ├── App/                              # Application lifecycle, AppDelegate, background media keys
│   ├── Audio/                            # CoreAudio volume hooks, AVFoundation audio player
│   ├── Core/                             # Central coordinators, NowPlaying, StatusItemManager
│   ├── Input/                            # MultiTouch gesture engine & global keyboard shortcuts
│   ├── Managers/                         # Local SQLite3, YTMClient, synced lyrics, yt-dlp downloader
│   ├── Models/                           # State representations, playlist records, audio configs
│   ├── Views/                            # Dynamic Island player UI, waveform, floating lyrics HUD
│   ├── Web/                              # Sandboxed WebKit bridge for YouTube Music streaming
│   └── YouTube/                          # Native YouTube video player subsystem
│       ├── Core/                         # MainVideoWindowController, VideoPlayerCoordinator
│       ├── Database/                     # YouTubeDatabaseManager local watch history & likes
│       ├── Extensions/                   # WebExtensionHost, WebExtensionManager
│       ├── Input/                        # KeyboardShortcutHandler for fullscreen & playback
│       ├── Models/                       # VideoQuality, VideoPlaybackState, PlayerTheme
│       ├── Services/                     # YouTubeDownloadService via yt-dlp
│       ├── Settings/                     # YouTubeSettings (clutter filters, distraction-free)
│       ├── Views/                        # MooziacHeaderBarView, FloatingHUD, DownloadSheet
│       └── Web/                          # YouTubeWebView, QualityManager, SponsorBlock, Highlight
└── Tests/MooziacTests/                   # Parallelized unit test suite
    ├── DownloadManagerURLTests.swift     # URL & YouTube shorts ID extraction tests
    ├── DownloadQueuePersistenceTests.swift# Download queue SQLite/JSON persistence tests
    ├── MooziacTests.swift                # Hotkeys, seek modifiers, and playlist advancing tests
    ├── PlaylistFileCodecTests.swift      # JSON & M3U8 import/export codec tests
    ├── PlaylistReorderTests.swift        # Drag-and-drop playlist reordering tests
    ├── SyncedLyricsParserTests.swift     # LRC line-by-line timestamp parser tests
    ├── URLFilterTests.swift              # Link recognition & streaming domain tests
    ├── YouTubeVideoTests.swift           # Video quality, thermal defaults, state, & settings tests
    └── YTMClientSearchTests.swift        # YouTube Music search endpoint client tests

Playlist File Import & Export

In the Playlists view, use the + button to import an M3U/M3U8 or JSON playlist file. Right-click a playlist and choose Export Playlist to save it as M3U8 or JSON. Import creates a new playlist and references the local file paths in the playlist; it does not copy or move audio files. Relative paths are resolved from the playlist file's folder. Missing local files remain as references and can resolve when they become available. Online entries in imported playlists and non-local entries during export are skipped.

Mooziac's JSON playlist format is versioned and uses UTF-8:

{
  "version": 1,
  "name": "Road Trip",
  "tracks": [
    { "path": "/Users/me/Music/song.m4a", "title": "Song", "artist": "Artist" }
  ]
}

Frequently Asked Questions (FAQ)

Can I watch regular YouTube videos in Mooziac or only listen to music?

You can do both! In addition to the menu bar music player, Mooziac features a dedicated native YouTube video player window. It includes 4K hardware acceleration via VideoToolbox, distraction-free clean playback, automatic SponsorBlock skipping, and trackpad edge volume gestures. You can switch between music and video modes anytime from the menu bar context menu.

Is Mooziac free and open-source?

Yes. Mooziac is 100% free and open-source software distributed under the permissive MIT License. There are no subscriptions, paywalls, or hidden tracking.

Does Mooziac require a YouTube Music Premium account?

No. Mooziac works seamlessly with both free YouTube Music accounts and YouTube Music Premium accounts. Free users get access to the full standard catalog, while Premium users enjoy higher-bitrate audio streams.

How is Mooziac different from the official YouTube Music web or desktop apps?

Official and third-party desktop wrappers are built on Electron or Chromium, often consuming 500 MB to 1.2 GB of RAM and impacting laptop battery life. Mooziac is engineered in pure native Swift and AppKit with zero third-party runtime dependencies, consuming minimal system resources while running directly in the macOS menu bar.

How does the MacBook trackpad volume gesture work?

Mooziac captures multi-touch events along the rightmost 1mm border of your MacBook trackpad. Gliding your finger along that outer edge smoothly adjusts system volume while triggering physical tactile clicks through the Mac's built-in Taptic Engine. Intelligent palm rejection prevents accidental triggers during typing.

Does Mooziac collect any personal data or listening history?

None. Mooziac features a zero-telemetry architecture: no analytics beacons, no tracking SDKs, and no crash reporters. Your listening history, playlists, and liked songs are saved solely in a local SQLite database on your Mac, and credentials remain sandboxed in Apple's official WKWebsiteDataStore.

How do I install or update Mooziac using Homebrew?

Install via the official tap with one command:

brew install shirkeharsh/tap/mooziac

To upgrade in the future, run:

brew upgrade --cask mooziac

Can I play local audio files (FLAC, MP3, WAV) offline?

Yes. Mooziac features a dual audio engine: alongside YouTube Music streaming, it includes a native AVFoundation offline player supporting FLAC, ALAC, WAV, MP3, AAC, and M4A, complete with album artwork and integrated offline caching.

Support & Community

If you find Mooziac useful, please consider starring the repository — it helps more Mac users discover native, lightweight open-source software!

Found a bug? Open an issue
Have a feature idea? Submit a feature request
Official Website: mooziac.pages.dev

License & Disclaimer

Disclaimer: YouTube Music is a trademark of Google LLC. Mooziac is an independent open-source project and is not affiliated with, authorized, or endorsed by Google LLC.