yonlu
7f0c6d362a
Migration 15: add in_library and is_similar INTEGER columns to
explore_index. Backfills in_library from existing library MBIDs.
Search index FTS5 query now includes personalization in scoring:
ORDER BY bm25(...) - (ln(pop+1) * 1.5)
- (in_library * 3.0) - (is_similar * 1.5)
For equal text+popularity scores:
- Library artist beats unrelated by 3.0 points
- Similar artist beats unrelated by 1.5 points
- Library > Similar > Neither
Tier 3 (library) entries get in_library=1 via markInLibrary.
Tier 4 (similar) entries get is_similar=1 via markSimilar.
MB result reranking (boostWithIndexPopularity) adds a 10M
popularity bonus for library artists, ensuring they always
rank above non-library artists with equal text relevance.
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/.