SoundLeaf v1.5 & v1.6: Less Flashy, More Solid

Not every update gets a headline feature. Sometimes the best thing you can do is make what’s already there actually work the way it should. That’s v1.5 and v1.6 in a nutshell — a bunch of fixes that were driving people (and me) nuts, plus some player improvements and a proper documentation section on the website.

Series books are finally in the right order

This one was embarrassing. If you had a series in your library, the books would sometimes show up in a seemingly random order instead of, you know, the actual sequence. Multiple people reported this (#43 — thanks @PandaUnit-TWL, @Atlas3686, @JoeSmartChicken, @Timo-1979, @marshallpt), and they were right.

The root cause was that the series API endpoint didn’t reliably return sequence data. So I rewrote the fetch to do a two-phase approach: first grab all your series metadata, then fetch the actual books per series from an endpoint that returns proper sequence numbers. Books now sort by sequence first, then fall back to published year, then title. The way it should have been from the start.

The login screen that wouldn’t stay away

This was the most annoying bug in v1.4. A brief network hiccup — your phone switching from WiFi to cellular, a momentary drop in connectivity — and SoundLeaf would panic and throw you back to the login screen. Not great.

v1.5 and v1.6 completely reworked how sessions are handled:

• Silent re-authentication - The app now stores your credentials in the iOS Keychain and quietly re-authenticates in the background when a token refresh fails, instead of dumping you to login
• Smarter session expiry - The app now distinguishes between transient errors (network blip, server momentarily down) and actual auth failures (401/403). Only real auth failures trigger a session expiry.
• Token refresh loop killed - There was a bug where a failed token refresh would keep retrying forever, stacking up concurrent refresh attempts. Added a mutex and a 3-retry cap. That loop is gone.

Your progress actually syncs now

Here’s a fun one: if you listened to a book while offline and then came back online, your progress just… didn’t sync. You’d pick up your phone later and it would be like the last hour of listening never happened.

The fix was twofold. First, SoundLeaf now monitors your network connection and syncs pending sessions the moment connectivity comes back. Second, the periodic sync timer had a bug — it was running on a background thread’s run loop where it would silently stop firing. Moved it to the main thread. Also added protection so the server doesn’t overwrite your local progress if you’re actively listening (#59 — thanks @JoeSmartChicken for catching this).

Player got some new tricks

A few things that make the player nicer to use day-to-day:

• Chapter skip buttons - Dedicated previous/next chapter buttons in the player. Hit previous within the first 3 seconds and it jumps to the prior chapter; after that it rewinds to the start of the current one. Uses optimistic UI so the chapter title updates instantly instead of waiting for the seek to finish.
• Chapters list - A dedicated button to open the full chapters list from the player. It auto-scrolls to your current chapter, which is surprisingly handy in books with 60+ chapters.
• End-of-chapter sleep timer - Set the sleep timer to pause when the current chapter ends. Shows the estimated remaining time right in the player. It even drops bookmarks when the timer starts and stops, so you can find your place if you fell asleep before it fired.
• Author name in the player - The player now shows the author below the book title. Small thing, but useful when you’re deep in a series and can’t remember who wrote it.

Better error messages

API errors used to show cryptic status codes or generic “something went wrong” messages. Now every HTTP error maps to something human-readable — timeouts, rate limits, SSL failures, server errors all get their own clear messages. The app also parses error details from the server response when available.

Continue section and Resume/Play Again

The Continue section at the top of your library now shows your last 3 recently played books from local playback data, so you can quickly jump back into whatever you were listening to. Small change, but it makes the home screen way more useful if you’re juggling a few books at once.

And the play button on the book detail screen now actually tells you what it’s going to do. Partway through? It says “Resume.” Finished? “Play Again” with a replay icon. Not started? Just “Play.”

A proper docs section

The website at soundleafapp.com now has a documentation section with actual guides:

• Getting started - Setting up SoundLeaf with your Audiobookshelf server
• CarPlay - How to use SoundLeaf in your car
• Cloudflare Access - Connecting through Cloudflare Zero Trust tunnels
• Tailscale VPN - Using SoundLeaf over Tailscale
• Connection troubleshooting - Common connection issues and how to fix them

These were the questions I kept seeing in GitHub issues and on Reddit, so I figured I’d save everyone (including myself) some time.

Other fixes you might not notice (but will appreciate)

• Player observer leak - The player wasn’t cleaning up its notification observers during track transitions, only on full teardown. Over long listening sessions this could cause playback weirdness. Fixed.
• Lock screen skip intervals - Changing skip forward/backward duration in settings now actually updates the lock screen controls. Before, you had to restart the app.
• Token response parsing - The refresh token response was being parsed with a flat structure but the API actually nests tokens inside a user object. Fixed to match the real API.
• Restore purchases - Added a Restore Purchases button for when App Store purchases don’t sync properly.
• Sign out moved - Sign out is now in the library settings instead of buried in the main settings, and shows a loading spinner while it works.

Get the update

v1.6 is available now on the App Store. If you’re on TestFlight, you’ve had these fixes for a bit already — join here if you want early access to what’s next.

Running into something? GitHub is the place.

Happy listening, Hemant