Ultra-Advanced Native macOS Video Player
Powered by libVLC. Built with Swift + SwiftUI. No Xcode.
videOS is a premium macOS video player that bridges directly to libVLC's C API for maximum format support and performance. No VLCKit, no Objective-C wrappers — pure Swift-to-C interop with Unmanaged pointer callbacks dispatched to @MainActor.
The UI is built entirely in SwiftUI with a glass morphism design language: translucent materials, blur effects, gradient accents, and spring-based animations. The app is developed, built, and packaged entirely from the CLI — no Xcode project files.
- Play any video/audio format supported by libVLC (300+ codecs)
- Network stream playback (HTTP, HTTPS, RTSP, HLS, RTP, UDP, MMS)
- Variable speed playback (0.25x – 4.0x)
- Audio/subtitle track selection with delay adjustment
- External subtitle loading (.srt, .ass, .ssa, .vtt) with auto-detection of sidecar files
- Resume playback from last position (auto-saved every 5s)
- Playlist auto-advance with next/previous navigation
- Hardware-accelerated decoding via VideoToolbox
- Scan folders for media files with recursive discovery
- Search, sort (name, date, last played, duration), and filter
- List and grid view modes with hover effects
- Play count tracking and recently played history
- Drag-and-drop file/folder import
- "Show in Finder" and "Copy Path" context actions
- Create, rename (inline), and delete playlists
- Add/remove/reorder items with drag and drop
- "Play All" for instant playlist playback
- Persistent storage across sessions
- Named bookmarks at any timestamp in a video
- Jump to bookmark with one click
- Filtered by currently playing media
- URL validation with protocol detection
- Protocol hint chips (HTTP, RTSP, HLS, RTP)
- Recent streams history with relative timestamps
- Copy URL and quick-play actions
- Glass morphism design (
.ultraThinMaterial, blur, gradients) - Auto-hiding controls with configurable delay
- Seek bar with hover preview, buffered range, and glow thumb
- Volume slider with 4-level icons, expand-on-hover
- Branded empty state with action pills and keyboard shortcut hints
- Error banner with dismiss action
- Media info overlay (title, codec, resolution, duration, file size)
- Native macOS sidebar with sections, badges, and recently played
- Full Settings window (General, Playback, Library, Shortcuts tabs)
| Key | Action |
|---|---|
Space |
Play / Pause |
→ / ← |
Seek ±10s |
Shift+→ / Shift+← |
Seek ±30s |
Option+→ / Option+← |
Seek ±5s |
↑ / ↓ |
Volume ±5% |
M |
Toggle mute |
Cmd+F |
Toggle fullscreen |
[ / ] |
Speed down / up |
= |
Reset speed |
Cmd+N / Cmd+P |
Next / Previous track |
Cmd+O |
Open file |
Cmd+Shift+S |
Toggle sidebar |
Cmd+, |
Settings |
┌─────────────────────────────────────────────────────────┐
│ SwiftUI Views (15) │
│ Sidebar │ PlayerView │ ControlBar │ Library │ Playlists │
├─────────────────────────────────────────────────────────┤
│ ViewModels (3) — @MainActor │
│ PlayerVM │ LibraryVM │ PlaylistVM │
├─────────────────────────────────────────────────────────┤
│ Services (8) — ObservableObject │
│ PlayerEngine │ Library │ Playlists │ Bookmarks │ ... │
├─────────────────────────────────────────────────────────┤
│ CLibVLC Module — C bridging (80+ functions) │
│ shim.h │ module.modulemap │ -lvlc │
├─────────────────────────────────────────────────────────┤
│ libvlc.dylib (bundled from VLC.app) │
└─────────────────────────────────────────────────────────┘
videOS bridges to libVLC's raw C API through a custom SPM system library target:
CLibVLC/include/shim.h— declares 80+ VLC functions, opaque types, and event enumsCLibVLC/module.modulemap— makes the C headers importable as a Swift modulePlayerEngine.swift— wraps the C API withUnmanaged<Self>pointer casting for event callbacks- VLC events fire on background threads → dispatched to
@MainActorviaDispatchQueue.main - NSView passed to VLC via
libvlc_media_player_set_nsobject()for zero-copy rendering
videOS/
├── Package.swift # SPM: macOS 13+, CLibVLC + app target
├── Makefile # build, run, package, test, clean
├── CLAUDE.md # Architecture guide & roadmap
├── scripts/
│ ├── install-deps.sh # VLC dependency check/install
│ ├── build.sh # Debug/release builds
│ ├── run.sh # Launch with dylib paths
│ ├── package.sh # .app bundle creation
│ └── create-dmg.sh # DMG + codesign + notarize + staple
├── Sources/
│ ├── CLibVLC/ # C bridging layer
│ │ ├── include/shim.h # libVLC type/function declarations
│ │ └── module.modulemap # Swift module mapping
│ └── videOS/
│ ├── App.swift # @main + AppState (owns all services)
│ ├── AppDelegate.swift # NSApplicationDelegate
│ ├── Models/ # 7 Codable data models
│ ├── Services/ # 8 business logic services
│ ├── ViewModels/ # 3 @MainActor view models
│ ├── Views/ # 10 SwiftUI views
│ ├── Views/Components/ # 5 reusable UI components
│ └── Utilities/ # Constants, formatters, helpers
├── Tests/ # 14 unit tests
└── Resources/
├── Info.plist # App bundle config
├── videOS.entitlements # Security entitlements
├── logo.svg # App icon (SVG source)
└── icon.icns # App icon (macOS ICNS)
# Install VLC (provides libvlc.dylib + plugins)
brew install --cask vlcmake deps # Verify VLC is installed
make build # Debug build
make release # Optimized release build
make run # Build and launch
make test # Run unit tests
make package # Create videOS.app bundle
make clean # Clean build artifactsbash scripts/create-dmg.shThis script:
- Builds release binary
- Creates
.appbundle with bundled libVLC + 337 plugins - Fixes rpaths for self-contained distribution
- Codesigns everything with Developer ID (hardened runtime)
- Creates compressed DMG
- Submits to Apple notary service
- Staples notarization ticket
All data is stored in ~/Library/Application Support/videOS/:
| File | Content |
|---|---|
library.json |
Scanned media items |
playlists.json |
User playlists |
bookmarks.json |
Named bookmarks |
playback-state.json |
Resume positions |
streams.json |
Recent stream URLs |
- Auto-generate subtitles via Whisper
- Real-time subtitle translation
- Subtitle search (find when a word was said)
- Smart timing synchronization
- Trim and export video clips
- GIF export with subtitle burn-in
- Batch export bookmarked segments
- Auto-fetch movie/TV metadata from TMDb
- Poster art and backdrop integration
- Smart file rename from metadata
- A-B loop
- Picture-in-Picture
- Audio normalization
- Watch party (LAN synchronized playback)
| Layer | Technology |
|---|---|
| Language | Swift 5.9 |
| UI | SwiftUI (macOS 13+) |
| Playback | libVLC 3.x (C API) |
| Reactivity | Combine |
| Concurrency | @MainActor + Task |
| Persistence | Codable + JSON |
| Preferences | UserDefaults / @AppStorage |
| Build | Swift Package Manager + Make |
| Packaging | Shell scripts + hdiutil |
| Signing | codesign + Developer ID |
| Notarization | xcrun notarytool |
| Dependencies | Zero external Swift packages |
Built with Swift + SwiftUI by WorthDoing AI
Signed & Notarized for macOS. Zero third-party dependencies.