easytag 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d32bfe7e7828920f2801fd17d56c52362eeb9a97
+  data.tar.gz: 2e8739c3b7ed170e5db24ab52e75fb6494d777c6
+SHA512:
+  metadata.gz: fc522bd6064e15d3e08bfc13d0e0a5ff659730f7a684c4141ad3551e8dbce792bec92f9cee40a8772c64a991352d6d8be600d67b9c02fb696779c47e1485bb52
+  data.tar.gz: 41a958d976e06dd70321632b9b080d350ed82b2069124f26092b79f732f24fb90eadc0556368b277d977116a7196b78ca6d610468130f86a2eeac1a85a016b78

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+##### v0.2.0 (Not yet released) #####
+* added:
+  - `#track_num`
+  - `#disc_num`
+  - `#user_info`
+  - `#disc_subtitle`
+  - `#media`
+  - `#label`
+  - `#title_sort_order`
+  - `#artist_sort_order`
+  - `#album_artist_sort_order`
+  - `#album_sort_order`
+  - `#original_date`
+* fixed: bug related to M4A files without artwork
+
+##### v0.1.0 (2013-05-23) #####
+* initial release

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# read dependencies from gemspec file
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Chris Lucas <chris@chrisjlucas.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,52 @@
+EasyTag is an abstraction layer to the [TagLib](http://taglib.github.io/) audio tagging library. It is designed to provide a simple and consistent API regardless of file format being read.
+
+A quick reference to which attributes are currently supported can be found [here](https://github.com/cjlucas/ruby-easytag/wiki/Currently-Supported-Attributes).
+
+[![Build Status (master)](https://travis-ci.org/cjlucas/ruby-easytag.png?branch=master "Branch: master")](https://travis-ci.org/cjlucas/ruby-easytag)
+[![Build Status (develop)](https://travis-ci.org/cjlucas/ruby-easytag.png?branch=develop "Branch: develop")](https://travis-ci.org/cjlucas/ruby-easytag)
+
+---
+## Synopsis ##
+```ruby
+require 'easytag'
+
+mp3 = EasyTag::File.new("01 Shout Out Loud.mp3")
+
+# easy access to attributes
+mp3.title
+# => "Shout Out Loud"
+mp3.artist
+# => "Amos Lee"
+mp3.year
+# => 2006
+mp3.date
+# => #<DateTime: 2006-10-03T00:00:00+00:00 ((2454012j,0s,0n),+0s,2299161j)>
+mp3.album_art
+# => [#<EasyTag::Image:0x007f7fa542f528>]
+
+# get access to the taglib-powered backend
+mp3.info
+# => #<TagLib::MPEG::File:0x007f7fa539e050 @__swigtype__="_p_TagLib__MPEG__File">
+mp3.close
+
+# A block interface is also available
+EasyTag::File.open('01 Shout Out Loud.m4a') do |m4a|
+  puts m4a.title
+  puts m4a.comments
+  puts m4a.genre
+end
+```
+## Requirements ##
+- Ruby versions
+  - 1.9
+  - 2.0
+- Dependencies
+  - [TagLib](http://taglib.github.io/) (1.8+)
+  - [taglib-ruby](https://github.com/robinst/taglib-ruby) (0.6.0+)
+  - [ruby-mp3info](https://github.com/moumar/ruby-mp3info)
+  - [ruby-imagespec](https://github.com/andersonbrandon/ruby-imagespec)
+
+## TODO ##
+- API Documentation
+- FLAC and OGG support
+- Write support

data/Rakefile

@@ -0,0 +1,27 @@
+$LOAD_PATH.unshift(File.expand_path('../lib', __FILE__))
+
+require 'rake/testtask'
+
+require 'easytag/version'
+
+task :default => [:test]
+
+task :test do
+  Rake::TestTask.new do |t|
+    t.libs << 'test'
+    t.test_files = FileList['test/test_*.rb']
+    t.verbose = false
+  end
+end
+
+task :build do
+  system 'gem build easytag.gemspec'
+end
+
+task :release => :build do
+  system "gem push easytag-#{EasyTag::VERSION}.gem"
+end
+
+task :clean do
+  system 'rm -f *.gem'
+end

data/easytag.gemspec

@@ -0,0 +1,23 @@
+$LOAD_PATH.unshift(File.expand_path('../lib', __FILE__))
+
+require 'easytag/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'easytag'
+  s.version     = EasyTag::VERSION
+  s.summary     = 'A simple audio metadata tagging interface'
+  s.description = `head -n1 README.md | ./bin/strip_md.rb`
+  s.authors     = ['Chris Lucas']
+  s.email       = ['chris@chrisjlucas.com']
+  s.homepage    = 'https://github.com/cjlucas/ruby-easytag'
+  s.license     = 'MIT'
+  s.files       = `git ls-files | egrep '^[^\.]'`.split(/\r?\n/)
+  s.test_files  = s.files.select { |f| f.match(/^test\/.*\.rb$/) }
+  s.platform    = Gem::Platform::RUBY
+
+  s.add_runtime_dependency('taglib-ruby', '>= 0.6.0')
+  s.add_runtime_dependency('ruby-imagespec', '>= 0.3.1')
+  s.add_runtime_dependency('ruby-mp3info', '>= 0.8')
+
+  s.add_development_dependency('rake')
+end

data/lib/easytag.rb

@@ -0,0 +1,5 @@
+require 'bundler/setup'
+
+require 'easytag/util'
+require 'easytag/file'
+require 'easytag/interfaces'

data/lib/easytag/base.rb

@@ -0,0 +1,30 @@
+require 'taglib'
+
+require 'easytag/interfaces'
+
+module EasyTag
+  class EasyTagFileUnsupportedError < Exception; end
+
+  class Base
+    attr_reader :interface
+
+    def self.build_proxy_methods(iface)
+      # generate dynamic getters
+      (iface.instance_methods - Object.instance_methods).each do |m|
+        define_method(m) { proxy_getter(m) }
+      end
+    end
+
+    def proxy_getter(m)
+      if @interface.respond_to?(m)
+        @interface.send(m)
+      else
+        warn "#{@interface.class} doesn't support method #{m}"
+      end
+    end
+
+    # dynamic instance method generation
+    EasyTag::Interfaces.all.each { |iface| self.build_proxy_methods(iface) }
+  end
+end
+

data/lib/easytag/file.rb

@@ -0,0 +1,42 @@
+require 'easytag/base'
+
+module EasyTag
+  class File < Base
+    attr_reader :file
+
+    def initialize(file)
+      @file = file
+
+      if audio_interface_class.nil?
+        raise AudioMetadataProxyFileUnsupportedError.new(
+          "Couldn't determine which interface to use")
+      end
+
+      @interface = audio_interface_class.new(file)
+    end
+
+    # block interface
+    def self.open(file)
+      interface = self.new(file)
+      begin
+        yield interface if block_given?
+      ensure
+        interface.close if interface.respond_to?(:close)
+      end
+    end
+
+    private
+    # sufficient for now
+    def audio_interface_class
+      ext = ::File.extname(@file).downcase[1..-1]
+      case ext
+      when 'mp3'
+        EasyTag::Interfaces::MP3
+      when 'mp4', 'm4a', 'aac'
+        EasyTag::Interfaces::MP4
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/easytag/image.rb

@@ -0,0 +1,84 @@
+require 'image_spec'
+
+module EasyTag
+  # mimics constants of TagLib::ID3v2::AttachedPictureFrame
+  class ImageType
+    None               = -1
+    Other              = 0
+    FileIcon           = 1
+    OtherFileIcon      = 2
+    FrontCover         = 3
+    BackCover          = 4
+    LeafletPage        = 5
+    Media              = 6
+    LeadArtist         = 7
+    Artist             = 8
+    Conductor          = 9
+    Band               = 10
+    Composer           = 11
+    Lyricist           = 12
+    RecordingLocation  = 13
+    DuringRecording    = 14
+    DuringPerformance  = 15
+    MovieScreenCapture = 16
+    ColouredFish       = 17
+    Illustration       = 18
+    BandLogo           = 19
+    PublisherLogo      = 20
+
+    IMAGE_TYPE_TO_STRING_MAP = {
+      None               => '',
+      Other              => 'Other',
+      FileIcon           => 'File Icon (small)',
+      OtherFileIcon      => 'File Icon',
+      FrontCover         => 'Cover (front)',
+      BackCover          => 'Cover (back)',
+      LeafletPage        => 'Leaflet',
+      Media              => 'Media',
+      LeadArtist         => 'Lead Artist',
+      Artist             => 'Artist',
+      Conductor          => 'Conductor',
+      Band               => 'Band',
+      Composer           => 'Composer',
+      Lyricist           => 'Lyricist',
+      RecordingLocation  => 'Recording Location',
+      DuringRecording    => 'During Recording',
+      DuringPerformance  => 'During Performance',
+      MovieScreenCapture => 'Video Capture',
+      ColouredFish       => 'A Bright Colored Fish',
+      Illustration       => 'Illustration',
+      BandLogo           => 'Band Logo',
+      PublisherLogo      => 'Publisher Logo'
+    }
+
+  end
+
+  class Image
+    attr_reader :width, :height, :size
+    attr_accessor :data, :desc, :mime_type, :type, :type_s
+
+    def initialize(data)
+      self.data = data
+      type = ImageType::None
+    end
+
+    def type_s
+      ImageType::IMAGE_TYPE_TO_STRING_MAP[type]
+    end
+
+    def data=(data)
+      @data = data
+      @size = @data.length
+
+      begin
+        spec = ImageSpec.new(StringIO.new(data, 'rb'))
+        @mime_type = spec.content_type
+        @width     = spec.width
+        @height    = spec.height
+      rescue ImageSpec::Error => e
+        nil
+      end
+    end
+  end
+end
+

data/lib/easytag/interfaces.rb

@@ -0,0 +1,18 @@
+require 'easytag/image'
+require 'easytag/interfaces/base'
+require 'easytag/interfaces/mp3'
+require 'easytag/interfaces/mp4'
+
+module EasyTag::Interfaces
+  # get all audio interfaces
+  def self.all
+    # get all classes in Interfaces
+    classes = self.constants.map do |sym|
+      const = self.const_get(sym)
+      const if const.class == Class && const.method_defined?(:info)
+    end
+
+    # filter out nil's
+    classes.compact
+  end
+end

data/lib/easytag/interfaces/base.rb

@@ -0,0 +1,21 @@
+module EasyTag
+  module Interfaces
+    class Base
+      attr_reader :info
+
+      # avoid returing empty objects
+      def self.obj_or_nil(o)
+        if o.class == String
+          ret = o.empty? ? nil : o
+        else
+          o
+        end
+      end
+
+      def close
+        @info.close
+      end
+
+    end
+  end
+end

data/lib/easytag/interfaces/mp3.rb

@@ -0,0 +1,186 @@
+require 'mp3info'
+
+require 'easytag'
+
+module EasyTag::Interfaces
+
+  class MP3 < Base
+    def initialize(file)
+      @info = TagLib::MPEG::File.new(file)
+      @id3v1 = @info.id3v1_tag
+      @id3v2 = @info.id3v2_tag
+
+      # this is required because taglib hash issues with the TDAT/TYER
+      # frame (https://github.com/taglib/taglib/issues/127)
+      @id3v2_hash = ID3v2.new
+
+      File.open(file) do |fp|
+        fp.read(3) # read past ID3 identifier
+        begin
+          @id3v2_hash.from_io(fp)
+        rescue ID3v2Error => e
+          warn 'no id3v2 tags found'
+        end
+      end
+
+    end
+
+    def title
+      obj_for_frame_id('TIT2') or Base.obj_or_nil(@id3v1.title)
+    end
+
+    def title_sort_order
+      # TSOT - (v2.4 only)
+      # XSOT - Musicbrainz Picard custom
+      obj_for_frame_id('TSOT') || obj_for_frame_id('XSOT')
+    end
+
+    def artist
+      obj_for_frame_id('TPE1') or Base.obj_or_nil(@id3v1.artist)
+    end
+
+    def artist_sort_order
+      # TSOP - (v2.4 only)
+      # XSOP - Musicbrainz Picard custom
+      obj_for_frame_id('TSOP') || obj_for_frame_id('XSOP')
+    end
+
+    def album_artist
+      obj_for_frame_id('TPE2')
+    end
+
+    def album_artist_sort_order
+      user_info[:albumartistsort]
+    end
+
+    def album
+      obj_for_frame_id('TALB') or Base.obj_or_nil(@id3v1.album)
+    end
+
+    def album_sort_order
+      # TSOA - (v2.4 only)
+      # XSOA - Musicbrainz Picard custom
+      obj_for_frame_id('TSOA') || obj_for_frame_id('XSOA')
+    end
+
+    # REVIEW: TCON supports genre refining, which we currently don't utilize
+    def genre
+      obj_for_frame_id('TCON') or Base.obj_or_nil(@id3v1.genre)
+    end
+
+    def comments
+      return @comments unless @comments.nil?
+
+      comm_frame = lookup_frames('COMM').first
+      comm_str = comm_frame ? comm_frame.text : @id3v1.comment
+
+      @comments = Base.obj_or_nil(comm_str)
+    end
+
+    def year
+      date.nil? ? 0 : date.year
+    end
+
+    def date
+      return @date unless @date.nil?
+
+      v10_year = @id3v1.year.to_s if @id3v1.year > 0
+      v23_year = obj_for_frame_id('TYER')
+      v23_date = Base.obj_or_nil(@id3v2_hash['TDAT'])
+      v24_date = obj_for_frame_id('TDRC')
+
+      # check variables in order of importance
+      date_str = v24_date || v23_year || v10_year
+      # only append v23_date if date_str is currently a year
+      date_str << v23_date unless v23_date.nil? or date_str.length > 4
+      puts "MP3#date: date_str = \"#{date_str}\"" if $DEBUG
+
+      @date = EasyTag::Utilities.get_datetime(date_str)
+    end
+
+    def original_date
+      return @original_date unless @original_date.nil?
+
+      # TDOR - orig release date (v2.4 only)
+      # TORY - orig release year (v2.3)
+      date_str = obj_for_frame_id('TDOR') ||  obj_for_frame_id('TORY')
+      @original_date ||= EasyTag::Utilities.get_datetime(date_str)
+    end
+
+    def album_art
+      return @album_art unless @album_art.nil?
+
+      @album_art = []
+      @id3v2.frame_list('APIC').each do |apic|
+        img           = EasyTag::Image.new(apic.picture)
+        img.desc      = apic.description
+        img.type      = apic.type
+        img.mime_type = apic.mime_type
+
+        @album_art << img
+      end
+
+      @album_art
+    end
+
+    def track_num
+      return @track_num unless @track_num.nil?
+
+      pair = int_pair_for_frame_id('TRCK')
+      @track_num = (pair == [0, 0]) ? [@id3v1.track, 0] : pair
+    end
+
+    def disc_num
+      int_pair_for_frame_id('TPOS')
+    end
+
+    def user_info
+      return @user_info unless @user_info.nil?
+
+      @user_info = {}
+      lookup_frames('TXXX').each do |frame|
+        key, value = frame.field_list
+        key = EasyTag::Utilities.normalize_string(key)
+        @user_info[key.to_sym] = value
+      end
+
+      @user_info
+    end
+
+    def disc_subtitle
+      obj_for_frame_id('TSST')
+    end
+
+    def media
+      obj_for_frame_id('TMED')
+    end
+
+    def label
+      obj_for_frame_id('TPUB')
+    end
+
+    private
+
+    # for TPOS and TRCK
+    def int_pair_for_frame_id(frame_id)
+      str = obj_for_frame_id(frame_id)
+      EasyTag::Utilities.get_int_pair(str)
+    end
+
+    def obj_for_frame_id(frame_id)
+      Base.obj_or_nil(lookup_first_field(frame_id))
+    end
+
+    def lookup_frames(frame_id)
+      frames = @id3v2.frame_list(frame_id)
+    end
+
+    # get the first field in the first frame
+    def lookup_first_field(frame_id)
+      frame = lookup_frames(frame_id).first
+      warn "frame '#{frame_id}' is not present" if frame.nil?
+      frame.field_list.first unless frame.nil?
+    end
+  end
+end
+

data/lib/easytag/interfaces/mp4.rb

@@ -0,0 +1,188 @@
+# encoding: UTF-8
+
+module EasyTag::Interfaces
+  class MP4 < Base
+    # type of TagLib::MP4::Item
+    module ItemType
+      STRING         = 0 # not part of TagLib::MP4::Item, just for convenience
+      STRING_LIST    = 1
+      BOOL           = 2
+      INT            = 3
+      INT_PAIR       = 4
+      COVER_ART_LIST = 5
+    end
+
+    ITEM_LIST_KEY_MAP = {
+      :aart     => 'aART', # Album Artist
+      :akid     => 'akID',
+      :apid     => 'apID', # Apple ID
+      :atid     => 'atID',
+      :cnid     => 'cnID',
+      :covr     => 'covr', # Cover Art
+      :cpil     => 'cpil',
+      :cprt     => 'cprt',
+      :disk     => 'disk', # Disk [num, total]
+      :geid     => 'geID',
+      :pgap     => 'pgap',
+      :plid     => 'plID',
+      :purd     => 'purd', # Purchase Date
+      :rtng     => 'rtng',
+      :sfid     => 'sfID',
+      :stik     => 'stik',
+      :trkn     => 'trkn', # Track [num, total]
+      :art      => '©ART', # Track Artist
+      :alb      => '©alb', # Album
+      :cmt      => '©cmt', # Comments
+      :day      => '©day', # Release Date
+                           # (ex: 2006, 2004-08-10, 2007-11-27T08:00:00Z)
+      :gen      => '©gen', # Genre
+      :nam      => '©nam', # Title
+      :too      => '©too', # Encoder
+      :soaa     => 'soaa', # Sort Order - Album Artist
+      :soar     => 'soar', # Sort Order - Track Artist
+    }
+
+    def initialize(file)
+      @info = TagLib::MP4::File.new(file)
+      @tag = @info.tag
+    end
+
+    def title
+      obj_for_item_key(:nam, ItemType::STRING)
+    end
+
+    def title_sort_order
+      obj_for_item_key(:sonm, ItemType::STRING)
+    end
+
+    def artist
+      obj_for_item_key(:art, ItemType::STRING)
+    end
+
+    def artist_sort_order
+      obj_for_item_key(:soar, ItemType::STRING)
+    end
+
+    def album_artist
+      obj_for_item_key(:aart, ItemType::STRING)
+    end
+
+    def album_artist_sort_order
+      obj_for_item_key(:soaa, ItemType::STRING)
+    end
+
+    def album
+      obj_for_item_key(:alb, ItemType::STRING)
+    end
+
+    def album_sort_order
+      obj_for_item_key(:soal, ItemType::STRING)
+    end
+
+    def genre
+      obj_for_item_key(:gen, ItemType::STRING)
+    end
+
+    def comments
+      obj_for_item_key(:cmt, ItemType::STRING)
+    end
+
+    # because :day can be anything, including a year, or an exact date,
+    # we'll let #date do the parsing, and just grab the year from it
+    def year
+      date.nil? ? 0 : date.year
+    end
+
+    def date
+      return @date unless @date.nil?
+
+      date_str = obj_for_item_key(:day, ItemType::STRING)
+      @date ||= EasyTag::Utilities.get_datetime(date_str)
+    end
+
+    def album_art
+      return @album_art unless @album_art.nil?
+
+      @album_art = []
+      covers = obj_for_item_key(:covr, ItemType::COVER_ART_LIST) || []
+      covers.each do |cover|
+        @album_art << EasyTag::Image.new(cover.data)
+      end
+
+      @album_art
+    end
+
+    def apple_id
+      obj_for_item_key(:apid, ItemType::STRING)
+    end
+
+    def track_num
+      obj_for_item_key(:trkn, ItemType::INT_PAIR) || [0, 0]
+    end
+
+    def disc_num
+      obj_for_item_key(:disk, ItemType::INT_PAIR) || [0, 0]
+    end
+
+    def user_info
+      return @user_info unless @user_info.nil?
+
+      @user_info = {}
+      @tag.item_list_map.to_a.each do |key, value|
+        match_data = key.match(/\:com.apple.iTunes\:(.*)/)
+        if match_data
+          key = EasyTag::Utilities.normalize_string(match_data[1])
+          @user_info[key.to_sym] = value.to_string_list[0]
+        end
+      end
+
+      @user_info
+    end
+
+    def disc_subtitle
+      user_info[:discsubtitle]
+    end
+
+    def media
+      user_info[:media]
+    end
+
+    def label
+      user_info[:label]
+    end
+
+    private
+    def lookup_item(key)
+      item_id = ITEM_LIST_KEY_MAP.fetch(key, nil)
+      @tag.item_list_map.fetch(item_id) unless item_id.nil?
+    end
+
+    def item_to_obj(item, item_type)
+      case item_type
+      when ItemType::STRING
+        item.to_string_list[0]
+      when ItemType::STRING_LIST
+        item.to_string_list
+      when ItemType::BOOL
+        item.to_bool
+      when ItemType::INT
+        item.to_int
+      when ItemType::INT_PAIR
+        item.to_int_pair
+      when ItemType::COVER_ART_LIST
+        item.to_cover_art_list
+      else
+        nil
+      end
+    end
+
+    def obj_for_item_key(item_key, item_type)
+      return nil if @tag.nil?
+
+      item = lookup_item(item_key)
+      o = item_to_obj(item, item_type) unless item.nil?
+
+      Base.obj_or_nil(o)
+    end
+  end
+end

data/lib/easytag/util.rb

@@ -0,0 +1,63 @@
+require 'date'
+
+module EasyTag
+  module Utilities
+
+    # get_datetime
+    #
+    # return a DateTime object for a given string
+    def self.get_datetime(date_str)
+      return nil if date_str.nil?
+
+      # check for known possible formats
+      case date_str
+      when /^\d{4}$/ # YYYY
+        datetime = DateTime.strptime(date_str, '%Y')
+      when /^\d{4}\-\d{2}$/ # YYYY-MM
+        datetime = DateTime.strptime(date_str, '%Y-%m')
+      when /^\d{4}[0-3]\d[0-1]\d$/ # YYYYDDMM (TYER+TDAT)
+        datetime = DateTime.strptime(date_str, '%Y%d%m')
+      else
+        datetime = nil
+      end
+
+      # let DateTime try to parse the stored date as a last resort
+      if datetime.nil?
+        begin
+          datetime = DateTime.parse(date_str)
+        rescue ArgumentError
+          warn "DateTime couldn't parse '#{date_str}'"
+        end
+      end
+
+      datetime
+    end
+
+    # get_int_pair
+    #
+    # Parses a pos/total string and returns a pair of ints
+    def self.get_int_pair(str)
+      pair = [0, 0]
+
+      unless str.nil? || str.empty?
+        if str.include?('/')
+          pair = str.split('/').map { |it| it.to_i }
+        else
+          pair[0] = str.to_i
+        end
+      end
+
+      pair
+    end
+
+    def self.normalize_string(str)
+      # downcase string
+      str.downcase!
+      # we want snakecase
+      str.gsub!(/\s/, '_')
+      # we only want alphanumeric characters
+      str.gsub(/\W/, '')
+    end
+
+  end
+end

data/lib/easytag/version.rb

@@ -0,0 +1,10 @@
+module EasyTag
+  class Version
+    MAJOR = 0
+    MINOR = 2
+    TINY  = 0
+  end
+ 
+  VERSION = [Version::MAJOR, Version::MINOR, Version::TINY].join('.')
+ 
+end

data/test/test_consistency.rb

@@ -0,0 +1,183 @@
+require 'digest/sha1'
+require 'test/unit'
+
+require 'easytag'
+
+TEST_DIR = File.dirname(File.absolute_path(__FILE__)) << File::SEPARATOR
+
+class TestConsistencyMP301 < Test::Unit::TestCase
+  def setup
+    @mp3 = EasyTag::File.new("#{TEST_DIR}consistency.01.mp3")
+  end
+
+  def test_tags
+    assert_equal('Track Title',         @mp3.title)
+    assert_equal('Artist Name Here',    @mp3.artist)
+    assert_equal('Album Artist Here',   @mp3.album_artist)
+    assert_equal('Album Name Here',     @mp3.album)
+    assert_equal('This is my comment.', @mp3.comments)
+    assert_equal('Polka',               @mp3.genre)
+    assert_equal(1941,                  @mp3.year)
+    assert_equal([5, 0],                @mp3.track_num)
+    assert_equal([3, 0],                @mp3.disc_num)
+  end
+
+  def test_date
+    assert_equal(1941, @mp3.date.year)
+    assert_equal(12,   @mp3.date.month)
+    assert_equal(7,    @mp3.date.day)
+  end
+
+  def test_album_art
+    assert_equal(2, @mp3.album_art.count)
+
+    sha1 = Digest::SHA1.hexdigest(@mp3.album_art[0].data)
+    assert_equal('this is the front cover', @mp3.album_art[0].desc)
+    assert_equal('Cover (front)',           @mp3.album_art[0].type_s)
+    assert_equal('image/jpeg',              @mp3.album_art[0].mime_type)
+    assert_equal(10,                        @mp3.album_art[0].width)
+    assert_equal(5,                         @mp3.album_art[0].height)
+    assert_equal('6555697ca1bf96117608bfb5a44c05cb622f88eb', sha1)
+
+    sha1 = Digest::SHA1.hexdigest(@mp3.album_art[1].data)
+    assert_equal('this is the artist', @mp3.album_art[1].desc)
+    assert_equal('Artist',             @mp3.album_art[1].type_s)
+    assert_equal('image/png',          @mp3.album_art[1].mime_type)
+    assert_equal(10,                   @mp3.album_art[1].width)
+    assert_equal(5,                    @mp3.album_art[1].height)
+    assert_equal('9db2996823fb44ed64dfc8f57dc9df3b970c6b22', sha1)
+  end
+end
+
+class TestConsistency01 < Test::Unit::TestCase
+  def setup
+    @mp3 = EasyTag::File.new("#{TEST_DIR}consistency.01.mp3")
+    @mp4 = EasyTag::File.new("#{TEST_DIR}consistency.01.m4a")
+  end
+
+  def test_tags
+    assert_equal(@mp3.title, @mp4.title)
+    assert_equal(@mp3.artist, @mp4.artist)
+    assert_equal(@mp3.album_artist, @mp4.album_artist)
+    assert_equal(@mp3.album, @mp4.album)
+    assert_equal(@mp3.comments, @mp4.comments)
+    assert_equal(@mp3.genre, @mp4.genre)
+    assert_equal(@mp3.year, @mp4.year)
+  end
+
+  def test_date
+    # MP4 only supports year, so thats all we can test
+    assert_equal(@mp3.date.year, @mp4.date.year)
+  end
+
+  def test_album_art
+    # we're limited to what we can compare here, since mp4 is so limited
+    img_mp3 = @mp3.album_art[0]
+    img_mp4 = @mp4.album_art[0]
+    assert_equal(img_mp3.mime_type, img_mp4.mime_type)
+    assert_equal(img_mp3.data, img_mp4.data)
+  end
+
+end
+
+class TestConsistencyMP302 < Test::Unit::TestCase
+  def setup
+    @mp3 = EasyTag::File.new("#{TEST_DIR}consistency.02.mp3")
+  end
+
+  def test_tags
+    cases = [
+      ['She Lives in My Lap',           @mp3.title],
+      [nil,                             @mp3.title_sort_order],
+      ['OutKast feat. Rosario Dawson',  @mp3.artist],
+      ['OutKast feat. Dawson, Rosario', @mp3.artist_sort_order],
+      ['OutKast',                       @mp3.album_artist],
+      #[nil,                             @mp3.album_artist_sort_order],
+      ['Speakerboxxx / The Love Below', @mp3.album],
+      [nil,                             @mp3.album_sort_order],
+      [nil,                             @mp3.comments],
+      [nil,                             @mp3.genre],
+      [2003,                            @mp3.year],
+      [[8, 21],                         @mp3.track_num],
+      [[2, 2],                          @mp3.disc_num],
+      ['The Love Below',                @mp3.disc_subtitle],
+      ['CD',                            @mp3.media],
+      ['Arista',                        @mp3.label],
+    ]
+
+    cases.each do |c|
+      expected, actual = c
+      assert_equal(expected, actual)
+    end
+  end
+
+  def test_date
+    assert_equal(2003, @mp3.date.year)
+    assert_equal(9,   @mp3.date.month)
+    assert_equal(23,    @mp3.date.day)
+
+    assert_equal(2003, @mp3.original_date.year)
+    assert_equal(9,   @mp3.original_date.month)
+    assert_equal(23,    @mp3.original_date.day)
+  end
+
+  def test_album_art
+    assert_equal(1, @mp3.album_art.count)
+
+    #sha1 = Digest::SHA1.hexdigest(@mp3.album_art[0].data)
+    #assert_equal('this is the front cover', @mp3.album_art[0].desc)
+    #assert_equal('Cover (front)',           @mp3.album_art[0].type_s)
+    #assert_equal('image/jpeg',              @mp3.album_art[0].mime_type)
+    #assert_equal(10,                        @mp3.album_art[0].width)
+    #assert_equal(5,                         @mp3.album_art[0].height)
+    #assert_equal('6555697ca1bf96117608bfb5a44c05cb622f88eb', sha1)
+  end
+end
+
+class TestConsistency02 < Test::Unit::TestCase
+  def setup
+    @mp3 = EasyTag::File.new("#{TEST_DIR}consistency.02.mp3")
+    @mp4 = EasyTag::File.new("#{TEST_DIR}consistency.02.m4a")
+  end
+
+  def test_tags
+    cases = [
+      :title,
+      :title_sort_order,
+      :artist,
+      :artist_sort_order,
+      #:album_artist_sort_order, # MP3 isn't working
+      :album,
+      :album_sort_order,
+      :comments,
+      :genre,
+      :year,
+      :track_num,
+      :disc_num,
+      :disc_subtitle,
+      :media,
+      :label,
+    ]
+
+    cases.each do |c|
+      puts c
+      assert_equal(@mp3.send(c), @mp4.send(c))
+    end
+  end
+
+  def test_date
+    assert_equal(@mp3.date.year, @mp4.date.year)
+    assert_equal(@mp3.date.month, @mp4.date.month)
+    assert_equal(@mp3.date.day, @mp4.date.day)
+  end
+
+  def test_album_art
+    # we're limited to what we can compare here, since mp4 is so limited
+    img_mp3 = @mp3.album_art[0]
+    img_mp4 = @mp4.album_art[0]
+    assert_equal(img_mp3.mime_type, img_mp4.mime_type)
+    assert_equal(img_mp3.data, img_mp4.data)
+  end
+
+end
+

data/test/test_mp3.rb

@@ -0,0 +1,69 @@
+require 'test/unit'
+
+require 'easytag'
+
+TEST_DIR = File.dirname(File.absolute_path(__FILE__)) << File::SEPARATOR
+
+class TestID3v1OnlyMP3 < Test::Unit::TestCase
+  def setup
+    @f = EasyTag::File.new("#{TEST_DIR}only_id3v1.mp3")
+  end
+
+  def test_tags
+    assert_equal('Track Title',       @f.title)
+    assert_equal('Track Artist',      @f.artist)
+    assert_equal('Album Name',        @f.album)
+    assert_equal('this is a comment', @f.comments)
+    assert_equal('Swing',             @f.genre)
+    assert_equal(1988,                @f.year)
+    assert_equal(1988,                @f.date.year)
+    assert_equal(true,                @f.album_art.empty?)
+    assert_equal(nil,                 @f.apple_id)
+    assert_equal([3, 0],              @f.track_num)
+    assert_equal([0, 0],              @f.disc_num)
+
+  end
+end
+
+class TestID3v2OnlyMP3 < Test::Unit::TestCase
+  def setup
+    @f = EasyTag::File.new("#{TEST_DIR}only_id3v2.mp3")
+  end
+
+  def test_tags
+    assert_equal('Track Title',       @f.title)
+    assert_equal('Track Artist',      @f.artist)
+    assert_equal('Album Name',        @f.album)
+    assert_equal('this is a comment', @f.comments)
+    assert_equal('Swing',             @f.genre)
+    assert_equal(1988,                @f.year)
+    assert_equal(1988,                @f.date.year)
+    assert_equal(true,                @f.album_art.empty?)
+    assert_equal(nil,                 @f.apple_id)
+    assert_equal([3, 0],              @f.track_num)
+    assert_equal([0, 0],              @f.disc_num)
+
+  end
+end
+
+class TestNoTagsMP3 < Test::Unit::TestCase
+  def setup
+    @f = EasyTag::File.new("#{TEST_DIR}no_tags.mp3")
+  end
+
+  def test_tags
+    assert_equal(nil,  @f.title)
+    assert_equal(nil,  @f.artist)
+    assert_equal(nil,  @f.album)
+    assert_equal(nil,  @f.album_artist)
+    assert_equal(nil,  @f.comments)
+    assert_equal(nil,  @f.genre)
+    assert_equal(0,    @f.year)
+    assert_equal(nil,  @f.date)
+    assert_equal(true, @f.album_art.empty?)
+    assert_equal(nil,  @f.apple_id)
+    assert_equal([0, 0],  @f.track_num)
+    assert_equal([0, 0],  @f.disc_num)
+  end
+
+end

data/test/test_mp4.rb

@@ -0,0 +1,27 @@
+require 'test/unit'
+
+require 'easytag'
+
+TEST_DIR = File.dirname(File.absolute_path(__FILE__)) << File::SEPARATOR
+
+class TestNoTagsMP4 < Test::Unit::TestCase
+  def setup
+    @f = EasyTag::File.new("#{TEST_DIR}no_tags.m4a")
+  end
+
+  def test_tags
+    assert_equal(nil,    @f.title)
+    assert_equal(nil,    @f.artist)
+    assert_equal(nil,    @f.album)
+    assert_equal(nil,    @f.album_artist)
+    assert_equal(nil,    @f.comments)
+    assert_equal(nil,    @f.genre)
+    assert_equal(0,      @f.year)
+    assert_equal(nil,    @f.date)
+    assert_equal(true,   @f.album_art.empty?)
+    assert_equal(nil,    @f.apple_id)
+    assert_equal([0, 0], @f.track_num)
+    assert_equal([0, 0], @f.disc_num)
+  end
+
+end

data/test/test_util.rb

@@ -0,0 +1,52 @@
+require 'test/unit'
+
+require 'easytag/util'
+
+class TestUtilities < Test::Unit::TestCase
+  def test_get_datetime01
+    date = EasyTag::Utilities.get_datetime('2006')
+    assert_equal(2006, date.year)
+    assert_equal(1, date.month)
+    assert_equal(1, date.day)
+  end
+
+  def test_get_datetime02
+    date = EasyTag::Utilities.get_datetime('1955-05')
+    assert_equal(1955, date.year)
+    assert_equal(5, date.month)
+    assert_equal(1, date.day)
+  end
+
+  def test_get_datetime03
+    date = EasyTag::Utilities.get_datetime('2012-12-07T08:00:00Z')
+    assert_equal(2012, date.year)
+    assert_equal(12, date.month)
+    assert_equal(7, date.day)
+  end
+
+  def test_get_datetime03
+    date = EasyTag::Utilities.get_datetime('19880711')
+    assert_equal(1988, date.year)
+    assert_equal(11, date.month)
+    assert_equal(7, date.day)
+  end
+
+  def test_get_int_pair
+    assert_equal([0, 0],  EasyTag::Utilities.get_int_pair(''))
+    assert_equal([0, 0],  EasyTag::Utilities.get_int_pair(nil))
+    assert_equal([3, 0],  EasyTag::Utilities.get_int_pair('3'))
+    assert_equal([0, 9],  EasyTag::Utilities.get_int_pair('/9'))
+    assert_equal([5, 10], EasyTag::Utilities.get_int_pair('5/10'))
+  end
+
+  def test_normalize_string
+    cases = [
+    ['MusicBrainz Album Artist Id', 'musicbrainz_album_artist_id'],
+    ['\'hi ^''$there #guys\"', 'hi_there_guys'],
+    ]
+    cases.each do |c|
+      orig, result = c
+      assert_equal(result, EasyTag::Utilities.normalize_string(orig))
+    end
+  end
+end

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: easytag
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Chris Lucas
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: taglib-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+- !ruby/object:Gem::Dependency
+  name: ruby-imagespec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.3.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.3.1
+- !ruby/object:Gem::Dependency
+  name: ruby-mp3info
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  EasyTag is an abstraction layer to the TagLib audio tagging library. It is designed to provide a simple and consistent API regardless of file format being read.
+email:
+- chris@chrisjlucas.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- easytag.gemspec
+- lib/easytag.rb
+- lib/easytag/base.rb
+- lib/easytag/file.rb
+- lib/easytag/image.rb
+- lib/easytag/interfaces.rb
+- lib/easytag/interfaces/base.rb
+- lib/easytag/interfaces/mp3.rb
+- lib/easytag/interfaces/mp4.rb
+- lib/easytag/util.rb
+- lib/easytag/version.rb
+- test/consistency.01.m4a
+- test/consistency.01.mp3
+- test/consistency.02.m4a
+- test/consistency.02.mp3
+- test/musicbrainz.m4a
+- test/no_tags.m4a
+- test/no_tags.mp3
+- test/only_id3v1.mp3
+- test/only_id3v2.mp3
+- test/test_consistency.rb
+- test/test_mp3.rb
+- test/test_mp4.rb
+- test/test_util.rb
+homepage: https://github.com/cjlucas/ruby-easytag
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: A simple audio metadata tagging interface
+test_files:
+- test/test_consistency.rb
+- test/test_mp3.rb
+- test/test_mp4.rb
+- test/test_util.rb
+has_rdoc: