flacinfo-rb 0.2 → 0.3

data/flacinfo.rb

@@ -3,22 +3,21 @@
 # flacinfo-rb gives you access to low level information on Flac files.
 # * It parses stream information (METADATA_BLOCK_STREAMINFO).
 # * It parses Vorbis comments (METADATA_BLOCK_VORBIS_COMMENT).
+# * It allows you to add/delete/edit Vorbis comments and write them to the Flac file.
 # * It parses the seek table (METADATA_BLOCK_SEEKTABLE).
 # * It parses the 'application metadata block' (METADATA_BLOCK_APPLICATION).
-#   * If application is ID 0x41544348 (Flac File)
-#     then we can parse that too.
+#   * If application is ID 0x41544348 (Flac File) then we can parse that too.
 # * It recognizes (but does not yet parse) the cue sheet (METADATA_BLOCK_CUESHEET).
 # * It parses zero or more picture blocks (METADATA_BLOCK_PICTURE)
-#   * It allows you to write embedded images to a file.
+#   * It allows you to write the embedded images to a file.
 #
-# My plans are to eventually have this library write as well as read data to/from Flac files,
-# so in the future it should become quite a nice native Ruby library interface which will allow
+# My goals are to create a nice native Ruby library interface which will allow
 # the user to mimic most functionality of the 'metaflac' binary programmatically.
 #
 # = Copyright and Disclaimer
 #
-# Copyright:: (c) 2006 Darren Kirby
-# FlacInfo is free software. 
+# Copyright:: (c) 2006, 2007 Darren Kirby
+# FlacInfo is free software.
 # No warranty is provided and the author cannot accept responsibility
 # for lost or damaged files.
 # License:: Ruby
@@ -35,14 +34,33 @@
 #   http://www.xiph.org/vorbis/doc/v-comment.html
 
 
-# FlacInfoError is raised when an error occurs parsing the Flac file.
-# It will print an additional error string stating where the error occured.
+# FlacInfoError is raised for general user errors.
+# It will print a string that describes the problem.
 class FlacInfoError < StandardError
 end
 
+# FlacInfoReadError is raised when an error occurs parsing the Flac file.
+# It will print a string that describes in which block the error occured.
+class FlacInfoReadError < StandardError
+end
+
+# FlacInfoWriteError is raised when an error occurs writing the Flac file.
+# It will print a string that describes where the error occured.
+class FlacInfoWriteError < StandardError
+end
+
 # Note: STREAMINFO is the only block guaranteed to be present in the Flac file.
-# All attributes will be present, but empty if the associated block is not present in the Flac file.
+# All attributes will be present but empty if the associated block is not present in the Flac file,
+# except for 'picture' which will have the key 'n' with the value '0'.
+# All 'offset' and 'block_size' values do not include the block header. All block headers are 4 bytes
+# no matter the type, so if you need the offset including the header, subtract 4. If you need the size 
+# including the header, add 4.
 class FlacInfo
+  # A list of 'standard field names' according to the Vorbis Comment specification. It is certainly
+  # possible to use a non-standard name, but the spec recommends against it.
+  # See: http://www.xiph.org/vorbis/doc/v-comment.html
+  STANDARD_FIELD_NAMES= %w/TITLE VERSION ALBUM TRACKNUMBER ARTIST PERFORMER COPYRIGHT LICENSE
+                           ORGANIZATION DESCRIPTION GENRE DATE LOCATION CONTACT ISRC/
 
   # Hash of values extracted from the STREAMINFO block. Keys are:
   # 'offset':: The STREAMINFO block's offset from the beginning of the file (not including the block header).
@@ -70,7 +88,8 @@ class FlacInfo
   attr_reader :seektable
 
   # Array of "name=value" strings extracted from the VORBIS_COMMENT block. This is just the contents, metadata is in 'tags'.
-  attr_reader :comment
+  # You should not normally operate on this array directly. Rather, use the comment_add and comment_del methods to make changes.
+  attr_accessor :comment
 
   # Hash of the 'comment' values separated into "key => value" pairs as well as the keys:
   # 'offset':: The VORBIS_COMMENT block's offset from the beginning of the file (not including the block header).
@@ -138,12 +157,17 @@ class FlacInfo
     @tags["#{tag}"] ? true : false
   end
 
-  # Pretty print comment hash.
+  # Pretty print tags hash.
   #
   # :call-seq:
   #   FlacInfo.print_tags   -> nil
   #
+  # Raises FlacInfoError if METADATA_BLOCK_VORBIS_COMMENT is not present.
+  #
   def print_tags
+    if @tags == {}
+      raise FlacInfoError, "METADATA_BLOCK_VORBIS_COMMENT not present"
+    end
     @tags.each_pair { |key,val| puts "#{key}: #{val}" }
     nil
   end
@@ -154,6 +178,7 @@ class FlacInfo
   #   FlacInfo.print_streaminfo   -> nil
   #
   def print_streaminfo
+    #  No test: METADATA_BLOCK_STREAMINFO must be present in valid Flac file
     @streaminfo.each_pair { |key,val| puts "#{key}: #{val}" }
     nil
   end
@@ -163,7 +188,12 @@ class FlacInfo
   # :call-seq:
   #   FlacInfo.print_seektable   -> nil
   #
+  # Raises FlacInfoError if METADATA_BLOCK_SEEKTABLE is not present.
+  #
   def print_seektable
+    if @seektable == {}
+      raise FlacInfoError, "METADATA_BLOCK_SEEKTABLE not present"
+    end
     puts "  seek points: #{@seektable['seek_points']}"
     n = 0
     @seektable['seek_points'].times do
@@ -178,7 +208,7 @@ class FlacInfo
   # This method produces output similar to 'metaflac --list'.
   #
   # :call-seq:
-  #   FlacInfo.meta_flac   -> nil
+  #   FlacInfo.meta_flac ->   nil
   #
   def meta_flac
     n = 0
@@ -216,7 +246,8 @@ class FlacInfo
   #   FlacInfo.raw_data_dump(outfile)   -> nil
   #
   # If passed with 'outfile', the data will be written to a file with that name
-  # otherwise it is written to the console (even if binary!).
+  # otherwise it is written to the console (even if binary!). Raises FlacInfoError
+  # if there is no Flac File data present.
   #
   def raw_data_dump(outfile = nil)
     if @flac_file == {}
@@ -240,10 +271,10 @@ class FlacInfo
   # Writes embedded images to a file
   #
   # :call-seq:
-  #   FlacInfo.write_picture()                         -> nil
-  #   FlacInfo.write_picture(:outfile=>"str")          -> nil
-  #   FlacInfo.write_picture(:n=>int)                  -> nil
-  #   FlacInfo.write_picture(:outfile=>"str", :n=>int) -> nil
+  #   FlacInfo.write_picture()                           -> nil
+  #   FlacInfo.write_picture(:outfile=>"str")            -> nil
+  #   FlacInfo.write_picture(:n=>int)                    -> nil
+  #   FlacInfo.write_picture(:outfile=>"str", :n=>int)   -> nil
   #
   # If passed with ':outfile', the image will be written to a file with that name
   # otherwise it is written to the value of the 'album' tag if it exists, otherwise it
@@ -261,13 +292,14 @@ class FlacInfo
       n = 1
     end
 
-    # "image/jpeg" => "jpeg"
+    #  "image/jpeg" => "jpeg"
     extension = @picture[n]["mime_type"].split("/")[1]
 
     if not args.has_key?(:outfile)
       if @tags["album"] == nil or @tags["album"] == ""
         outfile = "flacimage#{n}.#{extension}"
       else
+        #  Try to use contents of "album" tag for the filename
         outfile = "#{@tags["album"]}#{n}.#{extension}"
       end
     else
@@ -277,7 +309,7 @@ class FlacInfo
     in_p  = File.new(@filename, "rb")
     out_p = File.new(outfile, "wb")
 
-    out_p.binmode
+    out_p.binmode #  For Windows folks...
 
     in_p.seek(@picture[n]['raw_data_offset'], IO::SEEK_CUR)
     raw_data = in_p.read(@picture[n]['raw_data_length'])
@@ -289,7 +321,82 @@ class FlacInfo
     nil
   end
 
+  # Writes changes to disk
+  #
+  # :call-seq:
+  #   FlacInfo.update   -> bool
+  #
+  # Returns true if write was successful, false otherwise.
+  #
+  def update
+    if write_to_disk
+      return true
+    else
+      return false
+    end
+  end
+
+  # Adds a new comment to the comment array
+  #
+  # :call-seq:
+  #   FlacInfo.comment_add(str)   -> bool
+  #
+  # 'str' must be in the form 'name=value', or 'name=' if you want to
+  # set an empty value for a particular tag.
+  # Returns 'true' if successful, false otherwise.
+  #
+  def comment_add(name)
+    if name !~ /\w=/  #  We accept 'name=' in case you want to leave the value empty
+      raise FlacInfoError, "comments must be in the form 'name=value'"
+    end
+    begin
+      @comment[@comment.length] = name
+      @comments_changed = 1
+    rescue
+      return false
+    end
+    return true
+  end
+
+  # Deletes a comment from the comment array
+  #
+  # :call-seq:
+  #   FlacInfo.comment_del(str)   -> bool
+  #
+  # If 'str' is in the form 'name=value' only exact matches
+  # will be deleted. If 'str' is in the form 'name' any and all
+  # comments named 'name' will be deleted. Returns 'true' if a
+  # comment was deleted, false otherwise.
+  #
+  def comment_del(name)
+    bc = Array.new(@comment)  #  We need a copy
+    if name.include? "="
+      nc = @comment.delete_if { |x| x == name }
+    else
+      nc = @comment.delete_if { |x| x.split("=")[0] == name }
+    end
+
+    if nc == bc
+      return false
+    else
+      @comments_changed = 1
+      return true
+    end
+  end
+
+  #--
+  #  This cleans up the output when using FlacInfo in irb
+  def inspect #:nodoc:
+    s = "#<#{self.class}:0x#{(self.object_id*2).to_s(16)} "
+    @metadata_blocks.each do |blk|
+      s += "(#{blk[0].upcase} size=#{blk[4]} offset=#{blk[3]}) "
+    end
+    s += "\b>"
+  end
+  #++
+
   private
+
   #  The following six methods are just helpers for meta_flac
   def meta_stream
     puts "  length: #{@streaminfo['block_size']}"
@@ -361,16 +468,20 @@ class FlacInfo
   end
 
 
-  # This is where the 'real' parsing starts.
+  #  This is where the 'real' parsing starts
   def parse_flac_meta_blocks
-    @fp = File.new(@filename, "rb")
-    @streaminfo = {}
-    @comment = {}
-    @seektable = {}
-    @padding = {}
+    @fp = File.new(@filename, "rb")  #  Our file pointer
+    @comments_changed = nil          #  Do we need to write a new VORBIS_BLOCK?
+
+    #  These next 8 lines initialize our public data structures.
+    @streaminfo  = {}
+    @comment     = []
+    @tags        = {}
+    @seektable   = {}
+    @padding     = {}
     @application = {}
-    @cuesheet = {}
-    @picture = {"n" => 0}
+    @cuesheet    = {}
+    @picture     = {"n" => 0}
 
     header = @fp.read(4)
     #  First 4 bytes must be 0x66, 0x4C, 0x61, and 0x43
@@ -384,22 +495,22 @@ class FlacInfo
 
     @metadata_blocks = []
     lastheader = 0
-    n = 0
+    pos = 1
 
     until lastheader == 1
-      # first bit = Last-metadata-block flag
-      # bits 2-7 = BLOCK_TYPE. See typetable above
+      #  first bit = Last-metadata-block flag
+      #  bits 2-8 = BLOCK_TYPE. See typetable above
       block_header = @fp.read(1).unpack("B*")[0]
       lastheader = block_header[0].to_i & 1
       type = sprintf("%u", "0b#{block_header[1..7]}").to_i
-      @metadata_blocks[n] = ["#{typetable[type]}", type, lastheader]
+      @metadata_blocks << [typetable[type], type, lastheader]
 
       if type >= typetable.size
         raise FlacInfoError, "Invalid block header type"
       end
 
+      pos += 1
       self.send "parse_#{typetable[type]}"
-      n += 1
     end
 
     @fp.close
@@ -407,9 +518,13 @@ class FlacInfo
 
   def parse_seektable
     begin
-      @seektable['block_size'] = @fp.read(3).reverse.unpack("v*")[0]
-      @seektable['offset'] = @fp.tell
+      @seektable['block_size']  = @fp.read(3).unpack("B*")[0].to_i(2)
+      @seektable['offset']      = @fp.tell
       @seektable['seek_points'] = @seektable['block_size'] / 18
+
+      @metadata_blocks[-1] << @seektable['offset']
+      @metadata_blocks[-1] << @seektable['block_size']
+
       n = 0
       @seektable['points'] = {}
 
@@ -430,8 +545,12 @@ class FlacInfo
   #  Not parsed yet, I have no flacs with a cuesheet!
   def parse_cuesheet
     begin
-      @cuesheet['block_size'] = @fp.read(3).reverse.unpack("v*")[0]
-      @cuesheet['offset'] = @fp.tell
+      @cuesheet['block_size'] = @fp.read(3).unpack("B*")[0].to_i(2)
+      @cuesheet['offset']     = @fp.tell
+
+      @metadata_blocks[-1] << @cuesheet['offset']
+      @metadata_blocks[-1] << @cuesheet['block_size']
+
       @fp.seek(@cuesheet['block_size'], IO::SEEK_CUR)
     rescue
       raise FlacInfoError, "Could not parse METADATA_BLOCK_CUESHEET"
@@ -441,7 +560,7 @@ class FlacInfo
   def parse_picture
     n = @picture["n"] + 1
     @picture["n"] = n
-    @picture[n] = {}
+    @picture[n]   = {}
 
     picture_type = ["Other", "32x32 pixels file icon", "Other file icon", "Cover (front)", "Cover (back)",
                     "Leaflet page", "Media", "Lead artist/lead performer/soloist", "Artist/performer",
@@ -450,20 +569,26 @@ class FlacInfo
                      coloured fish", "Illustration", "Band/artist logotype", "Publisher/Studio logotype"]
 
     begin
-      @picture[n]['block_size'] = @fp.read(3).reverse.unpack("v*")[0]
-      @picture[n]['offset'] = @fp.tell
-      @picture[n]['type_int'] = @fp.read(4).reverse.unpack("v*")[0]
-      @picture[n]['type_string'] = picture_type[@picture[n]['type_int']]
-      mime_length = @fp.read(4).reverse.unpack("v*")[0]
-      @picture[n]['mime_type'] = @fp.read(mime_length).unpack("a*")[0]
-      description_length = @fp.read(4).reverse.unpack("v*")[0]
+      @picture[n]['block_size'] = @fp.read(3).unpack("B*")[0].to_i(2)
+      @picture[n]['offset']     = @fp.tell
+
+      @metadata_blocks[-1] << @picture[n]['offset']
+
+      @picture[n]['type_int']           = @fp.read(4).reverse.unpack("v*")[0]
+      @picture[n]['type_string']        = picture_type[@picture[n]['type_int']]
+      mime_length                       = @fp.read(4).reverse.unpack("v*")[0]
+      @picture[n]['mime_type']          = @fp.read(mime_length).unpack("a*")[0]
+      description_length                = @fp.read(4).reverse.unpack("v*")[0]
       @picture[n]['description_string'] = @fp.read(description_length).unpack("M*")[0]
-      @picture[n]['width'] = @fp.read(4).reverse.unpack("v*")[0]
-      @picture[n]['height'] = @fp.read(4).reverse.unpack("v*")[0]
-      @picture[n]['colour_depth'] = @fp.read(4).reverse.unpack("v*")[0]
-      @picture[n]['n_colours'] = @fp.read(4).reverse.unpack("v*")[0]
-      @picture[n]['raw_data_length'] = @fp.read(4).reverse.unpack("V*")[0]
-      @picture[n]['raw_data_offset'] = @fp.tell
+      @picture[n]['width']              = @fp.read(4).reverse.unpack("v*")[0]
+      @picture[n]['height']             = @fp.read(4).reverse.unpack("v*")[0]
+      @picture[n]['colour_depth']       = @fp.read(4).reverse.unpack("v*")[0]
+      @picture[n]['n_colours']          = @fp.read(4).reverse.unpack("v*")[0]
+      @picture[n]['raw_data_length']    = @fp.read(4).reverse.unpack("V*")[0]
+      @picture[n]['raw_data_offset']    = @fp.tell
+
+      @metadata_blocks[-1] << @picture[n]['block_size']
+
       @fp.seek((@picture[n]['raw_data_length']), IO::SEEK_CUR)
     rescue
       raise FlacInfoError, "Could not parse METADATA_BLOCK_PICTURE"
@@ -472,8 +597,12 @@ class FlacInfo
 
   def parse_application
     begin
-      @application['block_size'] = @fp.read(3).reverse.unpack("v*")[0]
-      @application['offset'] = @fp.tell
+      @application['block_size'] = @fp.read(3).unpack("B*")[0].to_i(2)
+      @application['offset']     = @fp.tell
+
+      @metadata_blocks[-1] << @application['offset']
+      @metadata_blocks[-1] << @application['block_size']
+
       @application['ID'] = @fp.read(4).unpack("H*")[0]
 
       app_id = {"41544348" => "Flac File", "43756573" => "GoldWave Cue Points",
@@ -503,17 +632,20 @@ class FlacInfo
   #  separated into key=value pairs
   def parse_vorbis_comment
     begin
-      @tags = {}
-      @tags['block_size'] = @fp.read(3).reverse.unpack("v*")[0]
-      @tags['offset'] = @fp.tell
-      vendor_length = @fp.read(4).unpack("V")[0]
-      @tags['vendor_tag'] = @fp.read(vendor_length)
-      user_comment_list_length = @fp.read(4).unpack("V")[0]
-      @comment = []
-      n = 0
+      @tags['block_size'] = @fp.read(3).unpack("B*")[0].to_i(2)
+      @tags['offset']     = @fp.tell
+
+      @metadata_blocks[-1] << @tags['offset']
+      @metadata_blocks[-1] << @tags['block_size']
 
+      vendor_length = @fp.read(4).reverse.unpack("B*")[0].to_i(2)
+
+      @tags['vendor_tag']      = @fp.read(vendor_length)
+      user_comment_list_length = @fp.read(4).reverse.unpack("B*")[0].to_i(2)
+
+      n = 0
       user_comment_list_length.times do
-        length = @fp.read(4).unpack("V")[0]
+        length = @fp.read(4).reverse.unpack("B*")[0].to_i(2)
         @comment[n] = @fp.read(length)
         n += 1
       end
@@ -539,8 +671,12 @@ class FlacInfo
   # padding is just a bunch of '0' bytes
   def parse_padding
     begin
-      @padding['block_size'] = @fp.read(3).reverse.unpack("v*")[0]
-      @padding['offset'] = @fp.tell
+      @padding['block_size'] = @fp.read(3).unpack("B*")[0].to_i(2)
+      @padding['offset']     = @fp.tell
+
+      @metadata_blocks[-1] << @padding['offset']
+      @metadata_blocks[-1] << @padding['block_size']
+
       @fp.seek(@padding['block_size'], IO::SEEK_CUR)
     rescue
       raise FlacInfoError, "Could not parse METADATA_BLOCK_PADDING"
@@ -549,8 +685,12 @@ class FlacInfo
 
   def parse_streaminfo
     begin
-      @streaminfo['block_size']    = @fp.read(3).reverse.unpack("v*")[0]
+      @streaminfo['block_size']    = @fp.read(3).unpack("B*")[0].to_i(2)
       @streaminfo['offset']        = @fp.tell
+
+      @metadata_blocks[-1] << @streaminfo['offset']
+      @metadata_blocks[-1] << @streaminfo['block_size']
+
       @streaminfo['minimum_block'] = @fp.read(2).reverse.unpack("v*")[0]
       @streaminfo['maximum_block'] = @fp.read(2).reverse.unpack("v*")[0]
       @streaminfo['minimum_frame'] = @fp.read(3).reverse.unpack("v*")[0]
@@ -588,4 +728,108 @@ class FlacInfo
       raise FlacInfoError, "Could not parse Flac File data"
     end
   end
+
+  #  Here we begin the FlacInfo write methods
+
+
+  #  Build a block header given a type, a size, and whether it is last
+  def build_block_header(type, size, last)
+    begin
+      bit_string = sprintf("%b%7b", last, type).gsub(" ","0")
+      block_header_s = [bit_string].pack("B*")
+      block_header_s += [size].pack("VX").reverse  # size is 3 bytes
+    rescue
+      raise FlacInfoWriteError, "error building block header"
+    end
+  end
+
+  #  Build a string of packed data for the Vorbis comments
+  def build_vorbis_comment_block
+    begin
+      vorbis_comm_s  = [@tags["vendor_tag"].length].pack("V")
+      vorbis_comm_s += [@tags["vendor_tag"]].pack("A*")
+      vorbis_comm_s += [@comment.length].pack("V")
+      @comment.each do |c|
+        vorbis_comm_s += [c.length].pack("V")
+        vorbis_comm_s += [c].pack("A*")
+      end
+      vorbis_comm_s
+    rescue
+      raise FlacInfoWriteError, "error building vorbis comment block"
+    end
+  end
+
+  def write_to_disk
+    if @comments_changed == nil
+      raise FlacInfoWriteError, "No changes to write"
+    else
+      vcd = build_vorbis_comment_block            #  Build the VORBIS_COMMENT data
+      vch = build_block_header(4, vcd.length, 0)  #  Build the VORBIS_COMMENT header
+    end
+
+    #  Determine if we can shuffle the data or if a rewrite is necessary
+    begin
+      if not @padding.has_key?("block_size") or vcd.length > @padding['block_size']
+        rewrite(vcd, vch)  # Rewriting is simpler but more expensive
+      else
+        shuffle(vcd, vch)  # Shuffling is more complicated but cheaper
+      end
+      parse_flac_meta_blocks  #  Parse the file again to update new values
+      return true
+    rescue
+      raise FlacInfoWriteError, "error writing new data to #{@filename}"
+    end
+  end
+
+  #  Shuffle the data and update the PADDING block
+  def shuffle(vcd, vch)
+    flac = File.new(@filename, "r+b")
+    flac.binmode #  For Windows folks...
+
+    #  Position ourselves at end of current Vorbis block
+    flac.seek((@tags['offset'] + @tags['block_size']), IO::SEEK_CUR)
+    #  The data we need to shuffle starts at current position and ends at
+    #  the beginning of the padding block, so the size we need to read is:
+    #
+    #  (offset of padding minus 4 bytes for the padding header) minus our current position
+    #
+    size_to_read = (@padding['offset'] - 4) - flac.tell
+    data_to_shuffle = flac.read(size_to_read)
+
+    flac.seek((@tags['offset'] - 4), IO::SEEK_SET)
+    flac.write(vch)              #  Write the VORBIS_COMMENT header
+    flac.write(vcd)              #  Write the VORBIS_COMMENT data
+    flac.write(data_to_shuffle)  #  Write the shuffled data
+
+    new_padding_size = @padding['block_size'] - (vcd.length - @tags['block_size'])
+    ph = build_block_header(1, new_padding_size, 1)  #  Build the new PADDING header
+
+    flac.write(ph)  #  Write the new PADDING header
+    flac.close      #  ...and we're done
+  end
+
+  #  Rewrite the entire file
+  def rewrite(vcd, vch)
+    flac = File.new(@filename, "r+b")
+    flac.binmode #  For Windows folks...
+
+    flac.seek((@tags['offset'] + @tags['block_size']), IO::SEEK_CUR)
+    rest_of_file = flac.read()
+    flac.seek((@tags['offset'] - 4), IO::SEEK_SET)
+
+    flac.write(vch)           #  Write the VORBIS_COMMENT header
+    flac.write(vcd)           #  Write the VORBIS_COMMENT data
+    flac.write(rest_of_file)  #  Write the rest of the file
+
+    flac.close
+  end
+
+end
+
+# If called directly from the command line, run meta_flac on each argument
+if __FILE__ == $0
+  ARGV.each do |filename|
+    FlacInfo.new(filename).meta_flac
+    puts
+  end
 end

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: flacinfo-rb
 version: !ruby/object:Gem::Version 
-  version: "0.2"
-date: 2007-06-23 00:00:00 -06:00
+  version: "0.3"
+date: 2007-07-01 00:00:00 -06:00
 summary: Pure Ruby lib for accessing metadata (including Vorbis tags) from Flac files
 require_paths: 
 - lib