sonda/internal/library/types.go
tgiachi 6d004c4225 feat(library): count unsupported audio formats and skip NAS system folders
- feat: the scan summary has an unsupported counter for audio files in formats
  Sonda cannot read yet (m4a, ogg, opus, wav, wma, ...); they are counted and
  never opened, instead of disappearing without a trace. Video containers such
  as .mpg are not counted
- feat: folders named .@__thumb, @Recycle, #recycle, @eaDir, $RECYCLE.BIN and
  System Volume Information are skipped, matched by exact name ignoring case,
  so a NAS recycle bin does not end up in the library; a library whose own
  folder carries one of these names is still scanned, and files indexed before
  from such a folder are flagged missing like any vanished file
- docs: the README lists the new counter and the skipped folders
- test: system folders at any depth, near-miss names, a library inside a
  system-named folder, entries flagged missing, unsupported counting

Closes #14
2026-11-11 14:25:33 +01:00

133 lines
3.6 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.
type Tags struct {
Title string
Album string
AlbumArtist string
Artists []string
TrackNo int
DiscNo int
}
// 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
}