docs: split the README into a landing page and CONTRIBUTING
The README was two documents in one, and neither reader was served by the other's half. It opened on a feature list, then spent its second half on Go versions, WebKitGTK packages and `make` targets — while its install table named a `darwin-universal.app.zip` and a `windows-amd64.exe` that nothing has ever produced, and its header claimed Windows and never mentioned Android, which is the one platform with a published, self-updating channel. So this is a correctness pass as much as a friendliness one. The README now answers a user's questions only: what the app is, three screenshots from the seeded fixture library so anyone can retake them, the four formats, one install section per channel that names what is actually published, first run, where the data lives, and pointers out. The version-restart note is linked to the two documents that own it rather than copied, because a copy is a second thing to keep true. CONTRIBUTING.md takes the technical half: prerequisites, the system libraries, the build and codegen commands, which verification tier a change demands, the tracker workflow, the commit grammar and the style rules. CLAUDE.md is unchanged apart from one paragraph naming the split — it was already the deep reference both of the others point at, and stays the only one of the three that explains why a shape is what it is. Closes #50
This commit is contained in:
@@ -2,112 +2,139 @@
|
||||
|
||||
*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.
|
||||
YellowJacket plays the music you already own. Point it at your folders and it
|
||||
scans them, reads the tags and the cover art, and gives you a library you can
|
||||
browse, search, queue and tidy up — on your own machine, with no account, no
|
||||
streaming service and no telemetry.
|
||||
|
||||
Runs on **Linux**, **macOS**, and **Windows**.
|
||||
It plays **MP3**, **FLAC**, **OGG Vorbis** and **WAV**, on **Linux** and
|
||||
**Android**, and builds from source on **macOS**.
|
||||
|
||||
## 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
|
||||
## What it does
|
||||
|
||||
### 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
|
||||
**Plays your files.** Play, pause, seek and volume with a mute toggle; a
|
||||
read-ahead buffer so seeking is instant rather than gappy; a queue you can add
|
||||
to, reorder and shuffle, with play-next; shuffle and repeat (off / all / one).
|
||||
It remembers the track, the position and the queue between sessions, and it
|
||||
answers your desktop's media keys — MPRIS on Linux, a media notification and
|
||||
lock-screen controls on Android.
|
||||
|
||||
### 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
|
||||
**Keeps the library tidy.** It scans the folders you give it and rescans only
|
||||
what changed, so a big library costs its full scan once. It de-duplicates
|
||||
embedded cover art rather than storing the same image a hundred times, notices
|
||||
files that have gone away, and spots duplicate tracks. Browse by album, artist
|
||||
or genre, search across everything, mark favourites, and see what you have been
|
||||
playing.
|
||||
|
||||
### 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
|
||||
**Playlists, and playlists that write themselves.** Drag tracks in and reorder
|
||||
them, or describe what you want — genre, play count, how long since you played
|
||||
it — and let a smart playlist keep itself up to date.
|
||||
|
||||
**Explore and auto-tag, from the MusicBrainz catalog.** Explore browses artists,
|
||||
releases and genres from the catalog rather than only from what you own, so an
|
||||
album page can tell you that you have nine of its twelve tracks. Auto-tag
|
||||
matches your files against MusicBrainz and fills in the metadata that is
|
||||
missing, with a review step before anything is written to disk. Lyrics search
|
||||
finds a track from a line you remember.
|
||||
|
||||
Explore needs its catalog, which is a one-off ~0.6 GB download from
|
||||
**Settings → Search Index**. It asks first on a metered connection, and
|
||||
everything else in the app works without it.
|
||||
|
||||
## Install
|
||||
|
||||
Download the latest build for your platform from the
|
||||
Every download comes 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` |
|
||||
### Linux
|
||||
|
||||
Prefer to build it yourself? See [Building from source](#building-from-source).
|
||||
Download `yellowjacket-<version>-linux-amd64.tar.gz` from the latest release and
|
||||
unpack it. It holds the binary, a `.desktop` entry and an icon.
|
||||
|
||||
## Getting started
|
||||
On **Arch**, install it from the package registry instead and get updates with
|
||||
the rest of your system — the one-time key import and `pacman.conf` block are in
|
||||
[`packaging/arch/README.md`](packaging/arch/README.md):
|
||||
|
||||
```bash
|
||||
sudo pacman -Sy yellowjacket
|
||||
```
|
||||
|
||||
### Android
|
||||
|
||||
Install the APK from the release page, or from the URL below, which always
|
||||
points at the newest build:
|
||||
|
||||
```
|
||||
https://git.ljones.me/api/packages/yonlu/generic/yellowjacket-android/latest/yellowjacket.apk
|
||||
```
|
||||
|
||||
That URL needs no credentials, so [Obtainium](https://obtainium.imranr.dev/) can
|
||||
poll it directly and keep the app up to date. The build is `arm64-v8a` only, and
|
||||
[`docs/android-release.md`](docs/android-release.md) says why.
|
||||
|
||||
### macOS
|
||||
|
||||
Homebrew builds it from source on your own Mac — there is no prebuilt `.app`,
|
||||
because a signed macOS bundle needs a macOS machine to produce it and the
|
||||
release runner is a Linux container.
|
||||
|
||||
```bash
|
||||
brew install shadow-puppet/yellowjacket/yellowjacket
|
||||
```
|
||||
|
||||
See [`packaging/homebrew/README.md`](packaging/homebrew/README.md).
|
||||
|
||||
### Windows
|
||||
|
||||
Not published. It cross-compiles cleanly, but no Windows build of this app has
|
||||
ever been *run*, and nothing here can exercise one — so shipping it would be a
|
||||
promise that cannot be kept. You can still build it yourself: see
|
||||
[`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||
|
||||
### Coming from a 1.x install?
|
||||
|
||||
Versions restarted at **0.0.1** when releases became automatic, which every
|
||||
package manager reads as a downgrade. It costs one reinstall, once — the details
|
||||
are with each channel: [Homebrew](packaging/homebrew/README.md#upgrading-from-1x-needs-a-reinstall-once),
|
||||
[Android](docs/android-release.md#the-1x-installs-cannot-be-upgraded-to-00x).
|
||||
|
||||
## First run
|
||||
|
||||
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.
|
||||
2. Add the folder your music lives in — the first-run wizard asks, and
|
||||
**Settings → Libraries** is where you add more later.
|
||||
3. Watch the scan finish. It reports progress, and you can browse while it runs.
|
||||
4. Queue something and press play.
|
||||
|
||||
Your library and settings are stored locally:
|
||||
Your library and settings stay on your machine:
|
||||
|
||||
| | Linux / macOS | Windows |
|
||||
|---|---|---|
|
||||
| Config | `~/.config/yellowjacket/` | `%LOCALAPPDATA%\yellowjacket\config` |
|
||||
| Library data | `~/.local/share/yellowjacket/` | `%LOCALAPPDATA%\yellowjacket\data` |
|
||||
|
||||
## Building from source
|
||||
Setting `YJ_HOME` moves both, which is how you keep a second library separate.
|
||||
|
||||
YellowJacket is built with [Go](https://go.dev/) and a
|
||||
[Lit](https://lit.dev/)/TypeScript frontend, bridged by the
|
||||
[Wails](https://wails.io/) framework.
|
||||
## More screenshots
|
||||
|
||||
**Prerequisites**
|
||||
An album page knows what you own, and says so:
|
||||
|
||||
| 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.
|
||||
The home page suggests somewhere to start rather than opening on a wall of
|
||||
everything:
|
||||
|
||||
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
|
||||
```
|
||||
## Contributing, and the rest of the documentation
|
||||
|
||||
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.
|
||||
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — build it from source, run the tests,
|
||||
and how a change gets in.
|
||||
- [`CLAUDE.md`](CLAUDE.md) — the deep reference: the architecture and the reasons
|
||||
behind the shape of it.
|
||||
- [The issue tracker](https://git.ljones.me/yonlu/yellowjacket/issues) is what
|
||||
is wanted and what is being worked on; **#73** is the roadmap.
|
||||
- [Releases](https://git.ljones.me/yonlu/yellowjacket/releases) double as the
|
||||
changelog — every one is generated from the commits it contains.
|
||||
|
||||
Reference in New Issue
Block a user