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