# YellowJacket

[![CI](https://github.com/onion-4-dinner/yellowjacket/actions/workflows/ci.yml/badge.svg)](https://github.com/onion-4-dinner/yellowjacket/actions/workflows/ci.yml)
[![Release](https://github.com/onion-4-dinner/yellowjacket/actions/workflows/release.yml/badge.svg)](https://github.com/onion-4-dinner/yellowjacket/actions/workflows/release.yml)

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](https://github.com/onion-4-dinner/yellowjacket/releases/latest)**

| 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](https://wails.io/) framework to bridge a Go backend with a TypeScript/[Lit](https://lit.dev/) frontend running in a native webview.

- **Go backend** -- audio decoding and playback ([beep](https://github.com/gopxl/beep)), library scanning, SQLite database, cover art serving, TOML configuration
- **TypeScript frontend** -- Lit web components, singleton stores with reactive controllers, [Web Awesome](https://www.webawesome.com/) 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](https://sqlc.dev/); MusicBrainz-style data model (artists, artist credits, recordings, release groups)
- **Config page** -- HTMX-based, loads HTML fragments rendered by Go [templ](https://templ.guide/) 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:**
```bash
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

```bash
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

```bash
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

```bash
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/`](./docs/dev/overview.md).