transcodeParams validity, expiration, and error handling

[deluan]

As I'm implementing this in Navidrome, I have some questions about the transcodeParams lifecycle that I think need to be clarified in the spec.

Currently the transcodeParams description says:

"The client may not use the value instantly and should be kept valid by the server for a reasonable duration if stored in memory."

This leaves three things undefined:

1. How long is "reasonable"? A client may request a transcode decision when building a playlist/queue and only use the params hours later. Should servers support that? Or is this meant to be short-lived (seconds/minutes)?

2. What should the server return when transcodeParams is expired or invalid? The getTranscodeStream endpoint just says "a standard HTTP error code is returned with a descriptive message." Should this be a specific error code so clients can distinguish "bad params, re-request a decision" from other errors?

3. What should the client do in that case? The expected recovery path is presumably to call getTranscodeDecision again, but this isn't documented.

4. What if the underlying file changes between decision and stream? The media file could be replaced (e.g. upgraded from MP3 to FLAC), or deleted entirely after the decision was made. The transcodeParams may reference a transcoding plan that no longer makes sense for the current file — or a file that no longer exists. Should the server detect this and return an error? Which error?

Proposal

1. Add an optional validUntil field to the transcodeDecision response. This lets the server communicate its expiration policy explicitly. Clients know when to proactively re-request a decision rather than discover it failed at playback time. Servers that don't expire params (e.g. those that encode everything in the params themselves) can simply omit the field. This follows the same pattern we use in other places (e.g. validUntil in playlist entry).

2. Return HTTP 410 Gone when transcodeParams is no longer valid (expired, stale due to file changes, etc.). Clients receiving a 410 SHOULD call getTranscodeDecision again and retry.

3. Return HTTP 404 Not Found when the media file no longer exists on the server.

This gives clients a clear, unambiguous recovery path and avoids imposing a fixed duration on servers with different architectures.

Thoughts?

[Tolriq]

Sounds good but we should document the minimal duration to keep the data.

The 2 main needs are:

• Start to preload and or do checks near the end of the current file to prepare the next one. This is usually needed to last a couple of minutes max. (A client that request 40000 transcode decision to built a playlist is a bad client that will kill servers that don't have codec cache and need to do all that ...)

• Allow seeking inside the media via timeOffset, this is the most problematic (yet most frequent need to reuse the params) one to have a minimal duration as audiobook or long mixes and everything. Maybe add a note about that, like servers should keep the params even after the default duration as long as the transcode is active + X minutes ?

Having to redo a decision on seeks would increase the seek delays for end users so if we can avoid it's better.

[epoupon]

For the record, LMS stores transcode decisions in memory. A maximum of 1,000 decisions can be stored, and each decision is valid for up to 12 hours.
If too many decisions are stored in the cache, the oldest ones are removed. Not sure why I picked 12hours, could actually be valid forever, and only invalidated on scanner updates.
All that to say validUntil should be treated more as a hint than a guarantee?

[deluan]

A server reboot in the middle of the playback would in all case be problematic for the client :)

I'm thinking about the play queue use case, where you ask for the decision for the next song in the queue, but between the getTranscodeDecision and the actual getTranscodeStream call, the server is restarted (and the current played song was most probably already downloaded). But yes, a server restarting could cause other issues as well.

I'm also creating params valid for 12 hours, but they are "durable" (not stored in memory).

Anyway, I agree that the validUntil should be treated more as a hint, but then it has not real value. Maybe we should just suggest servers to keep the params/decision as long as possible, at least for the length of the file + 10(?) minutes? And clients should handle the response errors accordingly. WDYT?

Speaking of return codes, should we use standard HTTP codes (410, 404, 400), or extend the Subsonic errors?

[Tolriq]

Http codes as casting end points or ffmpeg can't interpret subsonic code.

The problem of duration based on length + duration is that if you seek back then it will play for more than that, same for repeat one. But for repeat most client probably pre start before for gapless so the decision call again should not delay things too much.

And yes in all cases clients needs to be able to handle errors. Just need to avoid errors for the common seek.

I get a lot more support stuff about seeking even is music than I thought, seems some people like to seek.

[deluan]

Http codes as casting end points or ffmpeg can't interpret subsonic code.

Yeah, that makes sense, but will clients (Sonos, Chromecast, etc..) handle 410? Or even 404? How will they be able to handle that?

I'm asking because I really don't know. I don't use casting at all :P

[Tolriq]

They all support 404 and most return better error code in that case than just failure to play.
If they don't support 410 they will just return the usual random error like they do now when fed with the subsonic json.