sonda/internal/library/types.go
tgiachi a92326c1b4 feat(player): play every song at a similar volume with ReplayGain
I want songs from different albums to play at about the same loudness without touching the volume.

- The scan reads REPLAYGAIN_TRACK_GAIN, REPLAYGAIN_ALBUM_GAIN and the two peaks from each file, offline, and keeps them on the file (migration 0029, SQLite and PostgreSQL). A tag that makes no sense (not a number, more than 60 dB) is left out. Files indexed before have none until a full rescan.
- A track in the API carries them as replay_gain (null when its first playable file says nothing).
- The web player levels each song with them: the sound passes through a gain node, so a quiet song can be raised too, but never so much that its peak would clip (and never more than 12 dB when there is no peak). Without Web Audio the element is turned down instead.
- A new Playback section in Settings chooses song by song (default), album by album or off; the choice stays on the device.
- README: the ReplayGain entry, and the old line that said the year was not in the index is removed.
- English and Italian.
2026-11-14 16:02:23 +01:00

163 lines
5 KiB
Go

// Package library scans the music directories and indexes audio files.
//
// The scanner only reads: it never writes, renames or deletes music files.
package library
import (
"context"
"errors"
"time"
)
// ErrUnreadable means a file could not be parsed as audio.
var ErrUnreadable = errors.New("unreadable audio file")
// Tags are the descriptive tags of a track. Fields the file lacks are empty.
//
// The MusicBrainz ids are what the file itself says, read offline. ArtistMBIDs is
// either empty or has one id per entry of Artists, in the same order: ids that
// cannot be paired with their artists with certainty are not kept.
//
// Genres are the genre tags of the file, lower case, without repeats and at most
// MaxGenresPerTrack: a file tagged with twenty genres is not telling anything.
type Tags struct {
Genres []string
Title string
Album string
AlbumArtist string
Artists []string
ArtistMBIDs []string
AlbumArtistMBID string
AlbumMBID string // the MusicBrainz release group id of the album, when the file has exactly one
TrackNo int
DiscNo int
Year int // the year the song came out (the original date first), 0 when the file has none or it is not a year
ReplayGain ReplayGain
}
// ReplayGain is what the file says about its own loudness, read offline from its ReplayGain tags. A field the file
// lacks (or writes in a way that makes no sense) is nil. Gains are in decibels (what to add to play the song at the
// reference loudness); peaks are linear, 1 being the loudest a sample can be.
type ReplayGain struct {
TrackGain, AlbumGain *float64
TrackPeak, AlbumPeak *float64
}
// MinYear and MaxYear bound what is taken for the year of a song.
const (
MinYear = 1000
MaxYear = 2999
)
// MaxGenresPerTrack bounds the genres kept for one file.
const MaxGenresPerTrack = 5
// Properties are the technical properties of an audio file.
type Properties struct {
Format string // "mp3", "flac", ...
DurationMs int64
SampleRate int
BitRate int // kbit/s
}
// Metadata is everything read from one audio file.
type Metadata struct {
Tags
Properties
}
// TagReader reads metadata from a file on disk. It must be safe for
// concurrent use and return ErrUnreadable for files that are not valid audio.
type TagReader interface {
Read(path string) (Metadata, error)
}
// FileInfo identifies a file inside a library root.
type FileInfo struct {
RelPath string // slash-separated, relative to the root
Size int64
MTimeUnix int64
}
// ExistingFile is a file already indexed in the database.
type ExistingFile struct {
ID int64
FileInfo
Missing bool // last scan did not find it
}
// ParsedFile is a file together with its metadata, ready to be stored.
type ParsedFile struct {
FileInfo
Metadata
}
// Store is what the scanner needs from persistence. All writes come from a
// single goroutine, so implementations need no extra locking for the scanner.
type Store interface {
ExistingFiles(ctx context.Context, libraryID int64) ([]ExistingFile, error)
// SaveFile creates the file (existingID == 0) or updates it, together with
// its track, album and artists. It reports whether a new file was created.
SaveFile(ctx context.Context, libraryID int64, f ParsedFile, existingID int64) (added bool, err error)
// RenameFile points an indexed file at a new relative path and clears its missing flag.
RenameFile(ctx context.Context, id int64, newRelPath string) error
// MarkMissing flags files that were not found. Rows are never deleted.
MarkMissing(ctx context.Context, ids []int64, at time.Time) error
// Restore clears the missing flag of files that reappeared.
Restore(ctx context.Context, ids []int64) error
}
// EventType names a scan progress event.
type EventType string
// Scan progress events.
const (
ScanStarted EventType = "scan_started"
FileScanned EventType = "file_scanned"
FileFailed EventType = "file_failed"
ScanFinished EventType = "scan_finished"
)
// Event is one progress notification. Done and Total count files being
// parsed in the current library.
type Event struct {
Type EventType
Time time.Time
LibraryID int64
Library string // library name
RelPath string
Error string
Done int
Total int
Summary *Summary // only on ScanFinished
}
// Summary counts what a scan did.
type Summary struct {
Libraries int
Found int // audio files seen on disk
Added int
Updated int
Unchanged int
Renamed int
Restored int
Missing int // newly marked missing
Failed int
Skipped int // symlinks and special files
// Unsupported counts audio files in formats Sonda cannot read yet (m4a, ogg,
// wav, ...), so they are not left out without a trace.
Unsupported int
}
func (s *Summary) add(o Summary) {
s.Found += o.Found
s.Added += o.Added
s.Updated += o.Updated
s.Unchanged += o.Unchanged
s.Renamed += o.Renamed
s.Restored += o.Restored
s.Missing += o.Missing
s.Failed += o.Failed
s.Skipped += o.Skipped
s.Unsupported += o.Unsupported
}