San is a native, ultra-lightweight, 100% offline macOS local music player built with Swift and SwiftUI.
Warning
Development Status: San is currently under active development and may be unstable. Features, behavior, and build artifacts are subject to change.
San (Japanese for Three / Harmony) provides a clean, modern interface for listening to local audio files without online accounts, telemetry, or external internet dependencies.
- 10 Selectable Spectrum Styles: Choose how live audio waveform spectrum bars render across the player stage, bottom bar, and status bar popover:
- Vertical Bars: Classic vertical spectrum bars with smooth level height gradients.
- Continuous Waveform: Connected frequency curve sine waveform line.
- Pulsing Dots Matrix: Illuminated dot matrix level meter grid.
- Audio Particles: Floating glowing particles bouncing to the rhythm.
- Minimal Pill Meters: Dual horizontal stereo level meters.
- Mirrored Dual Spectrum: Symmetrical top and bottom dual frequency spectrum bars.
- Cyberpunk Peak Equalizer: Segmented LED equalizer blocks with peak hold indicators.
- Circular Orbit Ring: Rotating circular ring with radial level bars.
- Fluid Liquid Wave: Organic fluid liquid wave filling with beat density.
- Strobe Pulse Meters: Concentric pulsating beat rings.
- Interactive Show Lyrics Auto-Scan: Clicking the Lyrics button or pressing
Cmd + Lexecutes an instant local search across files and metadata. - FLAC Vorbis Comment Extraction: Reads embedded lyrics from FLAC Vorbis comments (
LYRICS,UNSYNCEDLYRICS,SYNCEDLYRICS) and MP3 ID3 frames (USLT). - Raw Stream Binary Scanner: Fallback binary reader to parse embedded metadata tags directly from file streams when OS audio APIs omit them.
- Automatic LRC Synchronization: Automatically parses timestamp headers (
[MM:SS.xx]) for real-time synchronized line scrolling. - Sidecar File Finder: Scans local directories for
.lrcand.txtfiles matching track title or artist combinations.
- Automatic Library Integration: Importing or opening a folder automatically merges all unique tracks into the central library, populating the Artists Page and Albums Page instantly.
- Smart Folder Hierarchy Metadata Parsing:
- Album Auto-Detection: Fallback to parent directory name if ID3 album tag is missing.
- Artist Auto-Detection: Fallback to grandparent directory name or
"Artist - Song Title.mp3"filename format if ID3 artist tag is missing.
- Dedicated Artists Page: Automatically groups tracks by artist with artist profile banners, total album counts, and song totals.
- Auto-Detected Albums: Inspecting an artist page auto-detects and categorizes all albums belonging to that specific artist.
- Play Artist Collection: One-click action to play all tracks by an artist.
- 7 Selectable Motion Options: Custom artwork presentations in Settings (Fluid Spring, Vinyl Record Spin, Wave Spectrum Ring, Floating Glass Card, Ambient Aura Glow, Gentle Ease, Snappy Fast).
- Crossfade Transitions: Configurable overlap transition durations (Off, 1s, 2s, 3s, 5s) between tracks.
- Pre-Buffered Gapless Playback: Pre-loads next track buffers for zero-gap playback transitions.
- 5-Band Parametric Equalizer: Custom audio processing with presets (Flat, Bass Boost, Treble Boost, Vocal, Electronic).
- Play Count & History Tracking: Automatically increments track play counts and tracks last-played dates.
- Variable Playback Speed: Control speed from 0.5x to 2.0x.
- Stereo Balance Control: Adjust left/right audio channel balance.
- Smart Playlists: Auto-generated dynamic views for Recently Added, Most Played (Top 25), and Recently Played tracks.
- Sortable Column Headers: Clickable column headers to sort library by Title, Artist, Album, Genre, Play Count, or Duration.
- Genre & Release Year: Metadata parsing and display across track rows and the Now Playing card.
- Remove Tracks: Context menu option to remove tracks from library and playlists.
- Empty State Views: Clear guidance and drag-and-drop landing states when collections are empty.
- Scroll to Playing: Instant jump button to highlight the active track in large libraries.
- Resizable Sidebar: Drag-to-resize sidebar width (160pt to 280pt) with persisted dimensions.
- Dynamic Album Artwork Color Extraction: Samples dominant vibrant accent colors from playing album artwork in real time.
- Appearance Modes: Dark Mode, Pitch Black Mode (OLED), and Light Mode.
- Window State Persistence: Automatically restores exact window size and position on relaunch.
- macOS Integration: Menu bar popover HUD, Media key support, Now Playing Control Center integration, and Dock icon progress badge.
- Language: Swift 5.9
- Framework: SwiftUI + AppKit
- Audio Core: AVFoundation (AVAudioPlayer, AVURLAsset, CMAudioFormatDescription)
- Control Center Integration: MediaPlayer (MPRemoteCommandCenter, MPNowPlayingInfoCenter)
./build.shThe build script generates:
- Application binary:
dist/San.app - Installer package:
dist/San.dmg
A project by Hariom Sharnam