🎵 ID3 parsing and writing library for Go https://godoc.org/github.com/bogem/id3v2

Albert Nigmatzianov 051e4b2ea8 Handle empty strings encoded in UTF16 6 days ago
testdata ed68a94969 Update tests and testdata 4 weeks ago
.gitignore 5f2eaf0402 Add .gitignore 1 year ago
.travis.yml 3da5773345 Support older versions and 32bit 3 weeks ago
LICENSE 5aa0629ea3 First commit! 3 years ago
README.md 11beb2a105 Fix README.md 3 weeks ago
bench_test.go 6a143b684c Take off UDTF and UFID frames from benchmarks 1 year ago
buf_reader.go 051e4b2ea8 Handle empty strings encoded in UTF16 6 days ago
buf_reader_test.go 051e4b2ea8 Handle empty strings encoded in UTF16 6 days ago
buf_writer.go 88f2646e81 Fix UTF16LE parsing and writing 4 weeks ago
comment_frame.go 4de0eaa090 Add framer.UniqueIdentifier() 1 month ago
common_ids.go 1f38ceb0e3 Fix some comments 4 weeks ago
encoding.go 051e4b2ea8 Handle empty strings encoded in UTF16 6 days ago
encoding_test.go 051e4b2ea8 Handle empty strings encoded in UTF16 6 days ago
example_test.go bae247a045 Rename encodings 2 years ago
framer.go 4de0eaa090 Add framer.UniqueIdentifier() 1 month ago
go.mod bf62f74844 Use Go modules 3 weeks ago
go.sum bf62f74844 Use Go modules 3 weeks ago
header.go 5785be9ad4 Tag header size should always be synchsafe 1 year ago
header_test.go 8190b64040 Use own bufWriter 2 years ago
id3v2.go 1283c51623 Add encoding conversion support 2 years ago
options.go 0735adcee6 Add id3v2.Options 2 years ago
parse.go a4e250fe50 add frame overflow check 1 year ago
parse_test.go ed68a94969 Update tests and testdata 4 weeks ago
picture_frame.go 4de0eaa090 Add framer.UniqueIdentifier() 1 month ago
pools.go e4247ea7ec Fix getByteSlice 2 years ago
sequence.go 4de0eaa090 Add framer.UniqueIdentifier() 1 month ago
sequence_test.go c0bd2d010f Fix TestSequenceUSLFsUniqueness 1 month ago
size.go 3845103da5 Fix parsing and writing synchunsafe sizes, that are used in id3v2.3 1 year ago
size_test.go 5da9331ad6 Add more tests 1 year ago
tag.go 88f2646e81 Fix UTF16LE parsing and writing 4 weeks ago
tag_test.go 19c7101489 Fix test 4 weeks ago
text_frame.go 9d871ea687 Add comment 4 weeks ago
ufid_frame.go 4de0eaa090 Add framer.UniqueIdentifier() 1 month ago
unknown_frame.go 4de0eaa090 Add framer.UniqueIdentifier() 1 month ago
unsynchronised_lyrics_frame.go 4de0eaa090 Add framer.UniqueIdentifier() 1 month ago
user_defined_text_frame.go 4de0eaa090 Add framer.UniqueIdentifier() 1 month ago

README.md

id3v2 GoDoc Build Status

Fast, simple and powerful ID3 decoding and encoding library written in Go.

id3v2 can:

  • ✅ support of ID3v2.3 and ID3v2.4 tags;
  • ✅ parse and write tags;
  • ✅ work with all available encodings;
  • ✅ set and read all text frames, unsynchronised lyrics/text (USLT), comments, attached pictures, UFID and TXXX frames;
  • ✅ set and read frames, that can be used multiple times in tag;
  • ✅ be used in multiple goroutines.

id3v2 can't:

  • ❌ work with unsynchronisation, extended header, flags, padding, footer.

If you want some functionality, that library can't do, or you have some questions, just write an issue. And of course, pull requests are welcome!

Installation

go get -u github.com/bogem/id3v2

Example of usage

package main

import (
	"fmt"
	"log"

	"github.com/bogem/id3v2"
)

func main() {
	// Open file and parse tag in it.
	tag, err := id3v2.Open("file.mp3", id3v2.Options{Parse: true})
	if err != nil {
 		log.Fatal("Error while opening mp3 file: ", err)
 	}
	defer tag.Close()

	// Read frames.
	fmt.Println(tag.Artist())
	fmt.Println(tag.Title())

	// Set simple text frames.
	tag.SetArtist("New artist")
	tag.SetTitle("New title")

	// Set comment frame.
	comment := id3v2.CommentFrame{
		Encoding:    id3v2.EncodingUTF8,
		Language:    "eng",
		Description: "My opinion",
		Text:        "Very good song",
	}
	tag.AddCommentFrame(comment)

	// Write it to file.
	if err = tag.Save(); err != nil {
		log.Fatal("Error while saving a tag: ", err)
	}
}

Read multiple frames

pictures := tag.GetFrames(tag.CommonID("Attached picture"))
for _, f := range pictures {
	pic, ok := f.(id3v2.PictureFrame)
	if !ok {
		log.Fatal("Couldn't assert picture frame")
	}

	// Do something with picture frame.
	// For example, print the description:
	fmt.Println(pic.Description)
}

Options

// Options influence on processing the tag.
type Options struct {
	// Parse defines, if tag will be parsed.
	Parse bool

	// ParseFrames defines, that frames do you only want to parse. For example,
	// `ParseFrames: []string{"Artist", "Title"}` will only parse artist
	// and title frames. You can specify IDs ("TPE1", "TIT2") as well as
	// descriptions ("Artist", "Title"). If ParseFrame is blank or nil,
	// id3v2 will parse all frames in tag. It works only if Parse is true.
	//
	// It's very useful for performance, so for example
	// if you want to get only some text frames,
	// id3v2 will not parse huge picture or unknown frames.
	ParseFrames []string
}

Work with encodings

id3v2 can encode and decode text of avaialble encodings (ISO-8859-1, UTF-16 with BOM, UTF-16BE without BOM, UTF-8). Just set the desired encoding in Encoding field of frame and set UTF-8 encoded text to corresponding text fields.

For example, if you set comment frame with custom encoding and write it:

tag := id3v2.NewEmptyTag()
comment := id3v2.CommentFrame{
	Encoding:    id3v2.EncodingUTF16,
	Language:    "ger",
	Description: "Tier",
	Text:        "Der Löwe",
}
tag.AddCommentFrame(comment)

_, err := tag.WriteTo(w)
if err != nil {
	log.Fatal(err)
}

Text field will be automatically encoded with UTF-16BE with BOM and written to w.

By default, if version of tag is 4 then UTF-8 is used for methods like SetArtist, SetTitle, SetGenre and etc, otherwise ISO-8859-1.

Benchmarks

See benchmarks in the description of last release.

Reference

https://godoc.org/github.com/bogem/id3v2