Class ID3::Tag2

class ID3::Tag2

This class models version 2.x ID3-tags.

Provided Functionality:

Reads and parses audio files for ID3-tags
Dumps information contained in the Tag2 object raw into a string
Writes audio files and attaches ID3-tags to them
Keeps track of complete path name to audio file
Keeps track of where the raw audio portion of an audio-file is
Top-level interface to ID3-tags

Instance Variables:

version # either nil, or a string wtih the version number
raw # string containing the raw ID3 version 2 tag
rawflags # byte with the binary flags of the ID3 version 2 header
flags # parsed flags (accessible as a Hash)

Instance Methods:

new
read
write # not yet implemented..
dump # dump the ID3 version 2 tag raw into a string

Hash-like Access:

When accessing a Tag2 object wtih the Hash syntax, you can access the actual data (Frames) in the tag. Please note that there is only a very limited number of valid keys, and that the class does not allow "inventing" new keys (as those would not correspond to valid ID3-Frames and would not be defined in the ID3 definition)

To see which symbolic names (keys) are allowed, please check ID3::SUPPORTED_SYMBOLS[version].keys

Examples:

	> require 'id3'
	=> true

	> t = ID3::Tag2.new
	=> {}

	> t.read("mp3/d.mp3")
	=> true

	> t.version
	=> "2.3.0"

	> t.keys
	=> ["ARTIST", "SONGLEN", "CONTENTTYPE", "ALBUM", "TRACKNUM", "TITLE", "PICTURE", "MEDIATYPE"]

	> t.raw.size
        => 206561

	> t['PICTURE'].raw.size
	=> 206419

	> t.raw.size - t['PICTURE'].raw.size
	=> 142


	# PLEASE NOTE: this is how you can delete huge pictures which are sometimes attached to your audio-files!

	> t.delete('PICTURE')
	output omitted (returns the picture as a raw string, so you could save it)

	> t.keys
	=> ["ARTIST", "SONGLEN", "CONTENTTYPE", "ALBUM", "TRACKNUM", "TITLE", "MEDIATYPE"]

	> t
	=> {"ARTIST"=>{"encoding"=>0, "text"=>"Beatles"}, "SONGLEN"=>{"encoding"=>0, "text"=>"258847"}, "CONTENTTYPE"=>{"encoding"=>0, "text"=>"60's"}, "ALBUM"=>{"encoding"=>0, "text"=>"Abbey Road"}, "TRACKNUM"=>{"encoding"=>0, "text"=>"1"}, "TITLE"=>{"encoding"=>0, "text"=>"Come Together"}, "MEDIATYPE"=>{"encoding"=>0, "text"=>"DIG"}}

	# the padding size is a bit larger, that's why we don't get 142, but 170 bytes

	> t.dump.size
	=> 170


	# PLEASE NOTE that the entries are now a complex datastructure (according to the definition of ID3-Frames)

	> t['ARTIST']
	=> {"encoding"=>0, "text"=>"Beatles"}

	> t['ARTIST']['text'] = "The Beatles"
	=> "The Beatles"

	# PLEASE NOTE that you can not "invent" new Frame or field names:

	> t['ARTIST']['myrating'] = 4
	ArgumentError: You can not add new keys! The ID3-frame TPE1 has fixed entries!
                       valid key are: encoding,text

        from ./id3.rb:562:in `[]='
        from (irb):7

	> t['MYFIELD'] = "does not work!"
	ArgumentError: Incorrect ID3-field "MYFIELD" for ID3 version 2.3.0
                       valid fields are: PICTURE,FILEOWNER,CONDUCTOR,EVENTTIMING,DATE,CRYPTOREG,COMMENT,POPULARIMETER,GROUPINGREG,PUBLISHER,COPYRIGHT,EQUALIZATION,NETRADIOSTATION,ORIGFILENAME,WWWPUBLISHER,BUFFERSIZE,PLAYCOUNTER,ISRC,LYRICIST,RECORDINGDATES,SIZE,INVOLVEDPEOPLE,POSITIONSYNC,WWWCOMMERCIALINFO,PLAYLISTDELAY,ORIGLYRICIST,ALBUM,SYNCEDLYRICS,CONTENTTYPE,SONGLEN,MEDIATYPE,WWWPAYMENT,REVERB,COMPOSER,LINKEDINFO,CONTENTGROUP,BPM,ORIGYEAR,ORIGARTIST,UNIQUEFILEID,USERTEXT,FILETYPE,TIME,PRIVATE,SUBTITLE,TERMSOFUSE,BAND,WWWCOPYRIGHT,YEAR,INITIALKEY,SYNCEDTEMPO,PARTINSET,WWWUSER,AUDIOCRYPTO,MPEGLOOKUP,VOLUMEADJ,ORIGALBUM,CDID,ENCODEDBY,WWWAUDIOFILE,COMMERCIAL,TITLE,MIXARTIST,NETRADIOOWNER,TRACKNUM,WWWAUDIOSOURCE,GENERALOBJECT,WWWRADIOPAGE,LANGUAGE,ENCODERSETTINGS,WWWARTIST,ARTIST,UNSYNCEDLYRICS

        from ./id3.rb:636:in `[]='
        from (irb):8

	#  PLEASE NOTE that the raw tag is read only, and reflects the data that was read from the file!

	> t.raw
	output omitted (returns a string with the raw ID3-v2-tag)
	
	> t.raw.hexdump
	output omitted (returns a hexdump of the raw ID3-v2-tag)
	
	> t.raw.size
	=> 206561

	> t.dump
	=> "ID3\003\000\000\000\000\001 TPE1\000\000\000\t\000\000\000Beatles\000TLEN\000\000\000\010\000\000\000258847\000TCON\000\000\000\006\000\000\00060's\000TALB\000\000\000\f\000\000\000Abbey Road\000TRCK\000\000\000\003\000\000\0001\000TIT2\000\000\000\017\000\000\000Come Together\000TMED\000\000\000\005\000\000\000DIG\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000"
i

	> t.dump.hexdump

	 index       0 1 2 3  4 5 6 7  8 9 A B  C D E F

	00000000    49443303 00000000 01205450 45310000    ID3...... TPE1..
	00000010    00090000 00426561 746c6573 00544c45    .....Beatles.TLE
	00000020    4e000000 08000000 32353838 34370054    N.......258847.T
	00000030    434f4e00 00000600 00003630 27730054    CON.......60's.T
	00000040    414c4200 00000c00 00004162 62657920    ALB.......Abbey
	00000050    526f6164 00545243 4b000000 03000000    Road.TRCK.......
	00000060    31005449 54320000 000f0000 00436f6d    1.TIT2.......Com
	00000070    6520546f 67657468 65720054 4d454400    e Together.TMED.
	00000080    00000500 00004449 47000000 00000000    ......DIG.......
	00000090    00000000 00000000 00000000 00000000    ................
	000000a0    00000000 00000000 0000                 ..........
	=> nil

	> t.dump.size
	=> 170