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.
This commit is contained in:
@@ -1,35 +1,129 @@
|
||||
# YellowJacket
|
||||
|
||||
How music was meant to bee.
|
||||
[](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
|
||||
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user