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:

Download Latest Release

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/.