id3_tags 0.0.1

data/lib/id3_tags.rb

@@ -0,0 +1,182 @@
+require 'taglib'
+require 'active_support/core_ext/hash'
+
+# Provides two methods to read and write ID3 metadata from an MP3 file
+module Id3Tags
+
+  # Returns a Hash of ID3 attributes stored in the file located at +file_path+.
+  #
+  # @param [String] file_path Local path to an MP3 file
+  # @return [Hash] the ID3 attributes stored in the file
+  #
+  # @example Read tags from an MP3 full of metadata
+  #   Id3Tags.read_tags_from("all_id3.mp3")
+  #
+  #    # => {title: "Sample track", album: "Sample album", artist: Sample
+  #          artist", :comment=>"Sample comments", genre: "Sample Genre",
+  #          year: 1979, bitrate: 128, channels: 2, length: 38, samplerate:
+  #          44100, bpm: 110, lyrics: "Sample lyrics line 1\rand line 2",
+  #          composer: "Sample composer", grouping: "Sample group",
+  #          album_artist: "Sample album artist", compilation: true, track:
+  #          {number: 3, count: 12}, disk: {number: 1, count: 2}, cover_art:
+  #          {mime_type: "image/png", data: "\x89PNG\r\n\x1A[...]"}}
+  def self.read_tags_from(file_path)
+    attrs = {}
+    TagLib::MPEG::File.open(file_path) do |file|
+      tag_fields.each do |field, opts|
+        value = file.tag.send opts[:method]
+        assign! attrs, field, value, opts[:type]
+      end unless file.tag.nil?
+
+      audio_properties_fields.each do |field, opts|
+        value = file.audio_properties.send opts[:method]
+        assign! attrs, field, value, opts[:type]
+      end unless file.audio_properties.nil?
+
+      id3v2_tag_fields.each do |field, opts|
+        value = file.id3v2_tag.frame_list(opts[:frame_id]).first
+        value = value.to_string if value and opts[:type] != :image
+        assign! attrs, field, value, opts[:type]
+      end unless file.id3v2_tag.nil?
+    end
+
+    attrs.symbolize_keys
+  end
+
+  # Stores the +attrs+ Hash of ID3 attributes into the file at +file_path+.
+  #
+  # @param [String] file_path Local path to an MP3 file
+  # @param [Hash] attrs the ID3 attributes stored in the file
+  # @return [Boolean] true (the file gets changed)
+  #
+  # @example Write ID3 tags to an MP3 file
+  #   Id3Tags.write_tags_to("no_id3.mp3", {title: "Sample track", album:
+  #        "Sample album", artist: Sample artist", :comment=>"Sample comments",
+  #        genre: "Sample Genre", year: 1979, bitrate: 128, channels: 2,
+  #        length: 38, samplerate: 44100, bpm: 110, lyrics: "Sample lyrics
+  #        line 1\rand line 2", composer: "Sample composer", grouping: "Sample
+  #        group", album_artist: "Sample album artist", compilation: true,
+  #        track: {number: 3, count: 12}, disk: {number: 1, count: 2},
+  #        cover_art: {mime_type: "image/png", data: "\x89PNG\r\n\x1A[...]"}}
+  #
+  #    # => true
+  def self.write_tags_to(file_path, attrs = {})
+    attrs.symbolize_keys!
+
+    TagLib::MPEG::File.open(file_path) do |file|
+      tag_fields.each do |field, opts|
+        file.tag.send "#{opts[:method]}=", (attrs[field] || opts[:default])
+      end unless file.tag.nil?
+
+      id3v2_tag_fields.each do |field, opts|
+        file.id3v2_tag.remove_frames opts[:frame_id]
+        frame = new_frame_for attrs[field], opts[:frame_id], opts[:type]
+        file.id3v2_tag.add_frame frame if frame
+      end unless file.id3v2_tag.nil?
+
+      file.save
+    end
+  end
+
+  # @private
+  def self.fields
+    {
+    title:       {on: :tag, method: :title, type: :string},
+    album:       {on: :tag, method: :album, type: :string},
+    artist:      {on: :tag, method: :artist, type: :string},
+    comment:     {on: :tag, method: :comment, type: :string},
+    genre:       {on: :tag, method: :genre, type: :string},
+    year:        {on: :tag, method: :year, type: :integer, default: 0},
+    bitrate:     {on: :audio_properties, method: :bitrate, type: :integer},
+    channels:    {on: :audio_properties, method: :channels, type: :integer},
+    length:      {on: :audio_properties, method: :length, type: :integer},
+    samplerate:  {on: :audio_properties, method: :sample_rate, type: :integer},
+    bpm:         {on: :id3v2_tag, frame_id: 'TBPM', type: :integer},
+    lyrics:      {on: :id3v2_tag, frame_id: 'USLT', type: :text},
+    composer:    {on: :id3v2_tag, frame_id: 'TCOM', type: :string},
+    grouping:    {on: :id3v2_tag, frame_id: 'TIT1', type: :string},
+    album_artist:{on: :id3v2_tag, frame_id: 'TPE2', type: :string},
+    compilation: {on: :id3v2_tag, frame_id: 'TCMP', type: :boolean},
+    track:       {on: :id3v2_tag, frame_id: 'TRCK', type: :pair},
+    disk:        {on: :id3v2_tag, frame_id: 'TPOS', type: :pair},
+    cover_art:   {on: :id3v2_tag, frame_id: 'APIC', type: :image},
+    }
+  end
+
+  # @private
+  def self.tag_fields
+    fields.select{|k,v| v[:on] == :tag}
+  end
+
+  # @private
+  def self.audio_properties_fields
+    fields.select{|k,v| v[:on] == :audio_properties }
+  end
+
+  # @private
+  def self.id3v2_tag_fields
+    fields.select{|k,v| v[:on] == :id3v2_tag }
+  end
+
+  # @private
+  def self.assign!(attrs, field, value, type)
+    case type
+    when :string, :text
+      attrs[field] = value && value.to_s
+    when :integer
+      attrs[field] = value && value.to_i
+    when :boolean
+      attrs[field] = value.present? && value.eql?('1')
+    when :pair
+      pair = value ? value.split('/').map(&:to_i) : [nil, nil]
+      attrs[field] = {number: pair[0], count: pair[1]}
+    when :image
+      pair = [value && value.mime_type, value && value.picture].map(&:presence)
+      attrs[field] = {mime_type: pair[0], data: pair[1]}
+    end
+  end
+
+  # @private
+  def self.new_frame_for(content, frame_id, type)
+    return if content.nil?
+    case type
+    when :string, :integer
+      frame = new_string_frame(frame_id)
+      frame.text = content.to_s
+    when :text
+      frame = new_text_frame(frame_id)
+      frame.text = content.to_s
+    when :boolean
+      return unless content.eql?(true)
+      frame = new_string_frame(frame_id)
+      frame.text = '1'
+    when :pair
+      return unless content.has_key? :number
+      frame = new_string_frame(frame_id)
+      frame.text = content.values_at(:number, :count).compact.join '/'
+    when :image
+      return unless content.has_key? :data
+      frame = new_image_frame(frame_id)
+      frame.description = 'Cover'
+      frame.type = TagLib::ID3v2::AttachedPictureFrame::FrontCover
+      frame.mime_type = content[:mime_type]
+      frame.picture = content[:data]
+    end
+    frame
+  end
+
+  # @private
+  def self.new_string_frame(frame_id)
+    TagLib::ID3v2::TextIdentificationFrame.new frame_id, TagLib::String::UTF8
+  end
+
+  # @private
+  def self.new_text_frame(frame_id)
+    TagLib::ID3v2::UnsynchronizedLyricsFrame.new frame_id
+  end
+
+  # @private
+  def self.new_image_frame(frame_id)
+    TagLib::ID3v2::AttachedPictureFrame.new frame_id
+  end
+end

data/spec/helpers/duplicate_file_helper.rb

@@ -0,0 +1,11 @@
+require 'tmpdir'
+
+def with_duplicate_file_of(original)
+  duplicate = File.join Dir.tmpdir, File.basename(original)
+  begin
+    FileUtils.cp original, duplicate
+    yield(duplicate)
+  ensure
+    FileUtils.rm duplicate
+  end
+end

data/spec/lib/idempotency_spec.rb

@@ -0,0 +1,14 @@
+require 'id3_tags'
+require_relative '../helpers/duplicate_file_helper'
+
+describe Id3Tags do
+  it 'does not alter tracks after reading AND writing the metadata' do
+    original = File.join File.dirname(__FILE__), '../assets/all_id3.mp3'
+    original_id3_tags = Id3Tags.read_tags_from(original)
+    with_duplicate_file_of(original) do |duplicate|
+      Id3Tags.write_tags_to(duplicate, original_id3_tags)
+      Id3Tags.read_tags_from(duplicate).should == original_id3_tags
+      FileUtils.identical?(original, duplicate).should be_true
+    end
+  end
+end

data/spec/lib/read_id3_tags_spec.rb

@@ -0,0 +1,72 @@
+require 'id3_tags'
+
+describe 'Id3Tags.read_tags_from' do
+  context 'given a track with all the ID3 metadata' do
+    let(:track_with_metadata) {File.join File.dirname(__FILE__), '../assets/all_id3.mp3'}
+
+    it 'returns all the ID3 tag with the right value' do
+      id3_tags = Id3Tags.read_tags_from track_with_metadata
+
+      id3_tags.keys.should =~ [:album, :artist, :comment, :genre, :samplerate,
+        :track, :disk, :title, :year, :bitrate, :channels, :length, :grouping,
+        :album_artist, :composer, :bpm, :lyrics, :compilation, :cover_art]
+      id3_tags[:title].should == 'Sample track'
+      id3_tags[:album].should == 'Sample album'
+      id3_tags[:artist].should == 'Sample artist'
+      id3_tags[:comment].should == 'Sample comments'
+      id3_tags[:genre].should == 'Sample Genre'
+      id3_tags[:year].should == 1979
+      id3_tags[:track][:number].should == 3
+      id3_tags[:track][:count].should == 12
+      id3_tags[:disk][:number].should == 1
+      id3_tags[:disk][:count].should == 2
+      id3_tags[:bitrate].should == 128
+      id3_tags[:channels].should == 2
+      id3_tags[:length].should == 38
+      id3_tags[:samplerate].should == 44100
+      id3_tags[:album_artist].should == 'Sample album artist'
+      id3_tags[:composer].should == 'Sample composer'
+      id3_tags[:grouping].should == 'Sample group'
+      id3_tags[:bpm].should == 110
+      id3_tags[:lyrics].should == "Sample lyrics line 1\rand line 2"
+      id3_tags[:compilation].should be_true
+      id3_tags[:cover_art][:mime_type].should == 'image/png'
+      id3_tags[:cover_art][:data].length.should == 3368
+    end
+  end
+
+  context 'given a track with no ID3 metadata' do
+    let(:track_with_metadata) {File.join File.dirname(__FILE__), '../assets/no_id3.mp3'}
+
+    it 'returns all the ID3 tag with a nil value' do
+      id3_tags = Id3Tags.read_tags_from track_with_metadata
+
+      id3_tags.keys.should =~ [:album, :artist, :comment, :genre, :samplerate,
+        :track, :disk, :title, :year, :bitrate, :channels, :length, :grouping,
+        :album_artist, :composer, :bpm, :lyrics, :compilation, :cover_art]
+
+      id3_tags[:title].should == ' ' # can never be nil
+      id3_tags[:album].should be_nil
+      id3_tags[:artist].should be_nil
+      id3_tags[:comment].should be_nil
+      id3_tags[:genre].should be_nil
+      id3_tags[:year].should == 0 # can never be nil
+      id3_tags[:track][:number].should be_nil
+      id3_tags[:track][:count].should be_nil
+      id3_tags[:disk][:number].should be_nil
+      id3_tags[:disk][:count].should be_nil
+      id3_tags[:bitrate].should == 128 # can never be nil
+      id3_tags[:channels].should == 2 # can never be nil
+      id3_tags[:length].should == 38 # can never be nil
+      id3_tags[:samplerate].should == 44100 # can never be nil
+      id3_tags[:album_artist].should be_nil
+      id3_tags[:composer].should be_nil
+      id3_tags[:grouping].should be_nil
+      id3_tags[:bpm].should be_nil
+      id3_tags[:lyrics].should be_nil
+      id3_tags[:compilation].should be_false
+      id3_tags[:cover_art][:mime_type].should be_nil
+      id3_tags[:cover_art][:data].should be_nil
+    end
+  end
+end

data/spec/lib/write_id3_tags_spec.rb

@@ -0,0 +1,67 @@
+require 'id3_tags'
+require_relative '../helpers/duplicate_file_helper'
+
+describe 'Id3Tags.write_tags_to' do
+  context 'given a track with all the ID3 metadata and a Hash of empty ID3' do
+    let(:original_track) {File.join File.dirname(__FILE__), '../assets/all_id3.mp3'}
+    let(:new_metadata) { {} }
+
+    it 'resets all the editable ID3 tags of the track to nil' do
+      with_duplicate_file_of(original_track) do |duplicate|
+        Id3Tags.write_tags_to(duplicate, new_metadata)
+        id3_tags = Id3Tags.read_tags_from(duplicate)
+        [:album, :artist, :comment, :genre, :title, :grouping, :lyrics,
+         :album_artist, :composer, :bpm].each do |field|
+          id3_tags[field].should be_nil
+        end
+        id3_tags[:year].should == 0
+        id3_tags[:compilation].should be_false
+        # NOTE: Taglib does NOT allow the track_number to be nil; the old
+        #       value is persisted in this case, so we cannot test for nil?
+        #id3_tags[:track][:number].should be_nil
+        id3_tags[:track][:count].should be_nil
+        id3_tags[:disk][:number].should be_nil
+        id3_tags[:disk][:count].should be_nil
+        id3_tags[:cover_art][:mime_type].should be_nil
+        id3_tags[:cover_art][:data].should be_nil
+      end
+    end
+  end
+
+  context 'given a track with no metadata and a Hash full of ID3' do
+    let(:original_track) {File.join File.dirname(__FILE__), '../assets/no_id3.mp3'}
+    let(:new_cover_art) {File.join File.dirname(__FILE__), '../assets/black_pixel.png'}
+    let(:new_cover_art_data) {File.open(new_cover_art, 'rb') {|io| io.read}}
+    let(:new_metadata) { {title: "A track", album: "An album", artist:
+      "An artist", year: 2012, comment: "A comment", genre: "A genre", bpm: 68,
+      composer: "A composer", lyrics: "A lyrics line 1\rand line 2",
+      album_artist: "An album artist", grouping: "A group", compilation: true,
+      track: {number: 1, count: 24}, disk: {number: 1, count: 2}, cover_art:
+      {mime_type: "image/png", data: new_cover_art_data}}
+    }
+
+    it 'sets all the editable ID3 tags of a track' do
+      with_duplicate_file_of(original_track) do |duplicate|
+        Id3Tags.write_tags_to(duplicate, new_metadata)
+        id3_tags = Id3Tags.read_tags_from(duplicate)
+        id3_tags[:album].should == 'An album'
+        id3_tags[:artist].should == 'An artist'
+        id3_tags[:comment].should == 'A comment'
+        id3_tags[:genre].should == 'A genre'
+        id3_tags[:title].should == 'A track'
+        id3_tags[:grouping].should == 'A group'
+        id3_tags[:lyrics].should == "A lyrics line 1\rand line 2"
+        id3_tags[:album_artist].should == 'An album artist'
+        id3_tags[:composer].should == 'A composer'
+        id3_tags[:bpm].should == 68
+        id3_tags[:compilation].should be_true
+        id3_tags[:track][:number].should == 1
+        id3_tags[:track][:count].should == 24
+        id3_tags[:disk][:number].should == 1
+        id3_tags[:disk][:count].should == 2
+        id3_tags[:cover_art][:mime_type].should == 'image/png'
+        id3_tags[:cover_art][:data].should == new_cover_art_data
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,207 @@
+--- !ruby/object:Gem::Specification
+name: id3_tags
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Claudio Baccigalupo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: taglib-ruby
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Read and write ID3 metadata from/to MP3 files
+email:
+- claudio@topspinmedia.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- HISTORY.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- TODO.md
+- doc/Id3Tags.html
+- doc/_index.html
+- doc/class_list.html
+- doc/css/common.css
+- doc/css/full_list.css
+- doc/css/style.css
+- doc/file.README.html
+- doc/file_list.html
+- doc/frames.html
+- doc/index.html
+- doc/js/app.js
+- doc/js/full_list.js
+- doc/js/jquery.js
+- doc/method_list.html
+- doc/top-level-namespace.html
+- id3_tags.gemspec
+- lib/id3_tags.rb
+- lib/id3_tags/version.rb
+- spec/assets/all_id3.mp3
+- spec/assets/black_pixel.png
+- spec/assets/no_id3.mp3
+- spec/helpers/duplicate_file_helper.rb
+- spec/lib/idempotency_spec.rb
+- spec/lib/read_id3_tags_spec.rb
+- spec/lib/write_id3_tags_spec.rb
+homepage: https://github.com/topspin/id3_tags
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -1313956793775071095
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -1313956793775071095
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: ! 'Id3Tags provides two methods: * read_tags_from, which reads an MP3 file
+  and returns a Hash of metadata * write_tags_to, which writes a Hash of metadata
+  into an MP3 file'
+test_files:
+- spec/assets/all_id3.mp3
+- spec/assets/black_pixel.png
+- spec/assets/no_id3.mp3
+- spec/helpers/duplicate_file_helper.rb
+- spec/lib/idempotency_spec.rb
+- spec/lib/read_id3_tags_spec.rb
+- spec/lib/write_id3_tags_spec.rb
+has_rdoc: