sonda/internal/library/types.go
tgiachi 1857bb9c53 feat(discovery): remove provider data, genres from my files, full rescans
- feat: DELETE /api/v1/providers/{name}/data (admin) removes everything a
  provider gave: its lists of similar artists, its tags and the records of
  when it was asked, then the artists that only that data named and that
  nobody has files for. Last.fm's terms ask for this when an agreement ends.
  The user's own artists, music, listens and settings stay, the provider is not
  switched off, and a second call removes nothing
- feat: a discovered artist that no list names any more is removed when the
  list that named it is replaced, together with its tags, so they do not pile
  up. Real artists, and any artist that another list still names, are kept
- feat: the scan reads the GENRE tag of each file, offline (several genres
  separated by ";", lower case, at most five per file), and
  GET /artists/{id}/tags gets a third entry, files: the genres of the artist's
  own playable tracks, each weighted by how many tracks have it. It asks nobody
  and is always there
- feat: POST /library/scan and POST /libraries/{id}/scan take full=true to read
  every file again, not only the new or changed ones, so MusicBrainz ids and
  genres reach music that was indexed before. Files keep their identity, so
  listening history is kept. Anything but true or false is a 400
- test: the plan of a full scan, the scanner and the manager; the purge on both
  databases, checked by removing the rule that spares real artists; the
  cleanup of replaced lists; genres per file and per artist
- docs: README, OpenAPI and the todo list updated
2026-11-11 17:27:29 +01:00

146 lines
4.2 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
TrackNo int
DiscNo int
}
// 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
}