id3 0.5.0 → 1.0.0.pre4

data/lib/id3/module_methods.rb

@@ -0,0 +1,127 @@
+# ----------------------------------------------------------------------------
+# Module ID3 - MODULE METHODS
+# ----------------------------------------------------------------------------
+module ID3
+
+  # The ID3 module methods are to query or modify files directly by filename.
+  # They check directly if a file has a ID3-tag, but they don't parse the tags!
+  
+  # ----------------------------------------------------------------------------
+  # id3_versions
+  
+  def ID3.id3_versions
+    [ hasID3v1tag?(filename) ,hasID3v2tag?(filename) ].compact    # returns Array of ID3 tag versions found
+  end
+  
+  # ----------------------------------------------------------------------------
+  # hasID3v1tag? 
+  #              returns string with version 1.0 or 1.1 if tag was found 
+  #              returns false  otherwise
+
+  def ID3.hasID3v1tag?(filename)
+    hasID3v1tag     = false
+    
+    # be careful with empty or corrupt files..
+    return false if File.size(filename) < ID3v1tagSize
+    
+    f = File.open(filename, 'rb:binary')
+    f.seek(-ID3v1tagSize, IO::SEEK_END)
+    if (f.read(3) == "TAG")
+      f.seek(-ID3v1tagSize + ID3v1versionbyte, IO::SEEK_END)
+      c = f.get_byte                         # this is character 125 of the tag
+      if (c == 0) 
+        hasID3v1tag = "1.0"
+      else
+        hasID3v1tag = "1.1"
+      end
+    end
+    f.close
+    return hasID3v1tag
+  end
+  
+  # ----------------------------------------------------------------------------
+  # hasID3v2tag? 
+  #              returns string with version 2.2.0, 2.3.0 or 2.4.0 if tag found
+  #              returns false  otherwise
+  
+  def ID3.hasID3v2tag?(filename)
+    hasID3v2tag     = false
+    
+    f = File.open(filename, 'rb:binary')
+    if (f.read(3) == "ID3")
+      major = f.get_byte
+      minor = f.get_byte
+      version   = "2." + major.to_s + '.' + minor.to_s
+      hasID3v2tag = version
+    end
+    f.close
+    return hasID3v2tag
+  end
+  
+  # ----------------------------------------------------------------------------
+  # hasID3tag? 
+  #              returns string with all versions found, space separated
+  #              returns false  otherwise
+
+  def ID3.hasID3tag?(filename)
+    v1 = ID3.hasID3v1tag?(filename)
+    v2 = ID3.hasID3v2tag?(filename)
+    
+    return false if !v1 && !v2 
+    return v1    if !v2
+    return v2    if !v1
+    return "#{v1} #{v2}"
+  end
+
+  # ----------------------------------------------------------------------------
+  # removeID3v1tag
+  #            returns  nil  if no v1 tag was found, or it couldn't be removed
+  #            returns  true if v1 tag found and it was removed..
+  #
+  # in the future:
+  #            returns  ID3.Tag1  object if a v1 tag was found and removed
+
+  def ID3.removeID3v1tag(filename)
+    stat = File.stat(filename)
+    if stat.file? && stat.writable? && ID3.hasID3v1tag?(filename)
+      
+      # CAREFUL: this does not check if there really is a valid tag,
+      #          that's why we need to check above!!
+      
+      newsize = stat.size - ID3v1tagSize
+      File.open(filename, "r+") { |f| f.truncate(newsize) }
+      
+      return true
+    else
+      return nil
+    end
+  end
+
+  # ----------------------------------------------------------------------
+  # convert the 4 bytes found in the id3v2 header and return the size
+  def ID3.unmungeSize(bytes)
+    size = 0
+    j = 0; i = 3 
+    while i >= 0
+      size += 128**i * (bytes.getbyte(j) & 0x7f)
+      j += 1
+      i -= 1
+    end
+    return size
+  end
+  # ----------------------------------------------------------------------
+  # convert the size into 4 bytes to be written into an id3v2 header
+  def ID3.mungeSize(size)
+    bytes = Array.new(4,0)
+    j = 0;  i = 3
+    while i >= 0
+      bytes[j],size = size.divmod(128**i)
+      j += 1
+      i -= 1
+    end
+    return bytes
+  end
+
+end
+# ----------------------------------------------------------------------------
+

data/lib/id3/string_extensions.rb

@@ -0,0 +1,40 @@
+#
+# EXTENSIONS to Class String
+#
+# if you have a (partial) MP3-file stored in a String.. you can check if it contains ID3 tags
+
+class String
+  # str = File.open(filename, 'rb:binary').read; 1
+  # str.hasID3v2tag?
+  # str.hasID3v1tag?
+  
+  def id3_versions
+    [ hasID3v1tag? ,hasID3v2tag? ].compact   # returns an Array of version numbers
+  end
+
+  def hasID3tag?
+    hasID3v2tag? || hasID3v1tag? ? true : false     # returns true or false
+  end
+  
+  def hasID3v2tag?  # returns either nil or the version number -- this can be used in a boolean comparison
+    return nil if self !~ /^ID3/
+    major = self.getbyte(ID3::ID3v2major)
+    minor = self.getbyte(ID3::ID3v2minor)
+    version   = "2." + major.to_s + '.' + minor.to_s
+  end
+  
+  # we also need a method to return the size of the ID3v2 tag , 
+  # e.g. needed when we need to determine the buffersize to read the tag from a file or from a remote location
+  def ID3v2_tag_size
+    return 0 if self !~ /^ID3/
+    return ID3::ID3v2headerSize + ID3.unmungeSize( self[ID3::ID3v2tagSize..ID3::ID3v2tagSize+4] )
+  end
+
+  def hasID3v1tag?  # returns either nil or the version number -- this can be used in a boolean comparison
+    return nil if size < ID3::ID3v1tagSize  # if the String is too small to contain a tag
+    size = self.bytesize
+    tag = self[size-128,size] # get the last 128 bytes
+    return nil if tag !~/^TAG/
+    return tag[ID3::ID3v1versionbyte] == ZEROBYTE ? "1.0" : "1.1"   # return version number otherwise
+  end
+end

data/lib/id3/tag1.rb

@@ -0,0 +1,131 @@
+module ID3
+
+  # ==============================================================================
+  # Class Tag1    ID3 Version 1.x Tag
+  #
+  #      parses ID3v1 tags from a binary array
+  #      dumps  ID3v1 tags into a binary array
+  #      allows to modify tag's contents
+
+  class Tag1 < GenericTag
+
+    def initialize
+      super
+      @version = '1.1'
+    end
+
+    # ----------------------------------------------------------------------
+    # read     reads a version 1.x ID3tag
+    #
+
+    def read(filename)
+      f = File.open(filename, 'r')
+      f.seek(-ID3::ID3v1tagSize, IO::SEEK_END)
+      hastag = (f.read(3) == 'TAG')
+      if hastag
+        f.seek(-ID3::ID3v1tagSize, IO::SEEK_END)
+        @raw = f.read(ID3::ID3v1tagSize)
+
+        #           self.parse!(raw)    # we should use "parse!" instead of duplicating code!
+
+        if (raw.getbyte(ID3v1versionbyte) == 0) 
+          @version = "1.0"
+        else
+          @version = "1.1"
+        end
+      else
+        @raw = @version = nil
+      end
+      f.close
+      #
+      # now parse all the fields
+
+      ID3::SUPPORTED_SYMBOLS[@version].each{ |key,val|
+        if val.class == Range
+          #               self[key] = @raw[val].squeeze(" \000").chomp(" ").chomp("\000")
+          self[key] = @raw[val].strip
+        elsif val.class == Fixnum
+          self[key] = @raw.getbyte(val).to_s
+        else 
+          # this can't happen the way we defined the hash..
+          #              printf "unknown key/val : #{key} / #{val}  ; val-type: %s\n", val.type
+        end
+      }
+      hastag
+    end
+    # ----------------------------------------------------------------------
+    # write    writes a version 1.x ID3tag
+    #
+    # not implemented yet..
+    #
+    # need to loacte old tag, and remove it, then append new tag..
+    #
+    # always upgrade version 1.0 to 1.1 when writing
+    
+    # not yet implemented, because AudioFile.write does the job better
+    
+    # ----------------------------------------------------------------------
+    # this routine modifies self, e.g. the Tag1 object
+    #
+    # tag.parse!(raw)   returns boolean value, showing if parsing was successful
+    
+    def parse!(raw)
+
+      return false    if raw.size != ID3::ID3v1tagSize
+
+      if (raw[ID3v1versionbyte] == 0) 
+        @version = "1.0"
+      else
+        @version = "1.1"
+      end
+
+      self.clear    # remove all entries from Hash, we don't want left-overs..
+
+      ID3::SUPPORTED_SYMBOLS[@version].each{ |key,val|
+        if val.class == Range
+          #               self[key] = raw[val].squeeze(" \000").chomp(" ").chomp("\000")
+          self[key] = raw[val].strip
+        elsif val.class == Fixnum
+          self[key] = raw[val].to_s
+        else 
+          # this can't happen the way we defined the hash..
+          #              printf "unknown key/val : #{key} / #{val}  ; val-type: %s\n", val.class
+        end       
+      }
+      @raw = raw
+      return true
+    end
+    # ----------------------------------------------------------------------
+    # dump version 1.1 ID3 Tag into a binary array
+    #
+    # although we provide this method, it's stongly discouraged to use it, 
+    # because ID3 version 1.x tags are inferior to version 2.x tags, as entries
+    # are often truncated and hence ID3 v1 tags are often useless..
+    
+    def dump
+      zeroes = ZEROBYTE * 32
+      raw = ZEROBYTE * ID3::ID3v1tagSize
+      raw[0..2] = 'TAG'
+
+      self.each{ |key,value|
+
+        range = ID3::Symbol2framename['1.1'][key]
+
+        if range.class == Range 
+          length = range.last - range.first + 1
+          paddedstring = value + zeroes
+          raw[range] = paddedstring[0..length-1]
+        elsif range.class == Fixnum
+          raw[range] = value.to_i.chr      # supposedly assigning a binary integer value to the location in the string
+        else
+          # this can't happen the way we defined the hash..
+          next
+        end
+      }
+
+      return raw
+    end
+    # ----------------------------------------------------------------------
+  end  # of class Tag1
+  
+end

data/lib/id3/tag2.rb

@@ -0,0 +1,261 @@
+module ID3
+
+  # ==============================================================================
+  # Class Tag2    ID3 Version 2.x.y Tag
+  #
+  #      parses ID3v2 tags from a binary array
+  #      dumps  ID3v2 tags into a binary array
+  #      allows to modify tag's contents
+  #
+  #      as per definition, the frames are in no fixed order
+  
+  class Tag2 < GenericTag
+    attr_reader :rawflags, :flags
+
+    def initialize
+      super
+      @rawflags = 0
+      @flags    = {}
+      @version  = '2.3.0'   # default version
+    end
+
+    # this is obviously half-baked.. does not really work!  We need SubClasses of ID3::Frame with specific handling
+    #
+    def []=(framename,val)
+      # if this is a valid frame of known type, we return it's total length and a struct
+      #
+      if ID3::SUPPORTED_SYMBOLS[@version].has_value?(framename)
+        frame = ID3::Frame.new( framename, @version)
+        self[ framename ] = frame
+        frame['text'] = val  if frame.has_key?('text')
+        return frame
+      else
+        return nil
+      end
+    end
+
+    def read_from_buffer(string)
+      has_tag = string =~ /^ID3/
+      if has_tag
+        major = string.getbyte(ID3::ID3v2major)
+        minor = string.getbyte(ID3::ID3v2minor)
+        @version  = "2." + major.to_s + '.' + minor.to_s
+        @rawflags = string.getbyte(ID3::ID3v2flags)
+        size =  ID3::ID3v2headerSize + ID3.unmungeSize( string[ID3::ID3v2tagSize..ID3::ID3v2tagSize+4] )
+        return false if string.size < size
+        @raw = string[0...size]
+        # parse the raw flags:
+        if (@rawflags & ID3::TAG_HEADER_FLAG_MASK[@version] != 0)
+          # in this case we need to skip parsing the frame... and skip to the next one...
+          wrong = @rawflags & ID3::TAG_HEADER_FLAG_MASK[@version]
+          error = printf "ID3 version %s header flags 0x%X contain invalid flags 0x%X !\n", @version, @rawflags, wrong
+          raise ArgumentError, error
+        end
+        
+        @flags = Hash.new
+        
+        ID3::TAG_HEADER_FLAGS[@version].each{ |key,val|
+          # only define the flags which are set..
+          @flags[key] = true   if  (@rawflags & val == 1)
+        }
+      else
+        @raw = nil
+        @version = nil
+        return false
+      end
+      #
+      # now parse all the frames
+      #
+      i = ID3::ID3v2headerSize; # we start parsing right after the ID3v2 header
+      
+      while (i < @raw.size) && (@raw.getbyte(i) != 0)
+        len,frame = parse_frame_header(i)   # this will create the correct frame
+        if len != 0
+          i += len
+        else
+          break
+        end
+      end
+      
+      has_tag
+    end
+
+    def read_from_file(filename)
+      f = File.open(filename, 'rb:BINARY')
+      has_tag = (f.read(3) == "ID3")
+      if has_tag
+        major = f.get_byte
+        minor = f.get_byte
+        @version = "2." + major.to_s + '.' + minor.to_s
+        @rawflags = f.get_byte
+        size = ID3::ID3v2headerSize + unmungeSize(f.read(4))  # was read_bytes, which was a BUG!!
+        f.seek(0)
+        @raw = f.read(size) 
+        
+        # parse the raw flags:
+        if (@rawflags & ID3::TAG_HEADER_FLAG_MASK[@version] != 0)
+          # in this case we need to skip parsing the frame... and skip to the next one...
+          wrong = @rawflags & ID3::TAG_HEADER_FLAG_MASK[@version]
+          error = printf "ID3 version %s header flags 0x%X contain invalid flags 0x%X !\n", @version, @rawflags, wrong
+          raise ArgumentError, error
+        end
+        
+        @flags = Hash.new
+        
+        ID3::TAG_HEADER_FLAGS[@version].each{ |key,val|
+          # only define the flags which are set..
+          @flags[key] = true   if  (@rawflags & val == 1)
+        }
+      else
+        @raw = nil
+        @version = nil
+        return false
+      end
+      f.close
+      #
+      # now parse all the frames
+      #
+      i = ID3::ID3v2headerSize; # we start parsing right after the ID3v2 header
+      
+      while (i < @raw.size) && (@raw.getbyte(i) != 0)
+        len,frame = parse_frame_header(i)   # this will create the correct frame
+        if len != 0
+          i += len
+        else
+          break
+        end
+      end
+      has_tag
+    end
+    alias read read_from_file
+    
+    # ----------------------------------------------------------------------
+    # write
+    #
+    # writes and replaces existing ID3-v2-tag if one is present
+    # Careful, this does NOT merge or append, it overwrites!
+    
+    # not yet implemented, because AudioFile.write does the job better
+    
+    #      def write(filename)
+    # check how long the old ID3-v2 tag is
+    
+    # dump ID3-v2-tag
+    
+    # append old audio to new tag
+    
+    #      end
+    
+    # ----------------------------------------------------------------------------
+    # writeID3v2
+    #    just writes the ID3v2 tag by itself into a file, no audio data is written
+    #
+    #    for backing up ID3v2 tags and debugging only..
+    #
+    
+    #      def writeID3v2
+    
+    #      end
+    
+    # ----------------------------------------------------------------------
+    # parse_frame_header
+    #
+    # each frame consists of a header of fixed length; 
+    # depending on the ID3version, either 6 or 10 bytes.
+    # and of a data portion which is of variable length,
+    # and which contents might not be parsable by us
+    #
+    # INPUT:   index to where in the @raw data the frame starts
+    # RETURNS: if successful parse: 
+    #             total size in bytes, ID3frame struct
+    #          else:
+    #             0, nil
+    #
+    #
+    #          Struct of type ID3frame which contains:
+    #                the name, size (in bytes), headerX, 
+    #                dataStartX, dataEndX, flags
+    #          the data indices point into the @raw data, so we can cut out
+    #          and parse the data at a later point in time.
+    # 
+    #          total frame size = dataEndX - headerX
+    #          total header size= dataStartX - headerX
+    #          total data size  = dataEndX - dataStartX
+    #
+    private
+    def parse_frame_header(x)
+      framename = ""; flags = nil
+      size = 0
+      
+      if @version =~ /^2\.2\./
+        frameHeaderSize = 6                     # 2.2.x Header Size is 6 bytes
+        header = @raw[x..x+frameHeaderSize-1]
+
+        framename = header[0..2]
+        size = (header.getbyte(3)*256**2)+(header.getbyte(4)*256)+header.getbyte(5)
+        flags = nil
+        #            printf "frame: %s , size: %d\n", framename , size
+
+      elsif @version =~ /^2\.[34]\./
+        # for version 2.3.0 and 2.4.0 the header is 10 bytes long
+        frameHeaderSize = 10
+        header = @raw[x..x+frameHeaderSize-1]
+
+        #           puts @raw.inspect
+
+        framename = header[0..3]
+        size = (header.getbyte(4)*256**3)+(header.getbyte(5)*256**2)+(header.getbyte(6)*256)+header.getbyte(7)
+        flags= header[8..9]
+        #            printf "frame: %s , size: %d, flags: %s\n", framename , size, flags
+
+      else
+        # we can't parse higher versions
+        return 0, false
+      end
+
+      # if this is a valid frame of known type, we return it's total length and a struct
+      # 
+      if ID3::SUPPORTED_SYMBOLS[@version].has_value?(framename)
+        frame = ID3::Frame.new( framename, @version , flags, self,  x, x+frameHeaderSize , x+frameHeaderSize + size - 1 )
+        self[ ID3::Framename2symbol[@version][frame.name] ] = frame
+        return size+frameHeaderSize , frame
+      else
+        return 0, nil
+      end
+    end
+    # ----------------------------------------------------------------------
+    # dump a ID3-v2 tag into a binary array
+    #
+    # NOTE:
+    #      when "dumping" an ID3-v2 tag, I would like to have more control about
+    #      which frames get dumped first.. e.g. the most important frames (with the
+    #      most important information) should be dumped first.. 
+    #
+    
+    public      
+    def dump
+      data = ""
+
+      # dump all the frames
+      self.each { |framename,framedata|
+        data << framedata.dump
+      }
+      # add some padding perhaps 32 bytes (should be defined by the user!)
+      # NOTE:    I noticed that iTunes adds excessive amounts of padding
+      data << ZEROBYTE * 32
+      
+      # calculate the complete length of the data-section 
+      size = mungeSize(data.size)
+      
+      major,minor = @version.sub(/^2\.([0-9])\.([0-9])/, '\1 \2').split
+      
+      # prepend a valid ID3-v2.x header to the data block
+      header = "ID3" << major.to_i << minor.to_i << @rawflags << size[0] << size[1] << size[2] << size[3]
+      
+      header + data
+    end
+    # ----------------------------------------------------------------------
+
+  end  # of class Tag2
+
+end