flacinfo-rb 0.1 → 0.2

data/README

@@ -17,8 +17,9 @@ seektable    :: hash of arrays of seek points
 comment      :: array of VORBIS COMMENT block metadata 
 tags         :: user-friendly hash of Vorbis comment metadata key=value pairs
 application  :: hash of APPLICATION block metadata
-padding      :: hash of PADDING block metadata (currently just ['block_size'])
-cuesheet     :: hash of CUESHEET block metadata (currently just ['block_size'])
+padding      :: hash of PADDING block metadata
+cuesheet     :: hash of CUESHEET block metadata
+picture      :: hash of PICTURE block metadata
 flac_file    :: hash of APPLICATION Id 0x41544348 (Flac File) metadata if present
 
  == Public methods ==
@@ -30,6 +31,7 @@ print_seektable   :: pretty-print seektable hash
 meta_flac         :: prints all META BLOCKS. (Mostly) equivelant to 'metaflac --list'
 raw_data_dump(?)  :: if passed a filename it will dump flac_file['raw_data'] to that file,
                      otherwise it will dump it to the console (even if binary!) 
+write_picture(?)  :: write image from PICTURE block(s) to optional file
 
 For more/different documentation see http://badcomputer.org/unix/code/flacinfo/
 

data/{lib/flacinfo.rb → flacinfo.rb}

@@ -1,27 +1,34 @@
 # = Description
 #
 # flacinfo-rb gives you access to low level information on Flac files.
-# * It parses stream information (STREAMINFO).
-# * It parses Vorbis comments (VORBIS_COMMENT).
-# * It parses the seek table (SEEKTABLE).
-# * It parses the 'application metadata block' (APPLICATION).
-#   * If (APPLICATION) is ID 0x41544348 (Flac File)
+# * It parses stream information (METADATA_BLOCK_STREAMINFO).
+# * It parses Vorbis comments (METADATA_BLOCK_VORBIS_COMMENT).
+# * 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.
-# * It recognizes (but does not yet parse) the cue sheet (CUESHEET TRACK).
+# * 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.
+#
+# 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
+# the user to mimic most functionality of the 'metaflac' binary programmatically.
 #
 # = Copyright and Disclaimer
+#
 # Copyright:: (c) 2006 Darren Kirby
 # FlacInfo is free software. 
 # No warranty is provided and the author cannot accept responsibility
 # for lost or damaged files.
 # License:: Ruby
 # Author:: Darren Kirby (mailto:bulliver@badcomputer.org)
-# Website:: http://badcomputer.org/unix/code/flacinfo/
+# Website:: http://badcomputer.org/unix/code/flacinfo/index.bot
 #
 # = More information
 #
 # * There is an example irb session that shows typical usage at
-#   http://badcomputer.org/unix/code/flacinfo/
+#   http://badcomputer.org/unix/code/flacinfo/index.bot
 # * The Flac spec is at:
 #   http://flac.sourceforge.net/format.html
 # * The Vorbis Comment spec is at:
@@ -33,39 +40,86 @@
 class FlacInfoError < StandardError
 end
 
-# Note: STREAMINFO is the only block guaranteed to be present.
-# Other attributes will be present, but empty if the associated block is not present in the Flac file.
+# 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.
 class FlacInfo
 
-  # Hash of values extracted from the STREAMINFO block. Keys are 'samplerate', 'bits_per_sample', 'total_samples'
-  # 'channels', 'minimum_frame', 'maximum_frame', 'minimum_block', 'maximum_block', 'md5', and 'block_size'
+  # 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).
+  # 'block_size':: The size of the STREAMINFO block (not including the block header).
+  # 'minimum_block':: The minimum block size (in samples) used in the stream.
+  # 'maximum_block':: The maximum block size (in samples) used in the stream.
+  # 'minimum_frame':: The minimum frame size (in bytes) used in the stream.
+  # 'maximum_frame':: The maximum frame size (in bytes) used in the stream.
+  # 'samplerate':: Sample rate in Hz.
+  # 'channels':: The number of channels used in the stream.
+  # 'bits_per_sample':: The number of bits per sample used in the stream.
+  # 'total_samples':: The total number of samples in stream.
+  # 'md5':: MD5 signature of the unencoded audio data.
   attr_reader :streaminfo
 
-  # Hash of values extracted from the SEEKTABLE block. Keys are 'seek_points', 'block_size' and 'points'.
-  # 'points' is another hash whose keys start at 0 and end at ('seek_points' - 1). Each "seektable['points'][n]" hash 
-  # contains an array whose values are [sample number, stream offset, number of frame samples] of each seek point.
+  # Hash of values extracted from the SEEKTABLE block. Keys are:
+  # 'offset':: The SEEKTABLE block's offset from the beginning of the file (not including the block header).
+  # 'block_size':: The size of the SEEKTABLE block (not including the block header).
+  # 'seek_points':: The number of seek points in the block.
+  # 'points':: Another hash whose keys start at 0 and end at ('seek_points' - 1). Each "seektable['points'][n]" hash
+  #            contains an array whose (integer) values are:
+  #            '0':: Sample number of first sample in the target frame, or 0xFFFFFFFFFFFFFFFF for a placeholder point.
+  #            '1':: Offset (in bytes) from the first byte of the first frame header to the first byte of the target frame's header.
+  #            '2':: Number of samples in the target frame.
   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
 
-  # Hash of the 'comment' values separated into "key => value" pairs as well as 'vendor_tag' and 'block_size'.
+  # 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).
+  # 'block_size':: The size of the VORBIS_COMMENT block (not including the block header).
+  # 'vendor_tag':: Typically, the name and version of the software that encoded the file.
   attr_reader :tags
 
-  # Hash of values extracted from the APPLICATION block. Keys are 'name', 'ID', and 'block_size'.
+  # Hash of values extracted from the APPLICATION block. Keys are:
+  # 'offset':: The APPLICATION block's offset from the beginning of the file (not including the block header).
+  # 'block_size':: The size of the APPLICATION block (not including the block header).
+  # 'ID':: Registered application ID. See http://flac.sourceforge.net/id.html
+  # 'name':: Name of the registered application ID.
   attr_reader :application
 
-  # Hash of values extracted from the PADDING block. Just one key: 'block_size'.
+  # Hash of values extracted from the PADDING block. Keys are:
+  # 'offset':: The PADDING block's offset from the beginning of the file (not including the block header).
+  # 'block_size':: The size of the PADDING block (not including the block header).
   attr_reader :padding
 
-  # Hash of values extracted from the CUESHEET block. Just one key: 'block_size'.
+  # Hash of values extracted from the CUESHEET block. Keys are:
+  # 'offset':: The CUESHEET block's offset from the beginning of the file (not including the block header).
+  # 'block_size':: The size of the CUESHEET block (not including the block header).
   attr_reader :cuesheet
 
-  # Hash of values extracted from an APPLICATION block if it is type 0x41544348 (Flac File). 
-  # Keys are 'description', 'mime_type', and 'raw_data'.
+  # Hash of values extracted from one or more PICTURE blocks. This hash always includes the key 'n' which is the number of
+  # PICTURE blocks found, else '0'. For each block found there will be an integer key starting from 1. Each of these is a
+  # hash which contains the keys:
+  # 'offset':: The PICTURE block's offset from the beginning of the file (not including the block header).
+  # 'block_size':: The size of the PICTURE block (not including the block header).
+  # 'type_int':: The picture type according to the ID3v2 APIC frame.
+  # 'type_string':: A text value representing the picture type.
+  # 'description_string':: A text description of the picture.
+  # 'mime_type':: The MIME type string. May be '-->' to signify that the data part is a URL of the picture.
+  # 'colour_depth':: The color depth of the picture in bits-per-pixel.
+  # 'n_colours':: For indexed-color pictures (e.g. GIF), the number of colors used, or 0 for non-indexed pictures.
+  # 'width':: The width of the picture in pixels.
+  # 'height':: The height of the picture in pixels.
+  # 'raw_data_offset':: The raw picture data's offset from the beginning of the file.
+  # 'raw_data_length':: The length of the picture data in bytes.
+  attr_reader :picture
+
+  # Hash of values extracted from an APPLICATION block if it is type 0x41544348 (Flac File).
+  # Keys are:
+  # 'description':: A brief text description of the contents.
+  # 'mime_type':: The Mime type of the contents.
+  # 'raw_data':: The contents. May be binary.
   attr_reader :flac_file
 
-  # FlacInfo is the main class for parsing Flac files
+  # FlacInfo is the class for parsing Flac files.
   #
   # :call-seq:
   #   FlacInfo.new(file)   -> FlacInfo instance
@@ -75,7 +129,7 @@ class FlacInfo
     parse_flac_meta_blocks
   end
 
-  # Returns true if @tags[<string>] has a value, false otherwise.
+  # Returns true if @tags[tag] has a value, false otherwise.
   #
   # :call-seq:
   #   FlacInfo.hastag?(tag)   -> bool
@@ -84,7 +138,7 @@ class FlacInfo
     @tags["#{tag}"] ? true : false
   end
 
-  # Prettyprint comment hash.
+  # Pretty print comment hash.
   #
   # :call-seq:
   #   FlacInfo.print_tags   -> nil
@@ -94,7 +148,7 @@ class FlacInfo
     nil
   end
 
-  # Prettyprint streaminfo hash
+  # Pretty print streaminfo hash.
   #
   # :call-seq:
   #   FlacInfo.print_streaminfo   -> nil
@@ -104,7 +158,7 @@ class FlacInfo
     nil
   end
 
-  # Prettyprint the seektable
+  # Pretty print the seektable.
   #
   # :call-seq:
   #   FlacInfo.print_seektable   -> nil
@@ -121,13 +175,14 @@ class FlacInfo
     nil
   end
 
-  # This method produces output (mostly) identical to 'metaflac --list'
+  # This method produces output similar to 'metaflac --list'.
   #
   # :call-seq:
   #   FlacInfo.meta_flac   -> nil
   #
   def meta_flac
     n = 0
+    pictures_seen = 0
     @metadata_blocks.each do |block|
       puts "METADATA block ##{n}"
       puts "  type: #{block[1]} (#{block[0].upcase})"
@@ -145,6 +200,9 @@ class FlacInfo
           meta_vorb
         when 5
           meta_cue
+        when 6
+          pictures_seen += 1
+          meta_pict(pictures_seen)
       end
       n += 1
     end
@@ -154,7 +212,7 @@ class FlacInfo
   # Dumps the contents of flac_file['raw_data']
   #
   # :call-seq:
-  #   FlacInfo.raw_data_dump()           -> nil
+  #   FlacInfo.raw_data_dump()          -> nil
   #   FlacInfo.raw_data_dump(outfile)   -> nil
   #
   # If passed with 'outfile', the data will be written to a file with that name
@@ -179,6 +237,57 @@ class FlacInfo
     end
   end
 
+  # 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
+  #
+  # 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
+  # is written to 'flacimage'. All three of these will have a dot plus the relevant file
+  # extension appended. The argument to ':n' is which image to write in case of multiples.
+  #
+  def write_picture(args = {})
+    if @picture["n"] == 0
+      raise FlacInfoError, "There is no METADATA_BLOCK_PICTURE"
+    end
+
+    if args.has_key?(:n)
+      n = args[:n]
+    else
+      n = 1
+    end
+
+    # "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
+        outfile = "#{@tags["album"]}#{n}.#{extension}"
+      end
+    else
+      outfile = "#{args[:outfile]}.#{extension}"
+    end
+
+    in_p  = File.new(@filename, "rb")
+    out_p = File.new(outfile, "wb")
+
+    out_p.binmode
+
+    in_p.seek(@picture[n]['raw_data_offset'], IO::SEEK_CUR)
+    raw_data = in_p.read(@picture[n]['raw_data_length'])
+    out_p.write(raw_data)
+
+    in_p.close
+    out_p.close
+
+    nil
+  end
 
   private
   #  The following six methods are just helpers for meta_flac
@@ -226,7 +335,7 @@ class FlacInfo
 
   def meta_vorb
     puts "  length: #{@tags['block_size']}"
-    puts "  length: #{@tags['vendor_tag']}"
+    puts "  vendor string: #{@tags['vendor_tag']}"
     puts "  comments: #{@comment.size}"
     n = 0
     @comment.each do |c|
@@ -239,6 +348,19 @@ class FlacInfo
     puts "  length: #{@cuesheet['block_size']}"
   end
 
+  def meta_pict(n)
+    puts "  length: #{@picture[n]['block_size']}"
+    puts "  type: #{@picture[n]['type_int']} => #{@picture[n]['type_string']}"
+    puts "  mimetype: #{@picture[n]['mime_type']}"
+    puts "  description: #{@picture[n]['description_string']}"
+    puts "  image width: #{@picture[n]['width']}"
+    puts "  image height: #{@picture[n]['height']}"
+    puts "  colour depth: #{@picture[n]['colour_depth']}"
+    puts "  number of colours: #{@picture[n]['n_colours']}"
+    puts "  image size: #{@picture[n]['raw_data_length']} bytes"
+  end
+
+
   # This is where the 'real' parsing starts.
   def parse_flac_meta_blocks
     @fp = File.new(@filename, "rb")
@@ -248,9 +370,7 @@ class FlacInfo
     @padding = {}
     @application = {}
     @cuesheet = {}
-
-    typetable = { 0 => "streaminfo", 1 => "padding", 2 => "application",
-                  3 => "seektable", 4 => "vorbis_comment", 5 => "cuesheet" }
+    @picture = {"n" => 0}
 
     header = @fp.read(4)
     #  First 4 bytes must be 0x66, 0x4C, 0x61, and 0x43
@@ -258,9 +378,14 @@ class FlacInfo
       raise FlacInfoError, "#{@filename} does not appear to be a valid Flac file"
     end
 
+    typetable = { 0 => "streaminfo", 1 => "padding", 2 => "application",
+                  3 => "seektable", 4 => "vorbis_comment", 5 => "cuesheet",
+                  6 => "picture" }
+
     @metadata_blocks = []
     lastheader = 0
     n = 0
+
     until lastheader == 1
       # first bit = Last-metadata-block flag
       # bits 2-7 = BLOCK_TYPE. See typetable above
@@ -268,17 +393,26 @@ class FlacInfo
       lastheader = block_header[0].to_i & 1
       type = sprintf("%u", "0b#{block_header[1..7]}").to_i
       @metadata_blocks[n] = ["#{typetable[type]}", type, lastheader]
+
+      if type >= typetable.size
+        raise FlacInfoError, "Invalid block header type"
+      end
+
       self.send "parse_#{typetable[type]}"
       n += 1
     end
+
+    @fp.close
   end
 
   def parse_seektable
     begin
       @seektable['block_size'] = @fp.read(3).reverse.unpack("v*")[0]
+      @seektable['offset'] = @fp.tell
       @seektable['seek_points'] = @seektable['block_size'] / 18
       n = 0
       @seektable['points'] = {}
+
       @seektable['seek_points'].times do
         pt_arr = []
         pt_arr << @fp.read(8).reverse.unpack("V*")[0]
@@ -287,23 +421,61 @@ class FlacInfo
         @seektable['points'][n] = pt_arr
         n += 1
       end
+
     rescue
-      raise FlacInfoError, "Could not parse seek table"
+      raise FlacInfoError, "Could not parse METADATA_BLOCK_SEEKTABLE"
     end
   end
 
   #  Not parsed yet, I have no flacs with a cuesheet!
   def parse_cuesheet
-    @cuesheet['block_size'] = @fp.read(3).reverse.unpack("v*")[0]
-    @fp.seek(@cuesheet['block_size'], IO::SEEK_CUR)
+    begin
+      @cuesheet['block_size'] = @fp.read(3).reverse.unpack("v*")[0]
+      @cuesheet['offset'] = @fp.tell
+      @fp.seek(@cuesheet['block_size'], IO::SEEK_CUR)
+    rescue
+      raise FlacInfoError, "Could not parse METADATA_BLOCK_CUESHEET"
+    end
+  end
+
+  def parse_picture
+    n = @picture["n"] + 1
+    @picture["n"] = 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",
+                    "Conductor", "Band/Orchestra", "Composer", "Lyricist/text writer", "Recording Location",
+                    "During recording", "During performance", "Movie/video screen capture", "A bright 
+                     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]['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
+      @fp.seek((@picture[n]['raw_data_length']), IO::SEEK_CUR)
+    rescue
+      raise FlacInfoError, "Could not parse METADATA_BLOCK_PICTURE"
+    end
   end
 
   def parse_application
     begin
       @application['block_size'] = @fp.read(3).reverse.unpack("v*")[0]
+      @application['offset'] = @fp.tell
       @application['ID'] = @fp.read(4).unpack("H*")[0]
 
-      #  See http://flac.sourceforge.net/id.html
       app_id = {"41544348" => "Flac File", "43756573" => "GoldWave Cue Points",
                 "4D754D4C" => "MusicML", "46696361" => "CUE Splitter",
                 "46746F6C" => "flac-tools", "5346464C" => "Sound Font FLAC",
@@ -319,30 +491,33 @@ class FlacInfo
         @application['raw_data'] = @fp.read(@application['block_size'] - 4)
       end
     rescue
-      raise FlacInfoError, "Could not parse application block" 
+      raise FlacInfoError, "Could not parse METADATA_BLOCK_APPLICATION" 
     end
   end
 
   #  Unlike most values in the Flac header
-  #  the Vorbis comments are in LSB order 
+  #  the Vorbis comments are in LSB order
   #
   #  @comment is an array of values according to the official spec implementation
-  #  @tags is a more user-friendly data structure with the values 
-  #  separated into key=value pairs 
+  #  @tags is a more user-friendly data structure with the values
+  #  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
+
       user_comment_list_length.times do
         length = @fp.read(4).unpack("V")[0]
         @comment[n] = @fp.read(length)
         n += 1
       end
+
       @comment.each do |c|
         k,v = c.split("=")
         #  Vorbis spec says we can have more than one identical comment ie:
@@ -355,21 +530,27 @@ class FlacInfo
           @tags[k] = v
         end
       end
+
     rescue
-      raise FlacInfoError, "Could not parse Vorbis comments block"
+      raise FlacInfoError, "Could not parse METADATA_BLOCK_VORBIS_COMMENT"
     end
   end
 
   # padding is just a bunch of '0' bytes
   def parse_padding
-    @padding['block_size'] = @fp.read(3).reverse.unpack("v*")[0]
-    @fp.seek(@padding['block_size'], IO::SEEK_CUR)
+    begin
+      @padding['block_size'] = @fp.read(3).reverse.unpack("v*")[0]
+      @padding['offset'] = @fp.tell
+      @fp.seek(@padding['block_size'], IO::SEEK_CUR)
+    rescue
+      raise FlacInfoError, "Could not parse METADATA_BLOCK_PADDING"
+    end
   end
 
   def parse_streaminfo
     begin
-      #  Length (in bytes) of metadata to follow (not including header)
       @streaminfo['block_size']    = @fp.read(3).reverse.unpack("v*")[0]
+      @streaminfo['offset']        = @fp.tell
       @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]
@@ -389,7 +570,7 @@ class FlacInfo
       #  128 bits :: MD5 signature of the unencoded audio data.
       @streaminfo['md5'] = @fp.read(16).unpack("H32")[0]
     rescue
-      raise FlacInfoError, "Could not parse stream info block"
+      raise FlacInfoError, "Could not parse METADATA_BLOCK_STREAMINFO"
     end
   end
 

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.8.11
+rubygems_version: 0.9.4
 specification_version: 1
 name: flacinfo-rb
 version: !ruby/object:Gem::Version 
-  version: "0.1"
-date: 2006-09-18 00:00:00 -07:00
+  version: "0.2"
+date: 2007-06-23 00:00:00 -06:00
 summary: Pure Ruby lib for accessing metadata (including Vorbis tags) from Flac files
 require_paths: 
 - lib
@@ -25,11 +25,12 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
 platform: ruby
 signing_key: 
 cert_chain: 
+post_install_message: 
 authors: 
 - Darren Kirby
 files: 
 - README
-- lib/flacinfo.rb
+- flacinfo.rb
 test_files: []
 
 rdoc_options: []