feature/gapless-albums: working gapless play for albums only.

[BowlOfSoup]

Since I'm an avid prog-rock listener, having setup my Navidrome server and using Aonsoku, I noticed that gapless play was not a feature yet. I've read #179 and I thought: lets give it a go.

I've implemented gapless playback so consecutive tracks from the same album play with no gap between them. It's opt-in and experimental*, off by default, under Settings > Audio > Playback. Playlists and shuffled queues are unaffected.

*It's not experimental in the sense that it sometimes does not work (it does in my tests), but I thought it would up the chance for approval and get people to (also) test the functionality.

How it works

• A new transitionMode setting switches between the existing streaming <AudioPlayer> and a new GaplessSongPlayer.
• The gapless engine streams the current track for an instant start, decodes it to memory in the background, then splices playback onto the decoded buffer mid track (inaudible).
• Once on the buffer, the next album track is decoded ahead of time and scheduled sample-accurately, so the seam has no gap and no click.
• Two songs are joined only when they are consecutive tracks of the same album and disc, and only when shuffle is off.
• ReplayGain resolution is shared with the stock player, so normalization is identical whichever engine is active.

Tests

• Unit tests for the pure transition logic (album-consecutive detection, next/standby selection across loop modes, shuffle and cross-album gating).
• A component test verifying the correct audio surface mounts for each mode.
• Seam audio quality (no click, sample accuracy) was verified manually, since it cannot be asserted reliably in a test.

Notes

• New UI strings are added to en.json only and can be picked up by Weblate for translation.

[vercel]

@BowlOfSoup is attempting to deploy a commit to the Victor Alves' projects Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
aonsoku	Ready	Preview, Comment	Jul 3, 2026 2:32pm

[victoralvesf]

Hi @BowlOfSoup, thanks for the PR!

Tested remotely and I could hear some minor clicks when the song changes (I was listening Pink Floyd's Dark Side of the Moon), but maybe is because I was using a tunnel to access externally, I'm gonna do more tests locally.

Some things I noticed:

• Synced lyrics stopped working.
• The Media Session is not being sent.

I was unable to do a complete code review for now, but I'm going to on the next few days.

[BowlOfSoup]

Valuable comments. Thanks. I didn't realize the MediaSession.

[BowlOfSoup]

@victoralvesf I fixed and (dev-)tested:

• Synced lyrics: now with a shared solution between the normal and gapless player
• Media Session: hidden track that indicates that audio is playing

I've also double checked for clicks, but even with a VPN tunnel I couldn't reproduce it. Let me know if I can/should test with your library.

[johnhabibi]

Awesome! Let's get this in!

[BowlOfSoup]

@victoralvesf if you'd like changes, or have comments, let me know :)