types

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 13, 2025 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package types provides core data structures for audio file metadata.

This package defines the File, Tags, AudioInfo, Chapter, and Artwork types that represent parsed audio file information across all supported formats.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Artwork 

type Artwork struct {
	MIMEType    string
	Description string
	Data        []byte
	Type        ArtworkType
	Width       int
	Height      int
}

Artwork represents embedded artwork (cover art, images).

Artwork can include album covers, artist photos, and other images embedded in audio files. Multiple artworks per file are supported.

func (Artwork) String 

func (a Artwork) String() string

String returns a human-readable representation of the artwork. Example output: "Front cover (1200x1200 JPEG, 245KB)".

type ArtworkType 

type ArtworkType int

ArtworkType categorizes the purpose/content of artwork.

Types are based on ID3v2 APIC frame picture types and FLAC picture types. See: https://id3.org/id3v2.4.0-frames (APIC frame) 

const (
	// ArtworkOther represents other/unspecified artwork.
	ArtworkOther ArtworkType = iota // Other
	// ArtworkIcon represents a file icon (32x32 PNG).
	ArtworkIcon // File icon (32x32 PNG)
	// ArtworkOtherIcon represents another file icon.
	ArtworkOtherIcon // Other file icon
	// ArtworkFrontCover represents front cover artwork.
	ArtworkFrontCover // Front cover
	// ArtworkBackCover represents back cover artwork.
	ArtworkBackCover // Back cover
	// ArtworkLeaflet represents leaflet page artwork.
	ArtworkLeaflet // Leaflet page
	// ArtworkMedia represents media artwork (CD/vinyl label).
	ArtworkMedia // Media (CD/vinyl label)
	// ArtworkLeadArtist represents lead artist/performer/soloist artwork.
	ArtworkLeadArtist // Lead artist/performer/soloist
	// ArtworkArtist represents artist/performer artwork.
	ArtworkArtist // Artist/performer
	// ArtworkConductor represents conductor artwork.
	ArtworkConductor // Conductor
	// ArtworkBand represents band/orchestra artwork.
	ArtworkBand // Band/orchestra
	// ArtworkComposer represents composer artwork.
	ArtworkComposer // Composer
	// ArtworkLyricist represents lyricist/text writer artwork.
	ArtworkLyricist // Lyricist/text writer
	// ArtworkRecordingLocation represents recording location artwork.
	ArtworkRecordingLocation // Recording location
	// ArtworkDuringRecording represents during recording artwork.
	ArtworkDuringRecording // During recording
	// ArtworkDuringPerformance represents during performance artwork.
	ArtworkDuringPerformance // During performance
	// ArtworkVideoCapture represents movie/video screen capture artwork.
	ArtworkVideoCapture // Movie/video screen capture
	// ArtworkBrightFish represents a bright colored fish artwork.
	ArtworkBrightFish // A bright colored fish
	// ArtworkIllustration represents illustration artwork.
	ArtworkIllustration // Illustration
	// ArtworkBandLogotype represents band/artist logotype artwork.
	ArtworkBandLogotype // Band/artist logotype
	// ArtworkPublisherLogotype represents publisher/studio logotype artwork.
	ArtworkPublisherLogotype // Publisher/studio logotype
)

func (ArtworkType) String 

func (i ArtworkType) String() string

type AudioInfo 

type AudioInfo struct {
	ReplayGain       *ReplayGainInfo
	Codec            string
	CodecDescription string
	CodecProfile     string
	Container        string
	Duration         time.Duration
	SampleRate       int
	BitDepth         int
	Channels         int
	Bitrate          int
	Lossless         bool
	VBR              bool
}

AudioInfo represents technical audio properties.

AudioInfo provides format-agnostic access to audio technical metadata such as duration, sample rate, bit depth, and codec information.

func (AudioInfo) ApplyReplayGain 

func (a AudioInfo) ApplyReplayGain(amplitude float64, mode string) float64

ApplyReplayGain applies ReplayGain adjustment to an amplitude.

Returns the adjusted amplitude. If ReplayGain is not available, returns the original amplitude.

mode should be "track" or "album".

Example: 

adjusted := audio.ApplyReplayGain(0.8, "track")

func (AudioInfo) FullCodecName 

func (a AudioInfo) FullCodecName() string

FullCodecName returns the full codec name with profile.

func (AudioInfo) IsHighRes 

func (a AudioInfo) IsHighRes() bool

IsHighRes returns true if the audio is high-resolution.

High-resolution is defined as:

  • Sample rate > 48kHz, OR
  • Bit depth > 16

Example: 

if file.Audio.IsHighRes() {
	fmt.Println("High-resolution audio")
}

func (AudioInfo) IsModernAudiobookCodec 

func (a AudioInfo) IsModernAudiobookCodec() bool

IsModernAudiobookCodec returns true for modern audiobook codecs.

func (AudioInfo) ShortCodecName 

func (a AudioInfo) ShortCodecName() string

ShortCodecName returns a short, human-readable codec name.

func (AudioInfo) String 

func (a AudioInfo) String() string

String returns a human-readable representation of the audio info. Example output: "FLAC 44.1kHz 16-bit stereo".

type Chapter 

type Chapter struct {
	Title     string        `json:"title"`
	Index     int           `json:"index"`
	StartTime time.Duration `json:"start_time"`
	EndTime   time.Duration `json:"end_time"`
}

Chapter represents a chapter marker in an audio file.

Chapters are supported in:

  • M4B/M4A files (QuickTime chapter tracks, Nero CHPL format)
  • MP3 files (ID3v2 CHAP frames)
  • FLAC files (CUESHEET metadata block)
  • Ogg Vorbis/Opus files (CHAPTER Vorbis comments)

Access chapters via file.Chapters: 

file, _ := audiometa.Open("audiobook.mp3")
for _, chapter := range file.Chapters {
    fmt.Printf("[%d] %s: %s - %s\n",
        chapter.Index,
        chapter.Title,
        chapter.StartTime,
        chapter.EndTime)
}

type CorruptedFileError 

type CorruptedFileError struct {
	Path   string
	Reason string
	Offset int64
}

CorruptedFileError is returned when file structure is invalid.

func (*CorruptedFileError) Error 

func (e *CorruptedFileError) Error() string

type File 

type File struct {
	Reader_  io.ReaderAt         //nolint:revive // Underscore indicates internal/unexported semantics
	Parser_  interface{}         //nolint:revive // Underscore indicates internal/unexported semantics
	RawTags_ map[string][]RawTag //nolint:revive // Underscore indicates internal/unexported semantics
	Path     string
	Chapters []Chapter
	Warnings []Warning
	Artwork_ []Artwork //nolint:revive // Underscore indicates internal/unexported semantics
	Tags     Tags
	Audio    AudioInfo
	Format   Format
	Size     int64
}

File represents an opened audio file with parsed metadata.

File provides access to format-agnostic metadata (Tags), technical audio properties (AudioInfo), and optional embedded artwork.

File uses lazy loading - opening a file reads only metadata, not audio content or artwork. Call ExtractArtwork() to load images.

Always call Close() when done to release file resources: 

file, err := audiometa.Open("song.flac")
if err != nil {
	return err
}
defer file.Close()

type Format 

type Format int

Format represents the detected audio format 

const (
	// FormatUnknown represents an unknown or unsupported format.
	FormatUnknown Format = iota // Unknown
	// FormatFLAC represents FLAC audio files.
	FormatFLAC // FLAC
	// FormatMP3 represents MP3 audio files.
	FormatMP3 // MP3
	// FormatM4A represents M4A audio files.
	FormatM4A // M4A
	// FormatM4B represents M4B audiobook files.
	FormatM4B // M4B
	// FormatOgg represents Ogg Vorbis audio files.
	FormatOgg // Ogg Vorbis
	// FormatOpus represents Opus audio files.
	FormatOpus // Opus
	// FormatWAV represents WAV audio files.
	FormatWAV // WAV
	// FormatAIFF represents AIFF audio files.
	FormatAIFF // AIFF
)

func DetectFormat 

func DetectFormat(r io.ReaderAt, size int64, path string) (Format, error)

DetectFormat determines the audio file format by examining magic bytes.

Supported formats: FLAC, MP3, M4A, M4B, Ogg Vorbis, Opus, WAV, AIFF

Detection is based on file signatures (magic bytes) at the beginning of the file. Format detection does not validate the entire file structure.

func (Format) Extensions 

func (f Format) Extensions() []string

Extensions returns common file extensions for this format.

func (Format) String 

func (i Format) String() string

type OutOfBoundsError 

type OutOfBoundsError struct {
	Path   string
	What   string
	Offset int64
	Length int
	Size   int64
}

OutOfBoundsError is returned when attempting to read beyond file bounds.

func (*OutOfBoundsError) Error 

func (e *OutOfBoundsError) Error() string

type RawTag 

type RawTag struct {
	Key      string
	Encoding string
	Value    []byte
	Type     RawTagType
}

RawTag represents an unparsed tag value.

RawTag preserves the original binary representation and encoding information for tags that are not mapped to standard Tag fields.

func (RawTag) String 

func (r RawTag) String() string

String returns the raw tag value as a string.

For non-text types, returns a placeholder description.

type RawTagType 

type RawTagType int

RawTagType indicates the semantic type of a raw tag value. 

const (
	// RawTagText represents a text string value.
	RawTagText RawTagType = iota // Text string
	// RawTagBinary represents binary data.
	RawTagBinary // Binary data
	// RawTagImage represents image data.
	RawTagImage // Image data
	// RawTagCounter represents a numeric counter.
	RawTagCounter // Numeric counter
	// RawTagURL represents a URL string.
	RawTagURL // URL string
)

type ReplayGainInfo 

type ReplayGainInfo struct {
	TrackGain float64 // Track gain adjustment in dB (can be negative)
	TrackPeak float64 // Track peak amplitude (0.0 to 1.0+)
	AlbumGain float64 // Album gain adjustment in dB (can be negative)
	AlbumPeak float64 // Album peak amplitude (0.0 to 1.0+)
}

ReplayGainInfo represents loudness normalization data.

ReplayGain provides information for normalizing playback volume across tracks and albums. See https://wiki.hydrogenaud.io/index.php?title=ReplayGain

type Tags 

type Tags struct {
	MusicBrainzAlbumID  string
	Narrator            string
	AlbumArtist         string
	Artist              string
	Copyright           string
	Label               string
	CatalogNumber       string
	Barcode             string
	Date                string
	OriginalDate        string
	ISRC                string
	MusicBrainzArtistID string
	Title               string
	Subtitle            string // Book/album subtitle (TIT3 in ID3v2)
	MusicBrainzTrackID  string
	Album               string
	Comment             string
	Description         string // Longer description text (separate from comment)
	Series              string
	Grouping            string // Content grouping (©grp in M4A, TIT1 in ID3v2) - often contains series info
	Publisher           string
	Lyrics              string
	SeriesPart          string
	ISBN                string
	ASIN                string
	Language            string // Language code or name (e.g., "en", "English")
	Performers          []string
	Composers           []string
	Genres              []string
	Artists             []string
	DiscTotal           int
	DiscNumber          int
	TrackTotal          int
	TrackNumber         int
	Year                int
	// contains filtered or unexported fields
}

Tags represents format-agnostic audio metadata.

Tags provides a unified view of metadata across different formats. Format-specific tags are mapped to standard fields where possible.

For access to unmapped or custom tags, use the All() iterator or Get() method to retrieve raw tag values by key.

func (*Tags) All 

func (t *Tags) All() iter.Seq2[string, []string]

All returns an iterator over all raw tags.

This uses Go 1.23+ iterator pattern for zero-allocation iteration. The iterator yields key-value pairs where values are string slices (as tags can have multiple values).

Example: 

for key, values := range file.Tags.All() {
	fmt.Printf("%s: %v\n", key, values)
}

The returned iterator is read-only. Do not modify the returned slices.

func (*Tags) Clone 

func (t *Tags) Clone() *Tags

Clone creates a deep copy of the Tags.

Example: 

backup := originalTags.Clone()

func (*Tags) Equal 

func (t *Tags) Equal(other *Tags) bool

Equal checks if two Tags are equal.

Compares all standard fields and raw tags for equality.

Example: 

if !tags1.Equal(tags2) {
	fmt.Println("Tags differ")
}

func (*Tags) Filter 

func (t *Tags) Filter(predicate func(string) bool) iter.Seq2[string, []string]

Filter returns an iterator over tags matching a predicate.

Example: 

// Find all MusicBrainz tags
for key, values := range file.Tags.Filter(func(k string) bool {
	return strings.HasPrefix(k, "MUSICBRAINZ")
}) {
	fmt.Printf("%s: %v\n", key, values)
}

func (*Tags) Get 

func (t *Tags) Get(key string) []string

Get retrieves all values for a tag key.

Tag keys are format-specific (e.g., "TITLE", "TIT2", "©nam"). Returns an empty slice if the key doesn't exist.

For standard fields, prefer accessing struct fields directly (Title, Artist, etc.) as they provide format-agnostic access.

Example: 

// Get custom tag
vendors := file.Tags.Get("VENDOR")
if len(vendors) > 0 {
	fmt.Println("Encoder:", vendors[0])
}

func (*Tags) GetBest 

func (t *Tags) GetBest(candidates ...string) string

GetBest tries multiple tag keys and returns the first non-empty value.

This is useful for handling format differences where the same metadata might be stored under different tag keys: 

// Try various artist tag formats
artist := tags.GetBest("ARTIST", "artist", "©ART", "TPE1")

Returns empty string if none of the candidates have values.

func (*Tags) GetFirst 

func (t *Tags) GetFirst(key string) string

GetFirst retrieves the first value for a tag key.

Returns empty string if the key doesn't exist or has no values.

Useful when you know a tag has a single value: 

encoder := file.Tags.GetFirst("ENCODER")

func (*Tags) Merge 

func (t *Tags) Merge(other *Tags)

Merge merges tags from another Tags object.

For standard fields, non-empty values in other override empty values in t. For raw tags, all tags from other are copied to t.

Example: 

// Apply fallback tags
fileTags.Merge(defaultTags)

func (*Tags) Set 

func (t *Tags) Set(key string, values ...string)

Set sets a tag value (for future write support).

If values is empty, the tag is removed. Multiple values can be provided for multi-value tags.

Note: This only modifies the in-memory representation. Write support is planned for a future release.

Example: 

tags.Set("COMMENT", "Remastered")
tags.Set("GENRE", "Rock", "Alternative") // Multi-value

type UnsupportedFormatError 

type UnsupportedFormatError struct {
	Path   string
	Reason string
}

UnsupportedFormatError is returned when the file format is not M4B/M4A.

func (*UnsupportedFormatError) Error 

func (e *UnsupportedFormatError) Error() string

type Warning 

type Warning struct {
	// Stage where the warning occurred
	Stage string // "metadata", "technical", "chapters", "artwork"

	// Warning message
	Message string

	// File offset where the issue occurred (0 if not applicable)
	Offset int64
}

Warning represents a non-fatal issue encountered during parsing.

Warnings indicate problems that don't prevent metadata extraction but may indicate corrupted or unusual data. Examples include:

  • Missing optional fields
  • Invalid encoding in a tag
  • Corrupted artwork
  • Unknown tag keys

Warnings are collected in File.Warnings during parsing.

func (Warning) String 

func (w Warning) String() string

String returns a human-readable warning message.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.