limit defaults to 10 and is capped at 100. An invalid limit returns 400.
Soundtrack entries: soundtrack_uuid, soundtrack_name, soundtrack_played, soundtrack_last_played (optional), songs (array, empty when the soundtrack has no songs).
Song entries: song_uuid, soundtrack_uuid, soundtrack_name, song_name, times_played, file_name.
The soundtrack_id integer fields are deprecated; use the UUIDs (see Sansan/MusicServer#31).
Suggested structure
MusicServerClient: hand-written calls such as fetch_statistics_summary(on_done, on_failed), fetch_most_played_soundtracks(limit, on_done, on_failed) and fetch_most_played_songs(limit, on_done, on_failed).
Typed response classes (StatisticsSummary, SoundtrackStats, SongStats) with static func from_dict(data: Dictionary), ideally generated (see #40).
A statistics view (popup or tab) showing the summary plus most/least played lists.
Acceptance criteria
Summary and most/least played lists shown in the player
Unit tests with the fake transport for each call, including 401 and 500 handling
Show play statistics from the server, using the `/api/v1/statistics` endpoints. Depends on #39.
## Endpoints (all GET, token required)
| Path | Returns |
|---|---|
| `/api/v1/statistics/summary` | `{total_soundtracks, played_soundtracks, never_played_soundtracks, total_soundtrack_plays, avg_soundtrack_plays, max_soundtrack_plays, min_soundtrack_plays}` |
| `/api/v1/statistics/soundtracks/most-played?limit=` | Soundtracks with their songs |
| `/api/v1/statistics/soundtracks/least-played?limit=` | Soundtracks with their songs |
| `/api/v1/statistics/soundtracks/last-played?limit=` | Most recently played soundtracks |
| `/api/v1/statistics/soundtracks/oldest-played?limit=` | Least recently played (but played at least once) |
| `/api/v1/statistics/soundtracks/never-played` | Soundtracks never played |
| `/api/v1/statistics/songs/most-played?limit=` | Songs with their soundtrack |
| `/api/v1/statistics/songs/least-played?limit=` | Songs with their soundtrack |
`limit` defaults to 10 and is capped at 100. An invalid limit returns 400.
Soundtrack entries: `soundtrack_uuid`, `soundtrack_name`, `soundtrack_played`, `soundtrack_last_played` (optional), `songs` (array, empty when the soundtrack has no songs).
Song entries: `song_uuid`, `soundtrack_uuid`, `soundtrack_name`, `song_name`, `times_played`, `file_name`.
The `soundtrack_id` integer fields are deprecated; use the UUIDs (see Sansan/MusicServer#31).
## Suggested structure
- `MusicServerClient`: hand-written calls such as `fetch_statistics_summary(on_done, on_failed)`, `fetch_most_played_soundtracks(limit, on_done, on_failed)` and `fetch_most_played_songs(limit, on_done, on_failed)`.
- Typed response classes (`StatisticsSummary`, `SoundtrackStats`, `SongStats`) with `static func from_dict(data: Dictionary)`, ideally generated (see #40).
- A statistics view (popup or tab) showing the summary plus most/least played lists.
## Acceptance criteria
- Summary and most/least played lists shown in the player
- Unit tests with the fake transport for each call, including 401 and 500 handling
Sansan
added the feature label 2026-10-06 16:11:39 +02:00
Update from MusicServer (develop, commit 973ebf2): the API docs are now generated with Huma instead of swag.
Spec: OpenAPI 3.1 at /openapi.json (also /openapi.yaml, and OpenAPI 3.0 at /openapi-3.0.json). Interactive docs at /docs. /openapi redirects to /openapi.json. Only /api/v1 is documented; legacy routes are hidden but still work.
Health:GET /api/v1/health now exists and needs no token (returns {"status": "up"}).
Sync aliases removed:/sync/new, /sync/quick and /sync/new/full are gone. Use POST /sync and POST /sync/full.
Errors: every error body is {"error": "..."}. Invalid or missing parameters (for example ?song=abc, a malformed UUID, limit=0) now return 422 instead of 400.
Lists: empty lists are [], never null. Arrays in the spec are not nullable.
**Update from MusicServer (`develop`, commit 973ebf2):** the API docs are now generated with Huma instead of swag.
- **Spec:** OpenAPI 3.1 at `/openapi.json` (also `/openapi.yaml`, and OpenAPI 3.0 at `/openapi-3.0.json`). Interactive docs at `/docs`. `/openapi` redirects to `/openapi.json`. Only `/api/v1` is documented; legacy routes are hidden but still work.
- **Health:** `GET /api/v1/health` now exists and needs no token (returns `{"status": "up"}`).
- **Sync aliases removed:** `/sync/new`, `/sync/quick` and `/sync/new/full` are gone. Use `POST /sync` and `POST /sync/full`.
- **Errors:** every error body is `{"error": "..."}`. Invalid or missing parameters (for example `?song=abc`, a malformed UUID, `limit=0`) now return **422** instead of 400.
- **Lists:** empty lists are `[]`, never `null`. Arrays in the spec are not nullable.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Show play statistics from the server, using the
/api/v1/statisticsendpoints. Depends on #39.Endpoints (all GET, token required)
/api/v1/statistics/summary{total_soundtracks, played_soundtracks, never_played_soundtracks, total_soundtrack_plays, avg_soundtrack_plays, max_soundtrack_plays, min_soundtrack_plays}/api/v1/statistics/soundtracks/most-played?limit=/api/v1/statistics/soundtracks/least-played?limit=/api/v1/statistics/soundtracks/last-played?limit=/api/v1/statistics/soundtracks/oldest-played?limit=/api/v1/statistics/soundtracks/never-played/api/v1/statistics/songs/most-played?limit=/api/v1/statistics/songs/least-played?limit=limitdefaults to 10 and is capped at 100. An invalid limit returns 400.Soundtrack entries:
soundtrack_uuid,soundtrack_name,soundtrack_played,soundtrack_last_played(optional),songs(array, empty when the soundtrack has no songs).Song entries:
song_uuid,soundtrack_uuid,soundtrack_name,song_name,times_played,file_name.The
soundtrack_idinteger fields are deprecated; use the UUIDs (see Sansan/MusicServer#31).Suggested structure
MusicServerClient: hand-written calls such asfetch_statistics_summary(on_done, on_failed),fetch_most_played_soundtracks(limit, on_done, on_failed)andfetch_most_played_songs(limit, on_done, on_failed).StatisticsSummary,SoundtrackStats,SongStats) withstatic func from_dict(data: Dictionary), ideally generated (see #40).Acceptance criteria
Update from MusicServer (
develop, commit 973ebf2): the API docs are now generated with Huma instead of swag./openapi.json(also/openapi.yaml, and OpenAPI 3.0 at/openapi-3.0.json). Interactive docs at/docs./openapiredirects to/openapi.json. Only/api/v1is documented; legacy routes are hidden but still work.GET /api/v1/healthnow exists and needs no token (returns{"status": "up"})./sync/new,/sync/quickand/sync/new/fullare gone. UsePOST /syncandPOST /sync/full.{"error": "..."}. Invalid or missing parameters (for example?song=abc, a malformed UUID,limit=0) now return 422 instead of 400.[], nevernull. Arrays in the spec are not nullable.