From d51f155a4de5bf2678564410903c413a4947d3d7 Mon Sep 17 00:00:00 2001 From: tgiachi Date: Sun, 15 Nov 2026 17:55:43 +0100 Subject: [PATCH] feat: a statistics page - GET /stats/library: the songs that can be played with their artists, albums, length and size, the files by format, the share of each genre and decade - GET /stats/listening: listens, time listened, songs and artists, listens by year, hour and weekday in the listener's time zone, top artists and songs, the share of each genre, for all time or a period - a song with several genres is split between them, so the shares add up - web: a Statistics page in the Your listening group, with bars made of CSS and four periods - the MP3 files, which the scanner calls mpeg, are shown as MP3 - README: the two endpoints --- README.md | 3 + cmd/sondad/main.go | 2 + internal/api/http/api_test.go | 4 + internal/api/http/contract_test.go | 7 + internal/api/http/handlers_stats.go | 126 ++++++++ internal/api/http/handlers_stats_test.go | 145 +++++++++ internal/api/http/router.go | 4 + internal/api/openapi/openapi.yaml | 160 ++++++++++ internal/stats/stats.go | 292 +++++++++++++++++++ internal/stats/stats_test.go | 208 +++++++++++++ internal/storage/stats.go | 256 ++++++++++++++++ internal/storage/stats_test.go | 241 +++++++++++++++ web/src/api/schema.d.ts | 181 ++++++++++++ web/src/api/stats.ts | 42 +++ web/src/components/StatBars.tsx | 60 ++++ web/src/components/layout/PhoneTabs.test.tsx | 2 +- web/src/components/layout/PhoneTabs.tsx | 2 +- web/src/components/layout/Sidebar.test.tsx | 6 +- web/src/components/layout/Sidebar.tsx | 3 +- web/src/i18n/locales/en.json | 43 ++- web/src/i18n/locales/it.json | 43 ++- web/src/lib/time.test.ts | 22 +- web/src/lib/time.ts | 14 + web/src/pages/LibraryPage.test.tsx | 3 +- web/src/pages/LibraryPage.tsx | 1 + web/src/pages/StatsPage.test.tsx | 239 +++++++++++++++ web/src/pages/StatsPage.tsx | 237 +++++++++++++++ web/src/router.tsx | 1 + 28 files changed, 2336 insertions(+), 11 deletions(-) create mode 100644 internal/api/http/handlers_stats.go create mode 100644 internal/api/http/handlers_stats_test.go create mode 100644 internal/stats/stats.go create mode 100644 internal/stats/stats_test.go create mode 100644 internal/storage/stats.go create mode 100644 internal/storage/stats_test.go create mode 100644 web/src/api/stats.ts create mode 100644 web/src/components/StatBars.tsx create mode 100644 web/src/pages/StatsPage.test.tsx create mode 100644 web/src/pages/StatsPage.tsx diff --git a/README.md b/README.md index 4d882bd..7246136 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ It is a single executable, one database (SQLite by default, PostgreSQL if you pr - **Importing from Spotify.** `POST /me/import/spotify` brings your listening history and your playlists from a Spotify data export into your own account. Ask Spotify for your data (Account, Privacy, "Extended streaming history" and "Account data") and send what it gives, as a multipart form with a `files` field for each file: the zip itself, or the JSON files in it (`Streaming_History_Audio_*.json`, the older `StreamingHistory_music_*.json` and `Playlist*.json`); a request may be up to 512 MB, and the rest of the export (the account, the searches, the library) is never opened. It all happens on your server and nothing is sent anywhere; the files are read from the request and not kept, and of each play only the song, the artist, the album, the time and how it ended are read, never the IP addresses, the country or the platform in the file. Of a play of a song you do not have that counts as listened, the name of the artist and the time are kept (and nothing else), so that Sonda can learn which artists you play together. A play is matched to a song of your library by artist and title (case, accents and punctuation do not matter, a `Remastered` note on either side does not, any credited artist will do, and a play of a compilation is matched by its album when Spotify says `Various Artists`). A match is recorded as a listen at the time of the play: `complete` when it ran to its end (or nine tenths were played), `skip` when Spotify says it was skipped or it lasted less than a listen, `play` otherwise; nothing is posted to Mastodon. Importing the same files again records nothing twice, and the same play in the extended and in the older history is one. A playlist becomes a playlist of yours with the songs that were found, in order; one whose name you already have is left alone, and one with none of its songs in your library is not made. The report counts what was added, what was already there and what is not in your library (and lists those artists, most played first), so you can see what is missing. One import of yours runs at a time. The report is kept: `GET /me/import/spotify` lists your past imports, newest first, with the numbers of each (never the files). The web app has an Import page for the form and for those numbers. - **Suggestions from your own listening.** `GET /me/suggestions` learns which artists you play together: your history is split into sittings (plays less than 30 minutes apart) and two artists that turn up in the same sitting often are linked (a cosine over the sittings of each). It is a count over your own data, built on your server in a moment and again when plays are added, with no provider and nothing sent anywhere; it needs `discover_from_listening` in `PATCH /me/settings`. The model reads your listening events and the plays of artists you have no music of that an import kept (the artist and the time only). `library` are artists you have that go with what you play and that you did not play for two months; `missing` are artists you played at least three times and have no music of, the ones you play most that also go with what you play now first. Each says which of your artists it goes with. `POST /me/suggestions/wishlist` puts an artist you played on your wishlist by name (it is made without music and without a MusicBrainz id: Sonda never looks one up by name, so it cannot be sent to Lidarr from here). The web app has a "From your listening" tab in Discover. - **Listening history by year and month.** `GET /listens/months` says how many listens that count you made in each calendar month, newest first, in the time zone you send as `tz` (UTC without it), and `GET /listens` takes `from` and `until` to read the listens of one of them; each listen now names its artists. The web app has a History page: a button for each year, the months of the year as bars, and the listens of the month a day at a time. +- **Statistics.** `GET /stats/library` says what the server holds: the songs that can be played (a song whose file is missing is not counted), their artists, albums, total length and the space their files take, the files by format, and the share of each genre (a song with several genres is split between them, so the shares add up to 1) and of each decade. `GET /stats/listening` says what you listened to, for all time or from `from` to `until` (dates with an offset, `until` excluded): the listens that count, the time listened, the songs and artists, the listens of each year, hour of the day and weekday in the time zone `tz`, your top ten artists and songs, and the share of each genre. Nobody else's listens are visible. The web app shows both on the Statistics page. - **Requests to Lidarr.** `GET /lidarr/requests` (admin) lists the artists you sent to your Lidarr with `POST /artists/{id}/lidarr`, newest first, and says for each whether its music has arrived: `waiting` while there is none in the library, `arrived` once a scan found some (by the artist you sent or by an artist of the same name; the day it was first noticed is kept). Sending an artist again keeps one request with the first date; only what you sent from Sonda is listed. The web app has a Requests page (admins only), with the waiting and the arrived artists apart. - **Sharing on Mastodon.** `PUT /me/mastodon` connects your own Mastodon account (the address of your instance and an access token that can only write posts); `GET` shows which account is connected and `DELETE` forgets it and the token. Nothing is connected by default. Once it is, each song of this server that counts as a listen is posted to your account as an unlisted status with the title, artists, album and `#NowPlaying`, and no link: at most one post a minute, never music of a friend. The token stays on the server and is never sent back. If the instance refuses the token on a post (it was revoked or expired), `GET /me/mastodon` says `problem: token_refused`, Settings shows it, and nothing is posted until you connect again with a new token. The address of the instance must be a domain name on https, and the server never connects to a private, loopback or link-local address for it, never follows a redirect and ignores proxy settings. - **Tags.** `GET /artists/{id}/tags` shows what Last.fm and MusicBrainz say kind of music an artist plays, each with its own weights, and the genres of the artist's own files, read offline. See [External providers](#external-providers). @@ -290,6 +291,7 @@ Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"er | Who | Method and path | What it does | |---|---|---| | anyone | `GET /health` | Liveness check. | +| signed in | `GET /version` | The version of Sonda and, when the binary knows it, the commit it was built from. The web app shows it under the menu and in Settings. | | anyone | `POST /auth/register` | Create the first user (admin). Closed afterwards. | | anyone | `POST /auth/login`, `/auth/refresh`, `/auth/logout` | Open, renew and end a session. | | signed in | `GET /auth/me`, `POST /auth/password` | Your account; change your password (signs you out everywhere). | @@ -301,6 +303,7 @@ Everything lives under `/api/v1`. Bodies are JSON. Errors always look like `{"er | signed in | `GET`, `HEAD /tracks/{id}/stream` | Stream the original file. Also accepts `?access_token=`. | | signed in | `POST /listens` | Record a `play`, `complete` or `skip`; the answer says whether it counts as a listen. | | signed in | `GET /listens` | Your own history, newest first, with `counted` per event. Query: `limit`, `offset`, `counted=true`. | +| signed in | `GET /stats/library`, `GET /stats/listening` | What the library holds; what you listened to, for all time or a period. Query of the second: `from`, `until`, `tz`. | | signed in | `GET /discover` | Artists you may like, with a score and its parts. Query: `seed` (an artist id, up to 5 times), `limit` (default 20, max 30), `in_library=true\|false`. | | signed in | `GET`, `HEAD /albums/{id}/cover` | The cover of an album, a JPEG made from your own files. Query: `size=small\|large`. Also accepts `?access_token=`. | | signed in | `GET /mixes`, `GET /mixes/{id}`, `POST /mixes/{id}/playlist` | Your mixes: list them, read one (query `variant`), keep one as a playlist. Made for you alone, from your history and your genres; nothing is stored. | diff --git a/cmd/sondad/main.go b/cmd/sondad/main.go index 9007f31..3daf6ef 100644 --- a/cmd/sondad/main.go +++ b/cmd/sondad/main.go @@ -45,6 +45,7 @@ import ( "git.kmalloc.org/squid/sonda/internal/providers/wikipedia" "git.kmalloc.org/squid/sonda/internal/smart" "git.kmalloc.org/squid/sonda/internal/spotifyimport" + "git.kmalloc.org/squid/sonda/internal/stats" "git.kmalloc.org/squid/sonda/internal/storage" "git.kmalloc.org/squid/sonda/internal/streaming" "git.kmalloc.org/squid/sonda/internal/taste" @@ -300,6 +301,7 @@ func run() error { router := httpapi.NewRouter(httpapi.Deps{ Logger: logger, Build: build(), + Stats: stats.NewService(storage.NewStatsRepo(db), cfg.Listening.MinListen()), Auth: auth.NewService(storage.NewUserRepo(db), storage.NewRefreshRepo(db), tokens, cfg.Auth.RefreshTTL()), Tokens: tokens, Listening: listening.NewService(storage.NewListeningRepo(db), cfg.Listening.MinListen()), diff --git a/internal/api/http/api_test.go b/internal/api/http/api_test.go index f44c16c..33a6d76 100644 --- a/internal/api/http/api_test.go +++ b/internal/api/http/api_test.go @@ -37,6 +37,7 @@ import ( "git.kmalloc.org/squid/sonda/internal/providers/lidarr" "git.kmalloc.org/squid/sonda/internal/smart" "git.kmalloc.org/squid/sonda/internal/spotifyimport" + "git.kmalloc.org/squid/sonda/internal/stats" "git.kmalloc.org/squid/sonda/internal/storage" "git.kmalloc.org/squid/sonda/internal/streaming" "git.kmalloc.org/squid/sonda/internal/taste" @@ -152,6 +153,9 @@ func newTestEnvDB(t *testing.T, mutate func(*Deps, *bun.DB)) (http.Handler, *bun } } // Built from the final services, so a test that swaps one gets a Discover that uses it. + if deps.Stats == nil { + deps.Stats = stats.NewService(storage.NewStatsRepo(db), 20*time.Second) + } if deps.Suggestions == nil { repo := storage.NewAffinityRepo(db) deps.Suggestions = affinity.NewService(repo, repo, feedbackSvc, repo, usersettings.NewService(storage.NewUserSettingsRepo(db)), 20*time.Second) diff --git a/internal/api/http/contract_test.go b/internal/api/http/contract_test.go index 85fdd53..6b9637b 100644 --- a/internal/api/http/contract_test.go +++ b/internal/api/http/contract_test.go @@ -363,6 +363,13 @@ func TestResponsesMatchTheSpec(t *testing.T) { c.expect(c.call("GET", "/version", "", nil), 401, "version without token", "unauthorized") c.expect(c.call("GET", "/version", token, nil), 200, "version") + c.expect(c.call("GET", "/stats/library", "", nil), 401, "library stats without token", "unauthorized") + c.expect(c.call("GET", "/stats/library", token, nil), 200, "library stats") + c.expect(c.call("GET", "/stats/listening", "", nil), 401, "listening stats without token", "unauthorized") + c.expect(c.call("GET", "/stats/listening", token, nil), 200, "listening stats") + c.expect(c.call("GET", "/stats/listening?tz=Europe/Rome&from=2025-01-01T00:00:00Z", token, nil), 200, "listening stats of a period") + c.expect(c.call("GET", "/stats/listening?tz=Mars/Base", token, nil), 400, "listening stats bad zone", "invalid_input") + renewed := c.expect(c.call("POST", "/auth/refresh", "", map[string]string{"refresh_token": refresh}), 200, "refresh") c.expect(c.call("POST", "/auth/refresh", "", map[string]string{"refresh_token": refresh}), 401, "refresh replay", "invalid_refresh_token") c.expect(c.call("POST", "/auth/refresh", "", "not an object"), 400, "refresh bad body", "invalid_input") diff --git a/internal/api/http/handlers_stats.go b/internal/api/http/handlers_stats.go new file mode 100644 index 0000000..a2cb1fd --- /dev/null +++ b/internal/api/http/handlers_stats.go @@ -0,0 +1,126 @@ +package httpapi + +import ( + "context" + "errors" + "net/http" + "time" + + "github.com/gin-gonic/gin" + + "git.kmalloc.org/squid/sonda/internal/stats" +) + +type statsService interface { + Library(ctx context.Context) (stats.Library, error) + Listening(ctx context.Context, userID int64, r stats.Range, loc *time.Location) (stats.Listening, error) +} + +type statsHandlers struct{ svc statsService } + +type sharesJSON struct { + Top []shareJSON `json:"top"` + Other float64 `json:"other"` + Untagged int `json:"untagged"` + UntaggedShare float64 `json:"untagged_share"` +} + +type shareJSON struct { + Name string `json:"name"` + Count int `json:"count"` + Share float64 `json:"share"` +} + +func genresJSON(g stats.Genres) sharesJSON { + out := sharesJSON{Top: make([]shareJSON, 0, len(g.Top)), Other: g.Other, Untagged: g.Untagged, UntaggedShare: g.UntaggedShare} + for _, s := range g.Top { + out.Top = append(out.Top, shareJSON{Name: s.Name, Count: s.Count, Share: s.Share}) + } + return out +} + +// library says what the server holds: the songs that can be played, their length and size, formats, genres and decades. +func (h *statsHandlers) library(c *gin.Context) { + lib, err := h.svc.Library(c.Request.Context()) + if err != nil { + _ = c.Error(err) + writeError(c, http.StatusInternalServerError, "internal", "internal error") + return + } + formats := make([]gin.H, 0, len(lib.Formats)) + for _, f := range lib.Formats { + formats = append(formats, gin.H{"format": f.Format, "files": f.Files, "bytes": f.Bytes}) + } + decades := make([]gin.H, 0, len(lib.Decades)) + for _, d := range lib.Decades { + decades = append(decades, gin.H{"decade": d.Decade, "songs": d.Songs}) + } + c.JSON(http.StatusOK, gin.H{ + "artists": lib.Artists, "albums": lib.Albums, "songs": lib.Songs, + "duration_ms": lib.DurationMs, "size_bytes": lib.SizeBytes, + "formats": formats, "genres": genresJSON(lib.Genres), "decades": decades, "no_year": lib.NoYear, + }) +} + +// listening says what the signed-in person listened to, for all time or for from (included) to until (excluded). The +// hours, weekdays and years are those of tz. +func (h *statsHandlers) listening(c *gin.Context) { + var rng stats.Range + for name, into := range map[string]*time.Time{"from": &rng.From, "until": &rng.Until} { + if raw := c.Query(name); raw != "" { + t, err := time.Parse(time.RFC3339, raw) + if err != nil { + writeError(c, http.StatusBadRequest, "invalid_input", name+" must be a date and time like 2025-03-01T00:00:00Z") + return + } + *into = t + } + } + if !rng.From.IsZero() && !rng.Until.IsZero() && rng.Until.Before(rng.From) { + writeError(c, http.StatusBadRequest, "invalid_input", "until must not be before from") + return + } + loc := time.UTC + if name := c.Query("tz"); name != "" { + var err error + if loc, err = time.LoadLocation(name); err != nil { + writeError(c, http.StatusBadRequest, "invalid_input", "tz must be a time zone like Europe/Rome") + return + } + } + got, err := h.svc.Listening(c.Request.Context(), currentUserID(c), rng, loc) + if errors.Is(err, stats.ErrInvalidRange) { + writeError(c, http.StatusBadRequest, "invalid_input", "until must not be before from") + return + } + if err != nil { + _ = c.Error(err) + writeError(c, http.StatusInternalServerError, "internal", "internal error") + return + } + years := make([]gin.H, 0, len(got.Years)) + for _, y := range got.Years { + years = append(years, gin.H{"year": y.Key, "listens": y.Count}) + } + artists := make([]gin.H, 0, len(got.TopArtists)) + for _, a := range got.TopArtists { + artists = append(artists, gin.H{"id": a.ID, "name": a.Name, "listens": a.Listens}) + } + songs := make([]gin.H, 0, len(got.TopSongs)) + for _, s := range got.TopSongs { + names := s.Artists + if names == nil { + names = []string{} + } + songs = append(songs, gin.H{"id": s.ID, "title": s.Name, "artists": names, "listens": s.Listens}) + } + body := gin.H{ + "listens": got.Listens, "songs": got.Songs, "artists": got.Artists, "played_ms": got.PlayedMs, + "years": years, "hours": got.Hours, "weekdays": got.Weekdays, + "top_artists": artists, "top_songs": songs, "genres": genresJSON(got.Genres), + } + if !got.First.IsZero() { + body["first"] = got.First.UTC().Format(time.RFC3339) + } + c.JSON(http.StatusOK, body) +} diff --git a/internal/api/http/handlers_stats_test.go b/internal/api/http/handlers_stats_test.go new file mode 100644 index 0000000..a8bb8e2 --- /dev/null +++ b/internal/api/http/handlers_stats_test.go @@ -0,0 +1,145 @@ +package httpapi + +import ( + "context" + "net/http" + "testing" + "time" + + "git.kmalloc.org/squid/sonda/internal/stats" +) + +type fakeStats struct { + library stats.Library + listening stats.Listening + err error + user int64 + rng stats.Range + loc *time.Location +} + +func (f *fakeStats) Library(context.Context) (stats.Library, error) { return f.library, f.err } +func (f *fakeStats) Listening(_ context.Context, user int64, r stats.Range, loc *time.Location) (stats.Listening, error) { + f.user, f.rng, f.loc = user, r, loc + return f.listening, f.err +} + +func statsAPI(t *testing.T, f *fakeStats) (http.Handler, string) { + t.Helper() + h := newTestAPIWith(t, func(d *Deps) { d.Stats = f }) + return h, registerAndLogin(t, h) +} + +func TestStatsAreForSignedInUsers(t *testing.T) { + h, _ := statsAPI(t, &fakeStats{}) + for _, p := range []string{"/api/v1/stats/library", "/api/v1/stats/listening"} { + if r := do(t, h, "GET", p, "", nil); r.Code != http.StatusUnauthorized { + t.Errorf("%s without a token: %d", p, r.Code) + } + } +} + +func TestTheLibraryStatsAreAnswered(t *testing.T) { + f := &fakeStats{library: stats.Library{ + Totals: stats.Totals{Artists: 2, Albums: 3, Songs: 40, DurationMs: 9_000_000, SizeBytes: 123456}, + Formats: []stats.Format{{Format: "flac", Files: 30, Bytes: 100000}}, + Genres: stats.Genres{Top: []stats.Share{{Name: "rock", Count: 20, Share: 0.5}}, Other: 0.25, Untagged: 10, UntaggedShare: 0.25}, + Decades: []stats.Decade{{Decade: 1990, Songs: 12}}, + NoYear: 4, + }} + h, tok := statsAPI(t, f) + r := do(t, h, "GET", "/api/v1/stats/library", tok, nil) + if r.Code != 200 { + t.Fatalf("%d %v", r.Code, r.Body) + } + if r.Body["songs"] != 40.0 || r.Body["albums"] != 3.0 || r.Body["artists"] != 2.0 || r.Body["duration_ms"] != 9000000.0 || r.Body["size_bytes"] != 123456.0 || r.Body["no_year"] != 4.0 { + t.Errorf("body = %v", r.Body) + } + formats, _ := r.Body["formats"].([]any) + if len(formats) != 1 || formats[0].(map[string]any)["format"] != "flac" || formats[0].(map[string]any)["bytes"] != 100000.0 { + t.Errorf("formats = %v", r.Body["formats"]) + } + g := sub(r.Body, "genres") + top, _ := g["top"].([]any) + if len(top) != 1 || top[0].(map[string]any)["name"] != "rock" || top[0].(map[string]any)["share"] != 0.5 || g["other"] != 0.25 || g["untagged"] != 10.0 || g["untagged_share"] != 0.25 { + t.Errorf("genres = %v", g) + } + decades, _ := r.Body["decades"].([]any) + if len(decades) != 1 || decades[0].(map[string]any)["decade"] != 1990.0 || decades[0].(map[string]any)["songs"] != 12.0 { + t.Errorf("decades = %v", r.Body["decades"]) + } +} + +func TestTheListeningStatsAreAskedForThePersonAndThePeriod(t *testing.T) { + first := time.Date(2020, 5, 1, 10, 0, 0, 0, time.UTC) + f := &fakeStats{listening: stats.Listening{ + Listens: 5, Songs: 3, Artists: 2, PlayedMs: 900_000, First: first, + Years: []stats.Bucket{{Key: 2020, Count: 5}}, + TopArtists: []stats.Ranked{{ID: 1, Name: "Blur", Listens: 3}}, + TopSongs: []stats.Ranked{{ID: 9, Name: "Song 2", Artists: []string{"Blur"}, Listens: 2}}, + Genres: stats.Genres{Top: []stats.Share{}}, + }} + f.listening.Hours[21] = 5 + f.listening.Weekdays[2] = 5 + h, tok := statsAPI(t, f) + r := do(t, h, "GET", "/api/v1/stats/listening?from=2025-01-01T00:00:00Z&until=2026-01-01T00:00:00Z&tz=Europe/Rome", tok, nil) + if r.Code != 200 { + t.Fatalf("%d %v", r.Code, r.Body) + } + if f.user == 0 || !f.rng.From.Equal(time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)) || !f.rng.Until.Equal(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)) { + t.Errorf("asked for user %d, %+v", f.user, f.rng) + } + if f.loc == nil || f.loc.String() != "Europe/Rome" { + t.Errorf("zone = %v", f.loc) + } + b := r.Body + if b["listens"] != 5.0 || b["songs"] != 3.0 || b["artists"] != 2.0 || b["played_ms"] != 900000.0 || b["first"] != "2020-05-01T10:00:00Z" { + t.Errorf("body = %v", b) + } + hours, _ := b["hours"].([]any) + weekdays, _ := b["weekdays"].([]any) + if len(hours) != 24 || hours[21] != 5.0 || len(weekdays) != 7 || weekdays[2] != 5.0 { + t.Errorf("hours %v weekdays %v", b["hours"], b["weekdays"]) + } + years, _ := b["years"].([]any) + if len(years) != 1 || years[0].(map[string]any)["year"] != 2020.0 || years[0].(map[string]any)["listens"] != 5.0 { + t.Errorf("years = %v", b["years"]) + } + artists, _ := b["top_artists"].([]any) + songs, _ := b["top_songs"].([]any) + if len(artists) != 1 || artists[0].(map[string]any)["name"] != "Blur" || artists[0].(map[string]any)["id"] != 1.0 { + t.Errorf("artists = %v", b["top_artists"]) + } + s0, _ := songs[0].(map[string]any) + if s0["title"] != "Song 2" || s0["listens"] != 2.0 || s0["id"] != 9.0 || s0["artists"].([]any)[0] != "Blur" { + t.Errorf("songs = %v", b["top_songs"]) + } +} + +func TestListeningStatsWithNoListensLeaveOutTheFirstDay(t *testing.T) { + f := &fakeStats{listening: stats.Listening{Years: []stats.Bucket{}, TopArtists: []stats.Ranked{}, TopSongs: []stats.Ranked{}, Genres: stats.Genres{Top: []stats.Share{}}}} + h, tok := statsAPI(t, f) + r := do(t, h, "GET", "/api/v1/stats/listening", tok, nil) + if r.Code != 200 { + t.Fatalf("%d %v", r.Code, r.Body) + } + if _, ok := r.Body["first"]; ok { + t.Errorf("first should be left out: %v", r.Body) + } + if f.loc == nil || f.loc != time.UTC { + t.Errorf("zone without tz = %v, want UTC", f.loc) + } + if a, ok := r.Body["top_artists"].([]any); !ok || len(a) != 0 { + t.Errorf("top_artists = %v, want []", r.Body["top_artists"]) + } +} + +func TestListeningStatsRefuseABadQuery(t *testing.T) { + h, tok := statsAPI(t, &fakeStats{}) + for _, q := range []string{"tz=Mars/Base", "from=yesterday", "until=2026", "from=2026-01-01T00:00:00Z&until=2025-01-01T00:00:00Z"} { + r := do(t, h, "GET", "/api/v1/stats/listening?"+q, tok, nil) + if r.Code != http.StatusBadRequest || errCode(r) != "invalid_input" { + t.Errorf("%s: %d %v", q, r.Code, r.Body) + } + } +} diff --git a/internal/api/http/router.go b/internal/api/http/router.go index 35edd03..2be2fa1 100644 --- a/internal/api/http/router.go +++ b/internal/api/http/router.go @@ -242,6 +242,7 @@ type Deps struct { Feedback feedbackService Playlists playlistService SpotifyImport spotifyImportService + Stats statsService Suggestions listeningSuggestionService Mixes mixService Smart smartService @@ -322,6 +323,9 @@ func NewRouter(d Deps) *gin.Engine { protected.GET("/listens", l.list) protected.GET("/listens/months", l.months) + sts := &statsHandlers{svc: d.Stats} + protected.GET("/stats/library", sts.library) + protected.GET("/stats/listening", sts.listening) sg := &listeningSuggestionHandlers{svc: d.Suggestions} protected.GET("/me/suggestions", sg.list) protected.POST("/me/suggestions/wishlist", sg.wish) diff --git a/internal/api/openapi/openapi.yaml b/internal/api/openapi/openapi.yaml index 31f8031..4731220 100644 --- a/internal/api/openapi/openapi.yaml +++ b/internal/api/openapi/openapi.yaml @@ -3222,6 +3222,58 @@ paths: application/json: schema: {$ref: '#/components/schemas/Error'} + /stats/library: + get: + tags: [Playback] + operationId: getLibraryStats + summary: What the library holds + description: | + The songs that can be played (a song whose file is missing is not counted), with their artists, albums, total + length and the space their files take, the files by format, the share of each genre and of each decade. The + genre shares count a song with several genres once, split between them, so `top`, `other` and + `untagged_share` add up to 1. The genres are the tags of the files, read offline. + security: [{bearerAuth: []}] + responses: + '200': + description: The numbers. + content: + application/json: + schema: {$ref: '#/components/schemas/LibraryStats'} + '401': {$ref: '#/components/responses/Unauthorized'} + + /stats/listening: + get: + tags: [Playback] + operationId: getListeningStats + summary: What you listened to + description: | + Your listens that count (see `POST /listens`), for all time or for a period: how many, how long, how many + songs and artists, the listens of each year (a year with none between the first and the last is 0), of each + hour of the day and of each weekday (Monday first), your most listened artists and songs, and the share of each + genre. Years, hours and weekdays are counted in the time zone `tz`. Nobody else's listens are visible. + security: [{bearerAuth: []}] + parameters: + - name: from + in: query + description: The start of the period, included, as a date and time with an offset. + schema: {type: string, format: date-time} + - name: until + in: query + description: The end of the period, excluded. It must not be before `from`. + schema: {type: string, format: date-time} + - name: tz + in: query + description: An IANA time zone name, like `Europe/Rome`. Anything else is `invalid_input`. + schema: {type: string, default: UTC} + responses: + '200': + description: The numbers. + content: + application/json: + schema: {$ref: '#/components/schemas/ListeningStats'} + '400': {$ref: '#/components/responses/InvalidInput'} + '401': {$ref: '#/components/responses/Unauthorized'} + /listens/months: get: tags: [Playback] @@ -5117,6 +5169,114 @@ components: name: {type: string} score: {type: number} + GenreShares: + type: object + additionalProperties: false + required: [top, other, untagged, untagged_share] + description: The share of each genre. `top`, `other` and `untagged_share` add up to 1. + properties: + top: + type: array + description: The ten biggest, biggest first. + items: + type: object + additionalProperties: false + required: [name, count, share] + properties: + name: {type: string} + count: {type: integer, description: How many songs (or listens) have this genre.} + share: {type: number, minimum: 0, maximum: 1} + other: {type: number, minimum: 0, maximum: 1, description: What the smaller genres add up to.} + untagged: {type: integer, description: How many songs (or listens) have no genre.} + untagged_share: {type: number, minimum: 0, maximum: 1} + + LibraryStats: + type: object + additionalProperties: false + required: [artists, albums, songs, duration_ms, size_bytes, formats, genres, decades, no_year] + properties: + artists: {type: integer} + albums: {type: integer} + songs: {type: integer} + duration_ms: {type: integer, format: int64, description: The length of all the songs together.} + size_bytes: {type: integer, format: int64, description: The space of all the files that are not missing.} + formats: + type: array + items: + type: object + additionalProperties: false + required: [format, files, bytes] + properties: + format: {type: string, example: flac} + files: {type: integer} + bytes: {type: integer, format: int64} + genres: {$ref: '#/components/schemas/GenreShares'} + decades: + type: array + description: How many songs came out in each decade, oldest first. 1990 is the nineties. + items: + type: object + additionalProperties: false + required: [decade, songs] + properties: + decade: {type: integer, example: 1990} + songs: {type: integer} + no_year: {type: integer, description: Songs whose file has no year.} + + ListeningStats: + type: object + additionalProperties: false + required: [listens, songs, artists, played_ms, years, hours, weekdays, top_artists, top_songs, genres] + properties: + listens: {type: integer} + songs: {type: integer, description: How many different songs.} + artists: {type: integer, description: How many different artists.} + played_ms: {type: integer, format: int64, description: The time listened to.} + first: {type: string, format: date-time, description: The first listen of the period. Left out when there is none.} + years: + type: array + items: + type: object + additionalProperties: false + required: [year, listens] + properties: + year: {type: integer} + listens: {type: integer} + hours: + type: array + minItems: 24 + maxItems: 24 + description: Listens in each hour of the day, from midnight. + items: {type: integer} + weekdays: + type: array + minItems: 7 + maxItems: 7 + description: Listens on each weekday, from Monday. + items: {type: integer} + top_artists: + type: array + items: + type: object + additionalProperties: false + required: [id, name, listens] + properties: + id: {type: integer, format: int64} + name: {type: string} + listens: {type: integer} + top_songs: + type: array + items: + type: object + additionalProperties: false + required: [id, title, artists, listens] + properties: + id: {type: integer, format: int64} + title: {type: string} + artists: {type: array, items: {type: string}} + listens: {type: integer} + genres: {$ref: '#/components/schemas/GenreShares'} + ListeningSuggestions: type: object additionalProperties: false diff --git a/internal/stats/stats.go b/internal/stats/stats.go new file mode 100644 index 0000000..1fdfa8d --- /dev/null +++ b/internal/stats/stats.go @@ -0,0 +1,292 @@ +// Package stats works out the numbers of the statistics page: what the library holds, and what a listener listened to. +// +// The store gives raw counts; the shares, the decades, the years with no listens and the hours and weekdays (which +// depend on the time zone of the listener) are worked out here, so that SQLite and PostgreSQL give the same answer. +package stats + +import ( + "context" + "errors" + "sort" + "time" +) + +// ErrInvalidRange is returned when a period ends before it starts. +var ErrInvalidRange = errors.New("the period ends before it starts") + +const ( + // topGenres is how many genres are named; the rest are one "other" share. + topGenres = 10 + // topRanked is how many artists and songs the lists have. + topRanked = 10 + // A year outside these is not a year a song came out: a bad tag. + minYear, maxYear = 1000, 2999 +) + +// Range is a period: From is included and Until is excluded. A zero time leaves that side open. +type Range struct{ From, Until time.Time } + +// Totals is what the library holds that can be played. +type Totals struct { + Artists, Albums, Songs int + DurationMs, SizeBytes int64 +} + +// FormatCount is how many files of a format there are, and the space they take. +type FormatCount struct { + Format string + Files int + Bytes int64 +} + +// GenreWeight is one genre: how many items (songs, or listens) have it, and their weight. An item that has several +// genres is split between them, so that the weights of all the genres add up to the items that have any. +type GenreWeight struct { + Genre string + Songs int + Weight float64 +} + +// YearCount is how many songs came out in a year. +type YearCount struct{ Year, Songs int } + +// ListenTotals sums up the listens in a period. +type ListenTotals struct { + Listens, Songs, Artists int + PlayedMs int64 + First int64 // unix seconds of the first listen, 0 when there is none +} + +// Ranked is an artist or a song with how often it was listened to. +type Ranked struct { + ID int64 + Name string + Artists []string // the artists of a song + Listens int +} + +// Store reads the raw counts. A listen is a complete event, or a play of at least minMs. +type Store interface { + Totals(ctx context.Context) (Totals, error) + Formats(ctx context.Context) ([]FormatCount, error) + // Genres gives the weight of each genre in the playable songs, and how many songs have at least one. + Genres(ctx context.Context) ([]GenreWeight, int, error) + Years(ctx context.Context) ([]YearCount, error) + + ListenTotals(ctx context.Context, userID, minMs int64, r Range) (ListenTotals, error) + // ListenTimes gives the moment of every listen, in unix seconds. + ListenTimes(ctx context.Context, userID, minMs int64, r Range) ([]int64, error) + TopArtists(ctx context.Context, userID, minMs int64, r Range, limit int) ([]Ranked, error) + TopSongs(ctx context.Context, userID, minMs int64, r Range, limit int) ([]Ranked, error) + // ListenGenres gives the weight of each genre in the listens, and how many listens have at least one. + ListenGenres(ctx context.Context, userID, minMs int64, r Range) ([]GenreWeight, int, error) +} + +// Share is a genre and how much of the whole it is, from 0 to 1. +type Share struct { + Name string + Count int + Share float64 +} + +// Genres is the share of each genre. Top are the biggest, Other is what the smaller ones add up to, and Untagged is the +// part that has no genre at all. Top, Other and Untagged add up to 1. +type Genres struct { + Top []Share + Other float64 + Untagged int + UntaggedShare float64 +} + +// Format is the files of one format. +type Format struct { + Format string + Files int + Bytes int64 +} + +// Decade is how many songs came out in a decade: 1990 is the nineties. +type Decade struct{ Decade, Songs int } + +// Library is what the server holds. +type Library struct { + Totals + Formats []Format + Genres Genres + Decades []Decade + NoYear int // songs whose file has no year +} + +// Bucket is a count under a key: a year. +type Bucket struct{ Key, Count int } + +// Listening is what a person listened to in a period. +type Listening struct { + Listens, Songs, Artists int + PlayedMs int64 + First time.Time // the zero time when there is no listen + Years []Bucket + Hours [24]int // from midnight, in the time zone of the listener + Weekdays [7]int // from Monday + TopArtists, TopSongs []Ranked + Genres Genres +} + +// Service works out the statistics. +type Service struct { + store Store + minListen time.Duration +} + +// NewService returns a service. minListen is the least a play must last to count as a listen. +func NewService(store Store, minListen time.Duration) *Service { + return &Service{store: store, minListen: minListen} +} + +// Library describes what the library holds. +func (s *Service) Library(ctx context.Context) (Library, error) { + totals, err := s.store.Totals(ctx) + if err != nil { + return Library{}, err + } + formats, err := s.store.Formats(ctx) + if err != nil { + return Library{}, err + } + weights, tagged, err := s.store.Genres(ctx) + if err != nil { + return Library{}, err + } + years, err := s.store.Years(ctx) + if err != nil { + return Library{}, err + } + + out := Library{Totals: totals, Formats: []Format{}, Genres: shapeGenres(weights, tagged, totals.Songs)} + for _, f := range formats { + out.Formats = append(out.Formats, Format(f)) + } + sort.SliceStable(out.Formats, func(i, j int) bool { return out.Formats[i].Files > out.Formats[j].Files }) + out.Decades, out.NoYear = decades(years, totals.Songs) + return out, nil +} + +// Listening describes what a person listened to in a period. Hours, weekdays and years are those of loc. +func (s *Service) Listening(ctx context.Context, userID int64, r Range, loc *time.Location) (Listening, error) { + if !r.From.IsZero() && !r.Until.IsZero() && r.Until.Before(r.From) { + return Listening{}, ErrInvalidRange + } + if loc == nil { + loc = time.UTC + } + minMs := s.minListen.Milliseconds() + totals, err := s.store.ListenTotals(ctx, userID, minMs, r) + if err != nil { + return Listening{}, err + } + times, err := s.store.ListenTimes(ctx, userID, minMs, r) + if err != nil { + return Listening{}, err + } + artists, err := s.store.TopArtists(ctx, userID, minMs, r, topRanked) + if err != nil { + return Listening{}, err + } + songs, err := s.store.TopSongs(ctx, userID, minMs, r, topRanked) + if err != nil { + return Listening{}, err + } + weights, tagged, err := s.store.ListenGenres(ctx, userID, minMs, r) + if err != nil { + return Listening{}, err + } + + out := Listening{ + Listens: totals.Listens, Songs: totals.Songs, Artists: totals.Artists, PlayedMs: totals.PlayedMs, + Years: []Bucket{}, + TopArtists: nonNil(artists), TopSongs: nonNil(songs), + Genres: shapeGenres(weights, tagged, totals.Listens), + } + if totals.First > 0 { + out.First = time.Unix(totals.First, 0) + } + perYear := map[int]int{} + for _, at := range times { + t := time.Unix(at, 0).In(loc) + perYear[t.Year()]++ + out.Hours[t.Hour()]++ + out.Weekdays[(int(t.Weekday())+6)%7]++ + } + out.Years = yearBuckets(perYear) + return out, nil +} + +func nonNil(r []Ranked) []Ranked { + if r == nil { + return []Ranked{} + } + return r +} + +// yearBuckets lists every year from the first to the last that has a listen, the ones with none as zero. +func yearBuckets(perYear map[int]int) []Bucket { + out := []Bucket{} + if len(perYear) == 0 { + return out + } + first, last := 1<<31-1, 0 + for y := range perYear { + first, last = min(first, y), max(last, y) + } + for y := first; y <= last; y++ { + out = append(out, Bucket{Key: y, Count: perYear[y]}) + } + return out +} + +// shapeGenres turns the weights into shares of total, the items counted, tagged of which have a genre. +func shapeGenres(weights []GenreWeight, tagged, total int) Genres { + out := Genres{Top: []Share{}} + if total <= 0 { + return out + } + sorted := append([]GenreWeight(nil), weights...) + sort.Slice(sorted, func(i, j int) bool { + if sorted[i].Weight != sorted[j].Weight { + return sorted[i].Weight > sorted[j].Weight + } + return sorted[i].Genre < sorted[j].Genre + }) + whole := float64(total) + for i, w := range sorted { + if i < topGenres { + out.Top = append(out.Top, Share{Name: w.Genre, Count: w.Songs, Share: w.Weight / whole}) + } else { + out.Other += w.Weight / whole + } + } + if out.Untagged = total - tagged; out.Untagged < 0 { + out.Untagged = 0 + } + out.UntaggedShare = float64(out.Untagged) / whole + return out +} + +// decades groups the years of the songs; the songs left over, with no year or a bad one, are returned apart. +func decades(years []YearCount, songs int) ([]Decade, int) { + by := map[int]int{} + dated := 0 + for _, y := range years { + if y.Year < minYear || y.Year > maxYear { + continue + } + by[y.Year/10*10] += y.Songs + dated += y.Songs + } + out := make([]Decade, 0, len(by)) + for d, n := range by { + out = append(out, Decade{Decade: d, Songs: n}) + } + sort.Slice(out, func(i, j int) bool { return out[i].Decade < out[j].Decade }) + return out, max(songs-dated, 0) +} diff --git a/internal/stats/stats_test.go b/internal/stats/stats_test.go new file mode 100644 index 0000000..4332ef2 --- /dev/null +++ b/internal/stats/stats_test.go @@ -0,0 +1,208 @@ +package stats + +import ( + "context" + "errors" + "fmt" + "math" + "testing" + "time" +) + +type fakeStore struct { + totals Totals + formats []FormatCount + genres []GenreWeight + tagged int + years []YearCount + listen ListenTotals + times []int64 + artists []Ranked + songs []Ranked + gotRange Range + gotMinMs int64 + gotUserID int64 +} + +func (f *fakeStore) Totals(context.Context) (Totals, error) { return f.totals, nil } +func (f *fakeStore) Formats(context.Context) ([]FormatCount, error) { return f.formats, nil } +func (f *fakeStore) Years(context.Context) ([]YearCount, error) { return f.years, nil } +func (f *fakeStore) Genres(context.Context) ([]GenreWeight, int, error) { + return f.genres, f.tagged, nil +} +func (f *fakeStore) note(userID, minMs int64, r Range) { + f.gotUserID, f.gotMinMs, f.gotRange = userID, minMs, r +} +func (f *fakeStore) ListenTotals(_ context.Context, u, m int64, r Range) (ListenTotals, error) { + f.note(u, m, r) + return f.listen, nil +} +func (f *fakeStore) ListenTimes(_ context.Context, u, m int64, r Range) ([]int64, error) { + f.note(u, m, r) + return f.times, nil +} +func (f *fakeStore) TopArtists(_ context.Context, u, m int64, r Range, _ int) ([]Ranked, error) { + f.note(u, m, r) + return f.artists, nil +} +func (f *fakeStore) TopSongs(_ context.Context, u, m int64, r Range, _ int) ([]Ranked, error) { + f.note(u, m, r) + return f.songs, nil +} +func (f *fakeStore) ListenGenres(_ context.Context, u, m int64, r Range) ([]GenreWeight, int, error) { + f.note(u, m, r) + return f.genres, f.tagged, nil +} + +func near(a, b float64) bool { return math.Abs(a-b) < 1e-9 } + +func TestLibraryGenresAreTheTenBiggestAndTheRest(t *testing.T) { + var genres []GenreWeight + for i := 0; i < 12; i++ { + genres = append(genres, GenreWeight{Genre: fmt.Sprintf("g%02d", i), Songs: 12 - i, Weight: float64(12 - i)}) + } + // 78 weight in all, 22 songs without a genre: 100 songs. + s := NewService(&fakeStore{totals: Totals{Songs: 100}, genres: genres, tagged: 78}, 20*time.Second) + lib, err := s.Library(context.Background()) + if err != nil { + t.Fatal(err) + } + g := lib.Genres + if len(g.Top) != 10 || g.Top[0].Name != "g00" || g.Top[9].Name != "g09" { + t.Fatalf("top = %+v", g.Top) + } + if !near(g.Top[0].Share, 0.12) || g.Top[0].Count != 12 { + t.Errorf("first = %+v", g.Top[0]) + } + if !near(g.Other, 0.03) { // g10 (2) + g11 (1) of 100 + t.Errorf("other = %v", g.Other) + } + if g.Untagged != 22 || !near(g.UntaggedShare, 0.22) { + t.Errorf("untagged = %d, %v", g.Untagged, g.UntaggedShare) + } +} + +func TestSharesOfAGenreThatSharesItsSongsAddUpToTheTaggedSongs(t *testing.T) { + // One song with two genres weighs half for each: 1 song in all. + s := NewService(&fakeStore{totals: Totals{Songs: 1}, genres: []GenreWeight{{"rock", 1, 0.5}, {"blues", 1, 0.5}}, tagged: 1}, time.Second) + lib, _ := s.Library(context.Background()) + if len(lib.Genres.Top) != 2 || !near(lib.Genres.Top[0].Share, 0.5) || !near(lib.Genres.Top[1].Share, 0.5) { + t.Errorf("%+v", lib.Genres) + } + if lib.Genres.Top[0].Name != "blues" { // equal weights: by name + t.Errorf("order: %+v", lib.Genres.Top) + } + if lib.Genres.Untagged != 0 || lib.Genres.Other != 0 { + t.Errorf("%+v", lib.Genres) + } +} + +func TestAnEmptyLibraryHasNoSharesAndNoNaN(t *testing.T) { + lib, err := NewService(&fakeStore{}, time.Second).Library(context.Background()) + if err != nil { + t.Fatal(err) + } + if lib.Songs != 0 || len(lib.Genres.Top) != 0 || lib.Genres.Other != 0 || lib.Genres.UntaggedShare != 0 { + t.Errorf("%+v", lib) + } + if lib.Formats == nil || lib.Decades == nil || lib.Genres.Top == nil { + t.Errorf("lists must be empty, not null: %+v", lib) + } +} + +func TestDecadesAreCountedFromTheYearsAndTheRestHaveNone(t *testing.T) { + s := NewService(&fakeStore{ + totals: Totals{Songs: 10}, + years: []YearCount{{1994, 2}, {1999, 3}, {2003, 1}, {0, 9}, {12, 1}}, + }, time.Second) + lib, _ := s.Library(context.Background()) + want := []Decade{{1990, 5}, {2000, 1}} + if len(lib.Decades) != 2 || lib.Decades[0] != want[0] || lib.Decades[1] != want[1] { + t.Errorf("decades = %+v", lib.Decades) + } + if lib.NoYear != 4 { // 10 songs, 6 with a believable year + t.Errorf("no year = %d", lib.NoYear) + } +} + +func TestListeningIsCountedInTheZoneOfTheListener(t *testing.T) { + rome, err := time.LoadLocation("Europe/Rome") + if err != nil { + t.Skip("no tzdata") + } + // 2025-12-31 23:30 UTC is already 2026-01-01 00:30 in Rome, a Thursday. + at := time.Date(2025, 12, 31, 23, 30, 0, 0, time.UTC).Unix() + st := &fakeStore{listen: ListenTotals{Listens: 1, First: at}, times: []int64{at}} + got, err := NewService(st, 20*time.Second).Listening(context.Background(), 7, Range{}, rome) + if err != nil { + t.Fatal(err) + } + if len(got.Years) != 1 || got.Years[0].Key != 2026 || got.Years[0].Count != 1 { + t.Errorf("years = %+v", got.Years) + } + if got.Hours[0] != 1 || got.Weekdays[3] != 1 { + t.Errorf("hours %v weekdays %v", got.Hours, got.Weekdays) + } + utc, _ := NewService(st, 20*time.Second).Listening(context.Background(), 7, Range{}, nil) + if utc.Years[0].Key != 2025 || utc.Hours[23] != 1 || utc.Weekdays[2] != 1 { // Wednesday + t.Errorf("utc: years %+v hours %v weekdays %v", utc.Years, utc.Hours, utc.Weekdays) + } + if st.gotUserID != 7 || st.gotMinMs != 20000 { + t.Errorf("asked for user %d, min %d", st.gotUserID, st.gotMinMs) + } +} + +func TestYearsWithoutListensBetweenTwoYearsAreShownAsZero(t *testing.T) { + y := func(year int) int64 { return time.Date(year, 6, 1, 12, 0, 0, 0, time.UTC).Unix() } + st := &fakeStore{listen: ListenTotals{Listens: 3, First: y(2019)}, times: []int64{y(2019), y(2019), y(2022)}} + got, _ := NewService(st, time.Second).Listening(context.Background(), 1, Range{}, time.UTC) + want := []Bucket{{2019, 2}, {2020, 0}, {2021, 0}, {2022, 1}} + if len(got.Years) != len(want) { + t.Fatalf("years = %+v", got.Years) + } + for i := range want { + if got.Years[i] != want[i] { + t.Errorf("years[%d] = %+v, want %+v", i, got.Years[i], want[i]) + } + } +} + +func TestListeningTotalsAndRankingsPassThrough(t *testing.T) { + first := time.Date(2020, 5, 1, 10, 0, 0, 0, time.UTC) + st := &fakeStore{ + listen: ListenTotals{Listens: 5, PlayedMs: 900_000, Songs: 3, Artists: 2, First: first.Unix()}, + artists: []Ranked{{ID: 1, Name: "Blur", Listens: 3}}, + songs: []Ranked{{ID: 9, Name: "Song 2", Artists: []string{"Blur"}, Listens: 2}}, + genres: []GenreWeight{{"rock", 5, 5}}, tagged: 5, + } + got, err := NewService(st, time.Second).Listening(context.Background(), 1, Range{}, time.UTC) + if err != nil { + t.Fatal(err) + } + if got.Listens != 5 || got.PlayedMs != 900_000 || got.Songs != 3 || got.Artists != 2 || !got.First.Equal(first) { + t.Errorf("%+v", got) + } + if len(got.TopArtists) != 1 || got.TopArtists[0].Name != "Blur" || len(got.TopSongs) != 1 { + t.Errorf("rankings: %+v %+v", got.TopArtists, got.TopSongs) + } + if len(got.Genres.Top) != 1 || !near(got.Genres.Top[0].Share, 1) { + t.Errorf("genres: %+v", got.Genres) + } +} + +func TestNoListensHaveNoFirstDayAndEmptyLists(t *testing.T) { + got, err := NewService(&fakeStore{}, time.Second).Listening(context.Background(), 1, Range{}, time.UTC) + if err != nil { + t.Fatal(err) + } + if !got.First.IsZero() || got.Years == nil || got.TopArtists == nil || got.TopSongs == nil || got.Genres.Top == nil { + t.Errorf("%+v", got) + } +} + +func TestARangeThatEndsBeforeItStartsIsRefused(t *testing.T) { + r := Range{From: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC), Until: time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)} + if _, err := NewService(&fakeStore{}, time.Second).Listening(context.Background(), 1, r, time.UTC); !errors.Is(err, ErrInvalidRange) { + t.Errorf("err = %v", err) + } +} diff --git a/internal/storage/stats.go b/internal/storage/stats.go new file mode 100644 index 0000000..601ad70 --- /dev/null +++ b/internal/storage/stats.go @@ -0,0 +1,256 @@ +package storage + +import ( + "context" + "fmt" + "sort" + + "github.com/uptrace/bun" + + "git.kmalloc.org/squid/sonda/internal/stats" +) + +// StatsRepo reads the counts behind the statistics page. Whatever is counted in "the library" is what can be played: +// a song with a file that is not missing. A listen is a complete event, or a play of at least minMs. +type StatsRepo struct{ db *bun.DB } + +// NewStatsRepo returns the repo. +func NewStatsRepo(db *bun.DB) *StatsRepo { return &StatsRepo{db: db} } + +var _ stats.Store = (*StatsRepo)(nil) + +// Totals counts what the library holds that can be played, and the space its files take. +func (r *StatsRepo) Totals(ctx context.Context) (stats.Totals, error) { + vis, _ := visible("t", 0) + var out stats.Totals + if err := r.db.QueryRowContext(ctx, "SELECT COUNT(*), COALESCE(SUM(t.duration_ms), 0) FROM tracks t WHERE "+vis).Scan(&out.Songs, &out.DurationMs); err != nil { + return out, fmt.Errorf("count songs: %w", err) + } + if err := r.db.QueryRowContext(ctx, "SELECT COUNT(*) FROM artists a WHERE "+playableArtist("a.id")).Scan(&out.Artists); err != nil { + return out, fmt.Errorf("count artists: %w", err) + } + if err := r.db.QueryRowContext(ctx, "SELECT COUNT(*) FROM albums al WHERE EXISTS (SELECT 1 FROM tracks t WHERE t.album_id = al.id AND "+vis+")").Scan(&out.Albums); err != nil { + return out, fmt.Errorf("count albums: %w", err) + } + if err := r.db.QueryRowContext(ctx, "SELECT COALESCE(SUM(size_bytes), 0) FROM audio_files WHERE missing_at IS NULL").Scan(&out.SizeBytes); err != nil { + return out, fmt.Errorf("sum sizes: %w", err) + } + return out, nil +} + +// Formats counts the files that are not missing by format. +func (r *StatsRepo) Formats(ctx context.Context) ([]stats.FormatCount, error) { + rows, err := r.db.QueryContext(ctx, + "SELECT LOWER(format), COUNT(*), COALESCE(SUM(size_bytes), 0) FROM audio_files WHERE missing_at IS NULL GROUP BY LOWER(format)") + if err != nil { + return nil, fmt.Errorf("count formats: %w", err) + } + defer rows.Close() + var out []stats.FormatCount + for rows.Next() { + var f stats.FormatCount + if err := rows.Scan(&f.Format, &f.Files, &f.Bytes); err != nil { + return nil, err + } + out = append(out, f) + } + return out, rows.Err() +} + +// weightedGenres adds up, for each genre, the items that have it. An item with several genres weighs 1/n for each. +// source is the FROM and WHERE of a query whose rows are items with the genre table joined as g and the count of genres +// of the item as c.n. +func (r *StatsRepo) weightedGenres(ctx context.Context, source string, args []any) ([]stats.GenreWeight, error) { + rows, err := r.db.QueryContext(ctx, "SELECT g.genre, COUNT(*), SUM(1.0 / c.n) "+source+" GROUP BY g.genre", args...) + if err != nil { + return nil, fmt.Errorf("weigh genres: %w", err) + } + defer rows.Close() + var out []stats.GenreWeight + for rows.Next() { + var g stats.GenreWeight + if err := rows.Scan(&g.Genre, &g.Songs, &g.Weight); err != nil { + return nil, err + } + out = append(out, g) + } + return out, rows.Err() +} + +const genresPerTrack = "(SELECT track_id, COUNT(*) AS n FROM track_genres GROUP BY track_id)" + +// Genres weighs the genres of the songs that can be played, and counts the songs that have one. +func (r *StatsRepo) Genres(ctx context.Context) ([]stats.GenreWeight, int, error) { + vis, _ := visible("t", 0) + out, err := r.weightedGenres(ctx, + "FROM track_genres g JOIN "+genresPerTrack+" c ON c.track_id = g.track_id JOIN tracks t ON t.id = g.track_id WHERE "+vis, nil) + if err != nil { + return nil, 0, err + } + var tagged int + if err := r.db.QueryRowContext(ctx, + "SELECT COUNT(DISTINCT g.track_id) FROM track_genres g JOIN tracks t ON t.id = g.track_id WHERE "+vis).Scan(&tagged); err != nil { + return nil, 0, fmt.Errorf("count tagged songs: %w", err) + } + return out, tagged, nil +} + +// Years counts the playable songs by the year in their tags. +func (r *StatsRepo) Years(ctx context.Context) ([]stats.YearCount, error) { + vis, _ := visible("t", 0) + rows, err := r.db.QueryContext(ctx, "SELECT t.year, COUNT(*) FROM tracks t WHERE t.year IS NOT NULL AND "+vis+" GROUP BY t.year") + if err != nil { + return nil, fmt.Errorf("count years: %w", err) + } + defer rows.Close() + var out []stats.YearCount + for rows.Next() { + var y stats.YearCount + if err := rows.Scan(&y.Year, &y.Songs); err != nil { + return nil, err + } + out = append(out, y) + } + return out, rows.Err() +} + +// listensWhere is the condition for the listens of a user in a period. +func listensWhere(userID, minMs int64, rng stats.Range) (string, []any) { + where := "e.user_id = ? AND " + counted + args := []any{userID, minMs} + if !rng.From.IsZero() { + where += " AND e.occurred_at >= ?" + args = append(args, rng.From.Unix()) + } + if !rng.Until.IsZero() { + where += " AND e.occurred_at < ?" + args = append(args, rng.Until.Unix()) + } + return where, args +} + +// ListenTotals sums up the listens of a user in a period. +func (r *StatsRepo) ListenTotals(ctx context.Context, userID, minMs int64, rng stats.Range) (stats.ListenTotals, error) { + where, args := listensWhere(userID, minMs, rng) + var out stats.ListenTotals + if err := r.db.QueryRowContext(ctx, + "SELECT COUNT(*), COALESCE(SUM(e.duration_played_ms), 0), COUNT(DISTINCT e.track_id), COALESCE(MIN(e.occurred_at), 0) FROM listening_events e WHERE "+where, + args...).Scan(&out.Listens, &out.PlayedMs, &out.Songs, &out.First); err != nil { + return out, fmt.Errorf("sum listens: %w", err) + } + if err := r.db.QueryRowContext(ctx, + "SELECT COUNT(DISTINCT ta.artist_id) FROM listening_events e JOIN track_artists ta ON ta.track_id = e.track_id WHERE "+where, + args...).Scan(&out.Artists); err != nil { + return out, fmt.Errorf("count artists listened to: %w", err) + } + return out, nil +} + +// ListenTimes gives the moment of each listen. The hour, weekday and year are worked out by the caller, in the time +// zone of the listener, so that both databases give the same answer. +func (r *StatsRepo) ListenTimes(ctx context.Context, userID, minMs int64, rng stats.Range) ([]int64, error) { + where, args := listensWhere(userID, minMs, rng) + rows, err := r.db.QueryContext(ctx, "SELECT e.occurred_at FROM listening_events e WHERE "+where, args...) + if err != nil { + return nil, fmt.Errorf("read listens: %w", err) + } + defer rows.Close() + var out []int64 + for rows.Next() { + var at int64 + if err := rows.Scan(&at); err != nil { + return nil, err + } + out = append(out, at) + } + return out, rows.Err() +} + +// TopArtists ranks the artists by listens, a listen counting once for each artist credited on the song. +func (r *StatsRepo) TopArtists(ctx context.Context, userID, minMs int64, rng stats.Range, limit int) ([]stats.Ranked, error) { + where, args := listensWhere(userID, minMs, rng) + rows, err := r.db.QueryContext(ctx, + `SELECT a.id, a.name, COUNT(DISTINCT e.id) AS n FROM listening_events e + JOIN track_artists ta ON ta.track_id = e.track_id JOIN artists a ON a.id = ta.artist_id + WHERE `+where+` GROUP BY a.id, a.name ORDER BY n DESC, a.name ASC, a.id ASC LIMIT ?`, append(args, limit)...) + if err != nil { + return nil, fmt.Errorf("rank artists: %w", err) + } + defer rows.Close() + var out []stats.Ranked + for rows.Next() { + var x stats.Ranked + if err := rows.Scan(&x.ID, &x.Name, &x.Listens); err != nil { + return nil, err + } + out = append(out, x) + } + return out, rows.Err() +} + +// TopSongs ranks the songs by listens, and names their artists. +func (r *StatsRepo) TopSongs(ctx context.Context, userID, minMs int64, rng stats.Range, limit int) ([]stats.Ranked, error) { + where, args := listensWhere(userID, minMs, rng) + rows, err := r.db.QueryContext(ctx, + `SELECT t.id, t.title, COUNT(*) AS n FROM listening_events e JOIN tracks t ON t.id = e.track_id + WHERE `+where+` GROUP BY t.id, t.title ORDER BY n DESC, t.title ASC, t.id ASC LIMIT ?`, append(args, limit)...) + if err != nil { + return nil, fmt.Errorf("rank songs: %w", err) + } + defer rows.Close() + var out []stats.Ranked + var ids []int64 + for rows.Next() { + var x stats.Ranked + if err := rows.Scan(&x.ID, &x.Name, &x.Listens); err != nil { + return nil, err + } + out = append(out, x) + ids = append(ids, x.ID) + } + if err := rows.Err(); err != nil { + return nil, err + } + if len(ids) == 0 { + return out, nil + } + names, err := r.db.QueryContext(ctx, + "SELECT ta.track_id, a.name FROM track_artists ta JOIN artists a ON a.id = ta.artist_id WHERE ta.track_id IN (?) ORDER BY ta.track_id, a.name", bun.In(ids)) + if err != nil { + return nil, fmt.Errorf("name the artists: %w", err) + } + defer names.Close() + byTrack := map[int64][]string{} + for names.Next() { + var id int64 + var name string + if err := names.Scan(&id, &name); err != nil { + return nil, err + } + if list := byTrack[id]; len(list) == 0 || list[len(list)-1] != name { // a role listed twice is one artist + byTrack[id] = append(list, name) + } + } + for i := range out { + out[i].Artists = byTrack[out[i].ID] + } + return out, names.Err() +} + +// ListenGenres weighs the genres of the listens, and counts the listens whose song has a genre. +func (r *StatsRepo) ListenGenres(ctx context.Context, userID, minMs int64, rng stats.Range) ([]stats.GenreWeight, int, error) { + where, args := listensWhere(userID, minMs, rng) + out, err := r.weightedGenres(ctx, + "FROM listening_events e JOIN track_genres g ON g.track_id = e.track_id JOIN "+genresPerTrack+" c ON c.track_id = e.track_id WHERE "+where, args) + if err != nil { + return nil, 0, err + } + var tagged int + if err := r.db.QueryRowContext(ctx, + "SELECT COUNT(*) FROM listening_events e WHERE "+where+" AND EXISTS (SELECT 1 FROM track_genres g WHERE g.track_id = e.track_id)", + args...).Scan(&tagged); err != nil { + return nil, 0, fmt.Errorf("count tagged listens: %w", err) + } + sort.Slice(out, func(i, j int) bool { return out[i].Genre < out[j].Genre }) + return out, tagged, nil +} diff --git a/internal/storage/stats_test.go b/internal/storage/stats_test.go new file mode 100644 index 0000000..cc00fdc --- /dev/null +++ b/internal/storage/stats_test.go @@ -0,0 +1,241 @@ +package storage + +import ( + "context" + "testing" + "time" + + "github.com/uptrace/bun" + + "git.kmalloc.org/squid/sonda/internal/listening" + "git.kmalloc.org/squid/sonda/internal/stats" +) + +type statsWorld struct { + alice, bob int64 + debaser, mind int64 + song2, karma int64 + repo *StatsRepo + listens *ListeningRepo + ctx context.Context + db *bun.DB + firstListenAt time.Time + jan, jun, next time.Time +} + +// seedStats builds a small library: Debaser and Where Is My Mind (Pixies), Song 2 (Blur), and Karma Police +// (Radiohead) whose file is missing. Debaser also has an mp3. +func seedStats(t *testing.T, db *bun.DB) statsWorld { + t.Helper() + ctx := context.Background() + users := NewUserRepo(db) + alice, err := users.CreateUser(ctx, "alice", "h", false) + if err != nil { + t.Fatal(err) + } + bob, err := users.CreateUser(ctx, "bob", "h", false) + if err != nil { + t.Fatal(err) + } + lib, err := NewLibraryRepo(db).CreateLibrary(ctx, "music", "/music") + if err != nil { + t.Fatal(err) + } + w := statsWorld{alice: alice.ID, bob: bob.ID, repo: NewStatsRepo(db), listens: NewListeningRepo(db), ctx: ctx, db: db} + w.debaser = affinitySong(t, db, lib.ID, "a.flac", "Debaser", "Pixies") + w.mind = affinitySong(t, db, lib.ID, "b.flac", "Where Is My Mind", "Pixies") + w.song2 = affinitySong(t, db, lib.ID, "c.flac", "Song 2", "Blur") + w.karma = affinitySong(t, db, lib.ID, "d.flac", "Karma Police", "Radiohead") + exec := func(q string, args ...any) { + t.Helper() + if _, err := db.ExecContext(ctx, q, args...); err != nil { + t.Fatalf("%s: %v", q, err) + } + } + exec("UPDATE audio_files SET missing_at = 1 WHERE track_id = ?", w.karma) + exec("INSERT INTO audio_files (track_id, library_id, rel_path, format, size_bytes, mtime_unix) VALUES (?, ?, 'a.mp3', 'mp3', 50, 1)", w.debaser, lib.ID) + for id, year := range map[int64]int{w.debaser: 1989, w.mind: 1988, w.song2: 1994, w.karma: 1990} { + exec("UPDATE tracks SET year = ? WHERE id = ?", year, id) + } + for _, g := range []struct { + track int64 + genre string + }{{w.debaser, "rock"}, {w.debaser, "alternative"}, {w.mind, "rock"}, {w.song2, "britpop"}, {w.karma, "rock"}} { + exec("INSERT INTO track_genres (track_id, genre) VALUES (?, ?)", g.track, g.genre) + } + + at := func(y int, m time.Month, d int) time.Time { return time.Date(y, m, d, 12, 0, 0, 0, time.UTC) } + w.jan, w.jun, w.next = at(2025, 1, 10), at(2025, 6, 10), at(2026, 2, 1) + w.firstListenAt = w.jan + n := 0 + rec := func(user, track int64, typ listening.EventType, when time.Time, played int64) { + t.Helper() + n++ + if _, err := w.listens.Record(ctx, listening.Event{UserID: user, TrackID: track, Type: typ, OccurredAt: when, DurationPlayedMs: played, IdempotencyKey: "k" + string(rune('a'+n))}); err != nil { + t.Fatal(err) + } + } + rec(alice.ID, w.debaser, listening.Complete, w.jan, 200_000) + rec(alice.ID, w.debaser, listening.Complete, w.jun, 200_000) + rec(alice.ID, w.debaser, listening.Complete, w.next, 200_000) + rec(alice.ID, w.song2, listening.Complete, at(2025, 3, 3), 200_000) + rec(alice.ID, w.mind, listening.Play, at(2025, 4, 4), 30_000) // long enough to count + rec(alice.ID, w.karma, listening.Play, at(2025, 4, 5), 5_000) // too short + rec(alice.ID, w.debaser, listening.Skip, at(2025, 4, 6), 1_000) + rec(bob.ID, w.debaser, listening.Complete, at(2025, 5, 5), 200_000) // someone else + return w +} + +func TestTheLibraryStatsCountWhatCanBePlayed(t *testing.T) { + forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) { + w := seedStats(t, db) + got, err := w.repo.Totals(w.ctx) + if err != nil { + t.Fatal(err) + } + want := stats.Totals{Artists: 2, Albums: 2, Songs: 3, DurationMs: 600_000, SizeBytes: 350} + if got != want { + t.Errorf("totals = %+v, want %+v (Karma Police has no file left, so Radiohead is not counted)", got, want) + } + + formats, err := w.repo.Formats(w.ctx) + if err != nil || len(formats) != 2 { + t.Fatalf("formats = %+v, %v", formats, err) + } + by := map[string]stats.FormatCount{} + for _, f := range formats { + by[f.Format] = f + } + if by["flac"].Files != 3 || by["flac"].Bytes != 300 || by["mp3"].Files != 1 || by["mp3"].Bytes != 50 { + t.Errorf("formats = %+v", by) + } + + genres, tagged, err := w.repo.Genres(w.ctx) + if err != nil || tagged != 3 { + t.Fatalf("genres = %+v, tagged %d, %v", genres, tagged, err) + } + g := map[string]stats.GenreWeight{} + for _, x := range genres { + g[x.Genre] = x + } + if len(g) != 3 || g["rock"].Songs != 2 || g["rock"].Weight != 1.5 || g["alternative"].Weight != 0.5 || g["britpop"].Weight != 1 { + t.Errorf("genres = %+v (the genre of the song with no file is not counted)", g) + } + + years, err := w.repo.Years(w.ctx) + if err != nil { + t.Fatal(err) + } + ys := map[int]int{} + for _, y := range years { + ys[y.Year] = y.Songs + } + if len(ys) != 3 || ys[1988] != 1 || ys[1989] != 1 || ys[1994] != 1 { + t.Errorf("years = %+v", years) + } + }) +} + +func TestTheListeningStatsAreOfOnePersonAndOnlyWhatCounts(t *testing.T) { + forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) { + w := seedStats(t, db) + minMs := int64(20_000) + all := stats.Range{} + + tot, err := w.repo.ListenTotals(w.ctx, w.alice, minMs, all) + if err != nil { + t.Fatal(err) + } + want := stats.ListenTotals{Listens: 5, PlayedMs: 830_000, Songs: 3, Artists: 2, First: w.firstListenAt.Unix()} + if tot != want { + t.Errorf("totals = %+v, want %+v", tot, want) + } + + times, err := w.repo.ListenTimes(w.ctx, w.alice, minMs, all) + if err != nil || len(times) != 5 { + t.Fatalf("times = %v, %v", times, err) + } + + artists, err := w.repo.TopArtists(w.ctx, w.alice, minMs, all, 10) + if err != nil || len(artists) != 2 || artists[0].Name != "Pixies" || artists[0].Listens != 4 || artists[1].Name != "Blur" || artists[1].Listens != 1 { + t.Errorf("artists = %+v, %v", artists, err) + } + if artists[0].ID == 0 { + t.Error("an artist has an id") + } + + songs, err := w.repo.TopSongs(w.ctx, w.alice, minMs, all, 10) + if err != nil || len(songs) != 3 { + t.Fatalf("songs = %+v, %v", songs, err) + } + if songs[0].Name != "Debaser" || songs[0].Listens != 3 || len(songs[0].Artists) != 1 || songs[0].Artists[0] != "Pixies" || songs[0].ID != w.debaser { + t.Errorf("first song = %+v", songs[0]) + } + if songs[1].Name != "Song 2" || songs[2].Name != "Where Is My Mind" { // a tie: by title + t.Errorf("tie = %q, %q", songs[1].Name, songs[2].Name) + } + if one, _ := w.repo.TopSongs(w.ctx, w.alice, minMs, all, 1); len(one) != 1 { + t.Errorf("limit 1 gave %d", len(one)) + } + + genres, tagged, err := w.repo.ListenGenres(w.ctx, w.alice, minMs, all) + if err != nil || tagged != 5 { + t.Fatalf("genres = %+v, tagged %d, %v", genres, tagged, err) + } + g := map[string]stats.GenreWeight{} + for _, x := range genres { + g[x.Genre] = x + } + if g["rock"].Songs != 4 || g["rock"].Weight != 2.5 || g["alternative"].Songs != 3 || g["alternative"].Weight != 1.5 || g["britpop"].Weight != 1 { + t.Errorf("listen genres = %+v", g) + } + }) +} + +func TestTheListeningStatsCanBeCutToAPeriod(t *testing.T) { + forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) { + w := seedStats(t, db) + year := stats.Range{From: time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC), Until: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)} + tot, err := w.repo.ListenTotals(w.ctx, w.alice, 20_000, year) + if err != nil || tot.Listens != 4 || tot.Songs != 3 { + t.Errorf("2025 = %+v, %v, want 4 listens (not the one of 2026)", tot, err) + } + since := stats.Range{From: time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)} + tot, _ = w.repo.ListenTotals(w.ctx, w.alice, 20_000, since) + if tot.Listens != 1 || tot.First != w.next.Unix() { + t.Errorf("since 2026 = %+v", tot) + } + songs, _ := w.repo.TopSongs(w.ctx, w.alice, 20_000, year, 10) + if songs[0].Listens != 2 { + t.Errorf("Debaser in 2025 = %d, want 2", songs[0].Listens) + } + none := stats.Range{From: time.Date(2030, 1, 1, 0, 0, 0, 0, time.UTC)} + tot, err = w.repo.ListenTotals(w.ctx, w.alice, 20_000, none) + if err != nil || tot != (stats.ListenTotals{}) { + t.Errorf("a period with no listens = %+v, %v", tot, err) + } + if times, _ := w.repo.ListenTimes(w.ctx, w.alice, 20_000, none); len(times) != 0 { + t.Errorf("times = %v", times) + } + }) +} + +func TestTheStatsOfAPersonWithNoListensAreEmpty(t *testing.T) { + forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) { + w := seedStats(t, db) + carol, err := NewUserRepo(db).CreateUser(w.ctx, "carol", "h", false) + if err != nil { + t.Fatal(err) + } + tot, err := w.repo.ListenTotals(w.ctx, carol.ID, 20_000, stats.Range{}) + if err != nil || tot != (stats.ListenTotals{}) { + t.Errorf("totals = %+v, %v", tot, err) + } + if a, err := w.repo.TopArtists(w.ctx, carol.ID, 20_000, stats.Range{}, 10); err != nil || len(a) != 0 { + t.Errorf("artists = %+v, %v", a, err) + } + if _, tagged, err := w.repo.ListenGenres(w.ctx, carol.ID, 20_000, stats.Range{}); err != nil || tagged != 0 { + t.Errorf("tagged = %d, %v", tagged, err) + } + }) +} diff --git a/web/src/api/schema.d.ts b/web/src/api/schema.d.ts index f484490..74ffdbe 100644 --- a/web/src/api/schema.d.ts +++ b/web/src/api/schema.d.ts @@ -2191,6 +2191,52 @@ export interface paths { patch?: never; trace?: never; }; + "/stats/library": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * What the library holds + * @description The songs that can be played (a song whose file is missing is not counted), with their artists, albums, total + * length and the space their files take, the files by format, the share of each genre and of each decade. The + * genre shares count a song with several genres once, split between them, so `top`, `other` and + * `untagged_share` add up to 1. The genres are the tags of the files, read offline. + */ + get: operations["getLibraryStats"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/stats/listening": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * What you listened to + * @description Your listens that count (see `POST /listens`), for all time or for a period: how many, how long, how many + * songs and artists, the listens of each year (a year with none between the first and the last is 0), of each + * hour of the day and of each weekday (Monday first), your most listened artists and songs, and the share of each + * genre. Years, hours and weekdays are counted in the time zone `tz`. Nobody else's listens are visible. + */ + get: operations["getListeningStats"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; "/listens/months": { parameters: { query?: never; @@ -3433,6 +3479,91 @@ export interface components { score: number; }[]; }; + /** @description The share of each genre. `top`, `other` and `untagged_share` add up to 1. */ + GenreShares: { + /** @description The ten biggest, biggest first. */ + top: { + name: string; + /** @description How many songs (or listens) have this genre. */ + count: number; + share: number; + }[]; + /** @description What the smaller genres add up to. */ + other: number; + /** @description How many songs (or listens) have no genre. */ + untagged: number; + untagged_share: number; + }; + LibraryStats: { + artists: number; + albums: number; + songs: number; + /** + * Format: int64 + * @description The length of all the songs together. + */ + duration_ms: number; + /** + * Format: int64 + * @description The space of all the files that are not missing. + */ + size_bytes: number; + formats: { + /** @example flac */ + format: string; + files: number; + /** Format: int64 */ + bytes: number; + }[]; + genres: components["schemas"]["GenreShares"]; + /** @description How many songs came out in each decade, oldest first. 1990 is the nineties. */ + decades: { + /** @example 1990 */ + decade: number; + songs: number; + }[]; + /** @description Songs whose file has no year. */ + no_year: number; + }; + ListeningStats: { + listens: number; + /** @description How many different songs. */ + songs: number; + /** @description How many different artists. */ + artists: number; + /** + * Format: int64 + * @description The time listened to. + */ + played_ms: number; + /** + * Format: date-time + * @description The first listen of the period. Left out when there is none. + */ + first?: string; + years: { + year: number; + listens: number; + }[]; + /** @description Listens in each hour of the day, from midnight. */ + hours: number[]; + /** @description Listens on each weekday, from Monday. */ + weekdays: number[]; + top_artists: { + /** Format: int64 */ + id: number; + name: string; + listens: number; + }[]; + top_songs: { + /** Format: int64 */ + id: number; + title: string; + artists: string[]; + listens: number; + }[]; + genres: components["schemas"]["GenreShares"]; + }; ListeningSuggestions: { library: components["schemas"]["ListeningSuggestion"][]; missing: components["schemas"]["ListeningSuggestion"][]; @@ -8048,6 +8179,56 @@ export interface operations { }; }; }; + getLibraryStats: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description The numbers. */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["LibraryStats"]; + }; + }; + 401: components["responses"]["Unauthorized"]; + }; + }; + getListeningStats: { + parameters: { + query?: { + /** @description The start of the period, included, as a date and time with an offset. */ + from?: string; + /** @description The end of the period, excluded. It must not be before `from`. */ + until?: string; + /** @description An IANA time zone name, like `Europe/Rome`. Anything else is `invalid_input`. */ + tz?: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description The numbers. */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["ListeningStats"]; + }; + }; + 400: components["responses"]["InvalidInput"]; + 401: components["responses"]["Unauthorized"]; + }; + }; listListenMonths: { parameters: { query?: { diff --git a/web/src/api/stats.ts b/web/src/api/stats.ts new file mode 100644 index 0000000..f18fe3d --- /dev/null +++ b/web/src/api/stats.ts @@ -0,0 +1,42 @@ +import { useQuery } from '@tanstack/react-query' +import { api } from '@/api/client' +import type { components } from '@/api/schema' +import { browserZone } from '@/api/history' + +export type LibraryStats = components['schemas']['LibraryStats'] +export type ListeningStats = components['schemas']['ListeningStats'] +export type GenreShares = components['schemas']['GenreShares'] + +/** The periods the listening can be cut to. */ +export const PERIODS = ['all', 'year', 'months12', 'days30'] as const +export type Period = (typeof PERIODS)[number] + +/** + * The start of a period, at midnight of the local day, so that a period starts where the listener's own days do. The + * period always runs up to now, so it has no end. + */ +export function periodStart(period: Period, now = new Date()): Date | null { + switch (period) { + case 'year': + return new Date(now.getFullYear(), 0, 1) + case 'months12': + return new Date(now.getFullYear() - 1, now.getMonth(), now.getDate()) + case 'days30': + return new Date(now.getFullYear(), now.getMonth(), now.getDate() - 30) + default: + return null + } +} + +/** What the library holds. */ +export function useLibraryStats() { + return useQuery({ queryKey: ['/stats/library'], queryFn: () => api.get('/stats/library') }) +} + +/** What the signed-in person listened to in a period, in the time zone of this browser. */ +export function useListeningStats(period: Period) { + return useQuery({ + queryKey: ['/stats/listening', period, browserZone()], + queryFn: () => api.get('/stats/listening', { from: periodStart(period)?.toISOString(), tz: browserZone() }), + }) +} diff --git a/web/src/components/StatBars.tsx b/web/src/components/StatBars.tsx new file mode 100644 index 0000000..eb4942d --- /dev/null +++ b/web/src/components/StatBars.tsx @@ -0,0 +1,60 @@ +import type { ReactNode } from 'react' +import { cn } from '@/lib/utils' + +export interface Bar { + key: string + /** What is shown at the side of the bar. */ + label: ReactNode + /** From 0 to 1: how much of the track the bar fills. */ + value: number + /** What is shown after the bar. */ + text: string +} + +/** + * Horizontal bars, one a line: a name, a bar as long as its share, and the figure. They are a list, so a screen reader + * reads each line (name and figure) and skips the drawing. + */ +export function ShareBars({ label, bars, wide = false }: { label: string; bars: Bar[]; wide?: boolean }) { + return ( +
    + {bars.map((b) => ( +
  • + {b.label} +
  • + ))} +
+ ) +} + +export interface Column { + key: string + /** What is shown under the column; the others can be left out when there are many. */ + label: string + value: number + /** What a screen reader reads for the column, which has no text of its own. */ + name: string +} + +const HEIGHT = 96 + +/** Vertical columns as high as their value, the highest filling the track: a year by year, or hour by hour chart. */ +export function Columns({ label, columns, className }: { label: string; columns: Column[]; className?: string }) { + const biggest = Math.max(1, ...columns.map((c) => c.value)) + return ( +
    + {columns.map((c) => ( +
  • +
  • + ))} +
+ ) +} diff --git a/web/src/components/layout/PhoneTabs.test.tsx b/web/src/components/layout/PhoneTabs.test.tsx index 7405a76..cafacb3 100644 --- a/web/src/components/layout/PhoneTabs.test.tsx +++ b/web/src/components/layout/PhoneTabs.test.tsx @@ -47,7 +47,7 @@ test('the tab of the page that is open is the current one', () => { expect(within(nav).getByRole('link', { name: 'Home' })).not.toHaveAttribute('aria-current') }) -test.each(['/library', '/artists', '/albums/4', '/songs', '/mixes', '/playlists/2', '/smart-playlists', '/history', '/import'])( +test.each(['/library', '/artists', '/albums/4', '/songs', '/mixes', '/playlists/2', '/smart-playlists', '/history', '/stats', '/import'])( 'Library is the current tab on %s, one of the pages it leads to', (path) => { const nav = renderTabs(path) diff --git a/web/src/components/layout/PhoneTabs.tsx b/web/src/components/layout/PhoneTabs.tsx index 786b685..fdff23a 100644 --- a/web/src/components/layout/PhoneTabs.tsx +++ b/web/src/components/layout/PhoneTabs.tsx @@ -6,7 +6,7 @@ import { cn } from '@/lib/utils' /** The pages the Home tab leads to (Home itself ends the list of them with links to Discover and, for an admin, Requests). */ const HOME = ['/discover', '/requests'] /** The pages the Library tab leads to: it is the current tab on all of them. */ -const LIBRARY = ['/library', '/artists', '/albums', '/songs', '/playlists', '/smart-playlists', '/mixes', '/history', '/import'] +const LIBRARY = ['/library', '/artists', '/albums', '/songs', '/playlists', '/smart-playlists', '/mixes', '/history', '/stats', '/import'] const MORE = ['/more', '/settings', '/admin'] const under = (path: string, prefixes: string[]) => prefixes.some((p) => path === p || path.startsWith(`${p}/`)) diff --git a/web/src/components/layout/Sidebar.test.tsx b/web/src/components/layout/Sidebar.test.tsx index 0836f4a..2ea0619 100644 --- a/web/src/components/layout/Sidebar.test.tsx +++ b/web/src/components/layout/Sidebar.test.tsx @@ -28,7 +28,7 @@ function renderSidebar(friends: { id: number; name: string }[] = [], path = '/al test('the menu has a link for each page, and the page that is open is the current one', () => { const nav = renderSidebar() - for (const name of ['Home', 'Search', 'Discover', 'Artists', 'Albums', 'Songs', 'Mixes', 'Playlists', 'Smart playlists', 'History', 'Import', 'Admin', 'Settings']) { + for (const name of ['Home', 'Search', 'Discover', 'Artists', 'Albums', 'Songs', 'Mixes', 'Playlists', 'Smart playlists', 'History', 'Statistics', 'Import', 'Admin', 'Settings']) { expect(within(nav).getByRole('link', { name })).toBeInTheDocument() } expect(within(nav).getByRole('link', { name: 'Albums' })).toHaveAttribute('aria-current', 'page') @@ -158,7 +158,7 @@ test('the links are in groups, in the order of what you do: find, the library, y expect(names(nav)).toEqual([ 'Home', 'Search', 'Discover', 'Requests', 'Artists', 'Albums', 'Songs', 'Playlists', 'Smart playlists', 'Mixes', - 'History', 'Import', + 'History', 'Statistics', 'Import', 'Friends', 'Settings', 'Admin', ]) @@ -169,7 +169,7 @@ test('the library and the listening have a quiet heading, and the groups that ex const library = within(nav).getByRole('list', { name: 'Library' }) expect(within(library).getAllByRole('link').map((a) => a.textContent)).toEqual(['Artists', 'Albums', 'Songs', 'Playlists', 'Smart playlists', 'Mixes']) const listening = within(nav).getByRole('list', { name: 'Your listening' }) - expect(within(listening).getAllByRole('link').map((a) => a.textContent)).toEqual(['History', 'Import']) + expect(within(listening).getAllByRole('link').map((a) => a.textContent)).toEqual(['History', 'Statistics', 'Import']) // The headings are words, not links, and not headings of the page. expect(within(nav).queryByRole('heading')).not.toBeInTheDocument() expect(within(nav).queryByRole('link', { name: 'Your listening' })).not.toBeInTheDocument() diff --git a/web/src/components/layout/Sidebar.tsx b/web/src/components/layout/Sidebar.tsx index e6c440c..e619677 100644 --- a/web/src/components/layout/Sidebar.tsx +++ b/web/src/components/layout/Sidebar.tsx @@ -1,5 +1,5 @@ import { useState } from 'react' -import { Blend, Compass, Disc3, History, House, Inbox, ListMusic, MicVocal, Music, PanelLeftClose, PanelLeftOpen, Search, Settings, ShieldCheck, Upload, Users, WandSparkles } from 'lucide-react' +import { Blend, ChartNoAxesColumn, Compass, Disc3, History, House, Inbox, ListMusic, MicVocal, Music, PanelLeftClose, PanelLeftOpen, Search, Settings, ShieldCheck, Upload, Users, WandSparkles } from 'lucide-react' import type { LucideIcon } from 'lucide-react' import { NavLink } from 'react-router-dom' import { useTranslation } from 'react-i18next' @@ -52,6 +52,7 @@ const GROUPS: Group[] = [ heading: 'nav.listening', items: [ { to: '/history', key: 'nav.history', icon: History }, + { to: '/stats', key: 'nav.stats', icon: ChartNoAxesColumn }, { to: '/import', key: 'nav.import', icon: Upload }, ], }, diff --git a/web/src/i18n/locales/en.json b/web/src/i18n/locales/en.json index 8b54cea..3c93c71 100644 --- a/web/src/i18n/locales/en.json +++ b/web/src/i18n/locales/en.json @@ -26,7 +26,8 @@ "more": "More", "collapse": "Collapse menu", "expand": "Expand menu", - "tabs": "Tabs" + "tabs": "Tabs", + "stats": "Statistics" }, "common": { "loading": "Loading", @@ -1087,5 +1088,45 @@ "plain": "Version {{version}}", "commit": "Version {{version}} · {{revision}}", "changed": "Version {{version}} · {{revision}} (changed)" + }, + "stats": { + "library": "Your library", + "listening": "Your listening", + "songs": "Songs", + "albums": "Albums", + "artists": "Artists", + "length": "Length", + "size": "Size on disk", + "genres": "Genres", + "formats": "Formats", + "decades": "Decades", + "other": "Smaller genres", + "noGenre": "No genre", + "noYear_one": "{{n}} song has no year in its tags.", + "noYear_other": "{{n}} songs have no year in their tags.", + "emptyLibrary": "There is no music in the library yet.", + "period": "Period", + "periods": { + "all": "All time", + "year": "This year", + "months12": "Last 12 months", + "days30": "Last 30 days" + }, + "listens": "Listens", + "timeListened": "Time listened", + "first": "First listen", + "byYear": "Listens by year", + "byHour": "Listens by hour of the day", + "byWeekday": "Listens by day of the week", + "topArtists": "Top artists", + "topSongs": "Top songs", + "yourGenres": "Genres you listen to", + "none": "No listens in this period.", + "decade": "{{decade}}s", + "songsIn_one": "{{label}}: {{n}} song", + "songsIn_other": "{{label}}: {{n}} songs", + "listensIn_one": "{{label}}: {{n}} listen", + "listensIn_other": "{{label}}: {{n}} listens", + "decadeShort": "{{short}}s" } } diff --git a/web/src/i18n/locales/it.json b/web/src/i18n/locales/it.json index 3705d87..e77f18c 100644 --- a/web/src/i18n/locales/it.json +++ b/web/src/i18n/locales/it.json @@ -26,7 +26,8 @@ "more": "Altro", "collapse": "Comprimi il menu", "expand": "Espandi il menu", - "tabs": "Schede" + "tabs": "Schede", + "stats": "Statistiche" }, "common": { "loading": "Caricamento", @@ -1087,5 +1088,45 @@ "plain": "Versione {{version}}", "commit": "Versione {{version}} · {{revision}}", "changed": "Versione {{version}} · {{revision}} (modificata)" + }, + "stats": { + "library": "La tua libreria", + "listening": "I tuoi ascolti", + "songs": "Brani", + "albums": "Album", + "artists": "Artisti", + "length": "Durata", + "size": "Spazio su disco", + "genres": "Generi", + "formats": "Formati", + "decades": "Decenni", + "other": "Generi minori", + "noGenre": "Senza genere", + "noYear_one": "{{n}} brano non ha l'anno nei tag.", + "noYear_other": "{{n}} brani non hanno l'anno nei tag.", + "emptyLibrary": "Non c'è ancora musica nella libreria.", + "period": "Periodo", + "periods": { + "all": "Sempre", + "year": "Quest'anno", + "months12": "Ultimi 12 mesi", + "days30": "Ultimi 30 giorni" + }, + "listens": "Ascolti", + "timeListened": "Tempo ascoltato", + "first": "Primo ascolto", + "byYear": "Ascolti per anno", + "byHour": "Ascolti per ora del giorno", + "byWeekday": "Ascolti per giorno della settimana", + "topArtists": "Artisti più ascoltati", + "topSongs": "Brani più ascoltati", + "yourGenres": "Generi che ascolti", + "none": "Nessun ascolto in questo periodo.", + "decade": "Anni {{short}}", + "songsIn_one": "{{label}}: {{n}} brano", + "songsIn_other": "{{label}}: {{n}} brani", + "listensIn_one": "{{label}}: {{n}} ascolto", + "listensIn_other": "{{label}}: {{n}} ascolti", + "decadeShort": "{{short}}" } } diff --git a/web/src/lib/time.test.ts b/web/src/lib/time.test.ts index eaed80e..4a2f146 100644 --- a/web/src/lib/time.test.ts +++ b/web/src/lib/time.test.ts @@ -1,5 +1,5 @@ -import { expect, test } from 'vitest' -import { formatTime } from './time' +import { describe, expect, test } from 'vitest' +import { formatLength, formatTime } from './time' test.each([ [0, '0:00'], @@ -20,3 +20,21 @@ test('a negative or unknown time is written as zero', () => { expect(formatTime(Number.NaN)).toBe('0:00') expect(formatTime(Number.POSITIVE_INFINITY)).toBe('0:00') }) + +describe('formatLength', () => { + const h = 3600_000 + test('tells days and hours, hours and minutes, or minutes, in the language of the reader', () => { + expect(formatLength((38 * 24 + 4) * h + 120_000, 'en')).toBe('38 days 4 hours') + expect(formatLength(25 * h, 'en')).toBe('1 day 1 hour') + expect(formatLength(2 * h + 5 * 60_000, 'en')).toBe('2 hours 5 minutes') + expect(formatLength(7 * 60_000 + 59_000, 'en')).toBe('7 minutes') + expect(formatLength(2 * 24 * h, 'it')).toBe('2 giorni') + }) + test('leaves out a second unit that is zero, and is 0 minutes for nothing or a bad number', () => { + expect(formatLength(3 * 24 * h + 10 * 60_000, 'en')).toBe('3 days') + expect(formatLength(4 * h, 'en')).toBe('4 hours') + expect(formatLength(0, 'en')).toBe('0 minutes') + expect(formatLength(Number.NaN, 'en')).toBe('0 minutes') + expect(formatLength(-5, 'en')).toBe('0 minutes') + }) +}) diff --git a/web/src/lib/time.ts b/web/src/lib/time.ts index d388d0a..9a3193d 100644 --- a/web/src/lib/time.ts +++ b/web/src/lib/time.ts @@ -7,3 +7,17 @@ export function formatTime(ms: number): string { const seconds = String(total % 60).padStart(2, '0') return hours > 0 ? `${hours}:${String(minutes).padStart(2, '0')}:${seconds}` : `${minutes}:${seconds}` } + +/** + * A long time in words, in the language of the reader: "38 days 4 hours", "2 hours 5 minutes", "7 minutes". Only the + * two biggest units are told, and a zero second unit is left out. + */ +export function formatLength(ms: number, lang: string): string { + const unit = (n: number, u: 'day' | 'hour' | 'minute') => new Intl.NumberFormat(lang, { style: 'unit', unit: u, unitDisplay: 'long' }).format(n) + const minutes = Math.floor(Math.max(0, Number.isFinite(ms) ? ms : 0) / 60000) + const hours = Math.floor(minutes / 60) + const days = Math.floor(hours / 24) + if (days >= 1) return hours % 24 > 0 ? `${unit(days, 'day')} ${unit(hours % 24, 'hour')}` : unit(days, 'day') + if (hours >= 1) return minutes % 60 > 0 ? `${unit(hours, 'hour')} ${unit(minutes % 60, 'minute')}` : unit(hours, 'hour') + return unit(minutes, 'minute') +} diff --git a/web/src/pages/LibraryPage.test.tsx b/web/src/pages/LibraryPage.test.tsx index 79caa46..9c96400 100644 --- a/web/src/pages/LibraryPage.test.tsx +++ b/web/src/pages/LibraryPage.test.tsx @@ -28,9 +28,10 @@ test('Library is a list of the places of the music, each a row that leads there' ['Smart playlists', '/smart-playlists'], ['Mixes', '/mixes'], ['History', '/history'], + ['Statistics', '/stats'], ['Import', '/import'], ]) - expect(within(screen.getByRole('region', { name: 'Your listening' })).getAllByRole('link')).toHaveLength(2) + expect(within(screen.getByRole('region', { name: 'Your listening' })).getAllByRole('link')).toHaveLength(3) expect(screen.queryByRole('link', { name: 'Discover' })).not.toBeInTheDocument() }) diff --git a/web/src/pages/LibraryPage.tsx b/web/src/pages/LibraryPage.tsx index 63e571c..67bc876 100644 --- a/web/src/pages/LibraryPage.tsx +++ b/web/src/pages/LibraryPage.tsx @@ -23,6 +23,7 @@ export default function LibraryPage() { diff --git a/web/src/pages/StatsPage.test.tsx b/web/src/pages/StatsPage.test.tsx new file mode 100644 index 0000000..9e53f9b --- /dev/null +++ b/web/src/pages/StatsPage.test.tsx @@ -0,0 +1,239 @@ +import { QueryClient, QueryClientProvider } from '@tanstack/react-query' +import { render, screen, waitFor, within } from '@testing-library/react' +import userEvent from '@testing-library/user-event' +import { MemoryRouter } from 'react-router-dom' +import { afterEach, beforeEach, expect, test, vi } from 'vitest' +import { initI18n } from '@/i18n' +import { apiError, mockFetch, type MockRoutes } from '@/test/mockFetch' +import StatsPage from './StatsPage' + +beforeEach(async () => { + vi.spyOn(navigator, 'language', 'get').mockReturnValue('en-US') + await initI18n() +}) + +afterEach(() => vi.useRealTimers()) + +const library = { + artists: 640, + albums: 1204, + songs: 12138, + duration_ms: ((38 * 24 + 4) * 3600 + 120) * 1000, // 38 days and 4 hours + size_bytes: 215 * 1024 ** 3, + formats: [ + { format: 'flac', files: 9000, bytes: 200 * 1024 ** 3 }, + { format: 'mpeg', files: 3000, bytes: 15 * 1024 ** 3 }, + ], + genres: { + top: [ + { name: 'rock', count: 6000, share: 0.5 }, + { name: 'jazz', count: 1800, share: 0.15 }, + ], + other: 0.1, + untagged: 3000, + untagged_share: 0.25, + }, + decades: [ + { decade: 1960, songs: 1000 }, + { decade: 1990, songs: 4000 }, + { decade: 2000, songs: 3000 }, + ], + no_year: 4138, +} + +const hours = Array.from({ length: 24 }, (_, h) => (h === 21 ? 30 : h === 8 ? 10 : 0)) +const listening = { + listens: 1234, + songs: 800, + artists: 150, + played_ms: ((2 * 24 + 3) * 3600 + 5 * 60) * 1000, // 2 days and 3 hours + first: '2019-03-05T10:00:00Z', + years: [ + { year: 2019, listens: 100 }, + { year: 2020, listens: 0 }, + { year: 2021, listens: 400 }, + ], + hours, + weekdays: [10, 20, 30, 40, 50, 60, 70], + top_artists: [ + { id: 11, name: 'Radiohead', listens: 90 }, + { id: 12, name: 'Blur', listens: 60 }, + ], + top_songs: [{ id: 5, title: 'Karma Police', artists: ['Radiohead'], listens: 33 }], + genres: { top: [{ name: 'rock', count: 700, share: 0.7 }], other: 0.1, untagged: 200, untagged_share: 0.2 }, +} + +const none = { + listens: 0, + songs: 0, + artists: 0, + played_ms: 0, + years: [], + hours: Array(24).fill(0), + weekdays: Array(7).fill(0), + top_artists: [], + top_songs: [], + genres: { top: [], other: 0, untagged: 0, untagged_share: 0 }, +} + +function setup(routes: MockRoutes = {}) { + const mocked = mockFetch({ + 'GET /api/v1/stats/library': () => library, + 'GET /api/v1/stats/listening': () => listening, + ...routes, + }) + render( + + + + + , + ) + return mocked +} + +/** A section, once what it asked for has come (or failed). */ +async function section(name: string) { + const region = await screen.findByRole('region', { name }) + await waitFor(() => expect(within(region).queryByRole('status')).not.toBeInTheDocument()) + return region +} + +test('the library says how much music there is: songs, albums, artists, length and space', async () => { + setup() + const lib = await section('Your library') + expect(within(lib).getByText('12,138')).toBeInTheDocument() + expect(within(lib).getByText('1,204')).toBeInTheDocument() + expect(within(lib).getByText('640')).toBeInTheDocument() + expect(within(lib).getByText('38 days 4 hours')).toBeInTheDocument() + expect(within(lib).getByText('215.0 GB')).toBeInTheDocument() +}) + +test('the genres of the library are shares of the whole, with what has no genre and the smaller ones', async () => { + setup() + const lib = await section('Your library') + const genres = within(lib).getByRole('list', { name: 'Genres' }) + const rows = within(genres).getAllByRole('listitem').map((li) => li.textContent) + expect(rows).toEqual(['rock50%', 'jazz15%', 'Smaller genres10%', 'No genre25%']) +}) + +test('the formats and the decades are shown too', async () => { + setup() + const lib = await section('Your library') + const formats = within(lib).getByRole('list', { name: 'Formats' }) + expect(within(formats).getAllByRole('listitem').map((li) => li.textContent)).toEqual(['FLAC75%', 'MP325%']) + const decades = within(lib).getByRole('list', { name: 'Decades' }) + expect(within(decades).getAllByRole('listitem').map((li) => li.getAttribute('aria-label'))).toEqual(['1960s: 1,000 songs', '1990s: 4,000 songs', '2000s: 3,000 songs']) +}) + +test('with many decades the labels under the columns are short, and the names stay whole', async () => { + const decades = [1940, 1950, 1960, 1970, 1980, 1990, 2000].map((decade) => ({ decade, songs: 10 })) + setup({ 'GET /api/v1/stats/library': () => ({ ...library, decades }) }) + const lib = await section('Your library') + const list = within(lib).getByRole('list', { name: 'Decades' }) + const items = within(list).getAllByRole('listitem') + expect(items.map((li) => li.textContent)).toEqual(['40s', '50s', '60s', '70s', '80s', '90s', '00s']) + expect(items[5]).toHaveAttribute('aria-label', '1990s: 10 songs') +}) + +test('listening says how many listens, the time, the songs and artists, and since when', async () => { + setup() + const l = await section('Your listening') + expect(within(l).getByText('1,234')).toBeInTheDocument() + expect(within(l).getByText('2 days 3 hours')).toBeInTheDocument() + expect(within(l).getByText('800')).toBeInTheDocument() + expect(within(l).getByText('150')).toBeInTheDocument() + expect(within(l).getByText(/March 5, 2019/)).toBeInTheDocument() +}) + +test('listens are shown by year (a year with none too), by hour and by weekday', async () => { + setup() + const l = await section('Your listening') + const years = within(l).getByRole('list', { name: 'Listens by year' }) + expect(within(years).getAllByRole('listitem').map((li) => li.getAttribute('aria-label'))).toEqual(['2019: 100 listens', '2020: 0 listens', '2021: 400 listens']) + const hoursList = within(l).getByRole('list', { name: 'Listens by hour of the day' }) + const items = within(hoursList).getAllByRole('listitem') + expect(items).toHaveLength(24) + expect(items[21]).toHaveAttribute('aria-label', '21:00: 30 listens') + const days = within(l).getByRole('list', { name: 'Listens by day of the week' }) + const week = within(days).getAllByRole('listitem') + expect(week).toHaveLength(7) + expect(week[0]).toHaveAttribute('aria-label', 'Mon: 10 listens') + expect(week[6]).toHaveAttribute('aria-label', 'Sun: 70 listens') +}) + +test('one year has no chart by year: there is nothing to compare', async () => { + setup({ 'GET /api/v1/stats/listening': () => ({ ...listening, years: [{ year: 2021, listens: 400 }] }) }) + const l = await section('Your listening') + expect(within(l).queryByRole('list', { name: 'Listens by year' })).not.toBeInTheDocument() +}) + +test('the most listened artists link to their page, and the songs name their artists', async () => { + setup() + const l = await section('Your listening') + const artists = within(l).getByRole('list', { name: 'Top artists' }) + const first = within(artists).getAllByRole('listitem')[0] + expect(within(first).getByRole('link', { name: 'Radiohead' })).toHaveAttribute('href', '/artists/11') + expect(first).toHaveTextContent('90') + const songs = within(l).getByRole('list', { name: 'Top songs' }) + expect(within(songs).getByText('Karma Police')).toBeInTheDocument() + expect(within(songs).getByText('Radiohead')).toBeInTheDocument() +}) + +test('the genres of the listening are shares too', async () => { + setup() + const l = await section('Your listening') + const genres = within(l).getByRole('list', { name: 'Genres you listen to' }) + expect(within(genres).getAllByRole('listitem').map((li) => li.textContent)).toEqual(['rock70%', 'Smaller genres10%', 'No genre20%']) +}) + +test('it asks for all time at first, in the time zone of this browser', async () => { + const { calls } = setup() + await section('Your listening') + const asked = calls.find((c) => c.key === 'GET /api/v1/stats/listening')! + expect(asked.url.searchParams.get('from')).toBeNull() + expect(asked.url.searchParams.get('until')).toBeNull() + expect(asked.url.searchParams.get('tz')).toBe(Intl.DateTimeFormat().resolvedOptions().timeZone) + const group = screen.getByRole('group', { name: 'Period' }) + expect(within(group).getByRole('button', { name: 'All time' })).toHaveAttribute('aria-pressed', 'true') +}) + +test.each([ + ['This year', () => new Date(2026, 0, 1)], + ['Last 12 months', () => new Date(2025, 10, 15)], + ['Last 30 days', () => new Date(2026, 9, 16)], +])('choosing %s asks for that period, counted in local days', async (label, from) => { + vi.useFakeTimers({ toFake: ['Date'], now: new Date(2026, 10, 15, 14, 30) }) + const { calls } = setup() + await section('Your listening') + await userEvent.click(within(screen.getByRole('group', { name: 'Period' })).getByRole('button', { name: label })) + await vi.waitFor(() => expect(calls.filter((c) => c.key === 'GET /api/v1/stats/listening')).toHaveLength(2)) + const asked = calls.filter((c) => c.key === 'GET /api/v1/stats/listening')[1] + expect(asked.url.searchParams.get('from')).toBe(from().toISOString()) + expect(asked.url.searchParams.get('until')).toBeNull() + expect(within(screen.getByRole('group', { name: 'Period' })).getByRole('button', { name: label })).toHaveAttribute('aria-pressed', 'true') +}) + +test('with no listens in the period it says so, and the library is still there', async () => { + setup({ 'GET /api/v1/stats/listening': () => none }) + const l = await section('Your listening') + expect(within(l).getByText('No listens in this period.')).toBeInTheDocument() + expect(within(l).queryByRole('list', { name: 'Top artists' })).not.toBeInTheDocument() + expect(within(await section('Your library')).getByText('12,138')).toBeInTheDocument() +}) + +test('an empty library says so and shows no charts', async () => { + setup({ + 'GET /api/v1/stats/library': () => ({ ...library, artists: 0, albums: 0, songs: 0, duration_ms: 0, size_bytes: 0, formats: [], decades: [], no_year: 0, genres: { top: [], other: 0, untagged: 0, untagged_share: 0 } }), + }) + const lib = await section('Your library') + expect(within(lib).getByText('There is no music in the library yet.')).toBeInTheDocument() + expect(within(lib).queryByRole('list', { name: 'Genres' })).not.toBeInTheDocument() +}) + +test('a failure to read one part does not hide the other', async () => { + setup({ 'GET /api/v1/stats/listening': () => apiError(500, 'internal') }) + expect(within(await section('Your library')).getByText('12,138')).toBeInTheDocument() + const l = await section('Your listening') + expect(await within(l).findByRole('alert')).toBeInTheDocument() +}) diff --git a/web/src/pages/StatsPage.tsx b/web/src/pages/StatsPage.tsx new file mode 100644 index 0000000..d0a8458 --- /dev/null +++ b/web/src/pages/StatsPage.tsx @@ -0,0 +1,237 @@ +import { useTranslation } from 'react-i18next' +import { Link } from 'react-router-dom' +import { PERIODS, useLibraryStats, useListeningStats, type GenreShares, type Period } from '@/api/stats' +import { Columns, ShareBars, type Bar } from '@/components/StatBars' +import PageTitle from '@/components/PageTitle' +import { EmptyMessage, ErrorMessage, Loading } from '@/components/Status' +import { Button } from '@/components/ui/button' +import { formatBytes } from '@/lib/bytes' +import { formatLength } from '@/lib/time' +import { useState, type ReactNode } from 'react' + +/** The title of a block of figures and the figures under it. */ +function Block({ title, children }: { title: string; children: ReactNode }) { + return ( +
+

{title}

+ {children} +
+ ) +} + +/** Figures with their names, side by side: a big number, then what it counts. */ +function Facts({ facts }: { facts: { name: string; value: string }[] }) { + return ( +
+ {facts.map((f) => ( +
+
{f.name}
+
{f.value}
+
+ ))} +
+ ) +} + +/** What a file format is called: the scanner says `mpeg` for the files that are MP3. */ +const formatName = (format: string) => (format === 'mpeg' ? 'MP3' : format.toUpperCase()) + +function useFormat() { + const { i18n } = useTranslation() + const count = new Intl.NumberFormat(i18n.language) + const percent = new Intl.NumberFormat(i18n.language, { style: 'percent', maximumFractionDigits: 0 }) + return { + count: (n: number) => count.format(n), + // A share that is there but under a half percent is not "0%". + percent: (share: number) => (share > 0 && share < 0.005 ? `<${percent.format(0.01)}` : percent.format(share)), + lang: i18n.language, + } +} + +/** The genres as bars: the biggest, what the smaller ones add up to, and what has no genre. */ +function GenreBars({ label, genres }: { label: string; genres: GenreShares }) { + const { t } = useTranslation() + const f = useFormat() + const bars: Bar[] = genres.top.map((g) => ({ key: `g:${g.name}`, label: g.name, value: g.share, text: f.percent(g.share) })) + if (genres.other > 0) bars.push({ key: 'other', label: t('stats.other'), value: genres.other, text: f.percent(genres.other) }) + if (genres.untagged > 0) bars.push({ key: 'none', label: t('stats.noGenre'), value: genres.untagged_share, text: f.percent(genres.untagged_share) }) + if (genres.top.length === 0) return null + return +} + +function LibrarySection() { + const { t } = useTranslation() + const f = useFormat() + const stats = useLibraryStats() + const body = () => { + if (stats.isError) return void stats.refetch()} /> + if (stats.isPending) return + const lib = stats.data + if (lib.songs === 0) return {t('stats.emptyLibrary')} + const files = lib.formats.reduce((sum, x) => sum + x.files, 0) + const decade = (d: number) => t('stats.decade', { decade: d, short: d >= 2000 ? d : d % 100 }) + return ( + <> + + {lib.genres.top.length > 0 && ( + + + + )} + {files > 0 && ( + + ({ key: x.format, label: formatName(x.format), value: x.files / files, text: f.percent(x.files / files) }))} + /> + + )} + {lib.decades.length > 0 && ( + + ({ + key: String(d.decade), + label: lib.decades.length > 6 ? t('stats.decadeShort', { short: String(d.decade % 100).padStart(2, '0') }) : decade(d.decade), + value: d.songs, + name: t('stats.songsIn', { count: d.songs, label: decade(d.decade), n: f.count(d.songs) }), + }))} + /> + {lib.no_year > 0 &&

{t('stats.noYear', { count: lib.no_year, n: f.count(lib.no_year) })}

} +
+ )} + + ) + } + return ( +
+

+ {t('stats.library')} +

+ {body()} +
+ ) +} + +function ListeningSection() { + const { t } = useTranslation() + const f = useFormat() + const [period, setPeriod] = useState('all') + const stats = useListeningStats(period) + const body = () => { + if (stats.isError) return void stats.refetch()} /> + if (stats.isPending) return + const l = stats.data + if (l.listens === 0) return {t('stats.none')} + const listens = (label: string, n: number) => t('stats.listensIn', { count: n, label, n: f.count(n) }) + const weekday = new Intl.DateTimeFormat(f.lang, { weekday: 'short' }) + const day = (i: number) => weekday.format(new Date(2024, 0, 1 + i)) // 1 January 2024 is a Monday + const shortYears = l.years.length > 8 + const rank = (value: number, list: { listens: number }[]) => value / Math.max(1, list[0]?.listens ?? 1) + return ( + <> + + {l.years.length > 1 && ( + + ({ key: String(y.year), label: shortYears ? String(y.year).slice(2) : String(y.year), value: y.listens, name: listens(String(y.year), y.listens) }))} + /> + + )} + + ({ key: String(h), label: h % 3 === 0 ? String(h) : '', value: n, name: listens(`${h}:00`, n) }))} + /> + + + ({ key: String(i), label: day(i), value: n, name: listens(day(i), n) }))} + /> + + + ({ + key: String(a.id), + label: ( + + {a.name} + + ), + value: rank(a.listens, l.top_artists), + text: f.count(a.listens), + }))} + /> + + + ({ + key: String(s.id), + label: ( + + {s.title} + {s.artists.join(', ')} + + ), + value: rank(s.listens, l.top_songs), + text: f.count(s.listens), + }))} + /> + + {l.genres.top.length > 0 && ( + + + + )} + + ) + } + return ( +
+

+ {t('stats.listening')} +

+
+ {PERIODS.map((p) => ( + + ))} +
+ {body()} +
+ ) +} + +/** The statistics: what the library holds, and what the signed-in person listened to, for all time or a period. */ +export default function StatsPage() { + const { t } = useTranslation() + return ( +
+ {t('nav.stats')} + + +
+ ) +} diff --git a/web/src/router.tsx b/web/src/router.tsx index b998b24..6af3c36 100644 --- a/web/src/router.tsx +++ b/web/src/router.tsx @@ -36,6 +36,7 @@ export const routes: RouteObject[] = [ { path: '/smart-playlists/:id/edit', lazy: page(() => import('@/pages/SmartEditorPage')) }, { path: '/requests', lazy: page(() => import('@/pages/RequestsPage')) }, { path: '/history', lazy: page(() => import('@/pages/HistoryPage')) }, + { path: '/stats', lazy: page(() => import('@/pages/StatsPage')) }, { path: '/import', lazy: page(() => import('@/pages/ImportPage')) }, { path: '/settings', lazy: page(() => import('@/pages/SettingsPage')) }, {