Merge pull request 'Show how the genres I listen to changed over time' (#6) from feat/genre-timeline into main

This commit is contained in:
squid 2026-11-15 17:19:26 +00:00
commit 9451765861
14 changed files with 586 additions and 8 deletions

View file

@ -30,7 +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.
- **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, the share of each genre, and how that share changed over time (`genre_timeline`: a column for each year, or for each month when all your listens are in one year, with the share of your five biggest genres, of the smaller ones and of what has no 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).

View file

@ -18,6 +18,36 @@ type statsService interface {
type statsHandlers struct{ svc statsService }
type timelineBucketJSON struct {
Year int `json:"year"`
Month int `json:"month,omitempty"`
Listens int `json:"listens"`
Shares []float64 `json:"shares"`
Other float64 `json:"other"`
Untagged float64 `json:"untagged"`
}
type timelineJSON struct {
Unit string `json:"unit"`
Genres []string `json:"genres"`
Buckets []timelineBucketJSON `json:"buckets"`
}
func timelineBody(t stats.Timeline) timelineJSON {
out := timelineJSON{Unit: t.Unit, Genres: t.Genres, Buckets: make([]timelineBucketJSON, 0, len(t.Buckets))}
if out.Genres == nil {
out.Genres = []string{}
}
for _, b := range t.Buckets {
shares := b.Shares
if shares == nil {
shares = []float64{}
}
out.Buckets = append(out.Buckets, timelineBucketJSON{Year: b.Year, Month: b.Month, Listens: b.Listens, Shares: shares, Other: b.Other, Untagged: b.Untagged})
}
return out
}
type sharesJSON struct {
Top []shareJSON `json:"top"`
Other float64 `json:"other"`
@ -118,6 +148,7 @@ func (h *statsHandlers) listening(c *gin.Context) {
"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),
"genre_timeline": timelineBody(got.GenreTimeline),
}
if !got.First.IsZero() {
body["first"] = got.First.UTC().Format(time.RFC3339)

View file

@ -78,6 +78,10 @@ func TestTheListeningStatsAreAskedForThePersonAndThePeriod(t *testing.T) {
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{}},
GenreTimeline: stats.Timeline{Unit: "month", Genres: []string{"rock", "jazz"}, Buckets: []stats.TimelineBucket{
{Year: 2025, Month: 3, Listens: 4, Shares: []float64{0.5, 0.25}, Other: 0, Untagged: 0.25},
{Year: 2025, Month: 4, Shares: []float64{0, 0}},
}},
}}
f.listening.Hours[21] = 5
f.listening.Weekdays[2] = 5
@ -105,6 +109,19 @@ func TestTheListeningStatsAreAskedForThePersonAndThePeriod(t *testing.T) {
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"])
}
tl := sub(b, "genre_timeline")
buckets, _ := tl["buckets"].([]any)
genres, _ := tl["genres"].([]any)
if tl["unit"] != "month" || len(genres) != 2 || genres[0] != "rock" || len(buckets) != 2 {
t.Fatalf("timeline = %v", tl)
}
m := buckets[0].(map[string]any)
if m["year"] != 2025.0 || m["month"] != 3.0 || m["listens"] != 4.0 || m["other"] != 0.0 || m["untagged"] != 0.25 || m["shares"].([]any)[1] != 0.25 {
t.Errorf("bucket = %v", m)
}
if e := buckets[1].(map[string]any); e["listens"] != 0.0 || len(e["shares"].([]any)) != 2 {
t.Errorf("empty bucket = %v", e)
}
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 {
@ -117,7 +134,7 @@ func TestTheListeningStatsAreAskedForThePersonAndThePeriod(t *testing.T) {
}
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{}}}}
f := &fakeStats{listening: stats.Listening{Years: []stats.Bucket{}, TopArtists: []stats.Ranked{}, TopSongs: []stats.Ranked{}, Genres: stats.Genres{Top: []stats.Share{}}, GenreTimeline: stats.Timeline{Unit: "year", Genres: []string{}, Buckets: []stats.TimelineBucket{}}}}
h, tok := statsAPI(t, f)
r := do(t, h, "GET", "/api/v1/stats/listening", tok, nil)
if r.Code != 200 {
@ -129,6 +146,9 @@ func TestListeningStatsWithNoListensLeaveOutTheFirstDay(t *testing.T) {
if f.loc == nil || f.loc != time.UTC {
t.Errorf("zone without tz = %v, want UTC", f.loc)
}
if tl := sub(r.Body, "genre_timeline"); tl["unit"] != "year" || len(tl["genres"].([]any)) != 0 || len(tl["buckets"].([]any)) != 0 {
t.Errorf("genre_timeline = %v, want an empty one", tl)
}
if a, ok := r.Body["top_artists"].([]any); !ok || len(a) != 0 {
t.Errorf("top_artists = %v, want []", r.Body["top_artists"])
}

View file

@ -5226,7 +5226,7 @@ components:
ListeningStats:
type: object
additionalProperties: false
required: [listens, songs, artists, played_ms, years, hours, weekdays, top_artists, top_songs, genres]
required: [listens, songs, artists, played_ms, years, hours, weekdays, top_artists, top_songs, genres, genre_timeline]
properties:
listens: {type: integer}
songs: {type: integer, description: How many different songs.}
@ -5276,6 +5276,35 @@ components:
artists: {type: array, items: {type: string}}
listens: {type: integer}
genres: {$ref: '#/components/schemas/GenreShares'}
genre_timeline:
type: object
additionalProperties: false
required: [unit, genres, buckets]
description: |
How the genres you listen to changed over time: by year, or by month when all the listens fall in one
year. Years and months with no listen between the first and the last are there, with no listens. The
time zone is `tz`.
properties:
unit: {type: string, enum: [year, month]}
genres:
type: array
description: The five biggest genres, biggest first. Each bucket has a share for each, in this order.
items: {type: string}
buckets:
type: array
items:
type: object
additionalProperties: false
required: [year, listens, shares, other, untagged]
properties:
year: {type: integer}
month: {type: integer, minimum: 1, maximum: 12, description: Left out when `unit` is `year`.}
listens: {type: integer}
shares:
type: array
items: {type: number, minimum: 0, maximum: 1}
other: {type: number, minimum: 0, maximum: 1, description: The share of the smaller genres.}
untagged: {type: number, minimum: 0, maximum: 1, description: The share with no genre.}
ListeningSuggestions:
type: object

View file

@ -7,6 +7,7 @@ package stats
import (
"context"
"errors"
"math"
"sort"
"time"
)
@ -21,6 +22,8 @@ const (
topRanked = 10
// A year outside these is not a year a song came out: a bad tag.
minYear, maxYear = 1000, 2999
// timelineGenres is how many genres the chart over time names; the rest are one "other" part.
timelineGenres = 5
)
// Range is a period: From is included and Until is excluded. A zero time leaves that side open.
@ -47,6 +50,14 @@ type GenreWeight struct {
Weight float64
}
// GenreListen is a listen with one of the genres of its song, and the part of the listen that genre has: 1 for a song
// with one genre, 1/n for a song with n. A listen of a song with no genre is one row with an empty Genre and weight 1.
type GenreListen struct {
At int64 // unix seconds
Genre string
Weight float64
}
// YearCount is how many songs came out in a year.
type YearCount struct{ Year, Songs int }
@ -80,6 +91,8 @@ type Store interface {
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)
// ListenGenreTimes gives every listen with the genres of its song, for the chart of the genres over time.
ListenGenreTimes(ctx context.Context, userID, minMs int64, r Range) ([]GenreListen, error)
}
// Share is a genre and how much of the whole it is, from 0 to 1.
@ -117,6 +130,25 @@ type Library struct {
NoYear int // songs whose file has no year
}
// TimelineBucket is a year or a month of listens, and what share of them each genre of the timeline has. Shares go with
// Timeline.Genres; Other is the part of the smaller genres and Untagged the part with no genre. A bucket with listens
// adds up to 1; one with none is all zero.
type TimelineBucket struct {
Year, Month int // Month is 0 when the timeline is by year
Listens int
Shares []float64
Other float64
Untagged float64
}
// Timeline is how the genres you listen to changed over time: by year, or by month when the listens are all in one
// year. The years and months with no listen between the first and the last are there, empty.
type Timeline struct {
Unit string // "year" or "month"
Genres []string
Buckets []TimelineBucket
}
// Bucket is a count under a key: a year.
type Bucket struct{ Key, Count int }
@ -130,6 +162,7 @@ type Listening struct {
Weekdays [7]int // from Monday
TopArtists, TopSongs []Ranked
Genres Genres
GenreTimeline Timeline
}
// Service works out the statistics.
@ -201,8 +234,14 @@ func (s *Service) Listening(ctx context.Context, userID int64, r Range, loc *tim
return Listening{}, err
}
genreTimes, err := s.store.ListenGenreTimes(ctx, userID, minMs, r)
if err != nil {
return Listening{}, err
}
out := Listening{
Listens: totals.Listens, Songs: totals.Songs, Artists: totals.Artists, PlayedMs: totals.PlayedMs,
GenreTimeline: shapeTimeline(genreTimes, loc),
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),
@ -221,6 +260,95 @@ func (s *Service) Listening(ctx context.Context, userID int64, r Range, loc *tim
return out, nil
}
// shapeTimeline groups the genres of the listens by year, or by month when they all fall in one year, in the time zone
// loc, and works out the share of each of the biggest genres in each.
func shapeTimeline(rows []GenreListen, loc *time.Location) Timeline {
out := Timeline{Unit: "year", Genres: []string{}, Buckets: []TimelineBucket{}}
if len(rows) == 0 {
return out
}
years := map[int]bool{}
weight := map[string]float64{}
for _, r := range rows {
years[time.Unix(r.At, 0).In(loc).Year()] = true
if r.Genre != "" {
weight[r.Genre] += r.Weight
}
}
if len(years) < 2 {
out.Unit = "month"
}
names := make([]string, 0, len(weight))
for g := range weight {
names = append(names, g)
}
sort.Slice(names, func(i, j int) bool {
if weight[names[i]] != weight[names[j]] {
return weight[names[i]] > weight[names[j]]
}
return names[i] < names[j]
})
if len(names) > timelineGenres {
names = names[:timelineGenres]
}
out.Genres = names
column := map[string]int{}
for i, g := range names {
column[g] = i
}
type sums struct {
total, other, untagged float64
genre []float64
}
key := func(t time.Time) int { // a year, or a year and a month: 202603
if out.Unit == "year" {
return t.Year() * 100
}
return t.Year()*100 + int(t.Month())
}
by := map[int]*sums{}
first, last := math.MaxInt, 0
for _, r := range rows {
k := key(time.Unix(r.At, 0).In(loc))
first, last = min(first, k), max(last, k)
b := by[k]
if b == nil {
b = &sums{genre: make([]float64, len(names))}
by[k] = b
}
b.total += r.Weight
switch i, named := column[r.Genre]; {
case r.Genre == "":
b.untagged += r.Weight
case named:
b.genre[i] += r.Weight
default:
b.other += r.Weight
}
}
for k := first; k <= last; {
year, month := k/100, k%100
bucket := TimelineBucket{Year: year, Month: month, Shares: make([]float64, len(names))}
if b := by[k]; b != nil && b.total > 0 {
bucket.Listens = int(math.Round(b.total))
for i, w := range b.genre {
bucket.Shares[i] = w / b.total
}
bucket.Other, bucket.Untagged = b.other/b.total, b.untagged/b.total
}
out.Buckets = append(out.Buckets, bucket)
if out.Unit == "year" {
k += 100
} else if month == 12 {
k = (year+1)*100 + 1
} else {
k++
}
}
return out
}
func nonNil(r []Ranked) []Ranked {
if r == nil {
return []Ranked{}

View file

@ -19,6 +19,7 @@ type fakeStore struct {
times []int64
artists []Ranked
songs []Ranked
genreTime []GenreListen
gotRange Range
gotMinMs int64
gotUserID int64
@ -49,6 +50,10 @@ func (f *fakeStore) TopSongs(_ context.Context, u, m int64, r Range, _ int) ([]R
f.note(u, m, r)
return f.songs, nil
}
func (f *fakeStore) ListenGenreTimes(_ context.Context, u, m int64, r Range) ([]GenreListen, error) {
f.note(u, m, r)
return f.genreTime, 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
@ -206,3 +211,121 @@ func TestARangeThatEndsBeforeItStartsIsRefused(t *testing.T) {
t.Errorf("err = %v", err)
}
}
func at(y int, m time.Month, d int) int64 { return time.Date(y, m, d, 12, 0, 0, 0, time.UTC).Unix() }
// one is a listen of a song with one genre; two is a listen of a song with two, each weighing half; none has no genre.
func one(when int64, genre string) []GenreListen { return []GenreListen{{when, genre, 1}} }
func two(when int64, a, b string) []GenreListen {
return []GenreListen{{when, a, 0.5}, {when, b, 0.5}}
}
func none(when int64) []GenreListen { return []GenreListen{{when, "", 1}} }
func join(parts ...[]GenreListen) []GenreListen {
var out []GenreListen
for _, p := range parts {
out = append(out, p...)
}
return out
}
func timeline(t *testing.T, rows []GenreListen, loc *time.Location) Timeline {
t.Helper()
got, err := NewService(&fakeStore{genreTime: rows}, time.Second).Listening(context.Background(), 1, Range{}, loc)
if err != nil {
t.Fatal(err)
}
return got.GenreTimeline
}
func TestGenresOverTimeAreSharesOfEachYearAndYearsWithNoListensAreEmpty(t *testing.T) {
tl := timeline(t, join(
one(at(2019, 3, 1), "rock"), one(at(2019, 4, 1), "rock"), one(at(2019, 5, 1), "jazz"), none(at(2019, 6, 1)),
one(at(2021, 1, 1), "jazz"), two(at(2021, 2, 1), "jazz", "rock"),
), time.UTC)
if tl.Unit != "year" {
t.Fatalf("unit = %q, two years of listens are shown by year", tl.Unit)
}
// rock: 2 + 0.5, jazz: 1 + 1.5 = 2.5 each; equal weights: by name.
if len(tl.Genres) != 2 || tl.Genres[0] != "jazz" || tl.Genres[1] != "rock" {
t.Fatalf("genres = %v", tl.Genres)
}
if len(tl.Buckets) != 3 || tl.Buckets[0].Year != 2019 || tl.Buckets[1].Year != 2020 || tl.Buckets[2].Year != 2021 {
t.Fatalf("buckets = %+v", tl.Buckets)
}
b := tl.Buckets[0] // 4 listens: 2 rock, 1 jazz, 1 without a genre
if b.Listens != 4 || !near(b.Shares[0], 0.25) || !near(b.Shares[1], 0.5) || !near(b.Other, 0) || !near(b.Untagged, 0.25) {
t.Errorf("2019 = %+v", b)
}
if e := tl.Buckets[1]; e.Listens != 0 || e.Shares[0] != 0 || e.Shares[1] != 0 || e.Other != 0 || e.Untagged != 0 {
t.Errorf("2020 = %+v, want empty", e)
}
if c := tl.Buckets[2]; c.Listens != 2 || !near(c.Shares[0], 0.75) || !near(c.Shares[1], 0.25) {
t.Errorf("2021 = %+v (a listen of two genres is split)", c)
}
}
func TestOneYearOfListensIsShownByMonthWithMonthsInBetween(t *testing.T) {
tl := timeline(t, join(one(at(2025, 1, 10), "rock"), one(at(2025, 4, 10), "rock"), one(at(2025, 4, 11), "jazz")), time.UTC)
if tl.Unit != "month" || len(tl.Buckets) != 4 {
t.Fatalf("unit %q, buckets %+v", tl.Unit, tl.Buckets)
}
for i, m := range []int{1, 2, 3, 4} {
if tl.Buckets[i].Year != 2025 || tl.Buckets[i].Month != m {
t.Errorf("bucket %d = %d-%d", i, tl.Buckets[i].Year, tl.Buckets[i].Month)
}
}
if tl.Buckets[1].Listens != 0 || tl.Buckets[3].Listens != 2 || !near(tl.Buckets[3].Shares[0], 0.5) {
t.Errorf("%+v", tl.Buckets)
}
}
func TestListensInTwoCalendarYearsAreShownByYearEvenWhenCloseTogether(t *testing.T) {
tl := timeline(t, join(one(at(2025, 11, 10), "rock"), one(at(2026, 1, 10), "rock")), time.UTC)
// Two calendar years: by year. The month view is for the listens of a single year.
if tl.Unit != "year" || len(tl.Buckets) != 2 {
t.Fatalf("%q %+v", tl.Unit, tl.Buckets)
}
}
func TestGenresOverTimeAreCountedInTheZoneOfTheListener(t *testing.T) {
rome, err := time.LoadLocation("Europe/Rome")
if err != nil {
t.Skip("no tzdata")
}
// 2025-12-31 23:30 UTC is 2026-01-01 00:30 in Rome.
tl := timeline(t, one(time.Date(2025, 12, 31, 23, 30, 0, 0, time.UTC).Unix(), "rock"), rome)
if tl.Unit != "month" || len(tl.Buckets) != 1 || tl.Buckets[0].Year != 2026 || tl.Buckets[0].Month != 1 {
t.Errorf("%q %+v", tl.Unit, tl.Buckets)
}
}
func TestOnlyTheFiveBiggestGenresAreNamedAndTheRestAreOther(t *testing.T) {
var rows []GenreListen
for i, g := range []string{"a", "b", "c", "d", "e", "f", "g"} {
for n := 0; n <= 6-i; n++ { // a: 7 listens ... g: 1
rows = append(rows, one(at(2025, 3, 1+n), g)...)
}
}
tl := timeline(t, rows, time.UTC)
if len(tl.Genres) != 5 || tl.Genres[0] != "a" || tl.Genres[4] != "e" {
t.Fatalf("genres = %v", tl.Genres)
}
b := tl.Buckets[0]
if b.Listens != 28 || !near(b.Other, 3.0/28) { // f (2) + g (1)
t.Errorf("%+v", b)
}
sum := b.Other + b.Untagged
for _, s := range b.Shares {
sum += s
}
if !near(sum, 1) {
t.Errorf("shares add up to %v", sum)
}
}
func TestNoListensHaveNoTimeline(t *testing.T) {
tl := timeline(t, nil, time.UTC)
if tl.Genres == nil || tl.Buckets == nil || len(tl.Genres) != 0 || len(tl.Buckets) != 0 || tl.Unit != "year" {
t.Errorf("%+v", tl)
}
}

View file

@ -2,6 +2,7 @@ package storage
import (
"context"
"database/sql"
"fmt"
"sort"
@ -254,3 +255,32 @@ func (r *StatsRepo) ListenGenres(ctx context.Context, userID, minMs int64, rng s
sort.Slice(out, func(i, j int) bool { return out[i].Genre < out[j].Genre })
return out, tagged, nil
}
// ListenGenreTimes gives every listen with the genres of its song: one row for each genre, weighing 1/n for a song with
// n, or one row with no genre for a song that has none. The listens of a year or a month, and the share of each genre in
// them, are worked out by the caller in the time zone of the listener.
func (r *StatsRepo) ListenGenreTimes(ctx context.Context, userID, minMs int64, rng stats.Range) ([]stats.GenreListen, error) {
where, args := listensWhere(userID, minMs, rng)
rows, err := r.db.QueryContext(ctx,
"SELECT e.occurred_at, g.genre, 1.0 / c.n FROM listening_events e LEFT JOIN track_genres g ON g.track_id = e.track_id "+
"LEFT JOIN "+genresPerTrack+" c ON c.track_id = e.track_id WHERE "+where, args...)
if err != nil {
return nil, fmt.Errorf("read the genres of the listens: %w", err)
}
defer rows.Close()
var out []stats.GenreListen
for rows.Next() {
var at int64
var genre sql.NullString
var weight sql.NullFloat64
if err := rows.Scan(&at, &genre, &weight); err != nil {
return nil, err
}
g := stats.GenreListen{At: at, Genre: genre.String, Weight: 1}
if genre.Valid {
g.Weight = weight.Float64
}
out = append(out, g)
}
return out, rows.Err()
}

View file

@ -239,3 +239,49 @@ func TestTheStatsOfAPersonWithNoListensAreEmpty(t *testing.T) {
}
})
}
func TestEachListenCarriesTheGenresOfItsSongAndTheyWeighOne(t *testing.T) {
forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) {
w := seedStats(t, db)
lib, _ := NewLibraryRepo(db).ListLibraries(w.ctx)
bare := affinitySong(t, db, lib[0].ID, "e.flac", "Untitled", "Nobody") // a song with no genre
if _, err := w.listens.Record(w.ctx, listening.Event{UserID: w.alice, TrackID: bare, Type: listening.Complete, OccurredAt: w.jun.Add(time.Hour), DurationPlayedMs: 100_000, IdempotencyKey: "bare"}); err != nil {
t.Fatal(err)
}
rows, err := w.repo.ListenGenreTimes(w.ctx, w.alice, 20_000, stats.Range{})
if err != nil {
t.Fatal(err)
}
// Debaser three times with two genres (6 rows), Where Is My Mind, Song 2 and the song with no genre (1 row each).
if len(rows) != 9 {
t.Fatalf("%d rows: %+v", len(rows), rows)
}
perListen := map[int64]float64{}
genres := map[string]float64{}
for _, r := range rows {
perListen[r.At] += r.Weight
genres[r.Genre] += r.Weight
}
if len(perListen) != 6 {
t.Errorf("%d listens, want 6", len(perListen))
}
for at, sum := range perListen {
if sum != 1 {
t.Errorf("the listen at %d weighs %v, want 1", at, sum)
}
}
if genres["rock"] != 2.5 || genres["alternative"] != 1.5 || genres["britpop"] != 1 || genres[""] != 1 {
t.Errorf("genres = %v (the empty one is the song with no genre)", genres)
}
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)}
if cut, _ := w.repo.ListenGenreTimes(w.ctx, w.alice, 20_000, year); len(cut) != 7 { // not the listen of 2026 (2 rows), nor bob's
t.Errorf("2025 has %d rows, want 7", len(cut))
}
bob, _ := w.repo.ListenGenreTimes(w.ctx, w.bob, 20_000, stats.Range{})
if len(bob) != 2 {
t.Errorf("bob has %d rows, want the 2 of one listen", len(bob))
}
})
}

View file

@ -3563,6 +3563,28 @@ export interface components {
listens: number;
}[];
genres: components["schemas"]["GenreShares"];
/**
* @description How the genres you listen to changed over time: by year, or by month when all the listens fall in one
* year. Years and months with no listen between the first and the last are there, with no listens. The
* time zone is `tz`.
*/
genre_timeline: {
/** @enum {string} */
unit: "year" | "month";
/** @description The five biggest genres, biggest first. Each bucket has a share for each, in this order. */
genres: string[];
buckets: {
year: number;
/** @description Left out when `unit` is `year`. */
month?: number;
listens: number;
shares: number[];
/** @description The share of the smaller genres. */
other: number;
/** @description The share with no genre. */
untagged: number;
}[];
};
};
ListeningSuggestions: {
library: components["schemas"]["ListeningSuggestion"][];

View file

@ -58,3 +58,38 @@ export function Columns({ label, columns, className }: { label: string; columns:
</ul>
)
}
export interface StackedColumn {
key: string
/** What is shown under the column. */
label: string
/** What a screen reader reads for the column. */
name: string
/** The parts of the whole, from the bottom up, each from 0 to 1. A column of no parts is empty. */
parts: number[]
}
const STACK_HEIGHT = 144
/**
* Columns that are each the whole, cut in parts: how the share of each genre changed from one year to the next. The
* colours are given by index, the same as in the legend; a part that is 0 is not drawn.
*/
export function StackedColumns({ label, columns, colors }: { label: string; columns: StackedColumn[]; colors: string[] }) {
return (
<ul aria-label={label} className="flex items-end gap-1">
{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="flex w-full flex-col-reverse overflow-hidden rounded-sm bg-card" style={{ height: `${STACK_HEIGHT}px` }}>
{c.parts.map((p, i) =>
p > 0 ? <span key={i} className="block w-full border-t border-background first:border-t-0" style={{ height: `${p * 100}%`, background: colors[i] }} /> : null,
)}
</span>
<span aria-hidden="true" className="h-4 text-[13px] leading-4 tabular-nums text-muted-foreground">
{c.label}
</span>
</li>
))}
</ul>
)
}

View file

@ -1127,6 +1127,9 @@
"songsIn_other": "{{label}}: {{n}} songs",
"listensIn_one": "{{label}}: {{n}} listen",
"listensIn_other": "{{label}}: {{n}} listens",
"decadeShort": "{{short}}s"
"decadeShort": "{{short}}s",
"overTime": "Genres over time",
"timelineNone": "{{label}}: no listens",
"timelineIn": "{{label}}: {{parts}}"
}
}

View file

@ -1127,6 +1127,9 @@
"songsIn_other": "{{label}}: {{n}} brani",
"listensIn_one": "{{label}}: {{n}} ascolto",
"listensIn_other": "{{label}}: {{n}} ascolti",
"decadeShort": "{{short}}"
"decadeShort": "{{short}}",
"overTime": "Generi nel tempo",
"timelineNone": "{{label}}: nessun ascolto",
"timelineIn": "{{label}}: {{parts}}"
}
}

View file

@ -61,6 +61,15 @@ const listening = {
],
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 },
genre_timeline: {
unit: 'year',
genres: ['rock', 'jazz'],
buckets: [
{ year: 2019, listens: 100, shares: [0.6, 0.2], other: 0.1, untagged: 0.1 },
{ year: 2020, listens: 0, shares: [0, 0], other: 0, untagged: 0 },
{ year: 2021, listens: 400, shares: [0.5, 0.3], other: 0.2, untagged: 0 },
],
},
}
const none = {
@ -74,6 +83,7 @@ const none = {
top_artists: [],
top_songs: [],
genres: { top: [], other: 0, untagged: 0, untagged_share: 0 },
genre_timeline: { unit: 'year', genres: [], buckets: [] },
}
function setup(routes: MockRoutes = {}) {
@ -168,6 +178,54 @@ test('one year has no chart by year: there is nothing to compare', async () => {
expect(within(l).queryByRole('list', { name: 'Listens by year' })).not.toBeInTheDocument()
})
test('the genres over time are columns by year, each said in words, with the parts that are there', async () => {
setup()
const l = await section('Your listening')
const chart = within(l).getByRole('list', { name: 'Genres over time' })
const items = within(chart).getAllByRole('listitem')
expect(items.map((li) => li.getAttribute('aria-label'))).toEqual([
'2019: rock 60%, jazz 20%, Smaller genres 10%, No genre 10%',
'2020: no listens',
'2021: rock 50%, jazz 30%, Smaller genres 20%',
])
expect(items.map((li) => li.textContent)).toEqual(['2019', '2020', '2021'])
})
test('the chart has a legend of the genres it names, the smaller ones and what has no genre', async () => {
setup()
const l = await section('Your listening')
const legend = within(l).getByTestId('timeline-legend')
expect(within(legend).getAllByRole('listitem').map((li) => li.textContent)).toEqual(['rock', 'jazz', 'Smaller genres', 'No genre'])
})
test('listens in a single year are shown by month', async () => {
setup({
'GET /api/v1/stats/listening': () => ({
...listening,
genre_timeline: {
unit: 'month',
genres: ['rock'],
buckets: [
{ year: 2025, month: 3, listens: 4, shares: [1], other: 0, untagged: 0 },
{ year: 2025, month: 4, listens: 2, shares: [0.5], other: 0.5, untagged: 0 },
],
},
}),
})
const l = await section('Your listening')
const items = within(within(l).getByRole('list', { name: 'Genres over time' })).getAllByRole('listitem')
expect(items.map((li) => li.getAttribute('aria-label'))).toEqual(['March 2025: rock 100%', 'April 2025: rock 50%, Smaller genres 50%'])
expect(items.map((li) => li.textContent)).toEqual(['M', 'A'])
})
test('one column is not a change over time: the chart is left out', async () => {
setup({
'GET /api/v1/stats/listening': () => ({ ...listening, genre_timeline: { unit: 'year', genres: ['rock'], buckets: [{ year: 2021, listens: 400, shares: [1], other: 0, untagged: 0 }] } }),
})
const l = await section('Your listening')
expect(within(l).queryByRole('list', { name: 'Genres over time' })).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')

View file

@ -1,7 +1,7 @@
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 { PERIODS, useLibraryStats, useListeningStats, type GenreShares, type ListeningStats, type Period } from '@/api/stats'
import { Columns, ShareBars, StackedColumns, type Bar } from '@/components/StatBars'
import PageTitle from '@/components/PageTitle'
import { EmptyMessage, ErrorMessage, Loading } from '@/components/Status'
import { Button } from '@/components/ui/button'
@ -59,6 +59,55 @@ function GenreBars({ label, genres }: { label: string; genres: GenreShares }) {
return <ShareBars label={label} bars={bars} />
}
/**
* The colours of the parts of a column of genres, from the biggest genre on: the colour of this server, thinner and
* thinner towards the background, so that the order of the legend is the order of the stack in every theme. Then the
* smaller genres and what has no genre, in greys.
*/
const TINTS = [100, 82, 66, 52, 42]
const tint = (i: number) => `color-mix(in oklab, var(--primary) ${TINTS[Math.min(i, TINTS.length - 1)]}%, var(--background))`
const OTHER_COLOR = 'color-mix(in oklab, var(--muted-foreground) 65%, var(--background))'
const NONE_COLOR = 'var(--muted)'
/** How the genres changed over time: a column for each year (or month), each genre's share of it, and the legend. */
function GenreTimeline({ timeline }: { timeline: ListeningStats['genre_timeline'] }) {
const { t } = useTranslation()
const f = useFormat()
if (timeline.buckets.length < 2) return null
const withOther = timeline.buckets.some((b) => b.other > 0)
const withNone = timeline.buckets.some((b) => b.untagged > 0)
const names = [...timeline.genres, ...(withOther ? [t('stats.other')] : []), ...(withNone ? [t('stats.noGenre')] : [])]
const colors = [...timeline.genres.map((_, i) => tint(i)), ...(withOther ? [OTHER_COLOR] : []), ...(withNone ? [NONE_COLOR] : [])]
const monthShort = new Intl.DateTimeFormat(f.lang, { month: 'narrow' })
const monthLong = new Intl.DateTimeFormat(f.lang, { month: 'long', year: 'numeric' })
const many = timeline.buckets.length > 8
const columns = timeline.buckets.map((b) => {
const parts = [...b.shares, ...(withOther ? [b.other] : []), ...(withNone ? [b.untagged] : [])]
const date = new Date(b.year, (b.month ?? 1) - 1, 1)
const label = timeline.unit === 'month' ? monthLong.format(date) : String(b.year)
const said = parts.flatMap((p, i) => (p > 0 ? [`${names[i]} ${f.percent(p)}`] : []))
return {
key: `${b.year}-${b.month ?? 0}`,
label: timeline.unit === 'month' ? monthShort.format(date) : many ? String(b.year).slice(2) : String(b.year),
name: b.listens === 0 ? t('stats.timelineNone', { label }) : t('stats.timelineIn', { label, parts: said.join(', ') }),
parts,
}
})
return (
<Block title={t('stats.overTime')}>
<StackedColumns label={t('stats.overTime')} columns={columns} colors={colors} />
<ul data-testid="timeline-legend" className="flex flex-wrap gap-x-5 gap-y-1 text-sm">
{names.map((n, i) => (
<li key={n} className="flex items-center gap-2">
<span aria-hidden="true" className="size-3 rounded-sm" style={{ background: colors[i] }} />
<span className="first-letter:uppercase">{n}</span>
</li>
))}
</ul>
</Block>
)
}
function LibrarySection() {
const { t } = useTranslation()
const f = useFormat()
@ -204,6 +253,7 @@ function ListeningSection() {
<GenreBars label={t('stats.yourGenres')} genres={l.genres} />
</Block>
)}
<GenreTimeline timeline={l.genre_timeline} />
</>
)
}