id3 0.4.1 → 0.5.0

data/CHANGES

@@ -1,5 +1,13 @@
 = id3 changes
 
+=== 0.5.0 (2008-08-18)
+
+* Added write support
+* Fixed bug in determining the audioEnd index
+* reverted UTF-16 fix because it broke the writing the tags
+  If you really need UTF-16 encoding, please stick with version 0.4.1 for now (read-only)
+
+
 === 0.4.1 (2008-08-16)
 
 * Included patch provided by Sergey Udaltsov for UTF-8 and UTF-16 encodings, and new parser routines

data/docs/index.html

@@ -120,6 +120,19 @@ without problems.&nbsp;&nbsp; <br>
 <br>
 <table border=1>
 <tr><th>Version</th><th>gem</th><th>tar.gz</th><th>Changes</th></tr>
+<tr>
+  <th>0.5.0</th>
+  <td><A HREF=../../id3-0.5.0.gem>id3-0.5.0.gem</A></td>
+  <td><A HREF=../../id3-0.5.0.tar.gz>id3-0.5.0.tar.gz</A></td>
+  <td>
+    <UL>
+     <LI>Added write support
+     <LI> Fixed bug in determining the audioEnd index
+     <LI> reverted UTF-16 fix because it broke the writing the tags
+          If you really need UTF-16 encoding, please stick with version 0.4.1 for now (read-only)
+    </UL>
+  </td>
+</tr>
 <tr>
   <th>0.4.1</th>
   <td><A HREF=../../id3-0.4.1.gem>id3-0.4.1.gem</A></td>

data/lib/id3.rb

@@ -2,16 +2,10 @@
 # id3.rb  Ruby Module for handling the following ID3-tag versions:
 #         ID3v1.0 , ID3v1.1,  ID3v2.2.0, ID3v2.3.0, ID3v2.4.0
 # 
-# Copyright (C) 2002..2008 by Tilo Sloboda <tilo@unixgods.org> 
+# Copyright (C) 2002 .. 2008 by Tilo Sloboda <tilo@unixgods.org> 
 #
 # created:      12 Oct 2002
-# updated:      Time-stamp: <Sat 16-Aug-2008 11:20:33 Tilo Sloboda>
-#
-# Version:      0.4.1
-#
-# Changes:
-#         0.4.1   thanks to Sergey Udaltsov for the UTF-8 UTF-16 patch
-#                 and parser routines!
+# updated:      Time-stamp: <Mon 18-Aug-2008 06:16:19 Tilo Sloboda>
 #
 # Docs:   http://www.id3.org/id3v2-00.txt
 #         http://www.id3.org/id3v2.3.0.txt
@@ -20,8 +14,8 @@
 #         http://www.id3.org/id3v2.4.0-frames.txt
 #  
 #         different versions of ID3 tags, support different fields.
-#         See: http://www.unixgods.org/~tilo/ID3v2_frames_comparison.txt
-#         See: http://www.unixgods.org/~tilo/ID3/docs/ID3_comparison.html
+#         See: http://www.unixgods.org/~tilo/Ruby/ID3/docs/ID3v2_frames_comparison.txt
+#         See: http://www.unixgods.org/~tilo/Ruby/ID3/docs/ID3_comparison.html
 #
 # License:     
 #         Freely available under the terms of the OpenSource "Artistic License"
@@ -42,6 +36,7 @@
 #         TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF THE COPYRIGHT HOLDERS OR OTHER PARTY HAS BEEN
 #         ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
 #
+#
 # Author's Rant:
 #         The author of this ID3-library for Ruby is not responsible in any way for 
 #         the definition of the ID3-standards..
@@ -71,7 +66,7 @@
 #       removeID3v1tag(filename)
 #
 #    Classes:
-#       File
+#       AudioFile
 #       Tag1
 #       Tag2
 #       Frame
@@ -79,13 +74,17 @@
 ################################################################################
 
 # ==============================================================================
-# Lading other stuff..
+# Loading other stuff..
 # ==============================================================================
 
-require "md5"
-require "iconv"
+require 'md5'
+require 'tempfile'
+require 'ftools'
+
+# my extensions:
 
 require 'hexdump'                  # load hexdump method to extend class String
+
 require 'invert_hash'              # new invert method for old Hash
 
 
@@ -97,6 +96,7 @@ class Hash                         # overwrite Hash.invert method
     end
 end
 
+# ==============================================================================
 
 module ID3
 
@@ -283,112 +283,28 @@ module ID3
     VARS    = 0
     PACKING = 1
 
-    BE16BOM = "\xFE\xFF"
-    LE16BOM = "\xFF\xFE"
-
-    def ID3.parse_string_rest(encoding, string)
-      case encoding 
-      when 0
-        # ISO8859-1
-        return Iconv.iconv("ISO8859-1", "UTF-8", string);
-      when 1
-        # utf-16
-        bom = string[0..1]
-        data = string[2..string.length-1]
-        srcenc = bom == LE16BOM ? "UTF-16LE" : bom == BE16BOM ? "UTF-16BE" : "??"
-        return Iconv.iconv("UTF-8", srcenc, data);
-      when 2
-        # utf-16BE
-        return
-          Iconv.iconv("UTF-16BE", "UTF-8", data);
-      when 3 
-        return string
-      else
-        raise 'Unknown encoding #{encoding}'
-      end
-    end
-
-    def ID3.parse_string_zeroend(encoding, string)
-      strend = encoding == 0 || encoding == 3 ? "\x00" : "\x00\x00";
-
-      endidx = string.index(strend)
-      if endidx.nil?
-        return parse_string_rest(encoding, string), string.length;
-      elsif endidx == 0
-        return "", strend.length;
-      else
-        return parse_string_rest(encoding, string[0..endidx-1]), endidx + strend.length;
-      end
-    end
-    
-    def ID3.parse_a(data)
-      return [data]
-    end
-
-    def ID3.parse_Z(data)
-      rest = parse_string_rest(data)
-      return first, rest
-    end
-    
-    def ID3.parse_CZ(data)
-      encoding = data[0]
-      rest = parse_string_rest(encoding, data[1..data.length-1])
-      return encoding, rest
-    end
-
-    def ID3.parse_CZZ(data)
-      encoding = data[0]
-      second,length = parse_string_zeroend(encoding, data[1..data.length-1])
-      rest = parse_string_rest(encoding, data[1 + length..data.length-1])
-      return encoding, second, rest
-    end
-
-    def ID3.parse_CZCZa(data)
-      encoding = data[0]
-      second,length = parse_string_zeroend(encoding, data[1..data.length-1])
-      third = data[length + 1]
-      fourth,nexpart2 = parse_string_zeroend(encoding, data[2 + length..data.length-1])
-      rest = data[2 + length + length2..data.length-1]
-      return encoding, second, third, fourth, rest
-    end
-
-    def ID3.parse_Ca3ZZ(data)
-      encoding = data[0]
-      second = data[1..3]
-      third,length = parse_string_zeroend(encoding,data[4..data.length-1])
-      rest = parse_string_rest(encoding, data[4 + length..data.length-1])
-      return encoding, second, third, rest
-    end
-    
-    PARSER_CZ = lambda { |data| parse_CZ(data) }
-    PARSER_CZZ = lambda { |data| parse_CZZ(data) }
-    PARSER_Z = lambda { |data| parse_Z(data) }
-    PARSER_a = lambda { |data| parse_a(data) }
-    PARSER_CZCZa = lambda { |data| parse_CZCZa(data) }
-    PARSER_Ca3ZZ = lambda { |data| parse_Ca3ZZ(data) }
-
                                 #  not sure if it's   Z* or  A*
                                 #  A*  does not append a \0 when writing!
                                 
-    # STILL NEED TO CAREFULLY VERIFY THESE AGAINST THE STANDARDS AND GET TEST-CASES!
+    # 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!
 
     FRAME_PARSER = {
-      "TEXT"      => [ %w(encoding text) , PARSER_CZ ] ,
-      "USERTEXT"  => [ %w(encoding description value) , PARSER_CZZ ] ,
+      "TEXT"      => [ %w(encoding text) , 'CZ*' ] ,
+      "USERTEXT"  => [ %w(encoding description value) , 'CZ*Z*' ] ,
 
-      "PICTURE"   => [ %w(encoding mimeType pictType description picture) , PARSER_CZCZa ] ,
+      "PICTURE"   => [ %w(encoding mimeType pictType description picture) , 'CZ*CZ*a*' ] ,
 
-      "WEB"       => [ "url" , PARSER_Z ] ,
-      "WWWUSER"   => [ %w(encoding description url) , PARSER_CZZ ] ,
+      "WEB"       => [ "url" , 'Z*' ] ,
+      "WWWUSER"   => [ %w(encoding description url) , 'CZ*Z*' ] ,
 
-      "LTEXT"     => [ %w(encoding language text) , PARSER_CZZ ] ,
-      "UNSYNCEDLYRICS"    => [ %w(encoding language content text) , PARSER_Ca3ZZ ] ,
-      "COMMENT"   => [ %w(encoding language short long) , PARSER_Ca3ZZ ] ,
-      "BINARY"    => [ "binary" , PARSER_a ] ,
-      "UNPARSED"  => [ "raw" , PARSER_a ]       # how would we do value checking for this?
+      "LTEXT"     => [ %w(encoding language text) , 'CZ*Z*' ] ,
+      "UNSYNCEDLYRICS"    => [ %w(encoding language content text) , 'Ca3Z*Z*' ] ,
+      "COMMENT"   => [ %w(encoding language short long) , 'Ca3Z*Z*' ] ,
+      "BINARY"    => [ "binary" , 'a*' ] ,
+      "UNPARSED"  => [ "raw" , 'a*' ]       # how would we do value checking for this?
     }
-
+    
     # ----------------------------------------------------------------------------
     # MODULE VARIABLES
     # ----------------------------------------------------------------------------
@@ -428,9 +344,8 @@ module ID3
     # MODULE FUNCTIONS:
     # ----------------------------------------------------------------------------
     # The ID3 module functions are to query or modify files directly.
-    # They give direct acess to files, and don't parse the tags, despite their headers
-    #
-    #
+    # They check directly if a file has a ID3-tag, but they don't parse the tags!
+
     
     # ----------------------------------------------------------------------------
     # hasID3v1tag? 
@@ -504,7 +419,8 @@ module ID3
       stat = File.stat(filename)
       if stat.file? && stat.writable? && ID3.hasID3v1tag?(filename)
          
-         # CAREFUL: this does not check if there really is a valid tag:
+         # 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) }
@@ -525,8 +441,8 @@ module ID3
     #    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 perhaps modified tags
-    #    To query the file itself, use the module functions
+    #    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
 
     class AudioFile
 
@@ -537,12 +453,11 @@ module ID3
       attr_reader :dirname,      :basename      # absolute dirname and basename of the file (computed)
 
       attr_accessor :tagID3v1, :tagID3v2
-      attr_reader   :hasID3tag                  # either false, or a string with all version numbers found
 
       # ----------------------------------------------------------------------------
       # initialize
       #
-      #   AudioFile.new   does NOT open the file, but scans it and parses the info
+      #   AudioFile.new   does NOT keep the file open, but scans it and parses the info
 
       #   e.g.:  ID3::AudioFile.new('mp3/a.mp3')
 
@@ -556,7 +471,7 @@ module ID3
           @tagID3v2     = nil
           
           audioStartX   = 0
-          audioEndX     = File.size(filename)
+          audioEndX     = File.size(filename) - 1  # points to the last index
 
           if ID3.hasID3v1tag?(@filename)
               @tagID3v1 = Tag1.new
@@ -572,15 +487,102 @@ module ID3
           end
           
           # audioStartX audioEndX indices into the file need to be set
-          @audioStartX = audioStartX 
-          @audioEndX   = audioEndX
+          @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
       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:
+          
+          File.open( @filename ) { |f|
+             f.seek(@audioStartX)
+             tf.write( f.read(@audioEndX - @audioStartX +1) )
+          }
+          
+          # 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'
+          File.move(filename, bakname) if backups && FileTest.exists?(filename) && ! FileTest.exists?(bakname)
+
+          File.move(tmpname, filename)
+          tf.close(true)
+          
+          # write md5sum file:
+          
+          writeMD5sum if @audioMD5sum
+
+      end
+      
+      # ----------------------------------------------------------------------------
+      # writeAudio
+      #     only for debugging, does not write any ID3-tags, but just the audio portion
+      
+      def writeAudio
+         tf = Tempfile.new( @basename )
+         
+         File.open( @filename ) { |f|
+            f.seek(@audioStartX)
+            tf.write( f.read(@audioEndX - @audioStartX + 1) )
+         }
+         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.
+      
       # ----------------------------------------------------------------------------
       # audioMD5sum
       #     if the user tries to access @audioMD5sum, it will be computed for him, 
@@ -647,6 +649,11 @@ module ID3
          
       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 version
          a = Array.new
          a.push(@tagID3v1.version) if @tagID3v1
@@ -664,6 +671,8 @@ module ID3
     
     # ==============================================================================
     # Class RestrictedOrderedHash
+    #    this is a helper Class for ID3::Frame
+    #
     
     class RestrictedOrderedHash < Hash
 
@@ -740,15 +749,20 @@ module ID3
     # ==============================================================================
     # Class GenericTag
     #
-    # as per ID3-definition, the frames are in no fixed order! that's why Hash is OK
+    # Helper class for Tag1 and Tag2
+    #
+    # Checks that user uses a valid key, and adds methods for size computation
+    #
+    # as per ID3-definition, the frames are in no fixed order! that's why we can derive
+    # this class from Hash.  But in the future we may want to write certain frames first 
+    # into the ID3-tag and therefore may want to derive it from RestrictedOrderedHash
 
-    class GenericTag < Hash        ###### should this be RestrictedOrderedHash as well? 
+    class GenericTag < Hash
        attr_reader :version, :raw
 
        # these definitions are to prevent users from inventing their own field names..
        # but on the other hand, they should be able to create a new valid field, if
        # it's not yet in the current tag, but it's valid for that ID3-version...
-       # ... so hiding this, is not enough!
        
        alias old_set []=
        private :old_set
@@ -810,12 +824,6 @@ module ID3
        # ----------------------------------------------------------------------
        # read     reads a version 1.x ID3tag
        #
-       #     30 title
-       #     30 artist
-       #     30 album
-       #      4 year
-       #     30 comment
-       #      1 genre
 
        def read(filename)
          f = File.open(filename, 'r')
@@ -825,7 +833,7 @@ module ID3
            f.seek(-ID3::ID3v1tagSize, IO::SEEK_END)
            @raw = f.read(ID3::ID3v1tagSize)
 
-#           self.parse!(raw)    # we should use "parse!" instead of re-coding everything..
+#           self.parse!(raw)    # we should use "parse!" instead of duplicating code!
 
            if (raw[ID3v1versionbyte] == 0) 
               @version = "1.1"
@@ -860,6 +868,7 @@ module ID3
        #
        # 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
@@ -896,7 +905,7 @@ module ID3
        #
        # 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 often useless..
+       # are often truncated and hence ID3 v1 tags are often useless..
        
        def dump
          zeroes = "\0" * 32
@@ -1000,14 +1009,28 @@ module ID3
       # writes and replaces existing ID3-v2-tag if one is present
       # Careful, this does NOT merge or append, it overwrites!
       
-      def write(filename)
+      # 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
+#      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
       #
@@ -1055,7 +1078,7 @@ module ID3
             framename = header[0..3]
             size = (header[4]*256**3)+(header[5]*256**2)+(header[6]*256)+header[7]
             flags= header[8..9]
-#            printf "frame (at %x, frameheader %d): %s , size: %d, flags: %x %x\n", x, frameHeaderSize, framename , size, flags[0], flags[1]
+#            printf "frame: %s , size: %d, flags: %s\n", framename , size, flags
 
          else
             # we can't parse higher versions
@@ -1074,6 +1097,12 @@ module ID3
       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
@@ -1083,7 +1112,8 @@ module ID3
         self.each { |framename,framedata|
            data << framedata.dump
         }
-        # add some padding perhaps
+        # add some padding perhaps 32 bytes (should be defined by the user!)
+        # NOTE:    I noticed that iTunes adds excessive amounts of padding
         data << "\0" * 32
         
         # calculate the complete length of the data-section 
@@ -1107,37 +1137,6 @@ module ID3
     #      dumps  ID3v2 frames into a binary array
     #      allows to modify frame's contents if the frame was decoded..
     #
-    # NOTE:   right now the class Frame is derived from Hash, which is wrong..
-    #         It should really be derived from something like RestrictedOrderedHash
-    #         ... a new class, which preserves the order of keys, and which does 
-    #         strict checking that all keys are present and reference correct values!
-    #         e.g.   frames["COMMENT"]
-    #         ==>  {"encoding"=>Byte, "language"=>Chars3, "text1"=>String, "text2"=>String}
-    #
-    #         e.g.  user should be able to create a new frame , like: 
-    #              tag2.frames["COMMENT"] = "right side"
-    #
-    #         and the following checks should be done:
-    #
-    #            1) if "COMMENT" is a correct key for tag2
-    #            2) if the "right side" contains the correct keys
-    #            3) if the "right side" contains the correct value for each key
-    #
-    #         In the simplest case, the "right side" might be just a string, 
-    #         but for most FrameTypes, it's a complex datastructure.. and we need
-    #         to check it for correctness before doing the assignment..
-    #
-    # NOTE2:  the class Tag2 should have hash-like accessor functions to let the user
-    #         easily access frames and their contents..
-    #
-    #         e.g.  tag2[framename] would really access tag2.frames[framename]
-    #
-    #         and if that works, we can make tag2.frames private and hidden!
-    #
-    #         This means, that when we generate the parse and dump routines dynamically, 
-    #         we may want to create the corresponding accessor methods for Tag2 class 
-    #         as well...? or are generic ones enough?
-    #
 
     class Frame < RestrictedOrderedHash
 
@@ -1181,11 +1180,7 @@ module ID3
                    end
                 EOB
                 
-                @rawflags = flags[0].to_i << 8 | flags[1]  # preserve the raw flags (for debugging only)
-
-                if (@rawflags & (FRAME_HEADER_FLAGS["2.4.0"]["Unsynchronisation"])) != 0
-                   @rawdata = @rawdata.gsub("\xFF\x00","\xFF")
-                end
+                @rawflags = flags.to_i   # preserve the raw flags (for debugging only)
 
                 if (flags.to_i & FRAME_HEADER_FLAG_MASK[@version] != 0)
                    # in this case we need to skip parsing the frame... and skip to the next one...
@@ -1223,7 +1218,7 @@ module ID3
                        vars2 = vars
                     end
 
-                    values = packing.call(self.rawdata)
+                    values = self.rawdata.unpack(packing)
                     vars.each { |key|
                        self[key] = values.shift
                     }

metadata

@@ -3,9 +3,9 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: id3
 version: !ruby/object:Gem::Version 
-  version: 0.4.1
-date: 2008-08-16 00:00:00 -07:00
-summary: id3-0.4.1 - ID3 tag library for Ruby http://www.unixgods.org/~tilo/Ruby/ID3
+  version: 0.5.0
+date: 2008-08-24 00:00:00 -07:00
+summary: A native ID3 tag library for Ruby, which does not depend on architecture-dependent C-libraries. It supports reading and writing ID3-tag versions 1.0, 1.1, and 2.2.x, 2,3.x, 2,4.x\n http://www.unixgods.org/~tilo/Ruby/ID3
 require_paths: 
 - lib
 email: tools@unixgods.org