id3v2

README

id3v2

IMHO

I think, ID3 is a very overwhelmed standard: it does more than it really should do. There are a lot of aspects, which developer should take into consideration. And that's why it's pretty complicated to write a good library. So if you have some thoughts about writing a new simply and elegant standard for providing information for digital music tracks, just write me. I think, it's a good time to write an appropriate standard for it 😉

Information

Fast and stable ID3 writing library for Go

This library can only set and write tags, but can't read them. So if you only want to set tags, it fits you. And if there is a tag of version 3 or 4, this library will just delete this tag, because it can't parse tags yet. If version of the tag is smaller than 3, this library will return an error.

What it can do:

• Set artist, album, year, genre, unsynchronised lyrics/text (USLT), comments and attached pictures (e.g. album covers) and write all to file
• Set several USLT, comments and attached pictures
• Work with all allowed encodings

What it can't do:

• Parse tags
• Work with extended header, flags, padding

If you want some functionality, that library can't do, just write an issue. I will implement it as fast as I can

And of course, pull requests are welcome!

Benchmarks

All benchmarks run on MacBook Air 13" (early 2013, 1,4GHz Intel Core i5, 4GB 1600MHz DDR3)

Set title, artist, year and 50KB picture to 4,6 MP3:

BenchmarkSetCommonCase-4	     200	   9255995 ns/op	   38386 B/op	      32 allocs/op

Set title, artist, album, year, genre, unsynchronised lyrics, comment and 50KB picture to 4,6MB MP3:

BenchmarkSetManyTags-4  	     200	   9268306 ns/op	   41177 B/op	      46 allocs/op

Installation

$ go get -u github.com/bogem/id3v2

Example of Usage:

package main

import (
  "github.com/bogem/id3v2"
  "log"
)

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

  // Set tags
  tag.SetArtist("Artist")
  tag.SetTitle("Title")

  comment := id3v2.NewCommentFrame()
  comment.SetLanguage("eng")
  comment.SetDescription("Short description")
  comment.SetText("The actual text")
  tag.AddCommentFrame(comment)

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

Documentation

You can find it here: https://godoc.org/github.com/bogem/id3v2

TODO

• Parse tags
• Work with extended header, flags, padding (Does anyone really use it?)
• Documentation
• Work with other encodings

License

MIT

Documentation

Overview

ID3v2 writing library for Go.

This library can only set and write tags, but can't read them. So if you only want to set tags, it fits you. And if there is a tag of version 3 or 4, this library will just delete this tag, because it can't parse tags yet. If version of the tag is small than 3, this library will return an error.

Example of creating a new tag and writing it in file:

package main

import (
	"github.com/bogem/id3v2"
	"log"
)

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

	// Set tags
	tag.SetArtist("Artist")
	tag.SetTitle("Title")

	comment := id3v2.NewCommentFrame()
	comment.SetLanguage("eng")
	comment.SetDescription("Short description")
	comment.SetText("The actual text")
	tag.AddCommentFrame(comment)

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

Index

• Constants
• Variables
• func NewAttachedPicture() *frame.PictureFrame
• func NewCommentFrame() *frame.CommentFrame
• func NewTextFrame(text string) *frame.TextFrame
• func NewUnsynchronisedLyricsFrame() *frame.UnsynchronisedLyricsFrame
• type Tag
  • func Open(name string) (*Tag, error)
  • func (t *Tag) AddAttachedPicture(pf frame.PictureFramer)
  • func (t *Tag) AddCommentFrame(cf frame.CommentFramer)
  • func (t *Tag) AddFrame(id string, f frame.Framer)
  • func (t *Tag) AddUnsynchronisedLyricsFrame(uslf frame.UnsynchronisedLyricsFramer)
  • func (t Tag) Flush() error
  • func (t *Tag) SetAlbum(album string)
  • func (t *Tag) SetArtist(artist string)
  • func (t *Tag) SetGenre(genre string)
  • func (t *Tag) SetTitle(title string)
  • func (t *Tag) SetYear(year string)

Constants

const (
	PTOther                   = 0
	PTFileIcon                = 1
	PTOtherFileIcon           = 2
	PTFrontCover              = 3
	PTBackCover               = 4
	PTLeafletPage             = 5
	PTMedia                   = 6
	PTLeadArtistSoloist       = 7
	PTArtistPerformer         = 8
	PTConductor               = 9
	PTBandOrchestra           = 10
	PTComposer                = 11
	PTLyricistTextWriter      = 12
	PTRecordingLocation       = 13
	PTDuringRecording         = 14
	PTDuringPerformance       = 15
	PTMovieScreenCapture      = 16
	PTBrightColouredFish      = 17
	PTIllustration            = 18
	PTBandArtistLogotype      = 19
	PTPublisherStudioLogotype = 20
)

Possible picture types for picture frame.

Variables

var (
	// ISO-8859-1.
	ENISO = util.Encoding{
		Key:              0,
		TerminationBytes: []byte{0},
	}

	// UTF-16 encoded Unicode with BOM.
	ENUTF16 = util.Encoding{
		Key:              1,
		TerminationBytes: []byte{0, 0},
	}

	// UTF-16BE encoded Unicode without BOM.
	ENUTF16BE = util.Encoding{
		Key:              2,
		TerminationBytes: []byte{0, 0},
	}

	// UTF-8 encoded Unicode.
	ENUTF8 = util.Encoding{
		Key:              3,
		TerminationBytes: []byte{0},
	}
)

Possible encodings.

Functions

func NewAttachedPicture

func NewAttachedPicture() *frame.PictureFrame

NewAttachedPicture creates and initializes a new attached picture frame.

Example of setting a new picture frame to existing tag:

pic := id3v2.NewAttachedPicture()
pic.SetMimeType("image/jpeg")
pic.SetDescription("Cover")
pic.SetPictureType(id3v2.PTFrontCover)
if err := pic.SetPictureFromFile("artwork.jpg"); err != nil {
	log.Fatal("Error while setting a picture from file: ", err)
}
tag.AddAttachedPicture(pic)

Available picture types you can see in constants.

func NewCommentFrame

func NewCommentFrame() *frame.CommentFrame

NewCommentFrame creates and initializes a new comment frame.

Example of setting a new comment frame to existing tag:

comm := id3v2.NewCommentFrame()
comm.SetLanguage("eng")
comm.SetDescription("Short description")
comm.SetText("The actual text")
tag.AddCommentFrame(comm)

You should choose a language code from ISO 639-2 code list: https://www.loc.gov/standards/iso639-2/php/code_list.php

func NewTextFrame

func NewTextFrame(text string) *frame.TextFrame

NewTextFrame creates and initializes a new text frame. E.g. it is used by such frames as artist, title and etc.

Example of setting a new text frame to existing tag:

textFrame := id3v2.NewTextFrame("Happy")
id := "TMOO" // Mood frame ID
tag.AddFrame(id, textFrame)

func NewUnsynchronisedLyricsFrame

func NewUnsynchronisedLyricsFrame() *frame.UnsynchronisedLyricsFrame

NewUnsynchronisedLyricsFrame creates and initializes a new unsynchronised lyrics/text frame.

Example of setting a new unsynchronised lyrics/text frame to existing tag:

uslt := id3v2.NewUnsynchronisedLyricsFrame()
uslt.SetLanguage("eng")
uslt.SetContentDescriptor("Content descriptor")
uslt.SetLyrics("Lyrics")
tag.AddUnsynchronisedLyricsFrame(uslt)

Types

type Tag

type Tag struct {
	// contains filtered or unexported fields
}

func Open

func Open(name string) (*Tag, error)

Open opens file with string name and find tag in it.

func (*Tag) AddAttachedPicture

func (t *Tag) AddAttachedPicture(pf frame.PictureFramer)

func (*Tag) AddCommentFrame

func (t *Tag) AddCommentFrame(cf frame.CommentFramer)

func (*Tag) AddFrame

func (t *Tag) AddFrame(id string, f frame.Framer)

func (*Tag) AddUnsynchronisedLyricsFrame

func (t *Tag) AddUnsynchronisedLyricsFrame(uslf frame.UnsynchronisedLyricsFramer)

func (Tag) Flush

func (t Tag) Flush() error

Flush writes tag to the file.

func (*Tag) SetAlbum

func (t *Tag) SetAlbum(album string)

func (*Tag) SetArtist

func (t *Tag) SetArtist(artist string)

func (*Tag) SetGenre

func (t *Tag) SetGenre(genre string)

func (*Tag) SetTitle

func (t *Tag) SetTitle(title string)

func (*Tag) SetYear

func (t *Tag) SetYear(year string)