ruby-mp3info 0.7.2 → 0.8

data/History.txt

@@ -1,3 +1,9 @@
+=== 0.8 / 2013-01-28
+
+* allow higher level of reading and writing to APIC tag:
+* tag2.pictures, tag2.remove_pictures, tag2.add_picture
+* added "<<...snip...>>>" to shorten APIC tag when Hash.inspect called (not a shallow copy hash, deep copied hash so does not effect data) tag2.inspect
+
 === 0.7.2 / 2012-12-24
 
 * do not try to commit changes to IO or StringIO

data/Manifest.txt

@@ -1,6 +1,6 @@
 History.txt
 Manifest.txt
-README.txt
+README.md
 Rakefile
 lib/mp3info.rb
 lib/mp3info/extension_modules.rb

data/README.md

@@ -0,0 +1,97 @@
+# ruby-mp3info
+
+* http://github.com/moumar/ruby-mp3info
+
+## Description
+
+ruby-mp3info read low-level informations and manipulate tags on mp3 files.
+
+## Features/Problems
+
+* Written in pure ruby 
+* Read low-level informations like bitrate, length, samplerate, etc...
+* Read, write, remove id3v1 and id3v2 tags
+* Correctly read VBR files (with or without Xing header)
+* Only 2.3 version is supported for writings id3v2 tags
+* id3v2 tags are always written in UTF-16 encoding
+
+## Synopsis
+
+```ruby
+    require "mp3info"
+
+    # Read and display infos & tags
+
+    Mp3Info.open("myfile.mp3") do |mp3info|
+      puts mp3info
+    end
+    
+    # read/write tag1 and tag2 with Mp3Info#tag attribute
+    # when reading tag2 have priority over tag1
+    # when writing, each tag is written.
+
+    Mp3Info.open("myfile.mp3") do |mp3|
+      puts mp3.tag.title   
+      puts mp3.tag.artist   
+      puts mp3.tag.album
+      puts mp3.tag.tracknum
+      mp3.tag.title = "track title"
+      mp3.tag.artist = "artist name"
+    end
+
+    # tags are written when calling Mp3Info#close or at the end of the #open block
+
+    ### access id3v2 tags
+
+    Mp3Info.open("myfile.mp3") do |mp3|
+      # you can access four letter v2 tags like this
+      puts mp3.tag2.TIT2
+      mp3.tag2.TIT2 = "new TIT2"
+      # or like that
+      mp3.tag2["TIT2"]
+      # at this time, only COMM tag is processed after reading and before writing
+      # according to ID3v2#options hash
+      mp3.tag2.options[:lang] = "FRE"
+      mp3.tag2.COMM = "my comment in french, correctly handled when reading and writing"
+    end
+
+    ### image manipulation
+
+    file = File.new('input_img','rb')
+    Mp3Info.open '1.mp3' do |m|
+       pictures = m.tag2.get_pictures # array of images :
+       pictures.each do |description, data|
+          File.open(description, "wb") { |f| f.write data }
+      end
+      m.tag2.remove_pictures # remove all images
+      m.tag2.add_picture(file.read) # optionally, you may include options for the header:
+      # options = { mime: 'gif', description: "description",
+      #             pic_type: 0 }
+    end
+```
+
+## Requirements
+
+* iconv when using ruby 1.8
+
+## Install
+
+    gem install ruby-mp3info
+
+## Developers
+
+After checking out the source, run:
+
+    $ rake newb
+
+This task will install any missing dependencies, run the tests/specs, and generate the RDoc.
+
+## License
+
+ruby
+
+## TODO:
+
+* encoder detection
+* support for more tags in id3v2
+* generalize id3v2 with other audio formats (APE, MPC, OGG, etc...)

data/lib/mp3info.rb

@@ -5,8 +5,8 @@
 
 require "fileutils"
 require "stringio"
-require "mp3info/extension_modules"
 require "mp3info/id3v2"
+require "mp3info/extension_modules"
 
 # ruby -d to display debugging infos
 
@@ -18,7 +18,7 @@ end
 
 class Mp3Info
 
-  VERSION = "0.7.2"
+  VERSION = "0.8"
 
   LAYER = [ nil, 3, 2, 1]
   BITRATE = {
@@ -471,7 +471,7 @@ class Mp3Info
   def to_s
     s = "MPEG #{@mpeg_version} Layer #{@layer} #{@vbr ? "VBR" : "CBR"} #{@bitrate} Kbps #{@channel_mode} #{@samplerate} Hz length #{@length} sec. header #{@header.inspect} "
     s << "tag1: "+@tag1.to_hash.inspect+"\n" if hastag1?
-    s << "tag2: "+@tag2.to_hash.inspect+"\n" if hastag2?
+    s << "tag2: "+@tag2.to_inspect_hash.inspect+"\n" if hastag2?
     s
   end
 

data/lib/mp3info/id3v2.rb

@@ -217,6 +217,136 @@ class ID3v2 < DelegateClass(Hash)
     end
   end
 
+  ### cuts out long tag values from hash for display on screen
+  def to_inspect_hash
+    result = Marshal.load(Marshal.dump(self.to_hash))
+    result.each do |k,v|
+      if v.is_a? Array
+        v.each_index do |i, item|
+          if (v[i].is_a? String and v[i].length > 128)
+            result[k][i] = pretty_header(v[i])
+          end
+        end
+      elsif v.is_a? String and v.length > 128
+        result[k] = pretty_header(v) # this method 'snips' long data
+      end
+    end
+    result
+  end
+
+  ### ID3V2::add_picture
+  ### Takes an image string as input and writes it with header. 
+  ### Mime type is automatically guessed by default.
+  ### It is possible but not necessary to include:
+  ###  :pic_type => 0 - 14 (see http://id3.org/id3v2.3.0#Attached_picture)
+  ###  :mime => 'gif' 
+  ###  :description => "Image description"
+  def add_picture(data, opts = {})
+    options = { 
+                :pic_type => 0,
+                :mime => nil,
+                :description => "image"
+              }
+    options.update(opts)
+    jpg = Regexp.new( "^\xFF".force_encoding("BINARY"),
+                 Regexp::FIXEDENCODING )
+    png = Regexp.new( "^\x89PNG".force_encoding("BINARY"),
+                 Regexp::FIXEDENCODING )
+    gif = Regexp.new( "^\x89GIF".force_encoding("BINARY"),
+                 Regexp::FIXEDENCODING )
+
+    mime = options[:mime]
+    mime ||= "jpg" if data.match jpg
+    mime ||= "png" if data.match png
+    mime ||= "gif" if data.match gif
+    pic_type = options[:pic_type]
+    pic_type = ["%02i" % pic_type].pack('H*')
+    desc = "#{options[:description]}"
+    header = "\x00image/#{mime}\x00#{pic_type}#{desc}\x00"
+    self["APIC"] = header + data.force_encoding('BINARY')
+  end
+
+  ### Returns an array of images:
+  ###   [  ["01_.jpg", "Image Data in Binary String"],
+  ###      ["02_.png", "Another Image in a String"]    ]
+  ###
+  ### e.g. to write all images:
+  ### mp3.tag2.pictures.each do |image|
+  ###   File.open(img[0], 'wb'){|f| f.write img[1])
+  ### end
+  def pictures
+    apic_images = [self["APIC"]].flatten.dup
+    result = []
+    apic_images.each_index do |index|
+      pic = apic_images[index]
+      next if !pic.is_a?(String) or pic == ""
+      pic.force_encoding 'BINARY' 
+      picture = []
+      jpg = Regexp.new("jpg|JPG|jpeg|JPEG".force_encoding("BINARY"),
+                   Regexp::FIXEDENCODING )
+      png = Regexp.new("png|PNG".force_encoding("BINARY"),
+                   Regexp::FIXEDENCODING )
+      header = pic.unpack('a120').first.force_encoding "BINARY"
+      mime_pos = 0
+      
+      # safest way to correctly extract jpg and png is finding mime
+      if header.match jpg
+        mime = "jpg"
+        mime_pos = header =~ jpg
+        start = Regexp.new("^\377".force_encoding("BINARY"),
+                         Regexp::FIXEDENCODING )
+      elsif header.match png
+        mime = "png"
+        mime_pos = header =~ png
+        start = Regexp.new("^\x89PNG".force_encoding("BINARY"),
+                         Regexp::FIXEDENCODING )
+      else
+        mime = "dat"
+      end
+
+      puts "analysing image: #{header.inspect}..." if $DEBUG
+      mim, pic_type, desc, data = pic[mime_pos, pic.length].unpack('Z*hZ*a*')
+
+      if mime != "dat" and (!data.match(start) or data.nil?)
+        real_start = pic =~ start
+        data = pic[real_start, pic.length]
+      end
+
+      if mime == "dat"
+        # if no jpg or png, extract data anyway e.g. gif
+        mime, desc, data = pic.unpack('h Z* h Z* a*').values_at(1,3,4)
+      end
+
+      if mime == "jpg"
+         # inspect jpg image header (first 10 chars) for "\xFF\x00" (expect "\xFF")
+         trailing_null_byte = Regexp.new("(\377)(\000)".force_encoding('BINARY'), 
+                                Regexp::FIXEDENCODING)
+         if (data =~ trailing_null_byte) < 10
+           data.gsub!(trailing_null_byte, "\xff".force_encoding('BINARY'))
+         end
+      end
+      
+      desc = "%02i_#{desc[0,25]}" % (index + 1)
+      
+      filename = desc.match("#{mime}$") ? desc : "#{desc}.#{mime}"
+      filename.gsub!('/','')
+      
+      picture[0] = filename
+      picture[1] = data
+      result << picture
+    end
+    result
+  end
+
+  def inspect
+    self.to_inspect_hash
+  end
+  
+  def remove_pictures
+    self.APIC = ""
+    self.PIC = ""
+  end
+
   ### gets id3v2 tag information from io object (must support #seek() method)
   def from_io(io)
     @io = io
@@ -461,6 +591,14 @@ class ID3v2 < DelegateClass(Hash)
   def to_syncsafe(num)
     ( (num<<3) & 0x7f000000 )  + ( (num<<2) & 0x7f0000 ) + ( (num<<1) & 0x7f00 ) + ( num & 0x7f )
   end
+  
+  ### this is especially useful for printing out APIC data because
+  ### only the header of the APIC tag is of interest
+  ### The result also shows some bytes escaped for cleaner display
+  def pretty_header(str, chars=128)
+    "#{str.unpack("a#{chars}").first}<<<...snip...>>>".force_encoding('BINARY').inspect[1..-2]
+  end
+
 
 end
 

data/test/test_ruby-mp3info.rb

@@ -189,6 +189,39 @@ class Mp3InfoTest < Test::Unit::TestCase
     assert_equal( "2.3.0", written_tag.version )
   end
 
+  # test for good output of APIC tag inspect (escaped and snipped)
+  def test_id3v2_to_inspect_hash
+    Mp3Info.open(TEMP_FILE) do |mp3|
+      mp3.tag2.APIC =  "\x00testing.jpg\x00" * 20
+      escaped_str = "\\x00testing.jpg\\x00" * 20
+      snipped_str = escaped_str.unpack('a185').first + "<<<...snip...>>>"     
+      assert_equal(snipped_str, mp3.tag2.to_inspect_hash["APIC"])
+    end
+  end
+
+  def test_id3v2_get_pictures
+    img = "\x89PNG".force_encoding('BINARY') + 
+      random_string(120).force_encoding('BINARY')
+    Mp3Info.open(TEMP_FILE) do |mp3|
+      mp3.tag2.add_picture(img, :description => 'example image.png')
+    end
+    Mp3Info.open(TEMP_FILE) do |mp3|
+      assert_equal(["01_example image.png", img], mp3.tag2.pictures[0])
+    end
+  end
+  
+  def test_id3v2_remove_pictures
+    jpg_data = "\xFF".force_encoding('BINARY') + 
+      random_string(123).force_encoding('BINARY')
+    Mp3Info.open(TEMP_FILE) do |mp|
+      mp.tag2.add_picture(jpg_data)
+    end
+    Mp3Info.open(TEMP_FILE) do |mp|
+      mp.tag2.remove_pictures
+      assert_equal([], mp.tag2.pictures)
+    end
+  end
+
   def test_id3v2_methods
     tag = { "TIT2" => "tit2", "TPE1" => "tpe1" }
     Mp3Info.open(TEMP_FILE) do |mp3|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mp3info
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: '0.8'
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-25 00:00:00.000000000 Z
+date: 2013-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hoe-yard
@@ -34,7 +34,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.4'
+        version: '3.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -42,10 +42,8 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.4'
-description: ! 'ruby-mp3info read low-level informations and manipulate tags on
-
-  mp3 files.'
+        version: '3.5'
+description: ruby-mp3info read low-level informations and manipulate tags on mp3 files.
 email:
 - guillaume.pierronnet@gmail.com
 executables: []
@@ -53,11 +51,10 @@ extensions: []
 extra_rdoc_files:
 - History.txt
 - Manifest.txt
-- README.txt
 files:
 - History.txt
 - Manifest.txt
-- README.txt
+- README.md
 - Rakefile
 - lib/mp3info.rb
 - lib/mp3info/extension_modules.rb

data/README.txt

@@ -1,82 +0,0 @@
-= ruby-mp3info
-
-* http://github.com/moumar/ruby-mp3info
-
-== DESCRIPTION:
-
-ruby-mp3info read low-level informations and manipulate tags on
-mp3 files.
-
-== FEATURES/PROBLEMS:
-
-* written in pure ruby 
-* read low-level informations like bitrate, length, samplerate, etc...
-* read, write, remove id3v1 and id3v2 tags
-* correctly read VBR files (with or without Xing header)
-* only 2.3 version is supported for writings id3v2 tags
-* id3v2 tags are always written in UTF-16 encoding
-
-== SYNOPSIS:
-
-  ### read and display infos & tags
-
-  require "mp3info"
-  # read and display infos & tags
-  Mp3Info.open("myfile.mp3") do |mp3info|
-    puts mp3info
-  end
-
-  # read/write tag1 and tag2 with Mp3Info#tag attribute
-  # when reading tag2 have priority over tag1
-  # when writing, each tag is written.
-  Mp3Info.open("myfile.mp3") do |mp3|
-    puts mp3.tag.title   
-    puts mp3.tag.artist   
-    puts mp3.tag.album
-    puts mp3.tag.tracknum
-    mp3.tag.title = "track title"
-    mp3.tag.artist = "artist name"
-  end
-
-  # tags are written when calling Mp3Info#close or at the end of the #open block
-
-  ### access id3v2 tags
-
-  Mp3Info.open("myfile.mp3") do |mp3|
-    # you can access four letter v2 tags like this
-    puts mp3.tag2.TIT2
-    mp3.tag2.TIT2 = "new TIT2"
-    # or like that
-    mp3.tag2["TIT2"]
-    # at this time, only COMM tag is processed after reading and before writing
-    # according to ID3v2#options hash
-    mp3.tag2.options[:lang] = "FRE"
-    mp3.tag2.COMM = "my comment in french, correctly handled when reading and writing"
-  end
-
-== REQUIREMENTS:
-
-* iconv when using ruby 1.8
-
-== INSTALL:
-
-* gem install ruby-mp3info
-
-== DEVELOPERS:
-
-After checking out the source, run:
-
-  $ rake newb
-
-This task will install any missing dependencies, run the tests/specs,
-and generate the RDoc.
-
-== LICENSE:
-
-ruby
-
-== TODO:
-
-* encoder detection
-* support for more tags in id3v2
-* generalize id3v2 with other audio formats (APE, MPC, OGG, etc...)