id3

Documentation

Overview

Package id3 reads the tags wrapped around an MP3 file.

Not part of any codec and not part of MP3 either. A tag is a block of text bolted onto the front or the back of a stream, and a decoder's only interest in one is skipping it — which the mp3 package does without this. This is for the other use: knowing what a file holds without decoding it.

Three formats appear in the wild and all three are read here. ID3v2 sits in front of the audio and is the one that matters; ID3v1 is a hundred and twenty-eight bytes at the end, from before there was anything better; APE is a third that some encoders write. A file may carry more than one, and where they disagree the richer one wins.

Reading only. Writing tags is a different job with different hazards, and nothing here needs it.

Index

• Variables
• type Tags
  • func Read(r io.Reader) (Tags, error)
  • func ReadPrefix(data []byte) (Tags, bool)
  • func (t Tags) Empty() bool
  • func (t Tags) Get(name string) string
  • func (t Tags) Merge(o Tags) Tags

Variables

var ErrMalformed = errors.New("id3: malformed tag")

ErrMalformed reports a tag that does not parse. A file with a broken tag still holds audio, so callers that only want to play it can carry on.

Types

type Tags

type Tags struct {
	Title       string
	Artist      string
	Album       string
	AlbumArtist string
	Composer    string
	Genre       string
	Comment     string

	// Year is the recording year, or zero. Date holds whatever the tag said, which may be a full date
	// or a year or something else entirely.
	Year int
	Date string

	// Track and Disc are the position, and Tracks and Discs the total where the tag gave one. A tag
	// that says "3/12" fills both; one that says "3" fills only the first.
	Track, Tracks int
	Disc, Discs   int

	// Version names the tag this came from: "ID3v2.4", "ID3v1", "APEv2" and so on. Empty when a file
	// carried no tag at all.
	Version string

	// Frames is every text field the tag held, keyed by its identifier — "TIT2" and the like for
	// ID3v2, or the key itself for APE. Repeated fields keep their order.
	Frames map[string][]string
}

Tags is what a file says about itself.

The named fields are the ones a listener would recognise and the ones a caller naming files by pattern reaches for. Everything the tag held is in Frames as well, under the identifier the format gave it, because no fixed set of fields covers what people put in these.

func Read

func Read(r io.Reader) (Tags, error)

Read reads whatever tags a stream carries.

The whole stream, because ID3v1 and APE sit at the end of it and there is no other way to reach them. A caller that only wants the leading tag and does not want to read a hundred megabytes to get it should use ReadPrefix.

func ReadPrefix

func ReadPrefix(data []byte) (Tags, bool)

ReadPrefix reads the ID3v2 tag at the start of a buffer, and reports whether there was one.

For a caller holding the first part of a file and no more, which is the ordinary case when the point is to name the file rather than play it.

func (Tags) Empty

func (t Tags) Empty() bool

Empty reports a file that said nothing about itself.

func (Tags) Get

func (t Tags) Get(name string) string

Get returns the first value of a frame, or the empty string.

func (Tags) Merge

func (t Tags) Merge(o Tags) Tags

Merge fills in whatever this tag does not say from another, poorer one.