[ENHANCEMENT] Server-side HLS persistence for AVAssetDownloadURLSession - proof of concept on an ABS fork

[walkermc20]

Hi @rasmuslos ,

I've been using ShelfPlayer regularly and hit the rough edges of the dual playback path (progressive stream vs. locally downloaded file, two code paths, plus the guard that stops a download while the same item is playing). The obvious collapse is AVAssetDownloadURLSession - it streams HLS and writes a persistent .movpkg in one pipeline, so "downloaded" becomes a flag on the asset task rather than a separate subsystem. Scrub buffering becomes AVFoundation's problem, not the app's.

The server-side gap is that AudioBookshelf's HLS output today is session-scoped: manifest URLs die when the playback session closes or idles out (36 h). That's fine for browser playback, but breaks AVAssetDownloadURLSession the moment a download spans more than one session, which it always will.

I built and tested a reference implementation that closes that gap with an opt-in flag. It's a ~40-line change on top of v2.33.2, default off:

• Fork commit: walkermc20/audiobookshelf@ac47208a - gated by ENABLE_IOS_HLS_PERSIST=1 on the server + request mediaPlayer: "ios-hls" from the client. If either is absent, behaviour is byte-identical to upstream ABS.
• Public test image: ghcr.io/walkermc20/audiobookshelf:ios-hls-persistent
• Test harness: https://github.com/walkermc20/audiobookshelf-hls-test - Python proxy + hls.js page that exercises the full flow end-to-end.

I've verified that manifest URLs on the fork survive session close, orphan sweeps, and container restarts - required for multi-day downloads/listening sessions.

Only the server side is in scope for what I've built. The iOS integration (AVAssetDownloadURLSession wiring in ShelfPlayer) is yours to take (hopefully) or leave. I dont have the chops to do the macOS development and can't test any AI code for it.

Ask: does this direction look viable enough that you'd consider prototyping ShelfPlayer against it? I can host a fork instance you point at, or you can run the public image yourself. I'm also drafting an upstream proposal for advplyr/audiobookshelf but would rather have your read first - the feature is motivated by ShelfPlayer's use case and the proposal will land better co-signed (or with your "this would be useful" in a comment).

Design is flexible - happy to change the opt-in shape, switch to per-user HMAC URLs, add per-library config, swap mpegts for fmp4, whatever you actually need. Just looking for direction right now, no code commitment from you.

— Michael / walkermc20

[rasmuslos]

Hey,

I know about AVAssetDownloadURLSession and have thought about implementing it before — it supposedly has other neat benefits too, like providing a download management UI in the Settings app.

Downloading codecs unsupported by iOS also doesn't work in ShelfPlayer right now (to be fair, last time I checked it didn't work in the official app either), and fixing that would be great.

The flow I'm picturing is roughly:

1. app requests an HLS transcode
2. app waits for it
3. app downloads it
4. app signals completion and the transcode is removed

What are your thoughts on that flow? If something along those lines lands upstream in ABS, I'd implement it on the client side.

Thanks for the idea!

[walkermc20]

Thanks! Good to know we're aligned on the direction. The codec coverage is a nice side effect I hadn't thought about.

One small amendment to the flow you sketched: I don't think the "app waits for it" step is needed.

• The HLS manifest ABS emits today is complete up front (full segment list derived from source duration) so a client can download segments as ffmpeg produces them.
• Playback against the same asset can start immediately, and the download completes in the background off the same pipeline. No separate wait-for-transcode phase, no duplicate bytes, one code path.
• The fork image is what makes that survive across sessions; I confirmed the server + manifest half end-to-end with an hls.js harness. AVAssetDownloadURLSession's behavior against an in-progress manifest is the one hop my harness doesn't cover - AVFoundation handles progressive HLS by design so I'd expect parity, but if it surprises us a ready-poll fallback is trivial.

Your step 4 - client signals completion, server removes the transcode - is the piece the upstream PR would formalize. It would be a DELETE /api/session/:id (or close?purge=true) the client calls when the AVAssetDownloadTask finishes or when the user removes the book, plus a server-side TTL as a safety net for crashed clients. The opt-in stays gated on mediaPlayer: "ios-hls" (or an explicit persistHls: true, whichever reads cleaner to you) so default ABS behavior is unchanged.

I'll take this as a green light and draft the upstream PR if you're ok with that. The only thing I'd want your read on before I send it:

• Do you have a preference on the teardown shape (DELETE /api/session/:id vs. purge=true on the existing close endpoint), or should I just pick the cleanest one and you push back on review?

[walkermc20]

Quick update - while your reply's still in flight I went ahead and picked a teardown shape so there's something concrete running on the fork to react to. Landed on a third option that's cleaner than either I floated:

DELETE /api/session/:id/hls-cache

Why not the two I originally offered:

• DELETE /api/session/:id - collides semantically with the existing DELETE /api/sessions/:id (plural, deletes the DB record). Same noun, different target, confusing.
• POST /api/session/:id/close?purge=true - the existing /close uses openSessionMiddleware, which 404s when the session isn't in memory. That's the case we most care about: if a download runs past the 36h idle-expiry (or the server restarts), the in-memory session is gone but the cache files are still there waiting to be released. The endpoint would 404 when we need it the most.

/session/:id/hls-cache sidesteps both. Session-independent, safe to retry, does what its name says.

Server-side behavior:

1. If the session is still in memory: verify user ownership, tear down via removeSession() (kills ffmpeg cleanly).
2. Unconditionally fs.remove(StreamsPath/:id) — works regardless of session state.
3. 200 either way. Safe for the client to retry.

Also wired up the TTL safety net - IOS_HLS_PERSIST_TTL_DAYS, default 30. Sweeps any .persistent dir whose marker mtime is past the threshold, at server startup. Covers the crashed-client case.

Both live on the fork image now (ghcr.io/walkermc20/audiobookshelf:ios-hls-persistent), commit 720a1aed.

• [Tested / Working] README has the full client lifecycle.

If you want a different shape - back to ?purge=true, something else entirely - renaming the route is two lines. If you get back to me before I file the upstream PR I'd be happy to adjust.

[walkermc20]

Quick status:

• server-side on the fork is test-verified (14/14 integration + a unit test suite on commit 6092c70f).
• Opening a Discussion on advplyr/audiobookshelf next to align on the upstream shape - I'll link it here when it's live.

No action on your side; just wanted you to know it's moving and your flow-sketch informed the final API.

[walkermc20]

Upstream discussion at ABS is live - advplyr/audiobookshelf#5207.
Nothing needed from you, just closing the loop per earlier. Feel free to subscribe if you want the updates in your inbox; I'll ping again here if/when advplyr engages and the design firms up.

[walkermc20]

This has been sitting a while...any interest in chiming in on the thread over at audiobookshelf?