feat: the seek bar shows the waveform of the track

The seek bar of the player is the shape of the track, with the part already
heard in colour, as in the approved mockups.

- GET /tracks/{id}/peaks gives 120 levels from 0 to 255 (the loudest part is
  255 whatever the volume). The server finds them by decoding the file, MP3 with
  go-mp3 and FLAC with eaburns/flac, both in pure Go. It takes a few seconds, so
  the first request starts the work in the background and answers 202 with
  Retry-After. It is done once for each file (migration 0025), worked out again
  if the size or the date of the file change, one track at a time so that a NAS
  is not kept busy, and a file that cannot be decoded is remembered as such. A
  track deleted while its file is being decoded is not an error.
- The seek bar of the player bar and of the full-screen player draws the shape
  and asks again every few seconds until it is there. Until then, and for a
  friend's track, which has none, the bar is flat. The heard part is teal, or
  the friend colour. It is still a native range input, 44 pixels high in the
  bar.
- OpenAPI path and schema, contract test, tests with real MP3 and FLAC files,
  and a real server checked: a 4-minute MP3 is ready in about a second and a
  half, a 12 MB FLAC in three, and asking again takes a millisecond.
This commit is contained in:
tgiachi 2026-11-13 17:35:00 +01:00
commit bfa3e6e458
14 changed files with 1213 additions and 55 deletions

View file

@ -37,6 +37,7 @@ import (
"codeberg.org/squidd/sonda/internal/streaming"
"codeberg.org/squidd/sonda/internal/taste"
"codeberg.org/squidd/sonda/internal/usersettings"
"codeberg.org/squidd/sonda/internal/waveform"
"codeberg.org/squidd/sonda/migrations"
)
@ -112,6 +113,7 @@ func newTestEnvDB(t *testing.T, mutate func(*Deps, *bun.DB)) (http.Handler, *bun
libRepo := storage.NewLibraryRepo(db)
deps.PeerCatalog = catalog.NewService(storage.NewSharedCatalogRepo(db))
deps.PeerStreams = streaming.NewService(libRepo.Shared())
deps.Waveform = waveform.NewService(storage.NewWaveformRepo(db), streaming.NewService(libRepo))
feedbackSvc := feedback.NewService(storage.NewFeedbackRepo(db))
deps.Feedback = feedbackSvc
deps.Playlists = playlists.NewService(storage.NewPlaylistRepo(db))

View file

@ -832,6 +832,7 @@ func TestResponsesMatchTheSpec(t *testing.T) {
c.mixes(t, token, libID)
c.smartPlaylists(t, token)
c.names(t, token)
c.peaks(t, token)
c.federation(t, token, libID, albumID)
// ---- every operation in the spec was exercised ----
@ -1355,3 +1356,14 @@ func (c *contract) friends(t *testing.T, token string) {
c.expect(c.call("GET", base+"/tracks", token, nil), 409, "a friend that removed this server", "friend_gone")
c.expect(c.call("DELETE", "/federation/friends/"+fid, token, nil), 204, "forget the friend")
}
// peaks asks for the shape of tracks. The files of this test are not audio, so none can be decoded.
func (c *contract) peaks(t *testing.T, token string) {
t.Helper()
c.expect(c.call("GET", "/tracks/1/peaks", "", nil), 401, "the shape of a track without a login", "unauthorized")
c.expect(c.call("GET", "/tracks/abc/peaks", token, nil), 400, "the shape of a track that is no number", "invalid_input")
c.expect(c.call("GET", "/tracks/999999/peaks", token, nil), 404, "the shape of a track that is not there", "track_not_found")
tracks := c.expect(c.call("GET", "/tracks?limit=1", token, nil), 200, "a track")["items"].([]any)
id := idOf(tracks[0].(map[string]any))
c.expect(c.call("GET", "/tracks/"+id+"/peaks", token, nil), 404, "the shape of a file that is not audio", "waveform_unavailable")
}

View file

@ -0,0 +1,46 @@
package httpapi
import (
"context"
"errors"
"net/http"
"github.com/gin-gonic/gin"
"codeberg.org/squidd/sonda/internal/streaming"
"codeberg.org/squidd/sonda/internal/waveform"
)
type waveformHandlers struct{ svc waveformService }
// peaks gives the shape of a track: how loud it is along its length, in a few levels from 0 to 255, for the seek bar.
// The first time it is asked for, the server starts working it out and says so (202); the page asks again.
func (h *waveformHandlers) peaks(c *gin.Context) {
id, ok := pathID(c)
if !ok {
return
}
peaks, err := h.svc.Peaks(c.Request.Context(), id)
switch {
case err == nil:
levels := make([]int, len(peaks))
for i, v := range peaks {
levels[i] = int(v)
}
c.JSON(http.StatusOK, gin.H{"count": len(levels), "peaks": levels})
case errors.Is(err, waveform.ErrNotReady):
c.Header("Retry-After", "3")
c.JSON(http.StatusAccepted, gin.H{"status": "working"})
case errors.Is(err, streaming.ErrNotFound):
writeError(c, http.StatusNotFound, "track_not_found", "no playable file for this track")
case errors.Is(err, streaming.ErrFileMissing), errors.Is(err, streaming.ErrUnsafePath):
writeError(c, http.StatusNotFound, "file_missing", "the audio file is not available")
case errors.Is(err, waveform.ErrUnsupported):
writeError(c, http.StatusNotFound, "waveform_unavailable", "the waveform of this file cannot be worked out")
case errors.Is(err, context.Canceled):
c.AbortWithStatus(statusClientClosed) // the page was left; nobody is waiting
default:
_ = c.Error(err)
writeError(c, http.StatusInternalServerError, "internal", "internal error")
}
}

View file

@ -179,6 +179,10 @@ type catalogService interface {
Track(ctx context.Context, id int64) (catalog.Track, error)
}
type waveformService interface {
Peaks(ctx context.Context, trackID int64) ([]byte, error)
}
type libraryService interface {
List(ctx context.Context) ([]library.Library, error)
Create(ctx context.Context, name, path string) (library.Library, error)
@ -224,6 +228,8 @@ type Deps struct {
PeerCatalog catalogService
PeerStreams streamService
PeerCovers coverService
// The shape of a track, for the seek bar.
Waveform waveformService
// Web is the built web app, served on / and for its own links. It is optional: with none (a build
// without the app) / shows a page that says how to build it, and the API works the same.
Web fs.FS
@ -360,6 +366,7 @@ func NewRouter(d Deps) *gin.Engine {
protected.GET("/albums/:id", cat.getAlbum)
protected.GET("/tracks", cat.listTracks)
protected.GET("/tracks/:id", cat.getTrack)
protected.GET("/tracks/:id/peaks", (&waveformHandlers{svc: d.Waveform}).peaks)
// Audio loaded by an <audio> element cannot send headers, so this route also
// takes the access token as a query parameter. It never records a listen.

View file

@ -0,0 +1,111 @@
package httpapi
import (
"context"
"net/http"
"net/http/httptest"
"path/filepath"
"testing"
"codeberg.org/squidd/sonda/internal/storage"
"codeberg.org/squidd/sonda/internal/streaming"
"codeberg.org/squidd/sonda/internal/waveform"
"github.com/uptrace/bun"
)
func TestThePeaksOfATrackNeedALoginAndAreItsWaveform(t *testing.T) {
root, err := filepath.Abs(filepath.Join("..", "..", "waveform", "testdata"))
if err != nil {
t.Fatal(err)
}
h, _ := newTestEnvDB(t, func(d *Deps, db *bun.DB) {
// Track 1 is made by the test environment; the second one is made here.
if _, err := db.Exec("INSERT INTO tracks (title) VALUES ('two')"); err != nil {
t.Fatal(err)
}
d.Waveform = waveform.NewService(storage.NewWaveformRepo(db), streaming.NewService(mapSource{
1: {Root: root, RelPath: "ramp.mp3"},
2: {Root: root, RelPath: "ramp.flac"},
}))
})
if r := do(t, h, "GET", "/api/v1/tracks/1/peaks", "", nil); r.Code != http.StatusUnauthorized {
t.Errorf("without a login: %d", r.Code)
}
tok := registerAndLogin(t, h)
for _, id := range []string{"1", "2"} {
r := do(t, h, "GET", "/api/v1/tracks/"+id+"/peaks", tok, nil)
if r.Code != http.StatusOK {
t.Fatalf("track %s: %d %v", id, r.Code, r.Body)
}
sameKeys(t, "peaks", r.Body, "count", "peaks")
peaks := r.Body["peaks"].([]any)
if r.Body["count"] != float64(waveform.Count) || len(peaks) != waveform.Count {
t.Fatalf("count = %v, %d levels", r.Body["count"], len(peaks))
}
if peaks[0].(float64) > 40 || peaks[len(peaks)-1].(float64) < 230 {
t.Errorf("track %s starts at %v and ends at %v: it is a tone that rises", id, peaks[0], peaks[len(peaks)-1])
}
for _, v := range peaks {
if v.(float64) < 0 || v.(float64) > 255 {
t.Fatalf("a level of %v", v)
}
}
}
}
type fakeWaveform struct {
peaks []byte
err error
}
func (f fakeWaveform) Peaks(context.Context, int64) ([]byte, error) { return f.peaks, f.err }
func TestWhileTheShapeIsBeingWorkedOutThePageIsToldToAskAgain(t *testing.T) {
h := newTestAPIWith(t, func(d *Deps) { d.Waveform = fakeWaveform{err: waveform.ErrNotReady} })
tok := registerAndLogin(t, h)
r := do(t, h, "GET", "/api/v1/tracks/1/peaks", tok, nil)
if r.Code != http.StatusAccepted || r.Body["status"] != "working" {
t.Fatalf("while it works: %d %v", r.Code, r.Body)
}
rec := doRaw(t, h, "GET", "/api/v1/tracks/1/peaks", tok)
if rec.Header().Get("Retry-After") == "" {
t.Error("no Retry-After: the page would not know when to ask again")
}
}
func TestATrackWithNoWaveformIsSaidInWords(t *testing.T) {
for name, tc := range map[string]struct {
err error
status int
code string
}{
"a track that is not there": {streaming.ErrNotFound, http.StatusNotFound, "track_not_found"},
"a file that is gone": {streaming.ErrFileMissing, http.StatusNotFound, "file_missing"},
"a format not decoded": {waveform.ErrUnsupported, http.StatusNotFound, "waveform_unavailable"},
} {
h := newTestAPIWith(t, func(d *Deps) { d.Waveform = fakeWaveform{err: tc.err} })
tok := registerAndLogin(t, h)
r := do(t, h, "GET", "/api/v1/tracks/1/peaks", tok, nil)
if r.Code != tc.status || errCode(r) != tc.code {
t.Errorf("%s: %d %v", name, r.Code, r.Body)
}
}
h := newTestAPIWith(t, func(d *Deps) { d.Waveform = fakeWaveform{} })
tok := registerAndLogin(t, h)
if r := do(t, h, "GET", "/api/v1/tracks/abc/peaks", tok, nil); r.Code != http.StatusBadRequest {
t.Errorf("a track that is no number: %d", r.Code)
}
}
// doRaw sends a request and returns the whole answer, headers included.
func doRaw(t *testing.T, h http.Handler, method, path, token string) *httptest.ResponseRecorder {
t.Helper()
req := httptest.NewRequest(method, path, nil)
if token != "" {
req.Header.Set("Authorization", "Bearer "+token)
}
rec := httptest.NewRecorder()
h.ServeHTTP(rec, req)
return rec
}

View file

@ -2575,6 +2575,49 @@ paths:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/tracks/{id}/peaks:
parameters:
- {$ref: '#/components/parameters/Id'}
get:
tags: [Playback]
operationId: getTrackPeaks
summary: The shape of a track, for the seek bar
description: |
How loud the track is along its length, as 120 levels from 0 to 255: the loudest part is 255 whatever the volume of
the track. The server finds it by decoding the file (MP3 and FLAC, no extra program needed), which takes a few
seconds, so the first request for a track starts the work in the background and answers `202` with `Retry-After`;
ask again then. It is done once for each file and worked out again if the size or the date of the file change. One
track is worked out at a time. A file that cannot be decoded (another format, or damaged) is `waveform_unavailable`,
and that is kept too, so it is not tried at every request.
security: [{bearerAuth: []}]
responses:
'200':
description: The shape.
content:
application/json:
schema: {$ref: '#/components/schemas/Peaks'}
'202':
description: The shape is being worked out. Ask again after `Retry-After` seconds.
headers:
Retry-After:
description: Seconds to wait.
schema: {type: integer}
content:
application/json:
schema:
type: object
additionalProperties: false
required: [status]
properties:
status: {type: string, enum: [working]}
'400': {$ref: '#/components/responses/InvalidInput'}
'401': {$ref: '#/components/responses/Unauthorized'}
'404':
description: No such track (`track_not_found`), its file is not available (`file_missing`), or its shape cannot be worked out (`waveform_unavailable`).
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/tracks/{id}/stream:
parameters:
- {$ref: '#/components/parameters/Id'}
@ -5255,6 +5298,16 @@ components:
route: {type: string, description: "The route pattern, like `/api/v1/peer/tracks/:id/stream`. Never the query."}
status: {type: integer}
bytes: {type: integer, format: int64, description: Bytes of the answer.}
Peaks:
type: object
additionalProperties: false
required: [count, peaks]
properties:
count: {type: integer, description: How many levels there are (120).}
peaks:
type: array
items: {type: integer, minimum: 0, maximum: 255}
description: From the start of the track to its end.
FriendRef:
type: object
additionalProperties: false

View file

@ -147,7 +147,7 @@ func TestMigrateCreatesSchemaAndIsIdempotent(t *testing.T) {
if err := Migrate(context.Background(), db, fsys); err != nil {
t.Fatalf("second Migrate: %v", err)
}
for _, table := range []string{"artists", "albums", "tracks", "track_artists", "audio_files", "users", "listening_events", "refresh_tokens", "libraries", "provider_settings", "artist_similar", "provider_fetches", "artist_tags", "track_genres", "user_settings", "artist_feedback", "images", "artist_descriptions", "federation_settings", "federation_invites", "federation_friends", "federation_requests"} {
for _, table := range []string{"artists", "albums", "tracks", "track_artists", "audio_files", "users", "listening_events", "refresh_tokens", "libraries", "provider_settings", "artist_similar", "provider_fetches", "artist_tags", "track_genres", "user_settings", "artist_feedback", "images", "artist_descriptions", "federation_settings", "federation_invites", "federation_friends", "federation_requests", "track_peaks"} {
if !tableExists(t, db, driver, table) {
t.Errorf("table %s missing", table)
}
@ -156,8 +156,8 @@ func TestMigrateCreatesSchemaAndIsIdempotent(t *testing.T) {
if err := db.QueryRow("SELECT COUNT(*) FROM schema_migrations").Scan(&applied); err != nil {
t.Fatal(err)
}
if applied != 24 {
t.Errorf("applied migrations = %d, want 24", applied)
if applied != 25 {
t.Errorf("applied migrations = %d, want 25", applied)
}
})
}

View file

@ -0,0 +1,68 @@
package storage
import (
"context"
"database/sql"
"errors"
"fmt"
"strings"
"time"
"github.com/uptrace/bun"
"codeberg.org/squidd/sonda/internal/waveform"
)
type peaksRow struct {
bun.BaseModel `bun:"table:track_peaks"`
TrackID int64 `bun:"track_id,pk"`
SizeBytes int64 `bun:"size_bytes,notnull"`
MTimeUnix int64 `bun:"mtime_unix,notnull"`
Peaks []byte `bun:"peaks,notnull"`
UpdatedAt int64 `bun:"updated_at,notnull"`
}
// WaveformRepo keeps the shape of tracks. It implements waveform.Store.
type WaveformRepo struct{ db *bun.DB }
// NewWaveformRepo builds a WaveformRepo.
func NewWaveformRepo(db *bun.DB) *WaveformRepo { return &WaveformRepo{db: db} }
// Get returns what is kept for a track, with found=false when nothing is.
func (r *WaveformRepo) Get(ctx context.Context, trackID int64) (waveform.Record, bool, error) {
var row peaksRow
err := r.db.NewSelect().Model(&row).Where("track_id = ?", trackID).Limit(1).Scan(ctx)
if errors.Is(err, sql.ErrNoRows) {
return waveform.Record{}, false, nil
}
if err != nil {
return waveform.Record{}, false, fmt.Errorf("select track peaks: %w", err)
}
return waveform.Record{SizeBytes: row.SizeBytes, MTimeUnix: row.MTimeUnix, Peaks: row.Peaks}, true, nil
}
// Save keeps the shape of a track, replacing an older one. A track that no longer exists is not an error: its shape is
// simply not kept (it was deleted while its file was being decoded).
func (r *WaveformRepo) Save(ctx context.Context, trackID int64, rec waveform.Record) error {
peaks := rec.Peaks
if peaks == nil {
peaks = []byte{} // the column cannot be NULL: empty means "could not be decoded"
}
row := &peaksRow{TrackID: trackID, SizeBytes: rec.SizeBytes, MTimeUnix: rec.MTimeUnix, Peaks: peaks, UpdatedAt: time.Now().Unix()}
_, err := r.db.NewInsert().Model(row).
On("CONFLICT (track_id) DO UPDATE").
Set("size_bytes = EXCLUDED.size_bytes").
Set("mtime_unix = EXCLUDED.mtime_unix").
Set("peaks = EXCLUDED.peaks").
Set("updated_at = EXCLUDED.updated_at").
Exec(ctx)
if err != nil {
// The track was deleted while its file was being decoded: there is nothing to keep the shape for.
if strings.Contains(strings.ToLower(err.Error()), "foreign key") {
return nil
}
return fmt.Errorf("save track peaks: %w", err)
}
return nil
}

View file

@ -0,0 +1,60 @@
package storage
import (
"bytes"
"context"
"testing"
"github.com/uptrace/bun"
"codeberg.org/squidd/sonda/internal/waveform"
)
func TestTheShapeOfATrackIsKeptAndReplaced(t *testing.T) {
forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) {
ctx := context.Background()
repo := NewWaveformRepo(db)
var id int64
if err := db.QueryRow("INSERT INTO tracks (title) VALUES ('song') RETURNING id").Scan(&id); err != nil {
t.Fatal(err)
}
if _, found, err := repo.Get(ctx, id); err != nil || found {
t.Fatalf("before any save: found %v, %v", found, err)
}
peaks := bytes.Repeat([]byte{0, 128, 255}, 40)
if err := repo.Save(ctx, id, waveform.Record{SizeBytes: 123456, MTimeUnix: 1_700_000_000, Peaks: peaks}); err != nil {
t.Fatal(err)
}
got, found, err := repo.Get(ctx, id)
if err != nil || !found || got.SizeBytes != 123456 || got.MTimeUnix != 1_700_000_000 || !bytes.Equal(got.Peaks, peaks) {
t.Fatalf("Get = %+v, %v, %v", got, found, err)
}
// Saving again replaces it (the file changed).
if err := repo.Save(ctx, id, waveform.Record{SizeBytes: 7, MTimeUnix: 8, Peaks: nil}); err != nil {
t.Fatal(err)
}
got, _, _ = repo.Get(ctx, id)
if got.SizeBytes != 7 || got.MTimeUnix != 8 || len(got.Peaks) != 0 {
t.Errorf("after the second save: %+v: no peaks means the file cannot be decoded, and that is kept too", got)
}
// A track that goes takes its shape with it.
if _, err := db.Exec("DELETE FROM tracks WHERE id = ?", id); err != nil {
t.Fatal(err)
}
if _, found, _ := repo.Get(ctx, id); found {
t.Error("the shape of a deleted track is still kept")
}
})
}
func TestTheShapeOfATrackThatIsGoneIsNotAnError(t *testing.T) {
forEachBackend(t, func(t *testing.T, db *bun.DB, _ string) {
repo := NewWaveformRepo(db)
if err := repo.Save(context.Background(), 999, waveform.Record{SizeBytes: 1, MTimeUnix: 1, Peaks: []byte{1}}); err != nil {
t.Errorf("Save for a track that is not there: %v", err)
}
if _, found, _ := repo.Get(context.Background(), 999); found {
t.Error("a shape was kept for a track that is not there")
}
})
}

BIN
internal/waveform/testdata/ramp.flac vendored Normal file

Binary file not shown.

BIN
internal/waveform/testdata/ramp.mp3 vendored Normal file

Binary file not shown.

BIN
internal/waveform/testdata/silence.flac vendored Normal file

Binary file not shown.

View file

@ -0,0 +1,292 @@
// Package waveform works out the shape of a track: how loud it is along its length, in a few levels, to draw as the
// seek bar of the player.
//
// The shape is found by decoding the file (MP3 and FLAC, in pure Go: nothing else has to be installed), which takes
// a few seconds, so it is done the first time a track is asked for, in the background, one track at a time, and
// remembered for that file. If the file changes, the shape is worked out again. A file that cannot be decoded is
// remembered as such, so it is not tried at every request.
package waveform
import (
"context"
"errors"
"fmt"
"io"
"math"
"os"
"path/filepath"
"strings"
"time"
"golang.org/x/sync/singleflight"
flac "github.com/eaburns/flac"
mp3 "github.com/hajimehoshi/go-mp3"
"codeberg.org/squidd/sonda/internal/streaming"
)
// Count is how many levels a shape has.
const Count = 120
// Errors returned by the service.
var (
// ErrNotReady: the shape is being worked out; ask again in a moment.
ErrNotReady = errors.New("the waveform is being worked out")
// ErrUnsupported: the file is in a format that is not decoded, or cannot be decoded.
ErrUnsupported = errors.New("the waveform of this file cannot be worked out")
)
// Record is what is remembered about one track: for which file, and the levels. No levels means the file could not
// be decoded.
type Record struct {
SizeBytes int64
MTimeUnix int64
Peaks []byte
}
// Store remembers the shapes.
type Store interface {
Get(ctx context.Context, trackID int64) (Record, bool, error)
Save(ctx context.Context, trackID int64, r Record) error
}
// Opener opens the file of a track. streaming.Service is one.
type Opener interface {
Open(ctx context.Context, trackID int64) (*streaming.Stream, error)
}
// Service finds, remembers and gives the shape of tracks.
type Service struct {
store Store
files Opener
flight singleflight.Group
sem chan struct{} // one job at a time: a NAS is not kept busy
// decode is Decode; tests replace it.
decode func(f *os.File, ext string) ([]byte, error)
// wait is how long a request waits for the job before saying "not yet"; timeout is how long a job may take.
wait time.Duration
timeout time.Duration
}
// NewService builds a Service.
func NewService(store Store, files Opener) *Service {
return &Service{store: store, files: files, sem: make(chan struct{}, 1), decode: Decode, wait: 2500 * time.Millisecond, timeout: 3 * time.Minute}
}
func supported(ext string) bool {
switch strings.ToLower(ext) {
case ".mp3", ".flac":
return true
}
return false
}
// Peaks returns the shape of a track: Count levels from 0 to 255. When it is not known yet the work starts in the
// background and the answer is ErrNotReady, for the caller to ask again; ErrUnsupported when the file cannot be
// decoded; streaming's errors when there is no file to play.
func (s *Service) Peaks(ctx context.Context, trackID int64) ([]byte, error) {
st, err := s.files.Open(ctx, trackID)
if err != nil {
return nil, err
}
info, statErr := st.File.Stat()
name, mtime := st.Name, st.ModTime.Unix()
_ = st.Close()
if statErr != nil {
return nil, fmt.Errorf("stat the audio file: %w", statErr)
}
size := info.Size()
ext := filepath.Ext(name)
rec, found, err := s.store.Get(ctx, trackID)
if err != nil {
return nil, fmt.Errorf("read the waveform: %w", err)
}
if found && rec.SizeBytes == size && rec.MTimeUnix == mtime {
if len(rec.Peaks) == 0 {
return nil, ErrUnsupported
}
return rec.Peaks, nil
}
if !supported(ext) {
return nil, ErrUnsupported
}
key := fmt.Sprintf("%d:%d:%d", trackID, size, mtime)
done := s.flight.DoChan(key, func() (any, error) { return s.work(trackID, size, mtime, ext) })
select {
case r := <-done:
if r.Err != nil {
return nil, r.Err
}
return r.Val.([]byte), nil
case <-time.After(s.wait):
return nil, ErrNotReady
case <-ctx.Done():
return nil, ctx.Err()
}
}
// work decodes the file and remembers the result. It runs on its own context: the request that started it may leave.
func (s *Service) work(trackID, size, mtime int64, ext string) ([]byte, error) {
ctx, cancel := context.WithTimeout(context.Background(), s.timeout)
defer cancel()
select {
case s.sem <- struct{}{}:
defer func() { <-s.sem }()
case <-ctx.Done():
return nil, ErrNotReady
}
st, err := s.files.Open(ctx, trackID)
if err != nil {
return nil, err
}
defer st.Close()
peaks, derr := s.decode(st.File, ext)
rec := Record{SizeBytes: size, MTimeUnix: mtime, Peaks: peaks}
if derr != nil {
rec.Peaks = nil // remembered as "cannot be done" for this file
}
if err := s.store.Save(ctx, trackID, rec); err != nil {
return nil, fmt.Errorf("remember the waveform: %w", err)
}
if derr != nil {
return nil, ErrUnsupported
}
return peaks, nil
}
// shape collects the loudest sample of each of Count equal parts of a track.
type shape struct {
total int64 // samples in the track (a sample is one instant, all its channels)
peaks [Count]float64
}
func (s *shape) add(index int64, amplitude float64) {
b := int(index * Count / s.total)
if b >= Count {
b = Count - 1
}
if amplitude > s.peaks[b] {
s.peaks[b] = amplitude
}
}
// levels turns the loudest samples into bytes: the loudest part is 255 whatever the volume of the track, and the rest
// is lifted a little (a square root) so that a quiet passage still shows.
func (s *shape) levels() []byte {
var top float64
for _, v := range s.peaks {
top = math.Max(top, v)
}
out := make([]byte, Count)
if top == 0 {
return out
}
for i, v := range s.peaks {
out[i] = byte(math.Round(255 * math.Sqrt(v/top)))
}
return out
}
// Decode reads an MP3 or FLAC file and returns its shape: Count levels from 0 to 255. ext is the extension of the file.
func Decode(f *os.File, ext string) ([]byte, error) {
switch strings.ToLower(ext) {
case ".mp3":
return decodeMP3(f)
case ".flac":
return decodeFLAC(f)
}
return nil, ErrUnsupported
}
func decodeMP3(f *os.File) ([]byte, error) {
dec, err := mp3.NewDecoder(f)
if err != nil {
return nil, fmt.Errorf("open the mp3: %w", err)
}
// The decoder always gives 16-bit stereo: four bytes for each instant.
total := dec.Length() / 4
if total <= 0 {
return nil, errors.New("the mp3 has no audio")
}
sh := &shape{total: total}
buf := make([]byte, 16<<10)
var index int64
for {
n, err := io.ReadFull(dec, buf)
for i := 0; i+4 <= n; i += 4 {
l := math.Abs(float64(int16(uint16(buf[i]) | uint16(buf[i+1])<<8)))
r := math.Abs(float64(int16(uint16(buf[i+2]) | uint16(buf[i+3])<<8)))
sh.add(index, math.Max(l, r)/32768)
index++
}
if err == io.EOF || err == io.ErrUnexpectedEOF {
break
}
if err != nil {
// A broken tail (a tag after the audio) is not a reason to lose the shape of what was read.
if index >= total*9/10 {
break
}
return nil, fmt.Errorf("decode the mp3: %w", err)
}
}
if index == 0 {
return nil, errors.New("the mp3 gave no audio")
}
return sh.levels(), nil
}
func decodeFLAC(f *os.File) ([]byte, error) {
dec, err := flac.NewDecoder(f)
if err != nil {
return nil, fmt.Errorf("open the flac: %w", err)
}
total := dec.TotalSamples
if total <= 0 {
return nil, errors.New("the flac does not say how long it is")
}
width := dec.BitsPerSample / 8
channels := dec.NChannels
if width < 1 || channels < 1 {
return nil, errors.New("the flac has no samples")
}
scale := float64(int64(1) << (dec.BitsPerSample - 1))
sh := &shape{total: total}
var index int64
for {
frame, err := dec.Next()
if err == io.EOF {
break
}
if err != nil {
if index >= total*9/10 {
break
}
return nil, fmt.Errorf("decode the flac: %w", err)
}
step := width * channels
for i := 0; i+step <= len(frame); i += step {
var loudest float64
for c := 0; c < channels; c++ {
// Little-endian, signed, as many bytes as the bits say.
var v int32
for b := 0; b < width; b++ {
v |= int32(frame[i+c*width+b]) << (8 * b)
}
if shift := 32 - 8*width; shift > 0 {
v = v << shift >> shift
}
loudest = math.Max(loudest, math.Abs(float64(v)))
}
sh.add(index, loudest/scale)
index++
}
}
if index == 0 {
return nil, errors.New("the flac gave no audio")
}
return sh.levels(), nil
}

View file

@ -0,0 +1,293 @@
package waveform
import (
"context"
"errors"
"os"
"path/filepath"
"sync"
"sync/atomic"
"testing"
"time"
"codeberg.org/squidd/sonda/internal/streaming"
)
func mean(p []byte) float64 {
var sum float64
for _, v := range p {
sum += float64(v)
}
return sum / float64(len(p))
}
func TestTheShapeOfARisingToneRisesInMp3AndFlac(t *testing.T) {
for _, name := range []string{"ramp.mp3", "ramp.flac"} {
f, err := os.Open(filepath.Join("testdata", name))
if err != nil {
t.Fatal(err)
}
peaks, err := Decode(f, filepath.Ext(name))
_ = f.Close()
if err != nil {
t.Fatalf("%s: %v", name, err)
}
if len(peaks) != Count {
t.Fatalf("%s: %d levels, want %d", name, len(peaks), Count)
}
third := Count / 3
first, middle, last := mean(peaks[:third]), mean(peaks[third:2*third]), mean(peaks[2*third:])
if !(first < middle && middle < last) {
t.Errorf("%s: the thirds are %.0f, %.0f, %.0f: a tone that rises must make a shape that rises", name, first, middle, last)
}
if peaks[Count-1] < 230 || peaks[0] > 40 {
t.Errorf("%s: starts at %d and ends at %d", name, peaks[0], peaks[Count-1])
}
var top byte
for _, v := range peaks {
top = max(top, v)
}
if top != 255 {
t.Errorf("%s: the loudest level is %d, want 255: a quiet track still fills the bar", name, top)
}
}
}
func TestASilentTrackIsFlatAndNothingDividesByZero(t *testing.T) {
f, err := os.Open(filepath.Join("testdata", "silence.flac"))
if err != nil {
t.Fatal(err)
}
defer f.Close()
peaks, err := Decode(f, ".flac")
if err != nil || len(peaks) != Count {
t.Fatalf("Decode = %d levels, %v", len(peaks), err)
}
for i, v := range peaks {
if v != 0 {
t.Fatalf("level %d is %d in a silent track", i, v)
}
}
}
func TestWhatCannotBeDecodedIsAnErrorAndNotAPanic(t *testing.T) {
dir := t.TempDir()
junk := filepath.Join(dir, "junk")
if err := os.WriteFile(junk, []byte("this is not audio at all, not even a little bit"), 0o644); err != nil {
t.Fatal(err)
}
for _, ext := range []string{".mp3", ".flac"} {
f, _ := os.Open(junk)
if _, err := Decode(f, ext); err == nil {
t.Errorf("%s: no error for text", ext)
}
_ = f.Close()
}
f, _ := os.Open(junk)
defer f.Close()
if _, err := Decode(f, ".ogg"); !errors.Is(err, ErrUnsupported) {
t.Errorf("an ogg file: %v, want ErrUnsupported", err)
}
}
// memStore keeps the shapes in memory.
type memStore struct {
mu sync.Mutex
recs map[int64]Record
}
func (m *memStore) Get(_ context.Context, id int64) (Record, bool, error) {
m.mu.Lock()
defer m.mu.Unlock()
r, ok := m.recs[id]
return r, ok, nil
}
func (m *memStore) Save(_ context.Context, id int64, r Record) error {
m.mu.Lock()
defer m.mu.Unlock()
if m.recs == nil {
m.recs = map[int64]Record{}
}
m.recs[id] = r
return nil
}
// files serves real files of testdata under track ids, and says what the last open found.
type files struct {
byID map[int64]string
as map[int64]string // the name a track reports, when it is not the name of its file
modtime time.Time
}
func (f *files) Open(_ context.Context, id int64) (*streaming.Stream, error) {
name, ok := f.byID[id]
if !ok {
return nil, streaming.ErrNotFound
}
file, err := os.Open(filepath.Join("testdata", name))
if err != nil {
return nil, err
}
if reported, ok := f.as[id]; ok {
name = reported
}
return &streaming.Stream{File: file, Name: name, ModTime: f.modtime}, nil
}
func newService(t *testing.T) (*Service, *memStore, *files, *atomic.Int32) {
t.Helper()
st := &memStore{}
fs := &files{byID: map[int64]string{1: "ramp.mp3", 2: "ramp.flac", 3: "silence.flac"}, modtime: time.Unix(1_700_000_000, 0)}
s := NewService(st, fs)
var calls atomic.Int32
real := s.decode
s.decode = func(f *os.File, ext string) ([]byte, error) {
calls.Add(1)
return real(f, ext)
}
return s, st, fs, &calls
}
func TestTheShapeIsWorkedOutOnceAndRememberedForTheFile(t *testing.T) {
ctx := context.Background()
s, st, fs, calls := newService(t)
peaks, err := s.Peaks(ctx, 1)
if err != nil || len(peaks) != Count {
t.Fatalf("Peaks = %d levels, %v", len(peaks), err)
}
again, err := s.Peaks(ctx, 1)
if err != nil || string(again) != string(peaks) || calls.Load() != 1 {
t.Errorf("second ask: %v, decoded %d times, want once", err, calls.Load())
}
if rec := st.recs[1]; rec.SizeBytes == 0 || rec.MTimeUnix != 1_700_000_000 || len(rec.Peaks) != Count {
t.Errorf("record = %+v", rec)
}
// The file changes: its shape is worked out again.
fs.modtime = fs.modtime.Add(time.Hour)
if _, err := s.Peaks(ctx, 1); err != nil || calls.Load() != 2 {
t.Errorf("after the file changed: %v, decoded %d times, want 2", err, calls.Load())
}
// Another track is another job.
if _, err := s.Peaks(ctx, 2); err != nil || calls.Load() != 3 {
t.Errorf("another track: %v, decoded %d times", err, calls.Load())
}
}
func TestATrackThatIsNotThereOrCannotBeReadIsSaidOnceAndNotTriedAgain(t *testing.T) {
ctx := context.Background()
s, _, fs, calls := newService(t)
if _, err := s.Peaks(ctx, 99); !errors.Is(err, streaming.ErrNotFound) {
t.Errorf("a track that is not there: %v", err)
}
fs.byID[4], fs.as = "ramp.mp3", map[int64]string{4: "song.ogg"}
if _, err := s.Peaks(ctx, 4); !errors.Is(err, ErrUnsupported) {
t.Errorf("a format that is not read: %v, want ErrUnsupported", err)
}
if calls.Load() != 0 {
t.Errorf("decoded %d times a format that has no decoder", calls.Load())
}
// A file that is broken: the failure is kept for that file, so it is not decoded at every request.
dir := t.TempDir()
if err := os.WriteFile(filepath.Join(dir, "broken.mp3"), []byte("not an mp3"), 0o644); err != nil {
t.Fatal(err)
}
broken := &brokenFiles{path: filepath.Join(dir, "broken.mp3"), modtime: fs.modtime}
s2 := NewService(&memStore{}, broken)
var n atomic.Int32
real := s2.decode
s2.decode = func(f *os.File, ext string) ([]byte, error) { n.Add(1); return real(f, ext) }
for i := 0; i < 3; i++ {
if _, err := s2.Peaks(ctx, 1); !errors.Is(err, ErrUnsupported) {
t.Fatalf("ask %d: %v, want ErrUnsupported", i, err)
}
}
if n.Load() != 1 {
t.Errorf("a broken file was decoded %d times, want once", n.Load())
}
}
type brokenFiles struct {
path string
modtime time.Time
}
func (b *brokenFiles) Open(context.Context, int64) (*streaming.Stream, error) {
f, err := os.Open(b.path)
if err != nil {
return nil, err
}
return &streaming.Stream{File: f, Name: filepath.Base(b.path), ModTime: b.modtime}, nil
}
func TestWhileTheShapeIsBeingWorkedOutTheAnswerIsNotReadyAndTheWorkGoesOn(t *testing.T) {
ctx := context.Background()
s, _, _, _ := newService(t)
s.wait = 30 * time.Millisecond
release := make(chan struct{})
real := s.decode
s.decode = func(f *os.File, ext string) ([]byte, error) {
<-release
return real(f, ext)
}
if _, err := s.Peaks(ctx, 1); !errors.Is(err, ErrNotReady) {
t.Fatalf("while it works: %v, want ErrNotReady", err)
}
close(release)
deadline := time.Now().Add(3 * time.Second)
for {
peaks, err := s.Peaks(ctx, 1)
if err == nil {
if len(peaks) != Count {
t.Fatalf("%d levels", len(peaks))
}
return
}
if !errors.Is(err, ErrNotReady) || time.Now().After(deadline) {
t.Fatalf("it never came: %v", err)
}
time.Sleep(10 * time.Millisecond)
}
}
func TestManyAsksForOneTrackAreOneJobAndTracksAreWorkedOutOneAtATime(t *testing.T) {
ctx := context.Background()
s, _, _, calls := newService(t)
var running, most atomic.Int32
real := s.decode
s.decode = func(f *os.File, ext string) ([]byte, error) {
now := running.Add(1)
for {
m := most.Load()
if now <= m || most.CompareAndSwap(m, now) {
break
}
}
time.Sleep(60 * time.Millisecond)
defer running.Add(-1)
return real(f, ext)
}
s.wait = 5 * time.Second
var wg sync.WaitGroup
for _, id := range []int64{1, 1, 1, 2, 3} {
wg.Add(1)
go func() {
defer wg.Done()
if _, err := s.Peaks(ctx, id); err != nil {
t.Errorf("track %d: %v", id, err)
}
}()
}
wg.Wait()
if calls.Load() != 3 {
t.Errorf("decoded %d times for 3 tracks asked 5 times", calls.Load())
}
if most.Load() != 1 {
t.Errorf("%d tracks were decoded at the same time, want 1", most.Load())
}
}