id3 0.5.0 → 1.0.0.pre4

data/lib/id3/frame.rb

@@ -0,0 +1,178 @@
+module ID3
+  # ==============================================================================
+  # Class Frame   ID3 Version 2.x.y Frame
+  #
+  #      parses ID3v2 frames from a binary array
+  #      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?
+  #
+  #
+  # NOTE3:  
+  #
+  #         The old way to pack / unpack frames to encode / decode them, is working, 
+  #         but has the disadvantage that it's a little bit too close to the metal.
+  #         e.g. encoding and textcontent are both accessible, but ideally only 
+  #         the textvalue should be accessible and settable, and the encoding should 
+  #         automatically be set correctly / accordingly...
+  #
+  # NOTE4:
+  #         for frames like TXXX , WXXX , which can occur multiple times in a ID3v2 frame,
+  #         we should manage those tags as an Array...
+  #
+
+  class Frame < RestrictedOrderedHash
+
+    attr_reader :name, :version
+    attr_reader :headerStartX, :dataStartX, :dataEndX, :rawdata, :rawheader  # debugging only
+
+    # ----------------------------------------------------------------------
+    # return the complete raw frame
+    
+    def raw
+      return @rawheader + @rawdata
+    end    
+    # ----------------------------------------------------------------------
+
+    def initialize(name, version = '2.3.0', flags = 0, tag,  headerStartX, dataStartX, dataEndX )
+      super
+
+      @name = name
+      @headerStartX = headerStartX if headerStartX
+      @dataStartX   = dataStartX   if dataStartX
+      @dataEndX     = dataEndX     if dataEndX
+
+      if tag
+        @rawdata   = tag.raw[dataStartX..dataEndX]
+        @rawheader = tag.raw[headerStartX..dataStartX-1]
+        # parse the darn flags, if there are any..
+        @version = tag.version  # caching..
+      else
+        @rawdata = ''
+        @rawheader= ''
+        @version = version
+      end
+
+      case @version
+      when /2\.2\.[0-9]/
+        # no flags, no extra attributes necessary
+
+      when /2\.[34]\.0/
+        
+        # dynamically create attributes and reader functions for flags in ID3-frames:
+        # (not defined in earlier ID3 versions)
+        instance_eval <<-EOB
+          class << self 
+            attr_reader :rawflags, :flags
+          end
+        EOB
+  
+        @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...
+          wrong = flags.to_i & FRAME_HEADER_FLAG_MASK[@version]
+          error = printf "ID3 version %s frame header flags 0x%X contain invalid flags 0x%X !\n", @version, flags, wrong
+          raise ArgumentError, error
+        end
+  
+        @flags = Hash.new
+        
+        FRAME_HEADER_FLAGS[@version].each do |key,val|
+          # only define the flags which are set..
+          @flags[key] = true   if  (flags.to_i & val == 1)
+        end
+        
+      else
+        raise ArgumentError, "ID3 version #{@version} not recognized when parsing frame header flags\n"
+      end # parsing flags
+                 
+      # generate methods for parsing data (low-level read support) and for dumping data out (low-level write-support)
+      #
+      # based on the particular ID3-version and the ID3-frame name, we basically obtain a string saying how to pack/unpack the data for that frame
+      # then we use that packing-string to define a parser and dump method for this particular frame
+                 
+      instance_eval <<-EOB
+        class << self
+
+          def parse
+            # here we GENERATE the code to parse, dump and verify  methods
+          
+            vars,packing = ID3::FRAME_PARSER[ ID3::FrameName2FrameType[ ID3::Framename2symbol[self.version][self.name]] ]
+
+            values = self.rawdata.unpack(packing)
+
+            vars.each do |key|
+              self[key] = values.shift
+            end
+            self.lock   # lock the OrderedHash
+          end
+          
+
+          def dump
+            vars,packing = ID3::FRAME_PARSER[ ID3::FrameName2FrameType[ ID3::Framename2symbol[self.version][self.name]] ]
+            
+            data = self.values.pack(packing)     # we depend on an OrderedHash, so the values are in the correct order!!!
+            header  = self.name.dup         # we want the value! not the reference!!
+            len     = data.length
+            if self.version =~ /^2\.2\./
+              byte2,rest = len.divmod(256**2)
+              byte1,byte0 = rest.divmod(256)
+              
+              header << byte2 << byte1 << byte0
+            
+            elsif self.version =~ /^2\.[34]\./          # 10-byte header
+              byte3,rest = len.divmod(256**3)
+              byte2,rest = rest.divmod(256**2)
+              byte1,byte0 = rest.divmod(256)            
+              
+              flags1,flags0 = self.rawflags.divmod(256)
+              
+              header << byte3 << byte2 << byte1 << byte0 << flags1 << flags0
+            end
+            header << data
+          end
+          
+        end
+      EOB
+
+      self.parse           # now we're using the just defined parsing routine
+        
+      return self
+    end
+    # ----------------------------------------------------------------------
+            
+  end  # of class Frame
+  # ==============================================================================
+
+end

data/lib/id3/frame_array.rb

@@ -0,0 +1,19 @@
+module ID3
+  # ==============================================================================
+  # Class FrameArray
+  # 
+  # basically nothing more than an Array, but it knows how to dump it's contents as ID3v2 frames
+  #
+  # this solves in part the problem of having multiple ID3v2 frames in one tag, e.g. TXXX , WXXX, APIC
+
+  class FrameArray < Array
+    def dump
+      result = ''
+      self.each do |element|
+        result << element.dump
+      end
+      return result
+    end
+  end
+
+end

data/lib/id3/generic_tag.rb

@@ -0,0 +1,73 @@
+module ID3
+
+  # ==============================================================================
+  # Class GenericTag
+  #
+  # 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
+
+  # BUG (4) : When an ID3frame is assigned a value, e.g. a String, then the Hash just stores the value right now.
+  #           Whereas when you read the ID3v2 tag, the object for the frame is ID3::Frame
+
+  class GenericTag < RestrictedOrderedHash
+    attr_accessor :version
+    attr_reader   :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...
+    
+    alias old_set []=
+      private :old_set
+    
+    # ----------------------------------------------------------------------
+    def []=(key,val)
+      if @version == ""
+        raise ArgumentError, "undefined version of ID3-tag! - set version before accessing components!\n" 
+      else
+        if ID3::SUPPORTED_SYMBOLS[@version].keys.include?(key)
+          old_set(key,val)
+        else 
+          # exception
+          raise ArgumentError, "Incorrect ID3-field \"#{key}\" for ID3 version #{@version}\n" +
+            "               valid ID3-fields are: " + SUPPORTED_SYMBOLS[@version].keys.join(",") +"\n"
+        end
+      end
+    end
+    # ----------------------------------------------------------------------
+    # convert the 4 bytes found in the id3v2 header and return the size
+    private
+    def 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
+    private
+    def 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 # of class GenericTag
+
+end # of module ID3

data/lib/id3/id3.rb

@@ -0,0 +1,159 @@
+################################################################################
+# 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 .. 2011 by Tilo Sloboda <firstname.lastname@google_email>
+#
+# created:      12 Oct 2002
+# updated:      Time-stamp: <Fri, 21 Oct 2011, 11:54:26 PDT  tilo>
+#
+# Docs:   http://www.id3.org/id3v2-00.txt
+#         http://www.id3.org/id3v2.3.0.txt
+#         http://www.id3.org/id3v2.4.0-changes.txt
+#         http://www.id3.org/id3v2.4.0-structure.txt
+#         http://www.id3.org/id3v2.4.0-frames.txt
+#  
+#         different versions of ID3 tags, support different fields.
+#         See: http://www.unixgods.org/~tilo/Ruby/ID3/docs/ID3v2_frames_comparison.txt
+#         See: http://www.unixgods.org/~tilo/Ruby/ID3/docs/ID3_comparison2.html
+#
+# PLEASE HELP:
+#
+#  >>>    Please contact me and email me the extracted ID3v2 tags, if you:
+#  >>>      - if you have tags with exotic character encodings (exotic for me, not for you, obviously ;-) )
+#  >>>      - if you find need support for any ID3v2 tags which are not yet supported by this library
+#  >>>        (e.g. they are currently just parsed 'raw' and you need them fully parsed)
+#  >>>      - if something terribly breaks
+#  >>>   
+#  >>>    You can find a small helper program in the examples folder, which extracts a ID3v2 tag from a file,
+#  >>>    and saves it separately, so you can email it to me without emailing the whole audio file.
+#  >>>
+#  >>>    THANK YOU FOR YOUR HELP!
+#
+# Non-ASCII encoded Strings:
+#
+#   This library's main purpose is to unify access across different ID3-tag versions. So you don't have to worry
+#   about the changing names of the frames in different ID3-versions, and e.g. just access "AUTHOR" symbolically
+#   no matter if it's ID3 v1.0 v2.1.0 or v2.4.0.  Think of this as a low-level library in that sense.
+#
+#   Non-ASCII encodings are currently not really dealt with. For Strings which can be encoded differntly, 
+#   you will see attributes like 'encoding' and 'text', where 'encoding' is a number representing the encoding,
+#   and the other attribute, e.g. 'text' or 'description', is the raw uninterpreted String.
+#
+#   If your code requires to assign values to a ID3v2-frame which are foreign encoded Strings, you will need to make
+#   a small wrapper class on top of ID3::Frame which detects the encoding and properly saves it as a number.
+#   I'd love to add this -- but I don't have enough examples of ID3-tags in foreign languages. See: PLEASE HELP
+#
+# Limitations:
+#
+#   - this library currently does not support the ID3v2.4 feature of having ID3v2 tags at the end of the file
+#     IMHO this doesn't make much sense in the age of streaming, and I haven't found examples for ths in any MP3-files. 
+#     I think this is just one of the many unused "features" in the ID3v2 specifications ;-)
+#
+#   - ID3v2 Chapters are not supported (see: Wikipedia)
+#
+#   - ID3v1 extended tags are currently not supported (see: Wikipedia)
+#
+# License:     
+#         Freely available under the terms of the OpenSource "Artistic License"
+#         in combination with the Addendum A (below)
+# 
+#         In case you did not get a copy of the license along with the software, 
+#         it is also available at:   http://www.unixgods.org/~tilo/artistic-license.html
+#
+# Addendum A:
+#         THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU!
+#         SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+#         REPAIR OR CORRECTION. 
+#
+#         IN NO EVENT WILL THE COPYRIGHT HOLDERS  BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, 
+#         SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY 
+#         TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED 
+#         INACCURATE OR USELESS OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM 
+#         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 awkward definition of the ID3-standards..
+#
+#         You're lucky though that you can use this little library, rather than having 
+#         to parse ID3v2 tags yourself!  Trust me!  At the first glance it doesn't seem
+#         to be so complicated, but the ID3v2 definitions are so convoluted and 
+#         unnecessarily complicated, with so many useless frame-types, it's a pain to 
+#         read the documents describing the ID3 V2.x standards.. with tiny bits of information
+#         strewn all accross the documents here and there..  and even worse to implement them.
+#
+#         I don't know what these people were thinking... can we make it any more 
+#         complicated than that??  ID3 version 2.4.0 tops everything!   If this flag
+#         is set and it's a full moon, and an even weekday number, then do this.. 
+#         Outch!!!  I assume that's why I don't find any 2.4.0 tags in any of my 
+#         MP3-files... seems like noone is writing 2.4.0 tags... iTunes writes 2.3.0
+#
+################################################################################
+# How does it work?
+#
+# Main concepts used:
+#
+#   - Unification of ID3 Frames according to this nomenclature, using "pretty" names for frames:
+#         http://www.unixgods.org/~tilo/Ruby/ID3/docs/ID3_comparison2.html
+#
+#   - String pack/unpack to parse and dump contents of ID3v2 frames; 
+#     For each ID3v2 frame type, there is a specific list of attributes for that frame 
+#     and a pack/unpack recipe associated with that frame type (see: FRAME_PARSER Hash)
+#
+#   - if there is a ID3v2 frame that's not parsed yet, it's easy to add:
+#     - create a new entry for that frame's symbolic (pretty) name in FRAMETYPE2FRAMENAME Hash
+#     - make sure to delete that name from the "UNPARSED" category
+#     - add an entry to FRAME_PARSER Hash
+#     - note how these pre-defined Hashes are used in ID3::Frame class during parse() and dump()
+#
+#   - Metaprogramming: when ID3v2 frames are instanciated when they are read, 
+#     we define parse and dump methods individually, using above pack/unpack recipes
+#     (check the two lines which use  ID3::FRAME_PARSER to better understand the internal mechanics)
+#
+#  - After the ID3v2 frames are parsed, they are Hashes; the keys are the attributes defined in FRAME_PARSER, 
+#    the values are the extracted data from the ID3v2 tag.
+#
+################################################################################
+#--
+# TO DO:
+#
+# - haven't touched the code in a very long time.. 
+#   - I should write a general write-up and explanation on how to use the classes
+#   - I should write a general write-up to explain the metaprogramming ;)
+# 
+# - they really changed all the IO calls in Ruby 1.9 -- how painful!!
+#   I need to make some wrappers, to handle this nicely in both Ruby 1.9 and 1.8
+#
+# - should probably use IO#sysopen , IO#sysseek , IO#sysread , IO#syswrite for low-level i/o
+# - files should be opened with the 'b' option - to tell Ruby 1.9 to open them in binary mode
+#
+# - Note: the external representation for non-printable characters in strings is now hex, not octal
+# - should use sha1 instead of md5
+# - some functionality , like has_id3...tag?  and is_mp3_file? should extend class File instead of being an ID3 module method
+# - class AudioFile could extend class IO or File - hmm, not sure
+# - class RestrictedOrderedHash vs OrderedHash vs Hash ...??   can we just do this with the ordered hash in 1.9?
+#   should probably at least inherit RestrictedOrderedHash < ActiveSupport::OrderedHash
+#
+# - tripple-check if the semantics of pack/unpack has changed between 1.8 and 1.9
+# - hexdump definitely barfs in Ruby 1.9 -- needs fixing
+#
+# - check out ruby-uuid on how he manipulates raw bytes.. looks like it is Ruby 1.9 compatible.. .ord .char .bytes
+#
+# - this needs some serious refactoring..
+#++
+
+
+# ==============================================================================
+
+
+
+# ==============================================================================
+
+module ID3
+
+# ... moved everything into separate files    
+
+end   # of module ID3

data/lib/id3/io_extensions.rb

@@ -0,0 +1,44 @@
+#
+# EXTENSIONS to Class IO (included in File)
+#
+
+# if you have a (partial) MP3-file stored in a File or IO object, you can check if it contains ID3 tags
+# NOTE: file needs to be opened in binary mode! 'rb:binary'
+
+class IO
+  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 hasID3v1tag?
+    seek(-ID3::ID3v1tagSize, IO::SEEK_END)
+    if (read(3) == 'TAG')
+      seek(-ID3::ID3v1tagSize + ID3::ID3v1versionbyte, IO::SEEK_END)
+      return get_byte == 0 ? "1.0" : "1.1"
+    else
+      return nil
+    end
+  end
+  
+  def ID3v2_tag_size
+    rewind
+    return 0 if (read(3) != 'ID3')
+    read_bytes(3)  # skip version and flags
+    return ID3::ID3v2headerSize + ID3.unmungeSize( read_bytes(4) )
+  end
+  
+  def hasID3v2tag?
+    rewind
+    if (read(3) == "ID3")
+      major = get_byte
+      minor = get_byte
+      return version   = "2." + major.to_s + '.' + minor.to_s
+    else
+      return nil
+    end
+  end
+end