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
This commit is contained in:
tgiachi 2026-11-15 17:55:43 +01:00
commit d51f155a4d
28 changed files with 2336 additions and 11 deletions

View file

@ -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. |

View file

@ -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()),

View file

@ -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)

View file

@ -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")

View file

@ -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)
}

View file

@ -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)
}
}
}

View file

@ -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)

View file

@ -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

292
internal/stats/stats.go Normal file
View file

@ -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)
}

View file

@ -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)
}
}

256
internal/storage/stats.go Normal file
View file

@ -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
}

View file

@ -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)
}
})
}

View file

@ -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?: {

42
web/src/api/stats.ts Normal file
View file

@ -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<LibraryStats>('/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<ListeningStats>('/stats/listening', { from: periodStart(period)?.toISOString(), tz: browserZone() }),
})
}

View file

@ -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 (
<ul aria-label={label} className="flex flex-col gap-2">
{bars.map((b) => (
<li key={b.key} className={cn('grid items-center gap-3', wide ? 'grid-cols-[minmax(9rem,20rem)_1fr_3.5rem]' : 'grid-cols-[minmax(6rem,10rem)_1fr_3.5rem]')}>
<span className="min-w-0 truncate font-medium first-letter:uppercase">{b.label}</span>
<span aria-hidden="true" className="h-2 overflow-hidden rounded-full bg-card">
<span className="block h-full rounded-full bg-primary" style={{ width: `${Math.min(1, Math.max(0, b.value)) * 100}%` }} />
</span>
<span className="text-right text-sm tabular-nums text-muted-foreground">{b.text}</span>
</li>
))}
</ul>
)
}
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 (
<ul aria-label={label} className={cn('flex items-end gap-1', className)}>
{columns.map((c) => (
<li key={c.key} aria-label={c.name} title={c.name} className="flex min-w-0 flex-1 flex-col items-center justify-end gap-1">
<span aria-hidden="true" className="w-full rounded-sm bg-primary" style={{ height: `${Math.max(c.value > 0 ? 3 : 0, (c.value / biggest) * HEIGHT)}px` }} />
<span aria-hidden="true" className="h-4 text-[13px] leading-4 tabular-nums text-muted-foreground">
{c.label}
</span>
</li>
))}
</ul>
)
}

View file

@ -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)

View file

@ -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}/`))

View file

@ -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()

View file

@ -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 },
],
},

View file

@ -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"
}
}

Some files were not shown because too many files have changed in this diff Show more