Repository navigation
Releases
v0.6.2
Fixed
- The gear button opens its settings on a smaller screen. The panel had grown
to 778 px of content, so on a 768-pixel-high screen (or a 1080p one scaled up)
it could not fit, and a popover that cannot fit is never shown at all. Clicking
the gear did nothing. The panel now scrolls, so it shrinks to fit the screen.
On a screen tall enough it looks exactly as before. Reproduced on a 1024×768
broadway display: unmapped before the fix, shown at 673 px after it.
v0.6.1 — open a song from the file manager
Fixed
-
Opening a song from the file manager now plays it. Double-clicking a track
(or Open with Gapless) brought the window up on last session's queue and
never mentioned the song that was clicked. Two halves: the app did not declare
HANDLES_OPEN, so GApplication refused file arguments outright, and the
desktop entry'sExec=gaplesshad no%F, so no file was passed anyway.The clicked song now plays at once, with the songs beside it in its folder
queued after it (that folder only, not everything under it — a song saved to
~would otherwise scan the whole home). A song already in the queue just
plays, without rebuilding it. A playlist or folder opened the same way loads
and plays from the top. Works on a cold start and against a copy already
running.POST /api/openaccepts a song too, with the same meaning. -
A second launch no longer builds a second window and audio engine. It
raises the one that is there.
v0.6.0 — Force tempo
Set a BPM and every track plays at it. A pitch-preserving stretch, so a 128 BPM track at 1.09x is still in the key it was recorded in.
Switch it on under Force tempo behind the gear button, pick a target from 60 to 200, and each track is sped up as far as it needs to reach it. It exists for one complaint — a workout playlist where one slow track is a slow patch in the workout — and every default follows from that.
| Control | Default | What it does |
|---|---|---|
| Target tempo | 140 BPM | The tempo to bring every track to. |
| Most a track may be stretched | 30% | A track that cannot reach the target inside the ceiling goes as far as the ceiling allows rather than further. |
| Never slow a track down | on | A track already at or above the target is left completely alone — verified bit-exact, not merely by length. |
Where a tempo comes from. The file's TBPM tag if it has a believable one; otherwise measured — half a minute decoded from 30 s in, reduced to an onset envelope at 10 ms and autocorrelated. Remembered per track, and the next track is analysed while the current one plays, so the only track ever heard at the wrong speed is the one that was already playing when you switched it on.
A track with no steady tempo is found to have none and left alone, and that finding is written down. "Nothing known yet" and "nothing there" stay two different states all the way out to the API — a player that invented a tempo for a podcast and played it 30% fast would be indefensible.
The measurement is editable, because you can hear when it is wrong. Type over the BPM in the now-playing panel; your number wins and is never quietly re-measured, and clearing it measures again.
GET/POST /api/tempo and four new fields on /api/settings do all of it.
Also fixed — a freeze that predates this release
Changing a playback setting twice while paused could hang the player outright: the window stopped repainting and the control API accepted connections it would never answer, with nothing printed anywhere, because nothing had crashed. A branch being torn down was blocked pushing into a mixer that was not consuming, and the main thread waited on its stream lock forever. Reproduced on v0.5.1 with two crossfade changes.
Verified
verify.sh 8/8 · verify-resume.sh 6/6 · verify-api.sh 81/81 · verify-mpris-modes.sh 4/4 · 69 unit tests.
The stretch check measures pitch as well as length, because naively resampling the audio shortens a render by exactly the same ratio and transposes it up — 440 Hz must still be 440 Hz. A deliberately resampled render was fed to the checker and is caught at 550 Hz.
v0.5.1 — the control API could be killed by regenerating its own key
Pressing Regenerate on the API key restarted the listener on the same port, and Server::drop returned without waiting for the accept thread to exit — so the old socket was still open when the new bind ran. Address already in use, and the control API stayed dead until the app was restarted. Drop now joins the thread.
GET /api/status reports pid, so a caller can act on that process instead of searching by name.
handover.sh no longer uses pgrep: it matches by name across the whole machine, so it escaped a private D-Bus session and a private config directory and SIGTERMed the real player mid-song. The outgoing pid now comes from the API's pid or from the bus, both scoped to the instance being handed over — and it refuses rather than guessing. It also gained an MPRIS fallback, so a player whose API is down can still be swapped without stopping the music (49 ms), and it keeps the replacement's stderr.
Scripts that touch the desktop are gated on the machine being idle via xprintidle: verify-input.sh will not run at all without GAPLESS_INPUT_OK=1 and abandons its run the instant a real keypress arrives; verify-api.sh and verify-mpris-modes.sh wait for a free desk before opening a window. verify.sh and verify-resume.sh touch nothing.
v0.5.0 — share a track: the file and its metadata
Share
A Share button under the song title, beside the star strip — and the same three actions on a right-click of any row in the list.
| Copy file | the audio file itself on the clipboard, and the metadata as text, from the same copy |
| Copy details | just the metadata, as text |
| Save a copy… | the audio file into a folder you choose, with a readable .txt of the details beside it |
One clipboard, several representations — that is the part that makes the button useful rather than decorative. Paste into Telegram, Discord or a file manager and it takes text/uri-list: you get the actual audio file. Paste into a text field and it takes text/plain: you get the metadata. Offering only one of those makes the button work in half the places somebody would press it.
The third payload, x-special/gnome-copied-files, is what GTK and Nautilus-derived file managers look for, and its copy prefix is what distinguishes a copy from a cut — without it, a paste can move your music out of your library.
Save a copy never overwrites. A clashing name gets (2), (3) and so on, and the audio and its metadata take the same suffix so the pair cannot be split up.
The metadata is plain text with aligned labels rather than JSON — a person is meant to read it — and empty fields are left out rather than printed as blank headings, so sharing an untagged file is not a column of empty labels.
POST /api/share — and it shares fully
The clipboard belongs to the running application, so an API caller gets the same clipboard the button would have set, not a lesser version of the feature.
curl -s -X POST -H "Authorization: Bearer $KEY" \
-d '{"index":6,"mode":"clipboard"}' "$BASE/api/share"mode: clipboard for the file and its details · mode: details for the text · dest for a copy on disk · neither for a description of what you would be sharing. An unknown mode is a 400, not a guess.
The first draft of this endpoint left the clipboard out because it was awkward to express over HTTP — which is exactly the reasoning that hollows an API out. The API does everything the window does is an invariant here.
Verification
verify-api.sh 44 → 55 and verify-input.sh 9 → 13, both reading the clipboard back off the X server rather than trusting that the call returned.
cargo test 40/40 · verify.sh 6/6 · verify-resume.sh 4/4 · verify-mpris-modes.sh 4/4 · verify-api.sh 55/55 · verify-input.sh 13/13
v0.4.0 — replace a playing player without a gap in the music
You can now swap the player mid-song
./scripts/handover.shStarts a second copy alongside the one that is playing, hands the track over, and retires the old one. Measured here: replacement up in 0.5 s while the old one kept playing, and a 34 ms swap — an overlap, not a hole.
This was impossible before, and the reason is worth stating: GApplication is single-instance, so launching Gapless while it is running hands the request to the copy already there and exits. Right for a desktop launcher; it also meant the only way to replace the player was to kill it first and stand in silence until the new one came up.
--new-instance |
run a second copy instead of deferring to the first |
--api-port N |
listen elsewhere for this run, since the outgoing copy still owns the configured port. Not saved. |
The order is deliberate: the replacement is pre-rolled paused at the right position so its pipeline is already built, then it plays as the old one pauses, back to back. A listener notices silence, not a brief doubling.
audio_sink in /api/status
The element autoaudiosink actually chose. This exists because of a real failure the same day: after an in-place update the player reported playing: true with the position climbing and no audio stream attached to the sink at all. Two minutes of silence, and nothing the player exposed could tell that apart from working — the pipeline's own state says PLAYING either way.
POST /api/listen {port}
Moves the API at run time, so a handover's replacement takes the configured port once the old copy is gone.
Fixed
A single wrong type in state.json silently reset every setting. One bad field fails the whole parse, and the loader swallowed the error — volume, resume point, API port, all quietly back to defaults and indistinguishable from the file having been deleted. It now names the file and the reason, and leaves it alone.
cargo test 34/34 · verify.sh 6/6 · verify-resume.sh 4/4 · verify-mpris-modes.sh 4/4 · verify-api.sh 44/44 · verify-input.sh 9/9
v0.3.2 — stop leaking the album-art cache, and verify the rating input
The album-art cache grew without bound, for ever
Every track change wrote ~/.cache/gapless/art-{n} for MPRIS clients to point at, and nothing ever deleted one. Worse, the sequence restarts at zero on every launch, so each run overwrote art-1, art-2… and permanently orphaned everything above its own high-water mark.
Measured on a real install before the fix: 283 orphaned cover files, at ~96 KB each on that library — tens of megabytes nothing would ever read again, growing for as long as the player runs.
The newest four are kept — more than one, because an MPRIS client fetches art asynchronously and may still be reading the previous track's file — and a launch sweeps whatever earlier runs left behind. Pruned by the sequence number parsed from the name, not lexically: art-9 sorts after art-10 as a string, which would delete the newest cover and keep nine stale ones.
Correction. The first version of these notes said 682 MB across 285 files. The count was right, the size was not:
~/.cache/gaplessalso holds this project's own AppImage build scratch (~500 MB), anddu -shon the directory counted it as leaked album art. The leak and the fix are unchanged; the number was published before it was checked against what those files actually were.
A cued track had no position
GET /api/status reported position_secs: 0.0 for a track restored from the last session. It has a position — it is where the resume will start — but nothing was loaded yet, so the pipeline answered zero. A caller was told the track was at the beginning when it was two minutes in.
New: scripts/verify-input.sh
The two rating paths nothing else could reach — the number-key accelerators and the right-click menu on a list row — now have 9 checks against the real window with real XTEST input.
Two things made that hard, both worth knowing if you automate a GTK4 app: GTK4 ignores synthetic key events (xdotool key --window uses XSendEvent and does nothing, silently), so the window must genuinely hold focus; and a window manager can refuse focus to a window that just appeared. The script maps, raises, activates and focuses, then verifies with getactivewindow before sending anything, and fails rather than skipping if focus is refused — a check that quietly does nothing is worse than no check.
cargo test 33/33 · verify.sh 6/6 · verify-resume.sh 4/4 · verify-mpris-modes.sh 4/4 · verify-api.sh 44/44 · verify-input.sh 9/9
v0.3.1 — four defects found by using the player, not by testing it
All four were found by operating the player. Three were in code that shipped hours earlier with a fully green suite; the fourth had been there since v0.1.0.
A media key ignored the resume point
The play button resumed where the last session stopped. A media key, or Play from the lock screen, did not — it started the queue from the top and threw the resume point away. Restart Gapless, press play on your keyboard, get the wrong track.
The resume point lived in the GTK front-end, which mpris.rs cannot see. It is a cue on the player now, and play() / play_pause() are the whole of "press play" for the button, media keys, MPRIS and the control API alike.
The control API described a state that had not caught up
POST /api/play answered "track": null about a track it had just started, and POST /api/rating {"stars":N} answered 409 nothing is playing while it was playing. Both read a field set by an event that arrives after the call returns. And is_playing() was briefly false after a successful play, because a GStreamer state change is asynchronous and only the current state was read — so a caller could not tell "starting" from "refused".
A deadlock, caught before release
if let Some(x) = self.cued.lock().unwrap().take() { … } holds the MutexGuard to the end of the body in edition 2021, and the body locked the same mutex. The app stayed alive and MPRIS kept answering while every call timed out with the main loop wedged.
Verification
verify-mpris-modes.sh gains a fourth case: seed a resume point, launch the real app, send Play over MPRIS, and require the cued track. verify-api.sh gains three, one per API defect — the existing 41 walked past all of them, because every scripted check rated by explicit index and read status after a sleep, so nothing ever asked the API a question a person would ask it.
cargo test 30/30 · verify.sh 6/6 · verify-resume.sh 4/4 · verify-mpris-modes.sh 4/4 · verify-api.sh 44/44
v0.3.0 — a local control API, with its own reference
A local HTTP control API, so agents and other programs can do everything the window does: open a folder or a playlist, play, pause, seek, skip, change every mode, rate a track, change the three playback settings, quit.
Off by default. Switch it on under the gear button → Remote control API, where the port and the key sit beside the switch.
KEY=$(gapless --api-key)
curl -s -H "Authorization: Bearer $KEY" http://127.0.0.1:8421/api/docsIt documents itself. docs/API.md is compiled into the binary and served at GET /api/docs (?section= narrows it), so the reference can never describe a different version than the one answering you. GET /api is a one-line index of every route. Pointing something at the port and the key is enough to get it started.
Not MPRIS, which is unchanged. MPRIS is the right interface for media keys and a lock screen and the wrong one for scripting: a caller needs a bus connection and bindings, its vocabulary is fixed by the spec so silence trimming, crossfade length, the interior-silence cap, ratings and favorites shuffle have nowhere to live in it, and its Shuffle is a bool where this player has three states.
Security. Loopback only. Every route needs the key — there is no unauthenticated endpoint, not even a health check. The key is 32 bytes from /dev/urandom, mode 0600, compared in constant time.
Fixed
Loading a folder could hang the whole application — introduced with the rating context menu in v0.2.0. load_source cleared the track list with first_child(), and a GtkListBox's children are not all rows: the rating popover is parented to it, so the loop never terminated. Found by the new API harness on its first POST /api/open, not by using the app.
Verification
verify.sh 6/6 · verify-resume.sh 4/4 · verify-mpris-modes.sh 3/3 · verify-api.sh 41/41 · cargo test 29/29
v0.2.0 — star ratings, and a shuffle that prefers them
Star ratings, 1–5, and a third shuffle state that weights the order towards them.
Ratings are set from the strip under the track title, the number keys (1–5 rate, 0 clears), or a right-click on any row — that last one because clicking a row in this player starts it, so without a menu you could only rate a track by playing it first.
They live in ~/.config/gapless/ratings.json, keyed by absolute path, and are never written into your audio files: rating a song would mean rewriting it, and POPM has no agreed 1–5-to-0–255 mapping, so a value read back only means something if you already know which player wrote it.
Favorites shuffle is an ordering, not a filter — every track still plays exactly once per pass, but the order is drawn with higher-rated tracks weighted towards the front. Weights double per star; unrated sits level with 2★, because "I have not judged this" is not "I do not like this".
Measured over 4,000 passes of a 12-track queue, where a plain shuffle puts every track at a mean slot of 5.50:
5-star 1.51 unrated 5.96 1-star 7.65
Also: state.json gains shuffle_mode, and MPRIS can no longer silently demote favorites shuffle to a plain one.
No AppImage on this release — it was superseded the same day by v0.3.0, which carries the build. See the full notes in CHANGELOG.md.