yonlu
4e52f6b494
Moved icons to sit outside the toggle track on either side. Both icons are always fully visible. The active side's icon gets the accent color, the inactive side dims to secondary. Track is a minimal 36×20px pill with a sliding thumb. - Off: globe bright, thumb left, hard-drive dimmed - On: globe dimmed, thumb right + yellow track, hard-drive accent
YellowJacket
Music how it was meant to bee.
YellowJacket is a cross-platform desktop music player built with Go and web technologies. It focuses on local music library management with a clean, responsive interface.
Install
Grab the latest release for your platform:
| Platform | Binary |
|---|---|
| Linux | yellowjacket-linux-amd64 |
| macOS | yellowjacket-darwin-universal.app.zip (Apple Silicon + Intel) |
| Windows | yellowjacket-windows-amd64.exe |
Features
Playback
- Play, pause, seek, and volume control with mute toggle
- Support for MP3, FLAC, OGG Vorbis, and WAV
- Queue management with add, remove, reorder, and play-next
- Shuffle mode (Fisher-Yates) and repeat modes (off, all, one)
- Session persistence -- resumes volume, track, and seek position on restart
Library
- Concurrent library scanning with automatic metadata extraction
- ID3v2, Vorbis Comments, and other tag format support
- Embedded cover art extraction with content-hash deduplication
- Incremental sync -- only processes new or changed files
- Orphan cleanup for deleted files
Interface
- Album cover grid view and track list view
- Now playing display with cover art
- Resizable sidebar navigation
- Slide-out queue panel
- Context menus for tracks and albums (play, add to queue, play next)
- Settings page for library directory configuration
Architecture
YellowJacket uses the Wails v2 framework to bridge a Go backend with a TypeScript/Lit frontend running in a native webview.
- Go backend -- audio decoding and playback (beep), library scanning, SQLite database, cover art serving, TOML configuration
- TypeScript frontend -- Lit web components, singleton stores with reactive controllers, Web Awesome UI components
- Communication -- bidirectional event system via Wails runtime; backend is the source of truth
- Database -- SQLite (pure-Go driver) with type-safe queries generated by sqlc; MusicBrainz-style data model (artists, artist credits, recordings, release groups)
- Config page -- HTMX-based, loads HTML fragments rendered by Go templ templates
Development
Prerequisites
| Tool | Version |
|---|---|
| Go | 1.25+ |
| Node.js | 22+ |
| pnpm | 10+ |
| Wails CLI | v2 (go install github.com/wailsapp/wails/v2/cmd/wails@latest) |
Linux system dependencies:
sudo apt-get install libasound2-dev libgtk-3-dev libwebkit2gtk-4.1-dev
On macOS and Windows, no additional system dependencies are needed. Run wails doctor to verify your environment.
Build & Run
make setup # Install git hooks (lefthook)
make dev # Development with hot-reload
make build-dev # Debug build
make build-prod # Production build (obfuscated + UPX compressed)
make generate # Run code generators (sqlc, templ)
Testing
make test # All tests (race detector, no cache, 2min timeout)
# Run tests manually (build tag required):
go test -tags webkit2_41 ./backend/player/ # Single package
go test -tags webkit2_41 -run TestFunctionName ./backend/player/ # Single test
go test -tags webkit2_41 -v -run TestFunctionName ./backend/player/ # Verbose
Linting
make lint # golangci-lint (v2 config, strict rules)
Data Locations
| Linux | macOS | Windows | |
|---|---|---|---|
| Config | ~/.config/yellowjacket/ |
~/.config/yellowjacket/ |
%LOCALAPPDATA%\yellowjacket\config |
| Data/DB | ~/.local/share/yellowjacket/ |
~/.local/share/yellowjacket/ |
%LOCALAPPDATA%\yellowjacket\data |
Project Structure
backend/ Go backend
player/ Audio playback (beep)
queue/ Queue management, shuffle, repeat
library/ Library scanning, metadata extraction, cover art
metadata/ Audio decoding and tag extraction
database/ SQLite connection, sqlc-generated queries
config/ TOML config, HTTP handler for settings page
events/ Event name constants (mirrored in frontend)
models/ Shared data types (Album, Track, Artist)
system/ OS-specific paths
frontend/src/ TypeScript/Lit frontend
components/ UI components (player, sidebar, track list, cover grid, queue)
store/ Singleton stores and reactive controllers
pages/ Config page (HTMX entry point)
internal/dev/ Build-tag dev/prod detection
test_data/ Audio test fixtures
Further development documentation is available in docs/dev/.