+- Jellyfin Forum (https://forum.jellyfin.org)
+-- Forum: Support (https://forum.jellyfin.org/f-support)
+--- Forum: Troubleshooting (https://forum.jellyfin.org/f-troubleshooting)
+--- Thread: Help understanding the PlayCount UserData from API. (/t-help-understanding-the-playcount-userdata-from-api)
Help understanding the PlayCount UserData from API. - Fingel - 2025-12-18
Hello!
First off, I love Jellyfin. In fact I love it so much I decided to write my own client, Gelly.
A feature I would like (and that has been requested) is to be able to view the play count for Items. So I took a look at the API and I was happy to see that it appears there is a field in the /Items/ endpoint response which looks like just the ticket:
Code:
{
"Items": [{
"Name": "string",
...,
"UserData": {
"PlayCount": 0,
...,
}
}]
}However, when I actually printed out these values, the numbers seemed off in the low direction. There are songs in my library I know I have listen to (possibly 10s of times!) and yet I don't see a PlayCount greater than 2.
How is this number calculated? One explanation that I can think of is that it's not actually updated automatically. I see there is a POST /UserItems/{itemId}/UserData endpoint. Does this mean clients are meant to explicitly update the playcount themselves? So in the case of badly behaving clients (such as my own) the counts could be totally off?
The other thing I can think of is that it works on some rolling window, though that seems less likely.
Any insight would be appreciated!
RE: Help understanding the PlayCount UserData from API. - niels - 2025-12-19
I would assume it is based in the reporting API, so increment by one when playback stop is reported and progress is near the duration of the item.
RE: Help understanding the PlayCount UserData from API. - Fingel - 2025-12-19
(2025-12-19, 06:37 AM)niels Wrote: I would assume it is based in the reporting API, so increment by one when playback stop is reported and progress is near the duration of the item.
Hi, I'm still not clear on what this means. Is the reporting API something clients are responsible for calling? Like they need to increment by one somehow (atomically)? The api docs are pretty bare in this regard. There is https://api.jellyfin.org/#tag/Playstate/operation/OnPlaybackStopped but it's marked as deprecated, but no indication if it's been replaced with anything.
RE: Help understanding the PlayCount UserData from API. - niels - 2025-12-19
Yes clients need to report start, progress (every few seconds) and stop messages for proper reporting in the dashboard among others. The ReportPlaybackProgress should be responsible for stuff like marking items as watched and incrementing the play count.
RE: Help understanding the PlayCount UserData from API. - Fingel - 2025-12-19
For anyone else finding this, I'm guessing this is the Playstate api: https://api.jellyfin.org/#tag/Playstate I will try to implement this and report back. Thank you!