[API Request] Timeline API for proper client playback status report

[Tolriq]

Type of change

API extension

Proposal description

Allow clients to properly report their timeline for display purpose on the server or forwarding to external services like discord.

Goal is to replace scrobble with submission=false with something actually usable.

Backward compatibility impact

No response

Backward compatibility

• No backward compatibility impact.

API details

Quick TL;DR; for discussion.

Extension name: playbackReport

Endpoint: reportPlayback.view

Params: songId, position, state(playing, paused, stopped), playbackRate (Default 1f), playbackRate, duration, ignoreScrobble.

ignoreScrobble is added here as a way for clients to eventually migrate to only use this endpoint to leave the server manage scrobbling based on more accurate data.
Clients who wants to opt out still can and still use the scrobble with submission.

getNowPlaying return will have the new fields returned as well.

Security impacts

No response

Potential issues

No response

Alternative solutions

No response

[lachlan-00]

Is this similar to player https://ampache.org/api/api-json-methods#player

Where you will report the status of the clien tstate to the server?

[lachlan-00]

do you intend any historical reporting or solely as a real time current state? On the server side i've always viewed these as a "happening right now" thing.

I don't know whether skipScrobble is needed as on the server side i can track whether or not anything is needed based on the timestamp of the song and current history

But other than that i think this tpye of endpoint is needed

[Tolriq]

It's for now playing only and I've explained why the ignore parameter is needed. To give clients control of when a scrobble is made or not because of the settings client side about that .....

[deluan]

When you say "give clients control of when a scrobble is made or not", are you referring to:

1. Sending the NowPlaying to the external scrobbling service
2. Sending an actual Scrobble (submit=true) to an external scrobbling service
3. or...?

If the idea is to eventually migrate to only this endpoint, it also needs to support offline (enqueue) scrobbles.

[lachlan-00]

As a server if you send me id and position i do all the things including scrobble.

If you sent ignoreScrobble i would skip the scrobble plugins but the state of the current playing tracks would be updated.

The endpoint would be useless if ignoreScrobble blocked everything.

[Tolriq]

@lachlan-00 The goal is display purpose if ignoreScoble is true .... You should not do anything else to leave the control to the client.

@deluan The goal is not to fully replace scrobble with submit as explicit command, it's to enable proper auto scrobble by the server based on accurate data to take a decision. The server now have playback start pause stop and position. It can increase Play count and scrobble based on it's rules accurately. Not all clients have options and want control like Symfonium. They report the playback state and the server do it's magic, like when you install pano or last FM app and it work automatically when you play music on other music apps. It just need the ignore for apps like Symfonium that will then use scrobble with submission.

[dweymouth]

I think this is a good idea. Should there also be a playbackRate parameter for clients to specify the playback speed? (e.g. 1.25, 0.75, default if not specified would be 1.0). That would allow the server to know the current playback position even if a client is playing with a speed multiplier, as long as the client calls this endpoint on every new track, seek, play/pause change, or play speed change

[Tolriq]

Yes I forget it. Some other servers also expect calls to happen at regular rate else timeout and assume failure. Not sure if we want that or not (If the end point is used for scrobbling but don't base on the stop event then it probably should, else no)

[lachlan-00]

does it need playback speed if the client reports the next song anyway? if the song/video finishes early then the server sets a new now playing

[Tolriq]

For display purpose yes, the server can't interpolate the current position between 2 calls without that.

[lachlan-00]

ok, i can see where some people would use that, all of this seems like a good idea

[deluan]

As part of this, should we extend the getNowPlaying to provide precise information (position/state)? I think it is just a couple of extra fields, that can be ignored by old clients as usual.

[Tolriq]

Yes probably I don't use it so forget about that one :)

[FoxxMD]

This is a pretty important change if your app primarily wants to monitor activity on a subsonic server. Please consider it!

[duckcantcode]

Would be great for any projects requiring precise position in a currently playing song, i.e. visualizers - I am waiting on this to be implemented for that reason

[deluan]

Question about the new extension:

When a new client uses reportPlayback with ignoreScrobble=false, should the server auto-scrobble based on play duration (e.g., after 50% or 4 minutes)? Or does the server only scrobble when it sees a stopped state after sufficient play time? Or does the client still call the old scrobble endpoint for the actual submission, and reportPlayback just feeds richer now-playing data?

Previously the client had full control on when to process the scrobble (count as played). If servers now do that, clients lose control of this, right?

[epoupon]

From what I understand, it would only happen at the next stop, but it could be triggered earlier if the client regularly sends playback state updates during playback, and if one of those updates meets the scrobbling rules (which should depend on the backend to which the scrobble is sent).

[deluan]

Now that I'm trying to implement it, I'm thinking that this new endpoint should not be used for scrobbling, just for reporting state/progress instead of /rest/scrobble?submit=false, and /rest/scrobble?submit=true should be used for actual scrobbles.

I'm not sure if the server should infer when to consider a track was played (and potentially send scrobbles to external sites). This should be controlled by the client, as managing this state in both sides can be tricky and cause issues like double scrobbling in situations where the client has a flaky connection with the server.

[Tolriq]

This was discussed too.

If each client controls when it's scrobbled it's multiplication of settings that apps usually don't even offer. All other providers works like that, you can push offline playcounts and scrobbles, but the server infers the automatic scrobbles via the settings it can expose that are applied automatically to all clients.

This simplifies client life and ensure better results usually. And no it should not be possible to have double scrobbling as you can't get multiple stop after a starting for a given media. Even with a bad client sending multiple stop you should ignore if there's no starting.

[kgarner7]

A question about the spec. ignoreScrobble says that

If true, server should only update now-playing display/state and should not trigger scrobble/playcount side effects.

What is considered a side effect? Is sending a nowPlaying event to scrobble backends (e.g., last.fm/listenbrainz) considered a side effect? I understand that it should not trigger play count changes.

[Tolriq]

It should not count as played there else we have drift between servers/clients and those backends and anything that do sync or restore from there will be wrong. Specially as real scrobble will be sent later.

[kgarner7]

That's not what I asked. With /rest/scrobble?submission=false, servers can trigger a "now playing" event which can also forward "this user is now playing track" to external services. Should servers that do this also forward events (not submissions, but now playing events) when ignoreScrobble=true?

[Tolriq]

Yes it is and my answer does not change if sending those events count as played on those services then it should not. Including the legacy endpoint else it does not matter.