yonlu
31ada14111
They do not merely lag it, they contradict it, which is worse than absent: the only way to find out one is wrong is to trust it. docs/dev/roadmap.md, 1648 lines. Its "Current State" describes an app with basic playback, a track list and an album grid. Phases 1, 2, 3 and 5 have shipped entire -- playlists, shuffle and repeat, shortcuts, virtualised lists, search, custom columns, smart playlists, the MusicBrainz client, autotag. Its Decision Log records "Testing: Deferred" against 836 Vitest tests, a Playwright suite on two engines and race-detector passes in three build configurations. .pi/journal.md, "what happened and what's next", frozen at plan 005 and still saying everything from phase 1 onward is uncommitted. That is the tracker's job now, and a work log that is wrong about what is committed is a hazard rather than a stale file. docs/dev/overview.md, a shallower and partly incorrect CLAUDE.md architecture section. README pointed at it and points at CLAUDE.md now. docs/dev/config-suggestions.md, eight suggestions of which one survived -- the rest were overtaken by rewrites: applyDefaults exists, scan concurrency is configurable with SSD/HDD detection, and httphandler.go and the WriteHeader-after-render bug it described are gone entirely. Nothing is lost: the genuinely unbuilt work was filed first, as #94 device sync, #95 layout customisation, #96 AcoustID and #97 the config setters that take no lock. Refs #98
114 lines
4.3 KiB
Markdown
114 lines
4.3 KiB
Markdown
# YellowJacket
|
|
|
|
*Music how it was meant to bee.*
|
|
|
|
YellowJacket is a fast, cross-platform desktop music player for your local
|
|
collection. It plays your files, keeps your library tidy, and helps you discover
|
|
and organize your music — all in a clean, responsive interface. No accounts, no
|
|
streaming, no telemetry: just your music on your machine.
|
|
|
|
Runs on **Linux**, **macOS**, and **Windows**.
|
|
|
|
## Features
|
|
|
|
### Play your music
|
|
- Plays **MP3, FLAC, OGG Vorbis, and WAV**
|
|
- Play, pause, seek, and volume control with a mute toggle
|
|
- Gapless, glitch-free seeking backed by a read-ahead buffer
|
|
- A queue you can add to, reorder, and shuffle, with play-next support
|
|
- Shuffle and repeat (off / all / one)
|
|
- Picks up right where you left off — remembers your track, position, and volume between sessions
|
|
- Media-key and MPRIS support on Linux, so your desktop's playback controls just work
|
|
|
|
### Keep your library organized
|
|
- Point it at your music folders and it scans them automatically
|
|
- Reads tags and embedded cover art, and de-duplicates artwork so it isn't stored twice
|
|
- Incremental sync — only new or changed files get reprocessed, and deleted files are cleaned up
|
|
- Browse by **album**, **artist**, or **genre**, or search across everything
|
|
- Mark favorites and see what you've been listening to with play history
|
|
- Edit track tags directly when something's off
|
|
|
|
### Playlists
|
|
- Create playlists, drag tracks in, and reorder them
|
|
- **Smart playlists** that build themselves from rules (by genre, rating, play count, and more)
|
|
- Pin a default playlist and spot duplicate tracks at a glance
|
|
|
|
### Discover and clean up (powered by MusicBrainz)
|
|
- **Explore** — browse artists, releases, and genres from the MusicBrainz catalog, not just what's already in your library
|
|
- **Auto-tag** — match your files against MusicBrainz to fill in correct artist, album, and track metadata, with a review step before anything is written
|
|
- **Lyrics search** — find a track by a line you remember
|
|
|
|
## Install
|
|
|
|
Download the latest build for your platform from the
|
|
[releases page](https://git.ljones.me/yonlu/yellowjacket/releases).
|
|
|
|
| Platform | Download |
|
|
|----------|----------|
|
|
| Linux | `yellowjacket-linux-amd64` |
|
|
| macOS | `yellowjacket-darwin-universal.app.zip` (Apple Silicon + Intel) |
|
|
| Windows | `yellowjacket-windows-amd64.exe` |
|
|
|
|
Prefer to build it yourself? See [Building from source](#building-from-source).
|
|
|
|
## Getting started
|
|
|
|
1. Launch YellowJacket.
|
|
2. Open **Settings** and add the folder(s) where your music lives.
|
|
3. Let the initial scan finish — you'll see progress as it works.
|
|
4. Browse by album, artist, or genre, queue something up, and press play.
|
|
|
|
Your library and settings are stored locally:
|
|
|
|
| | Linux / macOS | Windows |
|
|
|---|---|---|
|
|
| Config | `~/.config/yellowjacket/` | `%LOCALAPPDATA%\yellowjacket\config` |
|
|
| Library data | `~/.local/share/yellowjacket/` | `%LOCALAPPDATA%\yellowjacket\data` |
|
|
|
|
## Building from source
|
|
|
|
YellowJacket is built with [Go](https://go.dev/) and a
|
|
[Lit](https://lit.dev/)/TypeScript frontend, bridged by the
|
|
[Wails](https://wails.io/) framework.
|
|
|
|
**Prerequisites**
|
|
|
|
| Tool | Version |
|
|
|------|---------|
|
|
| Go | 1.25+ |
|
|
| Node.js | 22+ |
|
|
| pnpm | 10+ |
|
|
| Wails CLI | v3 — vendored, no install needed (`go tool wails3`) |
|
|
|
|
The Wails v3 CLI resolves from the `tool` block in `go.mod`, so there is nothing
|
|
to install globally; `make setup` fetches it with the rest of the tooling.
|
|
|
|
On Linux, install the system libraries Wails needs. v3 builds against GTK4 +
|
|
WebKitGTK 6.0 by default:
|
|
|
|
```bash
|
|
sudo apt-get install libasound2-dev libgtk-4-dev libwebkitgtk-6.0-dev # Debian/Ubuntu
|
|
sudo pacman -S alsa-lib gtk4 webkitgtk-6.0 # Arch
|
|
```
|
|
|
|
A machine without `webkitgtk-6.0` can still build with `-tags gtk3` against the
|
|
older WebKit2GTK 4.1 stack, but that is an escape hatch, not what CI or a
|
|
release builds.
|
|
|
|
macOS and Windows need no extra system packages. Run `go tool wails3 doctor` to
|
|
check your environment.
|
|
|
|
**Build**
|
|
|
|
```bash
|
|
make setup # install tooling and git hooks
|
|
make dev # run with hot-reload
|
|
make build-prod # produce a release binary
|
|
```
|
|
|
|
More detail for contributors lives in [`CLAUDE.md`](./CLAUDE.md) — the
|
|
architecture, the conventions and the reasons behind them. What is
|
|
being worked on is [the issue
|
|
tracker](https://git.ljones.me/yonlu/yellowjacket/issues); #73 is the
|
|
roadmap.
|