easytag 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d4c3f241efadea1f57ee59da86e825e2ab3e16f1
-  data.tar.gz: a14c85a009253c9f8b0fd468107a9e4cc0f39cee
+  metadata.gz: 00e00f1b32f68a4b82926812d67662a241f3ab90
+  data.tar.gz: 80062af54050c116c899d079df4ad98c0db23a70
 SHA512:
-  metadata.gz: 70ac3fa28f1bcef558a017bce6e58d2d09028fe38f24677873cbc178720e298e49a228d4b2335e9720baeb3638e70b937669999237b9f6e80ef7da5e62b2aa4f
-  data.tar.gz: 53fe63add857a0bed84914337587486a24c22fc27c1af50cc0db3a45cc0b6849b35f447e035ca7bbee1fbc5a349069f73c980bb4472e5302286390b54c208056
+  metadata.gz: 18effe5cc310fb3bfc02757404f82fa6fdc84848c23c720e6c020bea7157e948c8a27e0a18495e233180a3b4af4dcd9c8acd7ef02886ab7d0d29ae83e6f2428c
+  data.tar.gz: 701971062dfe40d066cc4ad1a61c5bbc906ea05c9f481059a55aa1fcecf6a79fee06cc4d194cbdababd9547a80cdbe89c025c2991a21bcc4270ef9aaafc2fcde

data/CHANGELOG.md

@@ -1,3 +1,36 @@
+##### v0.4.0 (2013-06-07) #####
+* added: general attributes
+  - `#asin`
+  - `#conductor`
+  - `#remixer`
+  - `#mood`
+* added: musicbrainz attributes
+  - `#musicbrainz_track_id`
+  - `#musicbrainz_album_id`
+  - `#musicbrainz_album_status`
+  - `#musicbrainz_album_type`
+  - `#musicbrainz_album_release_country`
+  - `#musicbrainz_artist_id`
+  - `#musicbrainz_album_artist_id`
+  - `#musicbrainz_release_group_id`
+* added: audio property attributes
+  - `#length` (alias: `#duration`)
+  - `#bitrate`
+  - `#sample_rate`
+  - `#channels`
+  - `MP3#layer`
+  - `MP3#copyrighted?`
+  - `MP3#original?`
+  - `MP3#protection_enabled?`
+  - `MP4#bits_per_sample`
+* added: support for attribute aliases
+* changed: attributes that return `String` now default to an empty string
+  instead of `nil`
+* changed: unsupported attributes now return a default value instead of always
+`nil` (ex: `MP3#apple_id`)
+* fixed: `#user_info` stores an array of values if item has multiple value
+* fixed: improvements to `#date` (issues #1 and #2)
+
 ##### v0.3.1 (2013-05-31) #####
 * fixed: `MP3#subtitle` now points to correct ID3 frame
 * fixed: restored `MP3#user_info`

data/README.md

@@ -1,4 +1,4 @@
-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.
+EasyTag is an abstract interface 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).
 

data/easytag.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
   s.version     = EasyTag::VERSION
   s.summary     = 'A simple audio metadata tagging interface'
   s.description = <<-EOF
-    EasyTag is an abstraction layer to the TagLib audio tagging library.
+    EasyTag is an abstract interface to the TagLib audio tagging library.
     It is designed to provide a simple and consistent API regardless
     of file format being read.
   EOF

data/lib/easytag/attributes/base.rb

@@ -8,16 +8,21 @@ module EasyTag::Attributes
     STRING_LIST = 4
     BOOLEAN     = 5
     DATETIME    = 6
+    LIST        = 7
   end
   class BaseAttribute
     Utilities = EasyTag::Utilities
+    
+    attr_reader :name, :aliases, :ivar
 
     def initialize(args)
-      @name = args[:name]
-      @default = args[:default]
-      @type = args[:type] || Type::STRING
-      @options = args[:options] || {}
-      @ivar = BaseAttribute.name_to_ivar(@name)
+      @name         = args[:name]
+      @type         = args[:type]
+      @default      = args[:default] || self.class.default_for_type(@type)
+      @options      = args[:options] || {}
+      @handler_opts = args[:handler_opts] || {}
+      @aliases      = args[:aliases] || []
+      @ivar         = BaseAttribute.name_to_ivar(@name)
 
       if args[:handler].is_a?(Symbol)
         @handler = method(args[:handler])
@@ -28,11 +33,13 @@ module EasyTag::Attributes
       # fill default options
       
       # Remove nil objects from array (post process)
-      @options[:compact]    ||= false
-      # normalizes key (if hash) (handler)
-      @options[:normalize]  ||= false
-      # cast key (if hash) to symbol (handler)
-      @options[:to_sym]     ||= false
+      @options[:compact]        ||= false
+      # Delete empty objects in array (post process)
+      @options[:delete_empty]   ||= false
+      # normalizes key (if hash) (handler or post process)
+      @options[:normalize]      ||= false
+      # cast key (if hash) to symbol (handler or post process)
+      @options[:to_sym]         ||= false
 
     end
     
@@ -44,13 +51,29 @@ module EasyTag::Attributes
       Marshal.load(Marshal.dump(obj))
     end
 
+    def self.default_for_type(type)
+      case type
+      when Type::STRING
+        ''
+      when Type::DATETIME
+        nil
+      when Type::INT
+        0
+      when Type::INT_LIST
+        [0, 0] # TODO: don't assume an INT_LIST is always an int pair
+      when Type::BOOLEAN
+        false
+      when Type::LIST
+        []
+      end
+    end
+
     def default
       BaseAttribute.can_clone?(@default) ?
         BaseAttribute.deep_copy(@default) : @default
     end
     
     def call(iface)
-      #puts 'entered call()'
       data = @handler.call(iface)
       data = type_cast(data)
       post_process(data)
@@ -62,6 +85,8 @@ module EasyTag::Attributes
         data = data.to_i
       when Type::DATETIME
         data = Utilities.get_datetime(data.to_s)
+      when Type::LIST
+        data = Array(data)
       end
       
       data
@@ -73,31 +98,46 @@ module EasyTag::Attributes
       end
 
       # fall back to default if data is nil
-      data = BaseAttribute.obj_or_nil(data) || default
+      data ||= default
+
+      # REVIEW: the compact option may not be needed anymore
+      #   since we've done away with casting empty strings to nil
+      data.compact! if @options[:compact] && data.respond_to?(:compact!)
+
+      if @options[:delete_empty]
+        data.select! { |item| !item.empty? if item.respond_to?(:empty?) }
+      end
 
-      # run obj_or_nil on each item in array
-      data.map! { |item| BaseAttribute.obj_or_nil(item) } if data.is_a?(Array)
+      data = Utilities.normalize_object(data) if @options[:normalize]
 
-      if @options[:compact] && data.respond_to?(:compact!)
-        data.compact!
+      # TODO: roll this out to a method that supports more than just array
+      if @options[:to_sym] && data.is_a?(Array)
+        data.map! { |item| item.to_sym if item.respond_to?(:to_sym) }
       end
 
       data
     end
-    # avoid returing empty objects
-    def self.obj_or_nil(o)
-      if o.class == String
-        ret = o.empty? ? nil : o
-      else
-        o
-      end
+    
+    def self.name_to_ivar(name)
+      name.to_s.gsub(/\?/, '').insert(0, '@').to_sym
     end
 
-    def self.name_to_ivar(name)
-      name = name.to_s if name.class == Symbol
-      name.gsub!(/\?/, '')
-      name.insert(0, '@')
-      name.to_sym
+    # read handlers
+
+    def read_default(iface)
+      default
+    end
+
+    def read_audio_property(iface)
+      key = @handler_opts[:key]
+      warn "@handler_opts[:key] doesn't exist" if key.nil?
+      iface.info.audio_properties.send(key)
+    end
+
+    def user_info_lookup(iface)
+      key = @handler_opts[:key]
+      warn "@handler_opts[:key] doesn't exist" if key.nil?
+      iface.user_info_normalized[key]
     end
   end
 end

data/lib/easytag/attributes/mp3.rb

@@ -105,10 +105,12 @@ module EasyTag::Attributes
       frame_data = read_all_id3(iface)
 
       frame_data.each do |data|
-        key, value = data
+        key = data[0]
+        values = data[1..-1]
+
         key = Utilities.normalize_string(key) if @options[:normalize]
         key = key.to_sym if @options[:to_sym]
-        kv_hash[key] = value
+        kv_hash[key] = values.count > 1 ? values : values.first
       end
 
       kv_hash
@@ -130,6 +132,20 @@ module EasyTag::Attributes
 
       date_str
     end
+
+    def read_ufid(iface)
+      frames = iface.info.id3v2_tag.frame_list('UFID')
+      ufid = nil
+
+      frames.each do |frame|
+        if @handler_opts[:owner].eql?(frame.owner)
+          ufid = frame.identifier
+          break
+        end
+      end
+
+      ufid
+    end
   end
 end
 
@@ -151,6 +167,7 @@ module EasyTag::Attributes
     :name         => :title_sort_order,
     :id3v2_frames => ['TSOT', 'XSOT'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # subtitle
@@ -158,6 +175,7 @@ module EasyTag::Attributes
     :name         => :subtitle,
     :id3v2_frames => ['TIT3'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # artist
@@ -166,6 +184,7 @@ module EasyTag::Attributes
     :id3v2_frames => ['TPE1'],
     :id3v1_tag    => :artist,
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # artist_sort_order
@@ -175,6 +194,7 @@ module EasyTag::Attributes
     :name         => :artist_sort_order,
     :id3v2_frames => ['TSOP', 'XSOP'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # album_artist
@@ -182,12 +202,15 @@ module EasyTag::Attributes
     :name         => :album_artist,
     :id3v2_frames => ['TPE2'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # album_artist_sort_order
   {
     :name         => :album_artist_sort_order,
-    :handler      => lambda { |iface| iface.user_info[:albumartistsort] }
+    :handler      => :user_info_lookup,
+    :handler_opts => {:key => :albumartistsort},
+    :type         => Type::STRING,
   },
 
   # album
@@ -196,14 +219,16 @@ module EasyTag::Attributes
     :id3v2_frames => ['TALB'],
     :id3v1_tag    => :album,
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # compilation?
   {
     :name         => :compilation?,
     :id3v2_frames => ['TCMP'],
-    :default      => false,
     :handler      => :read_first_id3,
+    :type         => Type::BOOLEAN,
+    # TODO: remove is_flag option, determine boolean value implicitly 
     :options      => {:is_flag => true},
   },
 
@@ -214,6 +239,7 @@ module EasyTag::Attributes
     :name         => :album_sort_order,
     :id3v2_frames => ['TSOA', 'XSOA'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
   
   # genre
@@ -222,6 +248,7 @@ module EasyTag::Attributes
     :id3v2_frames => ['TCON'],
     :id3v1_tag    => :genre,
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # disc_subtitle
@@ -229,6 +256,7 @@ module EasyTag::Attributes
     :name         => :disc_subtitle,
     :id3v2_frames => ['TSST'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # media
@@ -236,6 +264,7 @@ module EasyTag::Attributes
     :name         => :media,
     :id3v2_frames => ['TMED'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # label
@@ -243,6 +272,7 @@ module EasyTag::Attributes
     :name         => :label,
     :id3v2_frames => ['TPUB'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # encoded_by
@@ -250,6 +280,7 @@ module EasyTag::Attributes
     :name         => :encoded_by,
     :id3v2_frames => ['TENC'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # encoder_settings
@@ -257,6 +288,7 @@ module EasyTag::Attributes
     :name         => :encoder_settings,
     :id3v2_frames => ['TSSE'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # group
@@ -264,6 +296,7 @@ module EasyTag::Attributes
     :name         => :group,
     :id3v2_frames => ['TIT1'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # composer
@@ -271,6 +304,23 @@ module EasyTag::Attributes
     :name         => :composer,
     :id3v2_frames => ['TCOM'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
+  },
+
+  # conductor
+  {
+    :name         => :conductor,
+    :id3v2_frames => ['TPE3'],
+    :handler      => :read_first_id3,
+    :type         => Type::STRING,
+  },
+
+  # remixer
+  {
+    :name         => :remixer,
+    :id3v2_frames => ['TPE4'],
+    :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # lyrics
@@ -278,6 +328,7 @@ module EasyTag::Attributes
     :name         => :lyrics,
     :id3v2_frames => ['USLT'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # lyricist
@@ -285,6 +336,7 @@ module EasyTag::Attributes
     :name         => :lyricist,
     :id3v2_frames => ['TEXT'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # copyright
@@ -292,6 +344,7 @@ module EasyTag::Attributes
     :name         => :copyright,
     :id3v2_frames => ['TCOP'],
     :handler      => :read_first_id3,
+    :type         => Type::STRING,
   },
 
   # bpm
@@ -302,6 +355,14 @@ module EasyTag::Attributes
     :type         => Type::INT,
   },
 
+  # mood
+  {
+    :name         => :mood,
+    :id3v2_frames => ['TMOO'],
+    :handler      => :read_first_id3,
+    :type         => Type::STRING,
+  },
+
   # track_num
   {
     :name         => :track_num,
@@ -338,13 +399,14 @@ module EasyTag::Attributes
     :id3v1_tag    => :comment,
     :handler      => :read_all_id3,
     :default      => [],
-    :options      => { :compact => true }
+    :options      => { :compact => true, :delete_empty => true }
   },
   
   # comment
   {
     :name         => :comment,
-    :handler      => lambda { |iface| iface.comments.first }
+    :handler      => lambda { |iface| iface.comments.first },
+    :type         => Type::STRING,
   },
 
   # album_art
@@ -368,15 +430,177 @@ module EasyTag::Attributes
     :handler      => lambda { |iface| iface.date.nil? ? 0 : iface.date.year }
   },
 
+  # apple_id
+  {
+    :name         => :apple_id,
+    :handler      => :read_default,
+    :type         => Type::STRING,
+  },
+
   # user_info
   {
     :name         => :user_info,
     :id3v2_frames => ['TXXX'],
     :handler      => :read_field_list_as_key_value,
     :default      => {},
-    :options     => { :normalize => true, 
+    :options     => {:field_list => true},
+  },
+  
+  # user_info_normalized
+  {
+    :name         => :user_info_normalized,
+    :id3v2_frames => ['TXXX'],
+    :handler      => :read_field_list_as_key_value,
+    :default      => {},
+    :options     => {:normalize => true, 
       :to_sym => true,
       :field_list => true },
   },
+
+  # asin
+  {
+    :name         => :asin,
+    :handler      => :user_info_lookup,
+    :handler_opts => {:key => :asin},
+    :type         => Type::STRING,
+  },
+
+  #
+  # MusicBrainz Attributes
+  #
+
+  # musicbrainz_track_id
+  {
+    :name         => :musicbrainz_track_id,
+    :handler      => :read_ufid,
+    :handler_opts => {:owner => 'http://musicbrainz.org'},
+    :type         => Type::STRING,
+  },
+
+  # musicbrainz_album_artist_id
+  {
+    :name         => :musicbrainz_album_artist_id,
+    :handler      => :user_info_lookup,
+    :handler_opts => {:key => :musicbrainz_album_artist_id},
+    :type         => Type::STRING,
+  },
+
+  # musicbrainz_artist_id
+  {
+    :name         => :musicbrainz_artist_id,
+    :handler      => :user_info_lookup,
+    :handler_opts => {:key => :musicbrainz_artist_id},
+    :type         => Type::LIST,
+  },
+  
+  # musicbrainz_album_id
+  {
+    :name         => :musicbrainz_album_id,
+    :handler      => :user_info_lookup,
+    :handler_opts => {:key => :musicbrainz_album_id},
+    :type         => Type::STRING,
+  },
+  
+  # musicbrainz_album_status
+  {
+    :name         => :musicbrainz_album_status,
+    :handler      => :user_info_lookup,
+    :handler_opts => {:key => :musicbrainz_album_status},
+    :type         => Type::STRING,
+  },
+  
+  # musicbrainz_album_type
+  {
+    :name         => :musicbrainz_album_type,
+    :handler      => :user_info_lookup,
+    :handler_opts => {:key => :musicbrainz_album_type},
+    :type         => Type::LIST,
+  },
+
+  
+  # musicbrainz_release_group_id
+  {
+    :name         => :musicbrainz_release_group_id,
+    :handler      => :user_info_lookup,
+    :handler_opts => {:key => :musicbrainz_release_group_id},
+    :type         => Type::STRING,
+  },
+  
+  # musicbrainz_album_release_country
+  {
+    :name         => :musicbrainz_album_release_country,
+    :handler      => :user_info_lookup,
+    :handler_opts => {:key => :musicbrainz_album_release_country},
+    :type         => Type::STRING,
+  },
+
+  #
+  # Audio Properties
+  #
+ 
+  # length 
+  {
+    :name         => :length,
+    :aliases      => [:duration],
+    :handler      => :read_audio_property,
+    :handler_opts => {:key => :length},
+    :type         => Type::INT,
+  },
+
+  # bitrate
+  {
+    :name         => :bitrate,
+    :handler      => :read_audio_property,
+    :handler_opts => {:key => :bitrate},
+    :type         => Type::INT,
+  },
+
+  # sample_rate
+  {
+    :name         => :sample_rate,
+    :handler      => :read_audio_property,
+    :handler_opts => {:key => :sample_rate},
+    :type         => Type::INT,
+  },
+
+  # channels
+  {
+    :name         => :channels,
+    :handler      => :read_audio_property,
+    :handler_opts => {:key => :channels},
+    :type         => Type::INT,
+  },
+
+  # copyrighted?
+  {
+    :name         => :copyrighted?,
+    :handler      => :read_audio_property,
+    :handler_opts => {:key => :copyrighted?},
+    :type         => Type::BOOLEAN,
+  },
+
+  # layer
+  {
+    :name         => :layer,
+    :handler      => :read_audio_property,
+    :handler_opts => {:key => :layer},
+    :type         => Type::INT,
+  },
+
+  # original?
+  {
+    :name         => :original?,
+    :handler      => :read_audio_property,
+    :handler_opts => {:key => :original?},
+    :type         => Type::BOOLEAN,
+  },
+
+  # protection_enabled?
+  {
+    :name         => :protection_enabled?,
+    :handler      => :read_audio_property,
+    :handler_opts => {:key => :protection_enabled},
+    :type         => Type::BOOLEAN,
+  },
   ]
 end