tag

package module
v0.0.0-...-142ccac Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2024 License: BSD-2-Clause Imports: 13 Imported by: 0

README

MP3/MP4/OGG/FLAC metadata parsing library

GoDoc

This package provides MP3 (ID3v1,2.{2,3,4}) and MP4 (ACC, M4A, ALAC), OGG and FLAC metadata detection, parsing and artwork extraction.

Detect and parse tag metadata from an io.ReadSeeker (i.e. an *os.File):

m, err := tag.ReadFrom(f)
if err != nil {
	log.Fatal(err)
}
log.Print(m.Format()) // The detected format.
log.Print(m.Title())  // The title of the track (see Metadata interface for more details).

Parsed metadata is exported via a single interface (giving a consistent API for all supported metadata formats).

// Metadata is an interface which is used to describe metadata retrieved by this package.
type Metadata interface {
	Format() Format
	FileType() FileType

	Title() string
	Album() string
	Artist() string
	AlbumArtist() string
	Composer() string
	Genre() string
	Year() int

	Track() (int, int) // Number, Total
	Disc() (int, int) // Number, Total

	Picture() *Picture // Artwork
	Lyrics() string
	Comment() string

	Raw() map[string]interface{} // NB: raw tag names are not consistent across formats.
}

Audio Data Checksum (SHA1)

This package also provides a metadata-invariant checksum for audio files: only the audio data is used to construct the checksum.

https://pkg.go.dev/github.com/dhowden/tag#Sum

Tools

There are simple command-line tools which demonstrate basic tag extraction and summing:

$ go install github.com/dhowden/tag/cmd/tag@latest
$ cd $GOPATH/bin
$ ./tag 11\ High\ Hopes.m4a
Metadata Format: MP4
Title: High Hopes
Album: The Division Bell
Artist: Pink Floyd
Composer: Abbey Road Recording Studios/David Gilmour/Polly Samson
Year: 1994
Track: 11 of 11
Disc: 1 of 1
Picture: Picture{Ext: jpeg, MIMEType: image/jpeg, Type: , Description: , Data.Size: 606109}

$ ./sum 11\ High\ Hopes.m4a
2ae208c5f00a1f21f5fac9b7f6e0b8e52c06da29

Documentation

Overview

Package tag provides MP3 (ID3: v1, 2.2, 2.3 and 2.4), MP4, FLAC and OGG metadata detection, parsing and artwork extraction.

Detect and parse tag metadata from an io.ReadSeeker (i.e. an *os.File): 

m, err := tag.ReadFrom(f)
if err != nil {
	log.Fatal(err)
}
log.Print(m.Format()) // The detected format.
log.Print(m.Title())  // The title of the track (see Metadata interface for more details).

Index

Constants

This section is empty.

Variables

View Source 
var DefaultUTF16WithBOMByteOrder binary.ByteOrder = binary.LittleEndian

DefaultUTF16WithBOMByteOrder is the byte order used when the "UTF16 with BOM" encoding is specified without a corresponding BOM in the data.

View Source 
var ErrNoTagsFound = errors.New("no tags found")

ErrNoTagsFound is the error returned by ReadFrom when the metadata format cannot be identified.

View Source 
var ErrNotID3v1 = errors.New("invalid ID3v1 header")

ErrNotID3v1 is an error which is returned when no ID3v1 header is found.

Functions

func Identify 

func Identify(r io.ReadSeeker) (format Format, fileType FileType, err error)

Identify identifies the format and file type of the data in the ReadSeeker.

func Sum 

func Sum(r io.ReadSeeker) (string, error)

Sum creates a checksum of the audio file data provided by the io.ReadSeeker which is metadata (ID3, MP4) invariant.

func SumAll 

func SumAll(r io.ReadSeeker) (string, error)

SumAll returns a checksum of the content from the reader (until EOF).

func SumAtoms 

func SumAtoms(r io.ReadSeeker) (string, error)

SumAtoms constructs a checksum of MP4 audio file data provided by the io.ReadSeeker which is metadata invariant.

func SumFLAC 

func SumFLAC(r io.ReadSeeker) (string, error)

SumFLAC costructs a checksum of the FLAC audio file data provided by the io.ReadSeeker (ignores metadata fields).

func SumID3v1 

func SumID3v1(r io.ReadSeeker) (string, error)

SumID3v1 constructs a checksum of MP3 audio file data (assumed to have ID3v1 tags) provided by the io.ReadSeeker which is metadata invariant.

func SumID3v2 

func SumID3v2(r io.ReadSeeker) (string, error)

SumID3v2 constructs a checksum of MP3 audio file data (assumed to have ID3v2 tags) provided by the io.ReadSeeker which is metadata invariant.

Types

type Comm 

type Comm struct {
	Language    string
	Description string
	Text        string
}

Comm is a type used in COMM, UFID, TXXX, WXXX and USLT tag. It's a text with a description and a specified language For WXXX, TXXX and UFID, we don't set a Language

func (Comm) String 

func (t Comm) String() string

String returns a string representation of the underlying Comm instance.

type FileType 

type FileType string

FileType is an enumeration of the audio file types supported by this package, in particular there are audio file types which share metadata formats, and this type is used to distinguish between them. 

const (
	UnknownFileType FileType = ""     // Unknown FileType.
	MP3             FileType = "MP3"  // MP3 file
	M4A             FileType = "M4A"  // M4A file Apple iTunes (ACC) Audio
	M4B             FileType = "M4B"  // M4A file Apple iTunes (ACC) Audio Book
	M4P             FileType = "M4P"  // M4A file Apple iTunes (ACC) AES Protected Audio
	ALAC            FileType = "ALAC" // Apple Lossless file FIXME: actually detect this
	FLAC            FileType = "FLAC" // FLAC file
	OGG             FileType = "OGG"  // OGG file
	DSF             FileType = "DSF"  // DSF file DSD Sony format see https://dsd-guide.com/sites/default/files/white-papers/DSFFileFormatSpec_E.pdf
)

Supported file types.

type Format 

type Format string

Format is an enumeration of metadata types supported by this package. 

const (
	UnknownFormat Format = ""        // Unknown Format.
	ID3v1         Format = "ID3v1"   // ID3v1 tag format.
	ID3v2_2       Format = "ID3v2.2" // ID3v2.2 tag format.
	ID3v2_3       Format = "ID3v2.3" // ID3v2.3 tag format (most common).
	ID3v2_4       Format = "ID3v2.4" // ID3v2.4 tag format.
	MP4           Format = "MP4"     // MP4 tag (atom) format (see http://www.ftyps.com/ for a full file type list)
	VORBIS        Format = "VORBIS"  // Vorbis Comment tag format.
)

Supported tag formats.

type Metadata 

type Metadata interface {
	// Format returns the metadata Format used to encode the data.
	Format() Format

	// FileType returns the file type of the audio file.
	FileType() FileType

	// Title returns the title of the track.
	Title() string

	// Album returns the album name of the track.
	Album() string

	// Artist returns the artist name of the track.
	Artist() string

	// AlbumArtist returns the album artist name of the track.
	AlbumArtist() string

	// Composer returns the composer of the track.
	Composer() string

	// Year returns the year of the track.
	Year() int

	// Genre returns the genre of the track.
	Genre() string

	// Track returns the track number and total tracks, or zero values if unavailable.
	Track() (int, int)

	// Disc returns the disc number and total discs, or zero values if unavailable.
	Disc() (int, int)

	// Picture returns a picture, or nil if not available.
	Picture() *Picture

	// Lyrics returns the lyrics, or an empty string if unavailable.
	Lyrics() string

	// Comment returns the comment, or an empty string if unavailable.
	Comment() string

	// Raw returns the raw mapping of retrieved tag names and associated values.
	// NB: tag/atom names are not standardised between formats.
	Raw() map[string]interface{}
}

Metadata is an interface which is used to describe metadata retrieved by this package.

func ReadAtoms 

func ReadAtoms(r io.ReadSeeker) (Metadata, error)

ReadAtoms reads MP4 metadata atoms from the io.ReadSeeker into a Metadata, returning non-nil error if there was a problem.

func ReadDSFTags 

func ReadDSFTags(r io.ReadSeeker) (Metadata, error)

ReadDSFTags reads DSF metadata from the io.ReadSeeker, returning the resulting metadata in a Metadata implementation, or non-nil error if there was a problem. samples: http://www.2l.no/hires/index.html

func ReadFLACTags 

func ReadFLACTags(r io.ReadSeeker) (Metadata, error)

ReadFLACTags reads FLAC metadata from the io.ReadSeeker, returning the resulting metadata in a Metadata implementation, or non-nil error if there was a problem.

func ReadFrom 

func ReadFrom(r io.ReadSeeker) (Metadata, error)

ReadFrom detects and parses audio file metadata tags (currently supports ID3v1,2.{2,3,4}, MP4, FLAC/OGG). Returns non-nil error if the format of the given data could not be determined, or if there was a problem parsing the data.

func ReadID3v1Tags 

func ReadID3v1Tags(r io.ReadSeeker) (Metadata, error)

ReadID3v1Tags reads ID3v1 tags from the io.ReadSeeker. Returns ErrNotID3v1 if there are no ID3v1 tags, otherwise non-nil error if there was a problem.

func ReadID3v2Tags 

func ReadID3v2Tags(r io.ReadSeeker) (Metadata, error)

ReadID3v2Tags parses ID3v2.{2,3,4} tags from the io.ReadSeeker into a Metadata, returning non-nil error on failure.

func ReadOGGTags 

func ReadOGGTags(r io.Reader) (Metadata, error)

ReadOGGTags reads OGG metadata from the io.ReadSeeker, returning the resulting metadata in a Metadata implementation, or non-nil error if there was a problem. See http://www.xiph.org/vorbis/doc/Vorbis_I_spec.html and http://www.xiph.org/ogg/doc/framing.html for details. For Opus see https://tools.ietf.org/html/rfc7845

type Picture 

type Picture struct {
	Ext         string // Extension of the picture file.
	MIMEType    string // MIMEType of the picture.
	Type        string // Type of the picture (see pictureTypes).
	Description string // Description.
	Data        []byte // Raw picture data.
}

Picture is a type which represents an attached picture extracted from metadata.

func (Picture) String 

func (p Picture) String() string

String returns a string representation of the underlying Picture instance.

type UFID 

type UFID struct {
	Provider   string
	Identifier []byte
}

UFID is composed of a provider (frequently a URL and a binary identifier) The identifier can be a text (Musicbrainz use texts, but not necessary)

func (UFID) String 

func (u UFID) String() string

Source Files

View all Source files

Directories

Path Synopsis
cmd
check
The check tool performs tag lookups on full music collections (iTunes or directory tree of files).
 The check tool performs tag lookups on full music collections (iTunes or directory tree of files).
sum
The sum tool constructs a checksum of a media file exluding any metadata (as recognised by the tag library).
 The sum tool constructs a checksum of a media file exluding any metadata (as recognised by the tag library).
tag
The tag tool reads metadata from media files (as supported by the tag library).
 The tag tool reads metadata from media files (as supported by the tag library).
internal
id3v1_test
Package mbz extracts MusicBrainz Picard-specific tags from general tag metadata.
 Package mbz extracts MusicBrainz Picard-specific tags from general tag metadata.

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.