sonda/internal/waveform/waveform.go
tgiachi bfa3e6e458 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.
2026-11-13 17:35:00 +01:00

292 lines
8.1 KiB
Go

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