types

Documentation

Index

• func GenerateSongID(filePath string, startPos time.Duration) string
• func ResolveFilePath(musicRoot, relPath string) string
• func ToRelativePath(musicRoot, absPath string) string
• type Attrs
• type BookPosition
• type DocType
• type FileFormatType
• type FrameFormat
  • func (f FrameFormat) BytesPerSample() int
  • func (f FrameFormat) FrameSize() int
  • func (f FrameFormat) String() string
• type MusicDbDriverType
• type PlaybackMonitor
• type PlaybackStatus
• type PlaylistCollection
• type PlaylistItem
• type ReplayGainValues
• type SampleFormat
  • func SampleFormatFromBitsPerSample(bps int) SampleFormat
  • func (f SampleFormat) BytesPerSample() int
• type SongDocument
  • func (sd SongDocument) FolderPath() string
• type SongInfo
  • func (s *SongInfo) EnsureTitle()
  • func (s *SongInfo) NormalizeMetadata()
  • func (s *SongInfo) String() string

Functions

func GenerateSongID

func GenerateSongID(filePath string, startPos time.Duration) string

GenerateSongID produces a stable, deterministic ID for a song based on its file path and start position. The ID is a base36 string from FNV-64a hash. StartPos distinguishes CUE tracks that share the same audio file.

func ResolveFilePath

func ResolveFilePath(musicRoot, relPath string) string

ResolveFilePath returns the absolute path for a file. If relPath is already absolute (legacy data), it is returned as-is.

func ToRelativePath

func ToRelativePath(musicRoot, absPath string) string

ToRelativePath strips musicRoot prefix from an absolute path. Returns absPath as-is if it is not under musicRoot or is already relative.

Types

type Attrs

type Attrs map[string]string

Attrs is a generic string key-value map used for status reporting.

type BookPosition

type BookPosition struct {
	Book                string `json:"book"`
	ChapterID           int    `json:"chapterId"`
	ElapsedNs           int64  `json:"elapsed"`
	UpdatedAt           int64  `json:"updatedAt"`
	Completed           bool   `json:"completed"`
	CompletedChapters   []int  `json:"completedChapters,omitempty"`
	UncompletedChapters []int  `json:"uncompletedChapters,omitempty"`
}

BookPosition stores the last known playback position for an audiobook/playlist.

type DocType

type DocType string

DocType classifies entries in the music document tree.

const (
	DocTypeSong       DocType = "song"
	DocTypeFolder     DocType = "folder"
	DocTypeCuesheet   DocType = "cuesheet"
	DocTypeMusicRoot  DocType = "musicroot"
	DocTypeMusicStore DocType = "musicstore"
)

type FileFormatType

type FileFormatType string

FileFormatType identifies an audio file format by extension.

const (
	FileFormatMP3  FileFormatType = ".mp3"
	FileFormatFLAC FileFormatType = ".flac"
	FileFormatOGG  FileFormatType = ".ogg"
	FileFormatWAV  FileFormatType = ".wav"
	FileFormatCUE  FileFormatType = ".cue"
)

type FrameFormat

type FrameFormat struct {
	SampleRate    int
	Channels      int
	BitsPerSample int // 8, 16, 24, 32
}

FrameFormat describes the PCM audio sample format.

This is the canonical definition, shared across all learnAudio projects. Previously duplicated in sonet (3 versions), musiclab, and musictools.

func (FrameFormat) BytesPerSample

func (f FrameFormat) BytesPerSample() int

BytesPerSample returns the number of bytes per single-channel sample.

func (FrameFormat) FrameSize

func (f FrameFormat) FrameSize() int

FrameSize returns the number of bytes per complete frame (all channels, one sample period).

func (FrameFormat) String

func (f FrameFormat) String() string

type MusicDbDriverType

type MusicDbDriverType string

MusicDbDriverType identifies a database backend.

const (
	MusicDbMongo  MusicDbDriverType = "mongodb"
	MusicDbJson   MusicDbDriverType = "jsondb"
	MusicDbDuckDB MusicDbDriverType = "duckdb"
)

type PlaybackMonitor

type PlaybackMonitor interface {
	GetPlaybackStatus() PlaybackStatus
}

PlaybackMonitor is implemented by types that can report playback status.

type PlaybackStatus

type PlaybackStatus struct {
	FileName        string
	SampleRate      int
	Channels        int
	BitsPerSample   int
	FramesPerBuffer int
	PlayedSamples   uint64
	BufferedSamples uint64
	ElapsedTime     time.Duration
}

PlaybackStatus holds playback information for audio players.

type PlaylistCollection

type PlaylistCollection map[string][]PlaylistItem

PlaylistCollection maps playlist names to their items.

type PlaylistItem

type PlaylistItem struct {
	PlaylistID int
	SongInfo
}

PlaylistItem is a song with its position in a playlist.

type ReplayGainValues

type ReplayGainValues struct {
	TrackGain float64 `json:"trackGain,omitempty"`
	TrackPeak float64 `json:"trackPeak,omitempty"`
	AlbumGain float64 `json:"albumGain,omitempty"`
	AlbumPeak float64 `json:"albumPeak,omitempty"`
}

ReplayGainValues holds gain/peak data from a single source.

type SampleFormat

type SampleFormat int

SampleFormat describes the PCM sample encoding as an enum. Useful when the exact encoding matters (e.g., float vs int).

const (
	SampleFmtInt8 SampleFormat = iota + 1
	SampleFmtInt16
	SampleFmtInt24
	SampleFmtInt32
	SampleFmtFloat32
)

func SampleFormatFromBitsPerSample

func SampleFormatFromBitsPerSample(bps int) SampleFormat

SampleFormatFromBitsPerSample converts a bits-per-sample value to SampleFormat. Defaults to SampleFmtInt16 for unrecognized values.

func (SampleFormat) BytesPerSample

func (f SampleFormat) BytesPerSample() int

BytesPerSample returns the byte width for this sample format.

type SongDocument

type SongDocument struct {
	Type       DocType
	Song       *SongInfo `json:"Song,omitempty" bson:"Song,omitempty" structs:"Song,omitempty"`
	FolderName string    `db:"FolderName" json:"FolderName,omitempty" bson:"FolderName,omitempty" structs:"FolderName,omitempty"`
	Ancestors  []string  `db:"Ancestors" json:"Ancestors,omitempty" bson:"Ancestors,omitempty" structs:"Ancestors,omitempty"`
}

SongDocument represents a node in the music library tree.

func (SongDocument) FolderPath

func (sd SongDocument) FolderPath() string

FolderPath returns the full path for this document by joining ancestors and folder name.

type SongInfo

type SongInfo struct {
	Title      string
	Artist     string
	Album      string
	Genre      string
	Duration   time.Duration
	StartPos   time.Duration
	Format     FrameFormat
	FileFormat FileFormatType
	// FilePath is the path to the audio file, relative to the music root directory.
	// May be absolute for legacy compatibility (use ResolveFilePath to get absolute path).
	FilePath string `json:"FilePath,omitempty" bson:"FilePath,omitempty" structs:"FilePath,omitempty"`
	ID       string `json:"ID,omitempty" bson:"ID,omitempty" structs:"ID,omitempty"`

	// ReplayGain metadata — two independent sources, both can coexist.
	// nil pointer = no data from that source.
	RGEmbedded *ReplayGainValues `json:"rgEmbedded,omitempty" bson:"rgEmbedded,omitempty"`
	RGComputed *ReplayGainValues `json:"rgComputed,omitempty" bson:"rgComputed,omitempty"`
}

SongInfo holds metadata for a single audio track.

func (*SongInfo) EnsureTitle

func (s *SongInfo) EnsureTitle()

EnsureTitle sets the title to the filename if it is empty.

func (*SongInfo) NormalizeMetadata

func (s *SongInfo) NormalizeMetadata()

NormalizeMetadata fills empty metadata fields from the file path:

• Title: filename
• Album: parent directory name
• Artist: grandparent directory name

func (*SongInfo) String

func (s *SongInfo) String() string