yonlu
920a96d9b1
Two changes: 1. rerankReleaseGroups now uses blended scoring (text relevance + popularity) like artists, instead of pure popularity. This prevents obscure albums with high listen counts from outranking direct MB search matches. 2. boostNameMatches now uses rgMatchTier() for release groups, which checks artist credit before title. Albums BY the searched artist (tier 0: exact credit match) rank above albums that merely mention the artist in the title (tier 3: title substring). For 'hop along': Painted Shut by Hop Along → tier 0, but Simple Demands: A Hop Along Tribute by Various Artists → tier 3. Within the same tier, blended score breaks ties so more popular albums by the same artist rank first.
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/.