scrobbler-ng 2.0.0

data/.gitignore

@@ -0,0 +1,11 @@
+rdoc
+doc/*
+pkg/*
+nbproject
+scrobbler-*.gem
+*.rb~
+*.rake~
+coverage
+spec.html
+catalog.xml
+.yardoc

data/MIT-LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2007-2010 John Nunemaker, Kurt Schrader, Uwe L. Korn
+
+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.rdoc

@@ -0,0 +1,104 @@
+=Scrobbler-ng
+
+Scrobbler-ng is a wrapper for the audioscrobbler web services (http://www.audioscrobbler.net/data/webservices/). 
+
+Currently updating to use the 2.0 API. It is very much a work in progress.
+
+Below is just a sampling of how easy this lib is to use, full documentation of
+all functions is available at http://rdoc.info/projects/xhochy/scrobbler
+
+== Initialization
+
+  Scrobbler::Base.api_key = 'foo123'
+
+== Users
+
+  user = Scrobbler::User.new('jnunemaker')
+
+  puts "#{user.username}'s Recent Tracks"
+  puts "=" * (user.username.length + 16)
+  user.recent_tracks.each { |t| puts t.name }
+
+  puts
+  puts
+
+  puts "#{user.username}'s Top Tracks"
+  puts "=" * (user.username.length + 13)
+  user.top_tracks.each { |t| puts "(#{t.playcount}) #{t.name}" }
+	
+== Albums
+	
+  album = Scrobbler::Album.new('Some Hearts', :artist => 'Carrie Underwood', :include_info => true)
+
+  puts "Album: #{album.name}"
+  puts "Artist: #{album.artist}"
+  puts "Playcount: #{album.playcount}"
+  puts "URL: #{album.url}"
+  puts "Release Date: #{album.release_date.strftime('%m/%d/%Y')}"
+	
+==Artists
+	
+  artist = Scrobbler::Artist.new('Carrie Underwood')  
+  
+  puts 'Top Tracks'
+  puts "=" * 10
+  artist.top_tracks.each { |t| puts "(#{t.playcount}) #{t.name}" }
+
+  puts
+
+  puts 'Similar Artists'
+  puts "=" * 15
+  artist.similar.each { |a| puts "(#{a.match}%) #{a.name}" }
+
+==Geo
+
+  geo = Scrobbler::Geo.new()
+
+  puts 'Events'
+  puts "=" * 10
+  geo.events(:location => 'Manchester').each { |e| puts "(#{e.id}) #{e.title}" }
+
+  puts
+
+  puts 'Top Artists'
+  puts "=" * 10
+  geo.top_artists(:location => 'Manchester').each { |a| puts "(#{a.name}) #{a.playcount}" }
+
+  puts
+
+  puts 'Top Tracks'
+  puts "=" * 10
+  geo.top_tracks(:location => 'Manchester').each { |t| puts "(#{a.name}) #{a.playcount}" }
+
+	
+==Tags	
+	
+  tag = Scrobbler::Tag.new('country')
+
+  puts 'Top Albums'
+  tag.top_albums.each { |a| puts "(#{a.count}) #{a.name} by #{a.artist}" }
+
+  puts
+
+  puts 'Top Tracks'
+  tag.top_tracks.each { |t| puts "(#{t.count}) #{t.name} by #{t.artist}" }
+	
+==Tracks
+	
+  track = Scrobbler::Track.new('Carrie Underwood', 'Before He Cheats')
+  puts 'Fans'
+  puts "=" * 4
+  track.top_fans.each { |u| puts "(#{u.weight}) #{u.username}" }
+	
+== Simple Authentication (for Scrobbling)
+
+  work in progress...
+    
+== Scrobbling
+
+  work in progress...
+
+== Now Playing Submission
+
+  work in progress...
+

data/Rakefile

@@ -0,0 +1,11 @@
+# Rakefile
+
+require 'rubygems'
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+ 
+Dir['tasks/**/*.rake'].each { |rake| load rake }
+ 
+task :default => 'test:unit'

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 0
+:patch: 0
+:major: 2

data/examples/album.rb

@@ -0,0 +1,19 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'scrobbler'))
+
+Scrobbler::Base::api_key = "..add..";
+
+album = Scrobbler::Album.new('Some Hearts', :artist => 'Carrie Underwood', :include_info => true)
+
+puts "Album: #{album.name}"
+puts "Artist: #{album.artist}"
+puts "Playcount: #{album.playcount}"
+puts "URL: #{album.url}"
+puts "Release Date: #{album.release_date.strftime('%m/%d/%Y')}"
+
+puts
+puts
+
+puts "Tracks"
+longest_track_name = album.tracks.collect(&:name).sort { |x, y| y.length <=> x.length }.first.length
+puts "=" * longest_track_name
+album.tracks.each { |t| puts t.name }

data/examples/artist.rb

@@ -0,0 +1,13 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'scrobbler'))
+
+artist = Scrobbler::Artist.new('Carrie Underwood')
+
+puts 'Top Tracks'
+puts "=" * 10
+artist.top_tracks.each { |t| puts "(#{t.reach}) #{t.name}" }
+
+puts
+
+puts 'Similar Artists'
+puts "=" * 15
+artist.similar.each { |a| puts "(#{a.match}%) #{a.name}" }

data/examples/scrobble.rb

@@ -0,0 +1,31 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'scrobbler'))
+
+auth = Scrobbler::SimpleAuth.new(:user => 'chunky', :password => 'bacon')
+auth.handshake!
+
+puts "Auth Status: #{auth.status}"
+puts "Session ID: #{auth.session_id}"
+puts "Now Playing URL: #{auth.now_playing_url}"
+puts "Submission URL: #{auth.submission_url}"
+
+scrobble = Scrobbler::Scrobble.new(:session_id => auth.session_id,
+                                   :submission_url => auth.submission_url,
+                                   :artist => 'Coldplay',
+                                   :track => 'Viva La Vida',
+                                   :album => 'Viva La Vida',
+                                   :time => Time.new,
+                                   :length => 244,
+                                   :track_number => 7)
+scrobble.submit!
+puts "Scrobbler Submission Status: #{scrobble.status}"
+
+playing = Scrobbler::Playing.new(:session_id => auth.session_id,
+                                 :now_playing_url => auth.now_playing_url,
+                                 :artist => 'Anberlin',
+                                 :track => 'A Day Late',
+                                 :album => 'Never Take Friendship Personal',
+                                 :length => 214,
+                                 :track_number => 5)
+                                 
+playing.submit!         
+puts "Playing Submission Status: #{playing.status}"      

data/examples/tag.rb

@@ -0,0 +1,11 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'scrobbler'))
+
+tag = Scrobbler::Tag.new('country')
+
+puts 'Top Albums'
+tag.top_albums.each { |a| puts "(#{a.count}) #{a.name} by #{a.artist}" }
+
+puts
+
+puts 'Top Tracks'
+tag.top_tracks.each { |t| puts "(#{t.count}) #{t.name} by #{t.artist}" }

data/examples/track.rb

@@ -0,0 +1,6 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'scrobbler'))
+
+track = Scrobbler::Track.new('Carrie Underwood', 'Before He Cheats')
+puts 'Fans'
+puts "=" * 4
+track.fans.each { |u| puts "(#{u.weight}) #{u.username}" }

data/examples/user.rb

@@ -0,0 +1,14 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'scrobbler'))
+
+user = Scrobbler::User.new('jnunemaker')
+
+puts "#{user.username}'s Recent Tracks"
+puts "=" * (user.username.length + 16)
+user.recent_tracks.each { |t| puts t.name }
+
+puts
+puts
+
+puts "#{user.username}'s Top Tracks"
+puts "=" * (user.username.length + 13)
+user.top_tracks.each { |t| puts "(#{t.playcount}) #{t.name}" }

data/lib/scrobbler/album.rb

@@ -0,0 +1,165 @@
+# Getting information about an album such as release date and the tracks on it is very easy.
+# 
+#   album = Scrobbler::Album.new('Carrie Underwood', 'Some Hearts', :include_info => true)
+# 
+#   puts "Album: #{album.name}"
+#   puts "Artist: #{album.artist}"
+#   puts "Reach: #{album.reach}"
+#   puts "URL: #{album.url}"
+#   puts "Release Date: #{album.release_date.strftime('%m/%d/%Y')}"
+# 
+#   puts
+#   puts
+# 
+#   puts "Tracks"
+#   longest_track_name = album.tracks.collect(&:name).sort { |x, y| y.length <=> x.length }.first.length
+#   puts "=" * longest_track_name
+#   album.tracks.each { |t| puts t.name }
+#
+# Would output:
+#
+#   Album: Some Hearts
+#   Artist: Carrie Underwood
+#   Reach: 18729
+#   URL: http://www.last.fm/music/Carrie+Underwood/Some+Hearts
+#   Release Date: 11/15/2005
+# 
+# 
+#   Tracks
+#   ===============================
+#   Wasted
+#   Don't Forget to Remember Me
+#   Some Hearts
+#   Jesus, Take the Wheel
+#   The Night Before (Life Goes On)
+#   Lessons Learned
+#   Before He Cheats
+#   Starts With Goodbye
+#   I Just Can't Live a Lie
+#   We're Young and Beautiful
+#   That's Where It Is
+#   Whenever You Remember
+#   I Ain't in Checotah Anymore
+#   Inside Your Heaven
+#
+module Scrobbler
+  # @todo Add missing functions that require authentication
+  class Album < Base
+    mixins :image
+    
+    attr_reader :artist, :artist_mbid, :name, :mbid, :playcount, :rank, :url
+    attr_reader :reach, :release_date, :listeners, :playcount, :top_tags
+    attr_reader :image_large, :image_medium, :image_small, :tagcount
+    
+    # needed on top albums for tag
+    attr_reader :count
+    
+    # needed for weekly album charts
+    attr_reader :chartposition, :position
+    
+    class << self
+      def new_from_libxml(xml)
+        data = {}
+
+        xml.children.each do |child|
+          data[:name] = child.content if ['name', 'title'].include?(child.name)
+          data[:playcount] = child.content.to_i if child.name == 'playcount'
+          data[:tagcount] = child.content.to_i if child.name == 'tagcount'
+          data[:mbid] = child.content if child.name == 'mbid'
+          data[:url] = child.content if child.name == 'url'
+          data[:artist] = Artist.new_from_libxml(child) if child.name == 'artist'
+          maybe_image_node(data, child)
+        end
+        
+        # If we have not found anything in the content of this node yet then
+        # this must be a simple artist node which has the name of the artist
+        # as its content
+        data[:name] = xml.content if data == {}
+        
+        # Get all information from the root's attributes
+        data[:mbid] = xml['mbid'] if xml['mbid']
+        data[:rank] = xml['rank'].to_i if xml['rank']
+        data[:position] = xml['position'].to_i if xml['position']
+        
+        # If there is no name defined, than this was an empty album tag
+        return nil if data[:name].empty?
+        
+        Album.new(data[:name], data)
+      end
+    end
+      
+    # If the additional parameter :include_info is set to true, additional 
+    # information is loaded
+    #
+    # @todo Albums should be able to be created via a MusicBrainz id too
+    def initialize(name, input={})
+      super()      
+      # Support old version of initialize where we had (artist_name, album_name)
+      if input.class == String
+        data = {:artist => name, :name => input}
+        name = input, input = data
+      end
+      data = {:include_profile => false}.merge(input)
+      raise ArgumentError, "Artist or mbid is required" if data[:artist].nil? && data[:mbid].nil?
+      raise ArgumentError, "Name is required" if name.empty?
+      @name = name
+      populate_data(data)
+      load_info() if data[:include_info]
+    end
+    
+    # Indicates if the info was already loaded
+    @info_loaded = false 
+    
+    # Load additional information about this album
+    #
+    # Calls "album.getinfo" REST method
+    #
+    # @todo Parse wiki content
+    # @todo Add language code for wiki translation
+    def load_info
+      return nil if @info_loaded
+      xml = Base.request('album.getinfo', {'artist' => @artist, 'album' => @name})
+      unless xml.root['status'] == 'failed'
+        xml.root.children.each do |childL1|
+          next unless childL1.name == 'album'
+          
+          childL1.children.each do |childL2|
+            @url = childL2.content if childL2.name == 'url'
+            @id = childL2.content if childL2.name == 'id'
+            @mbid = childL2.content if childL2.name == 'mbid'
+            @release_date = Time.parse(childL2.content.strip) if childL2.name == 'releasedate'
+            check_image_node childL2
+            @listeners = childL2.content.to_i if childL2.name == 'listeners'
+            @playcount = childL2.content.to_i if childL2.name == 'playcount'
+            if childL2.name == 'toptags'
+              @top_tags = []
+              childL2.children.each do |childL3|
+                next unless childL3.name == 'tag'
+                @top_tags << Tag.new_from_libxml(childL3)
+              end # childL2.children.each do |childL3|
+            end # if childL2.name == 'toptags'
+          end # childL1.children.each do |childL2|
+        end # xml.children.each do |childL1|
+        @info_loaded  = true
+      end
+    end
+    
+    # Tag an album using a list of user supplied tags. 
+    def add_tags(tags)
+        # This function require authentication, but SimpleAuth is not yet 2.0
+        raise NotImplementedError
+    end
+
+    # Get the tags applied by an individual user to an album on Last.fm.
+    def tags()
+        # This function require authentication, but SimpleAuth is not yet 2.0
+        raise NotImplementedError
+    end
+
+    # Remove a user's tag from an album.
+    def remove_tag()
+        # This function require authentication, but SimpleAuth is not yet 2.0
+        raise NotImplementedError
+    end
+  end
+end

data/lib/scrobbler/artist.rb

@@ -0,0 +1,169 @@
+# Below are examples of how to find an artists top tracks and similar artists.
+# 
+#   artist = Scrobbler::Artist.new('Carrie Underwood')
+# 
+#   puts 'Top Tracks'
+#   puts "=" * 10
+#   artist.top_tracks.each { |t| puts "(#{t.reach}) #{t.name}" }
+# 
+#   puts
+# 
+#   puts 'Similar Artists'
+#   puts "=" * 15
+#   artist.similar.each { |a| puts "(#{a.match}%) #{a.name}" }
+# 
+# Would output something similar to:
+# 
+#   Top Tracks
+#   ==========
+#   (8797) Before He Cheats
+#   (3574) Don't Forget to Remember Me
+#   (3569) Wasted
+#   (3246) Some Hearts
+#   (3142) Jesus, Take the Wheel
+#   (2600) Starts With Goodbye
+#   (2511) Jesus Take The Wheel
+#   (2423) Inside Your Heaven
+#   (2328) Lessons Learned
+#   (2040) I Just Can't Live a Lie
+#   (1899) Whenever You Remember
+#   (1882) We're Young and Beautiful
+#   (1854) That's Where It Is
+#   (1786) I Ain't in Checotah Anymore
+#   (1596) The Night Before (Life Goes On)
+#   
+#   Similar Artists
+#   ===============
+#   (100%) Rascal Flatts
+#   (84.985%) Keith Urban
+#   (84.007%) Kellie Pickler
+#   (82.694%) Katharine McPhee
+#   (81.213%) Martina McBride
+#   (79.397%) Faith Hill
+#   (77.121%) Tim McGraw
+#   (75.191%) Jessica Simpson
+#   (75.182%) Sara Evans
+#   (75.144%) The Wreckers
+#   (73.034%) Kenny Chesney
+#   (71.765%) Dixie Chicks
+#   (71.084%) Kelly Clarkson
+#   (69.535%) Miranda Lambert
+#   (66.952%) LeAnn Rimes
+#   (66.398%) Mandy Moore
+#   (65.817%) Bo Bice
+#   (65.279%) Diana DeGarmo
+#   (65.115%) Gretchen Wilson
+#   (62.982%) Clay Aiken
+#   (62.436%) Ashlee Simpson
+#   (62.160%) Christina Aguilera
+module Scrobbler
+  # @todo Add missing functions that require authentication
+  # @todo Integrate search functionality into this class which is already implemented in Scrobbler::Search
+  class Artist < Base
+    mixins :image, :streamable
+    
+    attr_accessor :name, :mbid, :playcount, :rank, :url, :count
+    attr_accessor :chartposition
+    attr_accessor :match, :tagcount, :listeners
+    
+    class << self
+      def new_from_libxml(xml)
+        data = {}
+      
+        # Get all information from the root's children nodes
+        xml.children.each do |child|
+          data[:playcount] = child.content.to_i if child.name == 'playcount'
+          data[:mbid] = child.content if child.name == 'mbid'
+          data[:url] = child.content if child.name == 'url'
+          data[:match] = child.content.to_i if child.name == 'match'
+          data[:tagcount] = child.content.to_i if child.name == 'tagcount'
+          data[:chartposition] = child.content if child.name == 'chartposition'
+          data[:name] = child.content if child.name == 'name'
+          maybe_streamable_node(data, child)
+          maybe_image_node(data, child)
+        end        
+        
+        # If we have not found anything in the content of this node yet then
+        # this must be a simple artist node which has the name of the artist
+        # as its content
+        data[:name] = xml.content if data == {}
+        
+        # Get all information from the root's attributes
+        data[:name] = xml['name'] if xml['name']
+        data[:rank] = xml['rank'].to_i if xml['rank']
+        maybe_streamable_attribute data, xml
+        data[:mbid] = xml['mbid'] if xml['mbid']
+        
+        # Step 3 fill the object
+        Artist.new(data[:name], data)
+      end
+    end
+    
+    def initialize(name, data = {})
+      super()
+      raise ArgumentError, "Name is required" if name.empty?
+      @name = name
+      populate_data(data)
+    end
+    
+    # Get the URL to the ical or rss representation of the current events that
+    # a artist will play
+    #
+    # @todo Use the API function and parse that into a common ruby structure
+    def current_events(format=:ics)
+      format = :ics if format.to_s == 'ical'
+      raise ArgumentError unless ['ics', 'rss'].include?(format.to_s)
+      "#{API_URL.chop}/2.0/artist/#{CGI::escape(@name)}/events.#{format}"
+    end
+    
+    def similar(force=false)
+      get_response('artist.getsimilar', :similar, 'similarartists', 'artist', {'artist' => @name}, force)
+    end
+    
+    def top_fans(force=false)
+      get_response('artist.gettopfans', :top_fans, 'topfans', 'user', {'artist' => @name}, force)
+    end
+    
+    def top_tracks(force=false)
+      get_response('artist.gettoptracks', :top_tracks, 'toptracks', 'track', {'artist'=>@name}, force)
+    end
+    
+    def top_albums(force=false)
+      get_response('artist.gettopalbums', :top_albums, 'topalbums', 'album', {'artist'=>@name}, force)
+    end
+    
+    def top_tags(force=false)
+      get_response('artist.gettoptags', :top_tags, 'toptags', 'tag', {'artist' => @name}, force)
+    end
+    
+    @info_loaded = false
+    # Get the metadata
+    def load_info
+        doc = Base.request('artist.getinfo', {'artist' => @name})
+        doc.root.children.each do |childL1|
+            next unless childL1.name == 'artist'
+            childL1.children.each do |child|
+                @mbid = child.content if child.name == 'mbid'
+                @url = child.content if child.name == 'url'
+                check_image_node child
+                check_streamable_node child
+                if child.name == 'stats'
+                    child.children.each do |childL3|
+                        @listeners = childL3.content.to_i if childL3.name == 'listeners'
+                        @playcount = childL3.content.to_i if childL3.name == 'playcount'
+                    end
+                end
+            end
+        end
+        @info_loaded = true
+    end # load_info
+    
+    def ==(otherArtist)
+      if otherArtist.is_a?(Scrobbler::Artist)
+        return (@name == otherArtist.name)
+      end
+      false
+    end
+    
+  end
+end

data/lib/scrobbler/auth.rb

@@ -0,0 +1,47 @@
+module Scrobbler
+  # @todo everything
+  class Auth < Base
+  
+    def initialize(username)
+      super()
+      @username = username
+    end
+    
+    def session(token)
+      doc = Base.request('auth.getsession', :signed => true, :token => token)
+      asession = {}
+      doc.root.children.each do |child1|
+        next unless child1.name == 'session'
+        child1.children.each do |child2|
+          if child2.name == 'name'
+            asession[:name] = child2.content
+          elsif child2.name == 'key'
+            asession[:key] = child2.content
+          elsif child2.name == 'subscriber'
+            asession[:subscriber] = true if child2.content == '1'
+            asession[:subscriber] = false unless child2.content == '1'
+          end   
+        end
+      end
+      Scrobbler::Session.new(asession)
+    end
+    
+    def token
+      doc = Base.request('auth.gettoken', :signed => true)
+      stoken = ''
+      doc.root.children.each do |child|
+        next unless child.name == 'token'
+        stoken = child.content
+      end
+      stoken
+    end
+    
+    def url(options={})
+      options[:token] = token if options[:token].nil?
+      options[:api_key] = @@api_key
+      "http://www.last.fm/api/auth/?api_key=#{options[:api_key]}&token=#{options[:token]}"
+    end
+    
+  end
+end
+