id3 0.5.0 → 1.0.0.pre4

data/lib/id3/audiofile.rb

@@ -0,0 +1,261 @@
+# ==============================================================================
+# Class AudioFile    may call this ID3File
+#
+#    reads and parses audio files for tags
+#    writes audio files and attaches dumped tags to it..
+#    revert feature would be nice to have..
+# 
+#    If we query and AudioFile object, we query what's currently associated with it
+#    e.g. we're not querying the file itself, but the Tag object which is perhaps modified.
+#    To query the file itself, use the ID3 module functions
+#
+#    By default the audio portion of the file is not(!) read - to reduce memory footprint - the audioportion could be very long!
+#
+# BUG: (1) : when a id3v2 frame is deleted from a tag, e.g. 'PICTURE', then the raw tag is not updated
+# BUG: (2) : when a AudioFile is written to file, the raw tag is not updated to reflect the new raw tag value
+# BUG: (3) : FIXED. when a AufioFile is written, the order of frames is not the same as in the original file.. fixed using OrderedHash
+# BUG: (5) : when a FrameType is set for a ID3v2 tag, e.g. 'TITLE', the underlying attributes are not automatically pre-filled..
+
+class AudioFile
+  attr_reader :audioStartX , :audioEndX     # begin and end indices of audio data in file
+  
+  attr_reader :pwd,          :filename      # PWD and relative path/name how file was first referenced
+  attr_reader :dirname,      :basename      # absolute dirname and basename of the file (computed)
+  
+  attr_accessor :tagID3v1, :tagID3v2    # should make aliases id3v1_tag , id3v2_tag 
+  
+  # ----------------------------------------------------------------------------
+  # initialize
+  #
+  #   AudioFile.new   does NOT keep the file open, but scans it and parses the info
+  #   e.g.:  ID3::AudioFile.new('mp3/a.mp3')
+
+  # this should take two parameters, either Filename or String, and an options hash, e.g. {:read_audio => false}
+
+  def initialize( filename )
+    @filename     = filename      # similar to path method from class File, which is a mis-nomer!
+    @pwd          = ENV["PWD"]
+    @dirname      = File.dirname( filename )
+    @basename     = File.basename( filename )
+    
+    @tagID3v1     = nil
+    @tagID3v2     = nil
+
+    @audio        = nil           # this doesn't get initialized with the actual audio during new(), so we don't waste memory
+
+    audioStartX   = 0
+    audioEndX     = File.size(filename) - 1  # points to the last index
+
+    if ID3.hasID3v1tag?(@filename)
+      @tagID3v1 = ID3::Tag1.new
+      @tagID3v1.read(@filename)
+
+      audioEndX -= ID3::ID3v1tagSize
+    end
+    if ID3.hasID3v2tag?(@filename) 
+      @tagID3v2 = ID3::Tag2.new
+      @tagID3v2.read(@filename)
+
+      audioStartX = @tagID3v2.raw.size
+    end
+    
+    # audioStartX audioEndX indices into the file need to be set
+    @audioStartX = audioStartX     # first byte of audio data
+    @audioEndX   = audioEndX       # last byte of audio data
+    
+    # user may compute the MD5sum of the audio content later..
+    # but we're only doing this if the user requests it..
+    # because MD5sum computation takes a little bit time.
+
+    @audioMD5sum = nil
+    @audioSHA1sum = nil
+  end
+
+  # ----------------------------------------------------------------------------
+  # version    aka    versions
+  #     queries the tag objects and returns the version numbers of those tags
+  #     NOTE: this does not reflect what's currently in the file, but what's
+  #           currently in the AudioFile object
+  
+  def id3_versions       # returns Array of ID3 tag versions found
+    a = Array.new
+    a.push(@tagID3v1.version) if @tagID3v1
+    a.push(@tagID3v2.version) if @tagID3v2
+    return a
+  end
+  alias versions id3_versions
+  alias version  id3_versions
+  # ----------------------------------------------------------------------------
+  def has_id3v1tag?
+    return @tagID3v1
+  end
+  # ----------------------------------------------------------------------------
+  def has_id3v2tag?
+    return @tagID3v2
+  end
+  # ----------------------------------------------------------------------------
+  def audioLength
+    @audioEndX - @audioStartX + 1
+  end
+  # ----------------------------------------------------------------------------
+  # write
+  #     write the AudioFile to file, including any ID3-tags
+  #     We keep backups if we write to a specific filename
+  
+  def write(*filename)
+    backups = false
+    
+    if filename.size == 0     # this is an Array!!
+      filename = @filename
+      backups  = true        # keep backups if we write to a specific filename
+    else
+      filename = filename[0]
+      backups = false
+    end
+    
+    tf = Tempfile.new( @basename )
+    tmpname = tf.path
+    
+    # write ID3v2 tag:
+    
+    if @tagID3v2
+      tf.write( @tagID3v2.dump )
+    end
+    
+    # write Audio Data:
+    
+    tf.write( audio ) # reads audio from file if nil
+    
+    # write ID3v1 tag:
+    
+    if @tagID3v1
+      tf.write( @tagID3v1.dump )
+    end
+    
+    tf.close
+    
+    # now some logic about moving the tempfile and replacing the original
+
+    bakname = filename + '.bak'
+    move(filename, bakname) if backups && FileTest.exists?(filename) && ! FileTest.exists?(bakname)
+
+    move(tmpname, filename)
+    tf.close(true)
+    
+    # write md5sum sha1sum files:
+    writeMD5sum if @audioMD5sum
+    writeSHA1sum if @audioSHA1sum
+  end
+  
+  # ----------------------------------------------------------------------------
+  # readAudion
+  #     read audio into @audio buffer either from String or from File
+  def audio
+    @audio ||= readAudio    # read the audio portion of the file only once, the first time this is called.
+  end
+
+  def readAudio
+    File.open( File.join(@dirname, @basename) ) do |f|
+      f.seek(@audioStartX)
+      f.read(@audioEndX - @audioStartX + 1) 
+    end
+  end
+  # ----------------------------------------------------------------------------
+  # writeAudio
+  #     only for debugging, does not write any ID3-tags, but just the audio portion
+  
+  def writeAudioOnly
+    tf = Tempfile.new( @basename )
+    
+    File.open( @filename ) { |f|
+      f.seek(@audioStartX)
+      tf.write( audio )   # reads the audio from file if nil
+    }
+    tf.close
+    path = tf.path
+    
+    tf.open
+    tf.close(true)
+  end
+  
+  
+  # ----------------------------------------------------------------------------
+  # NOTE on md5sum's:
+  #    If you don't know what an md5sum is, you can think of it as a unique 
+  #    fingerprint of a file or some data.  I added the md5sum computation to
+  #    help users keep track of their converted songs - even if the ID3-tag of
+  #    a file changes(!), the md5sum of the audio data does not change..
+  #    The md5sum can help you ensure that the audio-portion of the file
+  #    was not changed after modifying, adding or deleting ID3-tags.
+  #    It can also help you identifying duplicates.
+  
+  # ----------------------------------------------------------------------------
+  # audioMD5sum
+  #     if the user tries to access @audioMD5sum, it will be computed for him, 
+  #     unless it was previously computed. We try to calculate that only once 
+  #     and on demand, because it's a bit expensive to compute..
+  
+  def audioMD5sum
+    @audioMD5sum ||= MD5.hexdigest( audio )
+  end
+
+  def audioSHA1sum
+    @audioSHA1sum ||= SHA1.hexdigest( audio )
+  end
+  # ----------------------------------------------------------------------------
+  # writeMD5sum
+  #     write the filename and MD5sum of the audio portion into an ascii file 
+  #     in the same location as the audio file, but with suffix .md5
+  #
+  #     computes the @audioMD5sum, if it wasn't previously computed..
+
+  def writeMD5sum
+    base = @basename.sub( /(.)\.[^.]+$/ , '\1')
+    base += '.md5'
+    File.open( File.join(@dirname,base) ,"w") { |f| 
+      f.printf("%s   %s\n",  File.join(@dirname,@basename), audioMD5sum ) # computes it if nil
+    }
+    @audioMD5sum
+  end
+
+  def writeSHA1sum
+    base = @basename.sub( /(.)\.[^.]+$/ , '\1')
+    base += '.sha1'
+    File.open( File.join(@dirname,base) ,"w") { |f| 
+      f.printf("%s   %s\n",  File.join(@dirname,@basename), audioSHA1sum ) # computes it if nil
+    }
+    @audioSHA1sum
+  end
+  # ----------------------------------------------------------------------------
+  # verifyMD5sum
+  #     compare the audioMD5sum against a previously stored md5sum file
+  #     and returns boolean value of comparison
+  #
+  #     If no md5sum file existed, we create one and return true.
+  #
+  #     computes the @audioMD5sum, if it wasn't previously computed..
+
+  def verifyMD5sum
+
+    oldMD5sum = ''
+    
+    self.audioMD5sum if ! @audioMD5sum  # compute MD5sum if it's not computed yet
+
+    base = @basename.sub( /(.)\.[^.]+$/ , '\1')   # remove suffix from audio-file
+    base += '.md5'                                # add new suffix .md5
+    md5name = File.join(@dirname,base)
+    
+    # if a MD5-file doesn't exist, we should create one and return TRUE ...
+    if File.exists?(md5name)
+      File.open( md5name ,"r") { |f| 
+        oldname,oldMD5sum = f.readline.split  # read old MD5-sum
+      }
+    else
+      oldMD5sum = self.writeMD5sum        # create MD5-file and return true..
+    end
+    @audioMD5sum == oldMD5sum
+    
+  end
+  # ----------------------------------------------------------------------------
+  
+end   # of class AudioFile

data/lib/id3/constants.rb

@@ -0,0 +1,292 @@
+module ID3
+  
+  # ----------------------------------------------------------------------------
+  #    CONSTANTS
+  # ----------------------------------------------------------------------------
+  Version = '1.0.0_pre4'
+
+  ID3v1tagSize     = 128     # ID3v1 and ID3v1.1 have fixed size tags
+  ID3v1versionbyte = 125
+
+  ID3v2headerSize  = 10
+  ID3v2major       =  3
+  ID3v2minor       =  4
+  ID3v2flags       =  5
+  ID3v2tagSize     =  6
+
+
+  VERSIONS = 
+    SUPPORTED_VERSIONS = ["1.0", "1.1", "2.2.0", "2.3.0", "2.4.0"]
+
+  SUPPORTED_SYMBOLS = {
+      "1.0"   => {
+      "ARTIST"=>33..62 , "ALBUM"=>63..92 ,"TITLE"=>3..32,
+      "YEAR"=>93..96 , "COMMENT"=>97..126,"GENREID"=>127,
+    #               "VERSION"=>"1.0"
+    }  ,
+    "1.1"   => {
+      "ARTIST"=>33..62 , "ALBUM"=>63..92 ,"TITLE"=>3..32,
+      "YEAR"=>93..96 , "COMMENT"=>97..124,
+      "TRACKNUM"=>126, "GENREID"=>127,
+    #                "VERSION"=>"1.1"
+    }  ,
+
+    "2.2.0" => {"CONTENTGROUP"=>"TT1", "TITLE"=>"TT2", "SUBTITLE"=>"TT3",
+      "ARTIST"=>"TP1", "BAND"=>"TP2", "CONDUCTOR"=>"TP3", "MIXARTIST"=>"TP4",
+      "COMPOSER"=>"TCM", "LYRICIST"=>"TXT", "LANGUAGE"=>"TLA", "CONTENTTYPE"=>"TCO",
+      "ALBUM"=>"TAL", "TRACKNUM"=>"TRK", "PARTINSET"=>"TPA", "ISRC"=>"TRC", 
+      "DATE"=>"TDA", "YEAR"=>"TYE", "TIME"=>"TIM", "RECORDINGDATES"=>"TRD",
+      "ORIGYEAR"=>"TOR", "BPM"=>"TBP", "MEDIATYPE"=>"TMT", "FILETYPE"=>"TFT", 
+      "COPYRIGHT"=>"TCR", "PUBLISHER"=>"TPB", "ENCODEDBY"=>"TEN", 
+      "ENCODERSETTINGS"=>"TSS", "SONGLEN"=>"TLE", "SIZE"=>"TSI",
+      "PLAYLISTDELAY"=>"TDY", "INITIALKEY"=>"TKE", "ORIGALBUM"=>"TOT",
+      "ORIGFILENAME"=>"TOF", "ORIGARTIST"=>"TOA", "ORIGLYRICIST"=>"TOL",
+      "USERTEXT"=>"TXX", 
+      "WWWAUDIOFILE"=>"WAF", "WWWARTIST"=>"WAR", "WWWAUDIOSOURCE"=>"WAS",
+      "WWWCOMMERCIALINFO"=>"WCM", "WWWCOPYRIGHT"=>"WCP", "WWWPUBLISHER"=>"WPB",
+      "WWWUSER"=>"WXX", "UNIQUEFILEID"=>"UFI",
+      "INVOLVEDPEOPLE"=>"IPL", "UNSYNCEDLYRICS"=>"ULT", "COMMENT"=>"COM",
+      "CDID"=>"MCI", "EVENTTIMING"=>"ETC", "MPEGLOOKUP"=>"MLL",
+      "SYNCEDTEMPO"=>"STC", "SYNCEDLYRICS"=>"SLT", "VOLUMEADJ"=>"RVA",
+      "EQUALIZATION"=>"EQU", "REVERB"=>"REV", "PICTURE"=>"PIC",
+      "GENERALOBJECT"=>"GEO", "PLAYCOUNTER"=>"CNT", "POPULARIMETER"=>"POP",
+      "BUFFERSIZE"=>"BUF", "CRYPTEDMETA"=>"CRM", "AUDIOCRYPTO"=>"CRA",
+      "LINKED"=>"LNK"
+    } ,
+
+    "2.3.0" => {"CONTENTGROUP"=>"TIT1", "TITLE"=>"TIT2", "SUBTITLE"=>"TIT3",
+      "ARTIST"=>"TPE1", "BAND"=>"TPE2", "CONDUCTOR"=>"TPE3", "MIXARTIST"=>"TPE4",
+      "COMPOSER"=>"TCOM", "LYRICIST"=>"TEXT", "LANGUAGE"=>"TLAN", "CONTENTTYPE"=>"TCON",
+      "ALBUM"=>"TALB", "TRACKNUM"=>"TRCK", "PARTINSET"=>"TPOS", "ISRC"=>"TSRC",
+      "DATE"=>"TDAT", "YEAR"=>"TYER", "TIME"=>"TIME", "RECORDINGDATES"=>"TRDA",
+      "ORIGYEAR"=>"TORY", "SIZE"=>"TSIZ", 
+      "BPM"=>"TBPM", "MEDIATYPE"=>"TMED", "FILETYPE"=>"TFLT", "COPYRIGHT"=>"TCOP",
+      "PUBLISHER"=>"TPUB", "ENCODEDBY"=>"TENC", "ENCODERSETTINGS"=>"TSSE",
+      "SONGLEN"=>"TLEN", "PLAYLISTDELAY"=>"TDLY", "INITIALKEY"=>"TKEY",
+      "ORIGALBUM"=>"TOAL", "ORIGFILENAME"=>"TOFN", "ORIGARTIST"=>"TOPE",
+      "ORIGLYRICIST"=>"TOLY", "FILEOWNER"=>"TOWN", "NETRADIOSTATION"=>"TRSN",
+      "NETRADIOOWNER"=>"TRSO", "USERTEXT"=>"TXXX",
+      "WWWAUDIOFILE"=>"WOAF", "WWWARTIST"=>"WOAR", "WWWAUDIOSOURCE"=>"WOAS",
+      "WWWCOMMERCIALINFO"=>"WCOM", "WWWCOPYRIGHT"=>"WCOP", "WWWPUBLISHER"=>"WPUB",
+      "WWWRADIOPAGE"=>"WORS", "WWWPAYMENT"=>"WPAY", "WWWUSER"=>"WXXX", "UNIQUEFILEID"=>"UFID",
+      "INVOLVEDPEOPLE"=>"IPLS", 
+      "UNSYNCEDLYRICS"=>"USLT", "COMMENT"=>"COMM", "TERMSOFUSE"=>"USER",
+      "CDID"=>"MCDI", "EVENTTIMING"=>"ETCO", "MPEGLOOKUP"=>"MLLT",
+      "SYNCEDTEMPO"=>"SYTC", "SYNCEDLYRICS"=>"SYLT", 
+      "VOLUMEADJ"=>"RVAD", "EQUALIZATION"=>"EQUA", 
+      "REVERB"=>"RVRB", "PICTURE"=>"APIC", "GENERALOBJECT"=>"GEOB",
+      "PLAYCOUNTER"=>"PCNT", "POPULARIMETER"=>"POPM", "BUFFERSIZE"=>"RBUF",
+      "AUDIOCRYPTO"=>"AENC", "LINKEDINFO"=>"LINK", "POSITIONSYNC"=>"POSS",
+      "COMMERCIAL"=>"COMR", "CRYPTOREG"=>"ENCR", "GROUPINGREG"=>"GRID", 
+      "PRIVATE"=>"PRIV"
+    } ,
+
+    "2.4.0" => {"CONTENTGROUP"=>"TIT1", "TITLE"=>"TIT2", "SUBTITLE"=>"TIT3",
+      "ARTIST"=>"TPE1", "BAND"=>"TPE2", "CONDUCTOR"=>"TPE3", "MIXARTIST"=>"TPE4",
+      "COMPOSER"=>"TCOM", "LYRICIST"=>"TEXT", "LANGUAGE"=>"TLAN", "CONTENTTYPE"=>"TCON",
+      "ALBUM"=>"TALB", "TRACKNUM"=>"TRCK", "PARTINSET"=>"TPOS", "ISRC"=>"TSRC",
+      "RECORDINGTIME"=>"TDRC", "ORIGRELEASETIME"=>"TDOR",
+      "BPM"=>"TBPM", "MEDIATYPE"=>"TMED", "FILETYPE"=>"TFLT", "COPYRIGHT"=>"TCOP",
+      "PUBLISHER"=>"TPUB", "ENCODEDBY"=>"TENC", "ENCODERSETTINGS"=>"TSSE",
+      "SONGLEN"=>"TLEN", "PLAYLISTDELAY"=>"TDLY", "INITIALKEY"=>"TKEY",
+      "ORIGALBUM"=>"TOAL", "ORIGFILENAME"=>"TOFN", "ORIGARTIST"=>"TOPE",
+      "ORIGLYRICIST"=>"TOLY", "FILEOWNER"=>"TOWN", "NETRADIOSTATION"=>"TRSN",
+      "NETRADIOOWNER"=>"TRSO", "USERTEXT"=>"TXXX",
+      "SETSUBTITLE"=>"TSST", "MOOD"=>"TMOO", "PRODUCEDNOTICE"=>"TPRO",
+      "ENCODINGTIME"=>"TDEN", "RELEASETIME"=>"TDRL", "TAGGINGTIME"=>"TDTG",
+      "ALBUMSORTORDER"=>"TSOA", "PERFORMERSORTORDER"=>"TSOP", "TITLESORTORDER"=>"TSOT",
+      "WWWAUDIOFILE"=>"WOAF", "WWWARTIST"=>"WOAR", "WWWAUDIOSOURCE"=>"WOAS",
+      "WWWCOMMERCIALINFO"=>"WCOM", "WWWCOPYRIGHT"=>"WCOP", "WWWPUBLISHER"=>"WPUB",
+      "WWWRADIOPAGE"=>"WORS", "WWWPAYMENT"=>"WPAY", "WWWUSER"=>"WXXX", "UNIQUEFILEID"=>"UFID",
+      "MUSICIANCREDITLIST"=>"TMCL", "INVOLVEDPEOPLE2"=>"TIPL",
+      "UNSYNCEDLYRICS"=>"USLT", "COMMENT"=>"COMM", "TERMSOFUSE"=>"USER",
+      "CDID"=>"MCDI", "EVENTTIMING"=>"ETCO", "MPEGLOOKUP"=>"MLLT",
+      "SYNCEDTEMPO"=>"SYTC", "SYNCEDLYRICS"=>"SYLT", 
+      "VOLUMEADJ2"=>"RVA2", "EQUALIZATION2"=>"EQU2",
+      "REVERB"=>"RVRB", "PICTURE"=>"APIC", "GENERALOBJECT"=>"GEOB",
+      "PLAYCOUNTER"=>"PCNT", "POPULARIMETER"=>"POPM", "BUFFERSIZE"=>"RBUF",
+      "AUDIOCRYPTO"=>"AENC", "LINKEDINFO"=>"LINK", "POSITIONSYNC"=>"POSS",
+      "COMMERCIAL"=>"COMR", "CRYPTOREG"=>"ENCR", "GROUPINGREG"=>"GRID", 
+      "PRIVATE"=>"PRIV",
+      "OWNERSHIP"=>"OWNE", "SIGNATURE"=>"SIGN", "SEEKFRAME"=>"SEEK",
+      "AUDIOSEEKPOINT"=>"ASPI"
+    }
+  }
+
+
+  # ----------------------------------------------------------------------------
+  # Flags in the ID3-Tag Header:
+  
+  TAG_HEADER_FLAG_MASK = {  # the mask is inverse, for error detection
+    # those flags are supposed to be zero!
+    "2.2.0" =>  0x3F,   # 0xC0 , 
+    "2.3.0" =>  0x1F,   # 0xE0 , 
+    "2.4.0" =>  0x0F    # 0xF0 
+  }
+  
+  TAG_HEADER_FLAGS = {
+    "2.2.0" => { 
+      "Unsynchronisation"      => 0x80 ,
+      "Compression"            => 0x40 ,
+    } ,
+    "2.3.0" => { 
+      "Unsynchronisation"      => 0x80 ,
+      "ExtendedHeader"         => 0x40 ,
+      "Experimental"           => 0x20 ,
+    } ,
+    "2.4.0" => { 
+      "Unsynchronisation"      => 0x80 ,
+      "ExtendedHeader"         => 0x40 ,
+      "Experimental"           => 0x20 ,
+      "Footer"                 => 0x10 , 
+    }
+  }
+
+  # ----------------------------------------------------------------------------
+  # Flags in the ID3-Frame Header:
+  
+  FRAME_HEADER_FLAG_MASK = { # the mask is inverse, for error detection
+    # those flags are supposed to be zero!
+    "2.3.0" =>  0x1F1F,   # 0xD0D0 ,
+    "2.4.0" =>  0x8FB0    # 0x704F ,
+  }
+  
+  FRAME_HEADER_FLAGS = {
+    "2.3.0" => { 
+      "TagAlterPreservation"   => 0x8000 ,
+      "FileAlterPreservation"  => 0x4000 ,
+      "ReadOnly"               => 0x2000 ,
+
+      "Compression"            => 0x0080 ,
+      "Encryption"             => 0x0040 ,
+      "GroupIdentity"          => 0x0020 ,
+    } ,
+    "2.4.0" => { 
+      "TagAlterPreservation"   => 0x4000 , 
+      "FileAlterPreservation"  => 0x2000 ,
+      "ReadOnly"               => 0x1000 ,
+
+      "GroupIdentity"          => 0x0040 ,
+      "Compression"            => 0x0008 ,
+      "Encryption"             => 0x0004 ,
+      "Unsynchronisation"      => 0x0002 ,
+      "DataLengthIndicator"    => 0x0001 ,
+    }
+  }
+
+  # the FrameTypes are not visible to the user - they are just a mechanism 
+  # to define only one parser for multiple FraneNames.. 
+  #
+
+  FRAMETYPE2FRAMENAME = {
+    "TEXT" => %w(TENTGROUP TITLE SUBTITLE ARTIST BAND CONDUCTOR MIXARTIST COMPOSER LYRICIST LANGUAGE CONTENTTYPE ALBUM TRACKNUM PARTINSET ISRC DATE YEAR TIME RECORDINGDATES ORIGYEAR BPM MEDIATYPE FILETYPE COPYRIGHT PUBLISHER ENCODEDBY ENCODERSETTINGS SONGLEN SIZE PLAYLISTDELAY INITIALKEY ORIGALBUM ORIGFILENAME ORIGARTIST ORIGLYRICIST FILEOWNER NETRADIOSTATION NETRADIOOWNER SETSUBTITLE MOOD PRODUCEDNOTICE ALBUMSORTORDER PERFORMERSORTORDER TITLESORTORDER INVOLVEDPEOPLE), 
+    "USERTEXT" => "USERTEXT",
+    
+    "WEB"      => %w(WWWAUDIOFILE WWWARTIST WWWAUDIOSOURCE WWWCOMMERCIALINFO WWWCOPYRIGHT WWWPUBLISHER WWWRADIOPAGE WWWPAYMENT) , 
+    "WWWUSER"  => "WWWUSER",
+    "LTEXT"    => "TERMSOFUSE" ,
+    "PICTURE"  => "PICTURE" , 
+    "UNSYNCEDLYRICS"  => "UNSYNCEDLYRICS" , 
+    "COMMENT"  => "COMMENT" , 
+
+    "PLAYCOUNTER" => "PLAYCOUNTER" , 
+    "POPULARIMETER" => "POPULARIMETER", 
+
+    "BINARY"   => %w( CDID ) , # Cee Dee I Dee
+
+    # For the following Frames there are no parser stings defined .. the user has access to the raw data
+    # The following frames are good examples for completely useless junk which was put into the ID3-definitions.. what were they smoking?
+    #
+    "UNPARSED"  => %w(UNIQUEFILEID OWNERSHIP SYNCEDTEMPO MPEGLOOKUP REVERB SYNCEDLYRICS CONTENTGROUP GENERALOBJECT VOLUMEADJ AUDIOCRYPTO CRYPTEDMETA BUFFERSIZE EVENTTIMING EQUALIZATION LINKED PRIVATE LINKEDINFO POSITIONSYNC GROUPINGREG CRYPTOREG COMMERCIAL SEEKFRAME AUDIOSEEKPOINT SIGNATURE EQUALIZATION2 VOLUMEADJ2 MUSICIANCREDITLIST INVOLVEDPEOPLE2 RECORDINGTIME ORIGRELEASETIME ENCODINGTIME RELEASETIME TAGGINGTIME)
+  }
+
+  VARS    = 0
+  PACKING = 1
+
+  # ----------------------------------------------------------------------------
+  # String Encodings:  See id3v2.4.0-structure document, at section 4.
+  #                    see also: http://en.wikipedia.org/wiki/ID3#ID3v2_Chapters
+  #
+  #   Frames that allow different types of text encoding contains a text
+  #   encoding description byte. Possible encodings:
+  #
+  #     $00   ISO-8859-1 [ISO-8859-1]. Terminated with $00. (ASCII)
+  #     $01   [UCS-2] in ID3v2.2,ID3v2.3  / UTF-16 [UTF-16] encoded Unicode [UNICODE] with BOM All in ID3v2.4
+  #           strings in the same frame SHALL have the same byteorder.
+  #           Terminated with $00 00.
+  #     $02   UTF-16BE [UTF-16] encoded Unicode [UNICODE] without BOM. (ID3v2.4 only)
+  #           Terminated with $00 00.
+  #     $03   UTF-8 [UTF-8] encoded Unicode [UNICODE]. Terminated with $00.  (ID3v2.4 only)
+
+  TEXT_ENCODINGS = ["ISO-8859-1", "UTF-16", "UTF-16BE", "UTF-8"]
+
+  # to get the BYTE-code for the encoding type: TEXT_ENCODINGS.index( string.encoding.to_s ).chr
+  # to read the string :    .force_encoding( Encoding::whatever )
+  # in Ruby 1.9 : Encoding::UTF_8 , Encoding::UTF_16BE, Encoding::ISO_8859_1
+  # BOM: see: http://www.websina.com/bugzero/kb/unicode-bom.html
+  # ----------------------------------------------------------------------------
+
+  #  not sure if it's   Z* or  A*
+  #  A*  does not append a \0 when writing!
+  
+  # STILL NEED TO GET MORE TEST-CASES! e.g. Japanese ID3-Tags! or other encodings..
+  # seems like i have no version 2.4.x ID3-tags!! If you have some, send them my way!
+
+  # NOTE: please note that all the first array entries need to be hashes, in order for Ruby 1.9 to handle this correctly!
+
+  FRAME_PARSER = {
+    "TEXT"      => [ %w(encoding text) , 'CZ*' ] ,
+    "USERTEXT"  => [ %w(encoding description value) , 'CZ*Z*' ] ,
+
+    "PICTURE"   => [ %w(encoding mime_type pict_type description picture) , 'CZ*CZ*a*' ] ,
+
+    "WEB"       => [ %w(url) , 'Z*' ] ,
+    "WWWUSER"   => [ %w(encoding description url) , 'CZ*Z*' ] ,
+
+    "LTEXT"     => [ %w(encoding language text) , 'CZ*Z*' ] ,
+    "UNSYNCEDLYRICS"    => [ %w(encoding language content text) , 'Ca3Z*Z*' ] ,
+    "COMMENT"   => [ %w(encoding language short long) , 'Ca3Z*Z*' ] ,
+
+    "PLAYCOUNTER"  =>  [%w(counter), 'C*'] ,
+    "POPULARIMETER" => [%w(email rating counter), 'Z*CC*'] ,
+
+    "BINARY"    => [ %w(binary) , 'a*' ] ,
+    "UNPARSED"  => [ %w(raw) , 'a*' ]       # how would we do value checking for this?
+  }
+  
+  # ----------------------------------------------------------------------------
+
+  Symbol2framename = ID3::SUPPORTED_SYMBOLS
+  Framename2symbol = Hash.new
+  Framename2symbol["1.0"]   = ID3::SUPPORTED_SYMBOLS["1.0"].invert
+  Framename2symbol["1.1"]   = ID3::SUPPORTED_SYMBOLS["1.1"].invert
+  Framename2symbol["2.2.0"] = ID3::SUPPORTED_SYMBOLS["2.2.0"].invert
+  Framename2symbol["2.3.0"] = ID3::SUPPORTED_SYMBOLS["2.3.0"].invert
+  Framename2symbol["2.4.0"] = ID3::SUPPORTED_SYMBOLS["2.4.0"].invert
+
+  FrameType2FrameName = ID3::FRAMETYPE2FRAMENAME
+
+  FrameName2FrameType = FrameType2FrameName.invert
+  
+  # ----------------------------------------------------------------------------
+  # the following piece of code is just for debugging, to sanity-check that all
+  # the FrameSymbols map back to a FrameType -- otherwise the library code will
+  # break if we encounter a Frame which can't be mapped to a FrameType..
+  # ----------------------------------------------------------------------------
+  #
+  # ensure we have a FrameType defined for each FrameName, otherwise
+  # code might break later..
+  #
+
+  #    print "\nMISSING SYMBOLS:\n"
+  
+  (ID3::Framename2symbol["2.2.0"].values +
+   ID3::Framename2symbol["2.3.0"].values +
+   ID3::Framename2symbol["2.4.0"].values).uniq.each { |symbol|
+    #       print "#{symbol} " if ! ID3::FrameName2FrameType[symbol]
+    print "SYMBOL: #{symbol} not defined!\n" if ! ID3::FrameName2FrameType[symbol]
+  }
+  #    print "\n\n"
+  
+end
+