// 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" "git.kmalloc.org/squid/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 }