sweeper 0.2 → 0.2.1

data/CHANGELOG

@@ -1,4 +1,6 @@
 
+v0.2.1. Better error handling.
+
 v0.2. Genre tagging; bugfixes.
 
 v0.1. First release.

data/README

@@ -24,29 +24,57 @@ If you use this software, please {make a donation}[http://blog.evanweaver.com/do
 * id3lib (Linux and OS X only)
 * some mp3 files
 
-== Installation
+== Usage
 
-Just install the gem:
+First, install the gem:
   sudo gem install sweeper
 
-== Usage
-
-Change to the directory of mp3s you want to tag and run:
-  sweeper
-  
-That's all.
+Now, change to the directory of mp3s you want to tag and run:
+  sweeper --genre --recursive
+
+Your mp3s will be updated with missing artist, genre, and trackname information, and a list of all tagged genres will be added to the <tt>comment</tt> field, for use in smart playlists.
+
+== Demo
+
+Unknown song before sweeping:
+
+  $ id3info 1_001.mp3 
+  *** Tag information for 1_001.mp3
+  *** mp3 info
+  MPEG1/layer III
+  Bitrate: 128KBps
+  Frequency: 44KHz
+ 
+Same song after running <tt>sweeper ----genre</tt>:
+
+  $ id3info 1_001.mp3   
+  *** Tag information for 1_001.mp3
+  === TPE1 (Lead performer(s)/Soloist(s)): Photon Band
+  === TIT2 (Title/songname/content description): To Sing For You
+  === WORS (Official internet radio station homepage): http://www.last.fm/music/Ph
+  oton+Band/_/To+Sing+For+You
+  === TCON (Content type): Psychadelic
+  === COMM (Comments): ()[]: rock, psychedelic, mod, Philly
+  *** mp3 info
+  MPEG1/layer III
+  Bitrate: 128KBps
+  Frequency: 44KHz
 
 == Options  
 
 Sweeper takes a few command line options:
   
-    -d, --dir                        Directory to search (defaults to current).
-    -r, --recursive                  Recurse directories.
-        --dry-run                    Do a dry run (no files will be changed).
-    -f, --force                      Overwrite all existing tags.
-    -g, --genre                      Add genre and genre comments.
-    -e, --force-genre                Add genre and genre comments, overwriting e
-        
+    -d, --dir            Directory to search (defaults to current).
+    -r, --recursive      Recurse directories.
+        --dry-run        Do a dry run (no files will be changed).
+    -f, --force          Overwrite all existing tags.
+    -g, --genre=[force]  Add genre tag and genre comments, optionally overwriting 
+                         existing ones.
+
+== Notes
+
+You will get cleaner tags if you convert your files to ID3v2 first. Sweeper reads both tag versions, but only outputs ID3v2.
+
 == Reporting problems
 
 The support forum is here[http://rubyforge.org/forum/forum.php?forum_id=23599].

data/TODO

@@ -1,3 +1,2 @@
 
-* Add genres via http://ws.audioscrobbler.com/1.0/artist/ARTIST/toptags.xml service.
-* Some kind of album detection?
+* Album detection via set clustering on http://ws.audioscrobbler.com/1.0/album/ARTIST/ALBUM/info.xml .

data/bin/sweeper

@@ -32,15 +32,9 @@ Choice.options do
   
   option :genre do
     short '-g'
-    long '--genre'
-    desc "Add genre and genre comments."
-  end
-  
-  option :"force-genre" do
-    short '-e'
-    long '--force-genre'
-    desc "Add genre and genre comments, overwriting existing ones."
-  end    
+    long '--genre=[force]'
+    desc "Add genre tag and genre comments, optionally overwriting existing ones."
+  end  
 end
 
 Sweeper.new(Choice.choices).run

data/lib/sweeper.rb

@@ -25,18 +25,20 @@ class Sweeper
 
   BASIC_KEYS = ['artist', 'title', 'url']
   GENRE_KEYS = ['genre', 'comment']
-  GENRES = ID3Lib::Info::Genres.sort
-  GENRE_COUNT = 7
+  ALBUM_KEYS = ['album', 'track']
+  GENRES = ID3Lib::Info::Genres
+  GENRE_COUNT = 10
   DEFAULT_GENRE = {'genre' => 'Other', 'comment' => 'other'}
 
   attr_reader :options
 
+  # Instantiate a new Sweeper. See <tt>bin/sweeper</tt> for <tt>options</tt> details.
   def initialize(options = {})
-    options['genre'] ||= options['force-genre']
     @dir = File.expand_path(options['dir'] || Dir.pwd)
     @options = options
   end
   
+  # Run the Sweeper according to the <tt>options</tt>.
   def run      
     @read = 0
     @updated = 0
@@ -44,7 +46,7 @@ class Sweeper
 
     Kernel.at_exit do
       if @read == 0
-        puts "No files found. Maybe you meant --recursive?"
+        puts "No mp3 files found. Maybe you meant --recursive?"
         exec "#{$0} --help"
       else
         puts "Read: #{@read}\nUpdated: #{@updated}\nFailed: #{@failed}"
@@ -61,75 +63,99 @@ class Sweeper
   
   #private
   
+  # Recurse one directory, reading, looking up, and writing each file, if appropriate. Accepts a directory path.
   def recurse(dir)
+    # Hackishly avoid problems with metacharacters in the Dir[] string.
+    dir = dir.gsub(/[^\s\w\.\/\\\-]/, '?')
+    # p dir if ENV['DEBUG']
     Dir["#{dir}/*"].each do |filename|
       if File.directory? filename and options['recursive']
         recurse(filename)
-      elsif File.extname(filename) == ".mp3"
+      elsif File.extname(filename) =~ /\.mp3$/i
         @read += 1
         tries = 0
         begin
           current = read(filename)  
           updated = lookup(filename, current)
           
-          if updated != current
+          if ENV['DEBUG']
+            p current, updated
+          end
+
+          if updated != current 
+            # Don't bother updating identical metadata.
             write(filename, updated)
             @updated += 1
+          else
+            puts "Unchanged: #{File.basename(filename)}"
           end
           
         rescue Problem => e          
           tries += 1 and retry if tries < 2
-          puts "Skipped #{File.basename(filename)}: #{e.message}"
+          puts "Skipped (#{e.message}): #{File.basename(filename)}"
           @failed += 1
         end
       end
-    end
+    end  
   end
   
+  # Read tags from an mp3 file. Returns a tag hash.
   def read(filename)
     tags = {}
-
-    song = ID3Lib::Tag.new(filename, ID3Lib::V2)
-    if song.empty?
-      song = ID3Lib::Tag.new(filename, ID3Lib::V1)
-    end
+    song = load(filename)
     
     (BASIC_KEYS + GENRE_KEYS).each do |key|      
       tags[key] = song.send(key) if !song.send(key).blank?
     end
     
+    # Change numeric genres into TCON strings
+    # XXX Might not work well
+    if tags['genre'] =~ /(\d+)/
+      tags['genre'] = GENRES[$1.to_i]
+    end
+    
     tags
   end
   
+  # Lookup all available remote metadata for an mp3 file. Accepts a pathname and an optional hash of existing tags. Returns a tag hash. 
   def lookup(filename, tags = {})
+    tags = tags.dup
     updated = {}
+
+    # Are there any empty basic tags we need to lookup?
     if options['force'] or 
       (BASIC_KEYS - tags.keys).any?
       updated.merge!(lookup_basic(filename))
     end
+
+    # Are there any empty genre tags we need to lookup?
     if options['genre'] and 
-      (options['force'] or options['force-genre'] or (GENRE_KEYS - tags.keys).any?)
+      (options['force'] or options['genre'] == 'force' or (GENRE_KEYS - tags.keys).any?)
       updated.merge!(lookup_genre(updated.merge(tags)))
     end
 
     if options['force']
+      # Force all remote tags.
       tags.merge!(updated)      
-    elsif options['force-genre']
-      tags.merge!(updated.slice('genre', 'comment'))
+    elsif options['genre'] == 'force'
+      # Force remote genre tags only.
+      tags.merge!(updated.slice(*GENRE_KEYS))
     end
 
+    # Merge back in existing tags.
     updated.merge(tags)    
   end
   
+  # Lookup the basic metadata for an mp3 file. Accepts a pathname. Returns a tag hash.
   def lookup_basic(filename)
     Dir.chdir File.dirname(binary) do
       response = silence { `./#{File.basename(binary)} #{filename.inspect}` }
       object = begin
         XSD::Mapping.xml2obj(response)
       rescue REXML::ParseException
-        raise Problem, "Server sent invalid response."
+        raise Problem, "Server sent invalid response"
       end              
-      raise Problem, "Fingerprint failed or not found." unless object
+      raise Problem, "Fingerprint failed or not found" unless object
       
       tags = {}
       song = Array(object.track).first      
@@ -140,7 +166,8 @@ class Sweeper
       tags
     end
   end
-  
+
+  # Lookup the genre metadata for a set of basic metadata. Accepts a tag hash. Returns a genre tag hash.  
   def lookup_genre(tags)
     return DEFAULT_GENRE if tags['artist'].blank?
     
@@ -157,36 +184,51 @@ class Sweeper
     return DEFAULT_GENRE if !genres.any?
     
     primary = nil
-    genres.each do |this|
+    genres.each_with_index do |this, index|
       match_results = Amatch::Levenshtein.new(this).similar(GENRES)
+      # Get the levenshtein best-match weight
       max = match_results.max
+      # Reverse lookup the canonical genre
       match = GENRES[match_results.index(max)]
+      # Bias slightly towards higher tagging counts
+      max += ((GENRE_COUNT - index) / GENRE_COUNT / 4.0)
 
       if ['Rock', 'Pop', 'Rap'].include? match
         # Penalize useless genres
         max = max / 3.0
       end
+            
+      p [max, match] if ENV['DEBUG']
       
       if !primary or primary.first < max
         primary = [max, match]
       end
     end
     
-    {'genre' => primary.last, 'comment' => genres.join(" ")}
+    {'genre' => primary.last, 'comment' => genres.join(", ")}
   end
   
+  # Write tags to an mp3 file. Accepts a pathname and a tag hash.
   def write(filename, tags)
     return if tags.empty?
-    puts File.basename(filename)
+    puts "Updated: #{File.basename(filename)}"
+    
+    song = load(filename)
     
-    file = ID3Lib::Tag.new(filename, ID3Lib::V2)
     tags.each do |key, value|
-      file.send("#{key}=", value)
+      song.send("#{key}=", value)
       puts "  #{key.capitalize}: #{value}"
     end
-    file.update! unless options['dry-run']
+    ALBUM_KEYS.each do |key|
+      puts "  #{key.capitalize}: #{song.send(key)}"
+    end
+    
+    unless options['dry-run']
+      song.update!(ID3Lib::V2) 
+    end
   end    
   
+  # Returns the path to the fingerprinter binary for this platform.
   def binary
     @binary ||= "#{File.dirname(__FILE__)}/../vendor/" + 
       case RUBY_PLATFORM
@@ -199,6 +241,12 @@ class Sweeper
         end
   end
   
+  # Loads metadata for an mp3 file. Looks for which ID3 version is already populated, instead of just the existence of frames.
+  def load(filename) 
+    ID3Lib::Tag.new(filename, ID3Lib::V_ALL)
+  end  
+  
+  # Silence STDERR and STDOUT for the duration of the block.
   def silence(outf = nil, errf = nil)
     # This method is annoying.
     outf, errf = Tempfile.new("stdout"), Tempfile.new("stderr")

data/sweeper.gemspec

@@ -1,10 +1,10 @@
 
-# Gem::Specification for Sweeper-0.2
+# Gem::Specification for Sweeper-0.2.1
 # Originally generated by Echoe
 
 Gem::Specification.new do |s|
   s.name = %q{sweeper}
-  s.version = "0.2"
+  s.version = "0.2.1"
 
   s.specification_version = 2 if s.respond_to? :specification_version=
 

data/test/integration/sweeper_test.rb

@@ -32,7 +32,7 @@ class SweeperTest < Test::Unit::TestCase
   
   def test_lookup_genre
     assert_equal(
-       {"genre"=>"Psychadelic", "comment"=>"rock psychedelic mod Philly"},
+       {"genre"=>"Psychadelic", "comment"=>"rock, psychedelic, mod, Philly"},
       @s.lookup_genre(@s.lookup_basic(@found_many))    
     )
     assert_equal(

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: sweeper
 version: !ruby/object:Gem::Version 
-  version: "0.2"
+  version: 0.2.1
 platform: ruby
 authors: 
 - Evan Weaver