logan
3dc302386c
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.
130 lines
5.0 KiB
Markdown
130 lines
5.0 KiB
Markdown
# YellowJacket
|
|
|
|
[](https://github.com/onion-4-dinner/yellowjacket/actions/workflows/ci.yml)
|
|
[](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).
|