feat: most-played-cards statistics

Adds a per-card play counter (NVS 'rfidPlayCnt'), incremented in the RFID lookup
handler when a music card starts a playlist (Playstats_NoteCardPlay). New GET /topcards
returns the top 10 cards by play count with their assigned fileOrUrl + mode; the info
dialog shows the top 3 next to the daily listening totals. A card's counter is cleared
when the card is deleted, so removed cards leave no ghost stats.

Verified on the test device: playing card A twice + B once -> /topcards ranks A(2)
before B(1) with their paths; deleting both clears the counters (/topcards empty);
no console errors. Synthetic test data cleaned from server + device.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: fhirschmann

README.md

@@ -147,6 +147,7 @@ neon logo that doubles as the SVG favicon ([`7be5254`](../../commit/7be5254)):
 | **Now-playing info dialog**: an info icon next to "Current track" in the Control tab opens a dialog with the full track detail — ID3 title/artist/album, embedded cover, file path + size, play mode, track x/y, **codec / sample rate / bitrate / channels**, position/duration and the RFID tag that started the playlist. Served on demand via a new `GET /currenttrack` (so it doesn't bloat the frequent `trackinfo` websocket). Also: the **Unlocked** control button now uses the neutral (inactive) styling like the other toggles — only **Locked** keeps an accent colour. i18n de/en/fr | [`trackinfo-dialog`](../../releases/tag/trackinfo-dialog) |
 | **Settings tabs de-cluttered**: the long "General" sub-tab was split — the **LED** settings (NeoPixel brightness + LED config) moved into a new **LEDs** sub-tab, and **Deep sleep + Battery** into a new **Power** sub-tab. Both new tabs are covered by the same auto-save. General now holds just volume/branding/options/playlist/rotary. i18n de/en/fr | [`settings-split`](../../releases/tag/settings-split) |
 | **Folder cover-art fallback**: when a track has no embedded ID3 cover, `/cover` now serves a sidecar image from the track's folder (`cover.jpg`/`.jpeg`/`.png` or `folder.jpg`/`.png`) before falling back to the placeholder icon — so audiobooks/albums with a folder image show art in the Control tab | [`cover-fallback`](../../releases/tag/cover-fallback) |
+| **Most-played cards (listening stats)**: a per-card play counter (incremented when a music card starts a playlist) drives a **most-played** list — the top 3 cards (path + play count) appear in the info dialog next to the daily totals; full top-10 via a new `GET /topcards`. A card's counter is cleared when the card is deleted (no ghost stats). Stored in NVS (`rfidPlayCnt`) | [`stats-topcards`](../../releases/tag/stats-topcards) |
 | **OpenAPI/Swagger spec updated**: the bundled `REST_API.yaml` (served at `/swagger.html`) now documents all fork-added endpoints (`/sync`, `/syncstop`, `/playlist`, `/githubupdate`, `/version`, `/login`, `/logout`, `/security`, `/eqrule(s)`, `/activeequalizer`, `/bluetooth*`, `/sdclean`) and declares the security schemes (`X-API-Key` header / `apikey` query param, or the `ESPUINO_SESSION` login cookie) so the Swagger "Authorize" button works. The web-interface footer links to the Swagger UI (`/swagger.html`) | [`f8298d9`](../../commit/f8298d9) |
 
 #### Feature highlights

html/locales/de.json

@@ -788,6 +788,7 @@
 		"lblPlayToday": "Heute gehört",
 		"lblPlayYesterday": "Gestern gehört",
 		"lblPlay7d": "Letzte 7 Tage",
-		"lblPlay30d": "Letzte 30 Tage"
+		"lblPlay30d": "Letzte 30 Tage",
+		"lblTopCard": "Meistgespielt"
 	}
 }

html/locales/en.json

@@ -788,6 +788,7 @@
 		"lblPlayToday": "Listened today",
 		"lblPlayYesterday": "Listened yesterday",
 		"lblPlay7d": "Last 7 days",
-		"lblPlay30d": "Last 30 days"
+		"lblPlay30d": "Last 30 days",
+		"lblTopCard": "Most played"
 	}
 }

html/locales/fr.json

@@ -777,6 +777,7 @@
 		"lblPlayToday": "Écouté aujourd'hui",
 		"lblPlayYesterday": "Écouté hier",
 		"lblPlay7d": "7 derniers jours",
-		"lblPlay30d": "30 derniers jours"
+		"lblPlay30d": "30 derniers jours",
+		"lblTopCard": "Plus joué"
 	}
 }

html/management.html

@@ -6599,6 +6599,16 @@ <h5 class="modal-title" data-i18n="tools.nvs.erase.title"></h5>
 			if (info.audio.playYesterday !== undefined) add('systeminfo.lblPlayYesterday', timestampToDuration(info.audio.playYesterday * 1000, true));
 			if (info.audio.play7d !== undefined) add('systeminfo.lblPlay7d', timestampToDuration(info.audio.play7d * 1000, true));
 			if (info.audio.play30d !== undefined) add('systeminfo.lblPlay30d', timestampToDuration(info.audio.play30d * 1000, true));
+			// most-played cards (top 3), label -> "name (N×)"
+			try {
+				const top = await (await fetch("http://" + host + "/topcards")).json();
+				if (Array.isArray(top)) {
+					top.slice(0, 3).forEach(function (c) {
+						const name = (c.fileOrUrl && c.fileOrUrl !== "0") ? c.fileOrUrl : c.id;
+						add('systeminfo.lblTopCard', name + ' (' + c.count + '×)');
+					});
+				}
+			} catch (e) { /* ignore */ }
 			if (info.sdcard && info.sdcard.size) add('systeminfo.lblSd', (info.sdcard.free / 1024).toFixed(1) + ' / ' + (info.sdcard.size / 1024).toFixed(1) + ' GB');
 			if (info.battery) {
 				add('systeminfo.lblVoltage', info.battery.currVoltage.toFixed(2) + ' V');

src/Playstats.cpp

@@ -21,6 +21,31 @@ static uint32_t gLastDay = 0; // local day number of the most recent tracked day
 static bool gDirty = false;
 static uint32_t gLastSaveMs = 0;
 
+// Per-card play counters live in their own NVS namespace, keyed by the 12-digit tag id.
+static Preferences gPrefsCardCnt;
+static bool gCardCntReady = false;
+static void Playstats_CardCntInit(void) {
+	if (!gCardCntReady) {
+		gPrefsCardCnt.begin("rfidPlayCnt");
+		gCardCntReady = true;
+	}
+}
+void Playstats_NoteCardPlay(const char *tagId) {
+	if (!tagId || !tagId[0]) {
+		return;
+	}
+	Playstats_CardCntInit();
+	gPrefsCardCnt.putULong(tagId, gPrefsCardCnt.getULong(tagId, 0) + 1);
+}
+uint32_t Playstats_GetCardPlays(const char *tagId) {
+	Playstats_CardCntInit();
+	return gPrefsCardCnt.getULong(tagId, 0);
+}
+void Playstats_ClearCardPlays(const char *tagId) {
+	Playstats_CardCntInit();
+	gPrefsCardCnt.remove(tagId);
+}
+
 // Days since 1970-01-01 for a (proleptic Gregorian) calendar date (Howard Hinnant's algorithm).
 // Avoids needing tm_gmtoff (not available in this newlib build): we feed it the local Y/M/D.
 static long Playstats_DaysFromCivil(int y, unsigned m, unsigned d) {

src/Playstats.h

@@ -15,6 +15,11 @@ uint32_t Playstats_GetToday(void); // seconds listened today (local calendar day
 uint32_t Playstats_GetYesterday(void); // seconds listened yesterday
 uint32_t Playstats_GetLastDays(uint16_t days); // sum over the last <days> calendar days (incl. today)
 
+// Per-card play counter (most-played statistics). Incremented when a music card starts a playlist.
+void Playstats_NoteCardPlay(const char *tagId);
+uint32_t Playstats_GetCardPlays(const char *tagId);
+void Playstats_ClearCardPlays(const char *tagId); // drop a card's play counter (e.g. when deleted)
+
 // Raw ring-buffer access for backup/restore (JSON is built/parsed by the caller).
 uint16_t Playstats_GetRingSize(void); // number of day-slots (365)
 uint32_t Playstats_GetRingLastDay(void); // local day number of the most recent tracked day

src/RfidCommon.cpp

@@ -7,6 +7,7 @@
 #include "Log.h"
 #include "MemX.h"
 #include "Mqtt.h"
+#include "Playstats.h"
 #include "Queues.h"
 #include "Rfid.h"
 #include "RfidConfig.h"
@@ -91,6 +92,7 @@ void Rfid_PreferenceLookupHandler(void) {
 				}
 	#endif
 
+				Playstats_NoteCardPlay(gCurrentRfidTagId); // count plays per music card (most-played stats)
 				AudioPlayer_SetPlaylist(_file, _lastPlayPos, _playMode, _trackLastPlayed);
 			}
 		}

src/Web.cpp

@@ -38,6 +38,7 @@
 #include <Update.h>
 #include <WiFi.h>
 #include <WiFiClientSecure.h>
+#include <algorithm>
 #include <atomic>
 #include <esp_random.h>
 #include <esp_task_wdt.h>
@@ -95,6 +96,7 @@ static void handleBluetoothResultsRequest(AsyncWebServerRequest *request);
 static void handleBluetoothConnectRequest(AsyncWebServerRequest *request, JsonVariant &json);
 static void handleWiFiScanRequest(AsyncWebServerRequest *request);
 static void handleGetRFIDRequest(AsyncWebServerRequest *request);
+bool DumpNvsToArrayCallback(const char *key, void *data); // defined later; used by the /topcards handler
 static void handlePostRFIDRequest(AsyncWebServerRequest *request, JsonVariant &json);
 static void handleCreatePlaylistRequest(AsyncWebServerRequest *request, JsonVariant &json);
 static void handleDeleteRFIDRequest(AsyncWebServerRequest *request);
@@ -1045,7 +1047,8 @@ void webserverStart(void) {
 			static uint32_t buf[365];
 			uint16_t c = 0;
 			if (o["days"].is<JsonArray>()) {
-				for (JsonVariant v : o["days"].as<JsonArray>()) {
+				JsonArray daysArr = o["days"].as<JsonArray>();
+				for (JsonVariant v : daysArr) {
 					if (c < 365) {
 						buf[c++] = v.as<uint32_t>();
 					}
@@ -1055,6 +1058,44 @@ void webserverStart(void) {
 			request->send(200, "text/plain; charset=utf-8", "ok");
 		}));
 
+		// Most-played RFID cards (top 10 by play count), with their assigned file/URL + play mode.
+		wServer.on("/topcards", HTTP_GET, [](AsyncWebServerRequest *request) {
+			std::vector<String> ids;
+			listNVSKeys("rfidPlayCnt", &ids, DumpNvsToArrayCallback);
+			std::vector<std::pair<uint32_t, String>> ranked;
+			for (const String &id : ids) {
+				ranked.push_back({Playstats_GetCardPlays(id.c_str()), id});
+			}
+			std::sort(ranked.begin(), ranked.end(), [](const std::pair<uint32_t, String> &a, const std::pair<uint32_t, String> &b) { return a.first > b.first; });
+			AsyncJsonResponse *response = new AsyncJsonResponse(true);
+			JsonArray arr = response->getRoot();
+			for (size_t i = 0; i < ranked.size() && i < 10; i++) {
+				JsonObject o = arr.add<JsonObject>();
+				o["id"] = ranked[i].second;
+				o["count"] = ranked[i].first;
+				// extract fileOrUrl + mode from the stored tag string "#fileOrUrl#pos#mode#track"
+				String s = gPrefsRfid.getString(ranked[i].second.c_str(), "");
+				if (s.length() > 0 && s != "-1") {
+					char buf[300];
+					strncpy(buf, s.c_str(), sizeof(buf) - 1);
+					buf[sizeof(buf) - 1] = '\0';
+					char *tok = strtok(buf, stringDelimiter);
+					uint8_t fi = 1;
+					while (tok != NULL) {
+						if (fi == 1) {
+							o["fileOrUrl"] = String(tok);
+						} else if (fi == 3) {
+							o["mode"] = (uint32_t) strtoul(tok, NULL, 10);
+						}
+						fi++;
+						tok = strtok(NULL, stringDelimiter);
+					}
+				}
+			}
+			response->setLength();
+			request->send(response);
+		});
+
 		// WiFi scan
 		wServer.on("/wifiscan", HTTP_GET, handleWiFiScanRequest);
 
@@ -3346,6 +3387,7 @@ static void handleDeleteRFIDRequest(AsyncWebServerRequest *request) {
 		}
 		if (gPrefsRfid.remove(tagId.c_str())) {
 			RfidSync_OnDelete(tagId.c_str()); // record tombstone + propagate the deletion to server/peers
+			Playstats_ClearCardPlays(tagId.c_str()); // drop the card's play counter too
 			Log_Printf(LOGLEVEL_INFO, "/rfid (DELETE): tag %s removed successfuly", tagId);
 			request->send(200, "text/plain; charset=utf-8", tagId + " removed successfuly");
 		} else {