logan
842fe47e9e
An underrun is audible and nothing counted it. When the ring is empty BufferedStreamer.Stream zeroes the caller's buffer and returns ok, so a run of zeros is spliced into the waveform and the step discontinuity at each edge is a click; a series of short ones is static. That is the one candidate in #135 whose audible signature matches the report. `starved` and `starvedSince` already existed, from #122's stall fix, and could not answer this: they are a *stall* detector, reset by every arriving sample, because their job is to end a track whose source has died and a merely slow source must not be cut short. That reset is exactly what made the audible case invisible -- a hundred 20ms underruns a minute never approach the give-up threshold, so they were invisible to the log, to the UI and to every tier. UnderrunStats counts runs, calls and samples for the life of the streamer. Runs is the number that means something audible: one episode is one pop however many callbacks it spans, and the ratio of runs to calls is what separates clicking from dropping out. Three things about the reporting are deliberate. **Counting is in Stream and reporting is not.** Stream runs on the speaker callback's real-time deadline, so a log line there would allocate, format and write on the exact path whose missed deadline is the defect -- measuring by making it worse. The count is two increments under a lock that was already held; the report is on the 1 Hz position ticker, which only runs while playing. **An unchanged count is not logged**, which is emitStatus' rule one package over. A healthy player is silent, so anything in the log is news and the line appears exactly while it is popping. **It is Info rather than Debug.** The default level is Info and a phone has no convenient way to set YJ_LOG_LEVEL, so a debug line here would be a counter nobody on the affected platform could read -- which is the shape of the bug that made #160 necessary. underrunDelta clamps at zero because the counter belongs to the streamer and the streamer is replaced on every track: a baseline carried across that boundary is the previous track's total subtracted from a fresh zero. The baseline is reset at the load as well; a negative count in a log line reads as a broken instrument and would discredit the measurement this exists to make. This is the instrument, not a fix. What it measures is on the issue.
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.
| 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.
Getting started
- Launch YellowJacket.
- Open Settings and add the folder(s) where your music lives.
- Let the initial scan finish — you'll see progress as it works.
- 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 and a Lit/TypeScript frontend, bridged by the Wails 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:
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
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 — the
architecture, the conventions and the reasons behind them. What is
being worked on is the issue
tracker; #73 is the
roadmap.