yonlu
52632b470c
Three search improvements: 1. MB queries now use AND + wildcard syntax instead of default OR. 'the teenagers' → 'the AND teenagers*'. This eliminates common- word pollution: The Beatles no longer match because they only contain 'the'. The trailing wildcard on the last term preserves type-ahead behavior. Special Lucene characters are escaped. 2. mbSearchLimit increased from 20 to 50. Gives the ranking pipeline more raw material — with AND filtering there's less noise, and our name-match tiers + popularity reranking handle the rest. Final display is still capped at 15. 3. Frontend library cache now uses fuzzy matching with Levenshtein edit distance (max 2) as fallback. Exact substring match is tried first, then per-word fuzzy matching for words >= 4 chars. 'florene and the machine' matches 'Florence and the Machine'. Pure JS, no API cost — runs against the in-memory library arrays.
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/.