From 3dc302386cd3264145a5ab20a7ce405f6930b7a8 Mon Sep 17 00:00:00 2001 From: Logan Jones Date: Sat, 14 Feb 2026 01:19:30 -0600 Subject: [PATCH] docs: rewrite README with features, architecture, and dev setup (#43) Replace the placeholder README with comprehensive documentation covering install instructions, feature list, architecture overview, development prerequisites, build/test/lint commands, data locations, and project structure. Add CI and Release badges. --- README.md | 126 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 110 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index ba3955a..35143ff 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,129 @@ # YellowJacket -How music was meant to bee. +[![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 -You can grab the latest release [here](https://github.com/LJ-Software/yellowjacket/releases/latest) +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 -TODO: add feature list and screenshots here +**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 -Development documentation can be found [here](./docs/dev/overview.md). - ### Prerequisites -1. First, you will need Go installed. +| Tool | Version | +|------|---------| +| Go | 1.25+ | +| Node.js | 22+ | +| pnpm | 10+ | +| Wails CLI | v2 (`go install github.com/wailsapp/wails/v2/cmd/wails@latest`) | -2. Then, you will need the `wails` cli tool. +**Linux system dependencies:** +```bash +sudo apt-get install libasound2-dev libgtk-3-dev libwebkit2gtk-4.1-dev +``` - Install it with +On macOS and Windows, no additional system dependencies are needed. Run `wails doctor` to verify your environment. - ```shell - go install github.com/wailsapp/wails/v2/cmd/wails@latest - ``` +### Build & Run -3. After installing the Wails CLI you may need some build dependencies. - View the missing Wails dependencies by running `wails doctor`. - Using your system's package manager, install the missing dependencies. +```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) +``` -### Dev Server +### Testing -To run the Wails hot-reloading dev server, run `make dev` in the root of the project. +```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).