scrobbler-ng 2.0.0

data/lib/scrobbler/scrobble.rb

@@ -0,0 +1,116 @@
+# exception definitions
+class BadAuthError < StandardError; end
+class BadSessionError < StandardError; end
+class BadTimeError < StandardError; end
+class ClientBannedError < StandardError; end
+class RequestFailedError < StandardError; end
+
+module Scrobbler
+  class Scrobble
+    SUBMISSION_HOST = 'http://post.audioscrobbler.com:80/'
+    SUBMISSION_PORT = 80
+    SUBMISSION_VERSION = '1.2.1'
+    
+    @@client_id = 'tst'
+    @@client_ver = '1.0'
+    @@default_options = {
+      :handshake_on_init => true
+    }
+
+    def Scrobble.client_id=(cid)
+      @@client_id = cid
+    end
+    
+    def Scrobble.client_ver=(cver)
+      @@client_ver = cver
+    end
+    
+    def initialize(options={})
+      params = @@default_options.merge(options)
+      warn 'Warning: Default client id used, this is for testing only' if @@client_id == 'tst'
+      raise ArgumentError, 'Session is required' if params[:session].nil?
+      raise ArgumentError, 'User is required' if params[:user].nil?
+      @session = params[:session]
+      @user = params[:user]
+    end
+    
+    def handshake
+      ts = Time.now.to_i.to_s
+      auth_token = Digest::MD5.hexdigest(@session.key + ts)
+      params = {
+        :hs => 'true',
+        :ps => SUBMISSION_VERSION,
+        :c => @@client_id,
+        :v => @@client_ver,
+        :u => @user.name,
+        :t => ts,
+        :a => auth_token,
+        :sk => @session.key
+      }
+      url = URI.join(SUBMISSION_HOST)
+      query = []
+      params.each do |k,v|
+        query << [Base.sanitize(k), Base.sanitize(v)]
+      end
+      url.query = query.join('&')
+      req = Net::HTTP::Get.new(url.request_uri)
+      res = Net::HTTP.start(SUBMISSION_HOST, SUBMISSION_PORT) do |conn|
+        conn.request(req)
+      end
+      res = res.body.split("\n")
+      if res[0] == 'OK'
+        # Handshake done, parse and return information
+        @session_id = res[1]
+        @now_playing_url = res[2]
+        @submission_url = res[3]
+      elsif res[0] == 'BANNED'
+        # This indicates that this client version has been banned from the
+        # server. This usually happens if the client is violating the protocol
+        # in a destructive way. Users should be asked to upgrade their client
+        # application.
+        raise ClientBannedError, 'Please update your client to a newer version.'
+      elsif res[0] == 'BADAUTH'
+        # This indicates that the authentication details provided were incorrect. 
+        # The client should not retry the handshake until the user has changed 
+        # their details
+        raise BadAuthError
+      elsif res[0] == 'BADTIME'
+        # The timestamp provided was not close enough to the current time. 
+        # The system clock must be corrected before re-handshaking.
+        raise BadTimeError, "Not close enough to current time: #{ts}"
+      else
+        # This indicates a temporary server failure. The reason indicates the
+        # cause of the failure. The client should proceed as directed in the
+        # failure handling section
+        raise RequestFailedError, res[0]
+      end
+    end #^ handshake
+    
+    def now_playing(track)
+      params = {
+        's' => @session_id,
+        't' => track.name,
+        'a' => track.artist.name,
+        'b' => '',
+        'l' => '',
+        'n' => '',
+        'm' => ''
+      }
+      params['b'] = track.album.name unless track.album.nil?
+      params['l'] = track.duration.to_s unless track.duration.nil? && track.duration > 30
+      # @todo params['n']
+      params['m'] = track.mbid unless track.mbid.nil?
+      res = Net::HTTP.post_form(URI.parse(SUBMISSION_HOST), params).body.split("\n")
+      if res[0] == 'BADSESSION'
+        # This indicates that the Session ID sent was somehow invalid, possibly
+        # because another client has performed a handshake for this user. On
+        # receiving this, the client should re-handshake with the server before
+        # continuing. 
+        raise BadSessionError
+      end
+    end #^ now_playing
+    
+    def submit(tracks={})
+    end #^ submit
+  end
+end

data/lib/scrobbler/session.rb

@@ -0,0 +1,9 @@
+module Scrobbler
+  class Session < Base
+    attr_reader :key, :name, :subscriber
+    
+    def initialize(data={})
+      populate_data(data)
+    end
+  end
+end

data/lib/scrobbler/shout.rb

@@ -0,0 +1,21 @@
+module Scrobbler
+  class Shout < Base
+    attr_reader :author, :date, :body
+    
+    class << self
+      def new_from_libxml(xml)
+        data={}
+        xml.children.each do |child|
+          data[:body] = child.content if child.name == 'body'
+          data[:author] = Scrobbler::User.new(child.content) if child.name == 'author'
+          data[:date] = Time.parse(child.content) if child.name == 'date'
+        end
+        Shout.new(data)
+      end
+    end
+
+    def initialize(input={})
+      populate_data(input)
+    end
+  end
+end

data/lib/scrobbler/simpleauth.rb

@@ -0,0 +1,60 @@
+require 'digest/md5'
+
+# exception definitions
+class BadAuthError < StandardError; end
+class BannedError < StandardError; end
+class BadTimeError < StandardError; end
+module Scrobbler
+  AUTH_URL = 'http://post.audioscrobbler.com'
+  AUTH_VER = '1.2.1'
+  
+  # @todo This is not 2.0!!
+  class SimpleAuth
+    # you should read last.fm/api/submissions#handshake
+
+    attr_accessor :user, :password, :client_id, :client_ver
+    attr_reader :status, :session_id, :now_playing_url, :submission_url
+
+    def initialize(args = {})
+      @user = args[:user] # last.fm username
+      @password = args[:password] # last.fm password
+      @client_id = 'rbs' # Client ID assigned by last.fm; Don't change this!
+      @client_ver = '0.2.13'
+
+      raise ArgumentError, 'Missing required argument' if @user.empty? || @password.empty?
+
+      @connection = REST::Connection.new(AUTH_URL)
+    end
+
+    def handshake!
+      password_hash = Digest::MD5.hexdigest(@password)
+      timestamp = Time.now.to_i.to_s
+      token = Digest::MD5.hexdigest(password_hash + timestamp)
+
+      query = { :hs => 'true',
+                :p => AUTH_VER,
+                :c => @client_id,
+                :v => @client_ver,
+                :u => @user,
+                :t => timestamp,
+                :a => token }
+      result = @connection.get('/', query)
+
+      @status = result.split(/\n/)[0]
+      case @status
+      when /OK/
+        @session_id, @now_playing_url, @submission_url = result.split(/\n/)[1,3]
+      when /BANNED/
+        raise BannedError # something is wrong with the gem, check for an update
+      when /BADAUTH/
+        raise BadAuthError # invalid user/password
+      when /FAILED/
+        raise RequestFailedError, @status
+      when /BADTIME/
+        raise BadTimeError # system time is way off
+      else
+        raise RequestFailedError
+      end  
+    end
+  end
+end

data/lib/scrobbler/tag.rb

@@ -0,0 +1,113 @@
+# Below is code samples for how to find the top albums and tracks for a tag.
+# 
+#   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}" }
+#   
+# Which would output something similar to:
+# 
+#   Top Albums
+#   (29) American IV: The Man Comes Around by Johnny Cash
+#   (14) Folks Pop In at the Waterhouse by Various Artists
+#   (13) Hapless by Flowers From The Man Who Shot Your Cousin
+#   (9) Taking The Long Way by Dixie Chicks
+#   (8) Unchained by Johnny Cash
+#   (8) American III: Solitary Man by Johnny Cash
+#   (8) Wide Open Spaces by Dixie Chicks
+#   (7) It's Now or Later by Tangled Star
+#   (7) Greatest Hits by Hank Williams
+#   (7) American Recordings by Johnny Cash
+#   (6) Forgotten Landscape by theNoLifeKing
+#   (6) At Folsom Prison by Johnny Cash
+#   (6) Fox Confessor Brings the Flood by Neko Case
+#   (6) Murder by Johnny Cash
+#   (5) Gloom by theNoLifeKing
+#   (5) Set This Circus Down by Tim McGraw
+#   (5) Blacklisted by Neko Case
+#   (5) Breathe by Faith Hill
+#   (5) Unearthed (disc 4: My Mother's Hymn Book) by Johnny Cash
+#   (4) Home by Dixie Chicks
+# 
+#   Top Tracks
+#   (221) Hurt by Johnny Cash
+#   (152) I Walk the Line by Johnny Cash
+#   (147) Ring of Fire by Johnny Cash
+#   (125) Folsom Prison Blues by Johnny Cash
+#   (77) The Man Comes Around by Johnny Cash
+#   (67) Personal Jesus by Johnny Cash
+#   (65) Not Ready To Make Nice by Dixie Chicks
+#   (63) Before He Cheats by Carrie Underwood
+#   (62) Give My Love to Rose by Johnny Cash
+#   (49) Jackson by Johnny Cash
+#   (49) What Hurts The Most by Rascal Flatts
+#   (48) Big River by Johnny Cash
+#   (46) Man in Black by Johnny Cash
+#   (46) Jolene by Dolly Parton
+#   (46) Friends in Low Places by Garth Brooks
+#   (46) One by Johnny Cash
+#   (44) Cocaine Blues by Johnny Cash
+#   (41) Get Rhythm by Johnny Cash
+#   (41) I Still Miss Someone by Johnny Cash
+#   (40) The Devil Went Down to Georgia by Charlie Daniels Band
+module Scrobbler
+  class Tag < Base
+    attr_accessor :name, :count, :url, :streamable
+    
+    class << self
+      def new_from_libxml(xml)
+        data = {}
+        xml.children.each do |child|
+          data[:name] = child.content if child.name == 'name'
+          data[:count] = child.content.to_i if child.name == 'count'
+          data[:url] = child.content if child.name == 'url'
+          if child.name == 'streamable'
+            if ['1', 'true'].include?(child.content)
+              data[:streamable] = true
+            else
+              data[:streamable] = false
+            end
+          end
+        end
+        
+        Tag.new(data[:name], data)
+      end
+    end
+    
+    def initialize(name, data={})
+      raise ArgumentError, "Name is required" if name.empty?
+      @name = name
+      @url = data[:url] unless data[:url].nil?
+      @count = data[:count] unless data[:count].nil?
+      @streamable = data[:streamable] unless data[:streamable].nil?
+    end
+    
+    def top_artists(force=false)
+      get_response('tag.gettopartists', :top_artists, 'topartists', 'artist', {'tag'=>@name}, force)
+    end
+    
+    def top_albums(force=false)
+      get_response('tag.gettopalbums', :top_albums, 'topalbums', 'album', {'tag'=>@name}, force)
+    end
+
+    def top_tracks(force=false)
+      get_response('tag.gettoptracks', :top_tracks, 'toptracks', 'track', {'tag'=>@name}, force)
+    end
+
+    def Tag.top_tags
+        self.get('tag.gettoptags', :toptags, :tag)
+    end
+    
+    # Search for tags similar to this one. Returns tags ranked by similarity, 
+    # based on listening data.
+    def similar(force=false)
+        params = {:tag => @name}
+        get_response('tag.getsimilar', :similar, 'similartags', 'tag', params, force)
+    end
+  end
+end

data/lib/scrobbler/track.rb

@@ -0,0 +1,138 @@
+# Below is an example of how to get the top fans for a track.
+# 
+#   track = Scrobbler::Track.new('Carrie Underwood', 'Before He Cheats')
+#   puts 'Fans'
+#   puts "=" * 4
+#   track.fans.each { |u| puts u.username }
+#   
+# Which would output something like:
+# 
+#   track = Scrobbler::Track.new('Carrie Underwood', 'Before He Cheats')
+#   puts 'Fans'
+#   puts "=" * 4
+#   track.fans.each { |u| puts "(#{u.weight}) #{u.username}" }
+# 
+#   Fans
+#   ====
+#   (69163) PimpinRose
+#   (7225) selene204
+#   (7000) CelestiaLegends
+#   (6817) muehllr
+#   (5387) Mudley
+#   (5368) ilovejohnny1984
+#   (5232) MeganIAD
+#   (5132) Veric
+#   (5097) aeVnar
+#   (3390) kristaaan
+#   (3239) kelseaowns
+#   (2780) syndication
+#   (2735) mkumm
+#   (2706) Kimmybeebee
+#   (2648) skorpcroze
+#   (2549) mistergreg
+#   (2449) mlmjcace
+#   (2302) tiNEey
+#   (2169) ajsbabiegirl
+module Scrobbler
+  class Track < Base
+    # Load Helper modules
+    include ImageObjectFuncs
+    extend  ImageClassFuncs
+    
+    attr_accessor :artist, :name, :mbid, :playcount, :rank, :url, :id, :count
+    attr_accessor :streamable, :album, :date, :now_playing, :tagcount
+    attr_accessor :duration, :listeners
+    
+    class << self
+      def new_from_libxml(xml)
+        data = {}
+        xml.children.each do |child|
+          data[:name] = child.content if child.name == 'name'
+          data[:mbid] = child.content if child.name == 'mbid'
+          data[:url] = child.content if child.name == 'url'
+          data[:date] = Time.parse(child.content) if child.name == 'date'
+          data[:artist] = Artist.new_from_libxml(child) if child.name == 'artist'
+          data[:album] = Album.new_from_libxml(child) if child.name == 'album'
+          data[:playcount] = child.content.to_i if child.name == 'playcount'
+          data[:tagcount] = child.content.to_i if child.name == 'tagcount'
+          maybe_image_node(data, child)
+          if child.name == 'streamable'
+            if ['1', 'true'].include?(child.content)
+              data[:streamable] = true
+            else
+              data[:streamable] = false
+            end
+          end
+        end
+        
+        
+        data[:rank] = xml['rank'].to_i if xml['rank']
+        data[:now_playing] = true if xml['nowplaying'] && xml['nowplaying'] == 'true'
+        
+        data[:now_playing] = false if data[:now_playing].nil?
+        
+        Track.new(data[:artist], data[:name], data)
+      end
+    end
+    
+    def initialize(artist, name, data={})
+      raise ArgumentError, "Artist is required" if artist.nil?
+      raise ArgumentError, "Name is required" if name.empty?
+      @artist = artist
+      @name = name
+      populate_data(data)
+    end
+    
+    def add_tags(tags)
+        # This function requires authentication, but SimpleAuth is not yet 2.0
+        raise NotImplementedError
+    end
+
+    def ban
+        # This function requires authentication, but SimpleAuth is not yet 2.0
+        raise NotImplementedError
+    end
+    
+    @info_loaded = false
+    def load_info
+        return nil if @info_loaded
+        doc = Base.request('track.getinfo', :artist => @artist.name, :track => @name)
+        doc.root.children.each do |childL1|
+            next unless childL1.name == 'track'
+            childL1.children.each do |child|
+                @id = child.content.to_i if child.name == 'id'
+                @mbid = child.content if child.name == 'mbid'
+                @duration = child.content.to_i if child.name == 'duration'
+                @url = child.content if child.name == 'url'
+                if child.name == 'streamable'
+                    if ['1', 'true'].include?(child.content)
+                      @streamable = true
+                    else
+                      @streamable = false
+                    end
+                end
+                @listeners = child.content.to_i if child.name == 'listeners'
+                @playcount = child.content.to_i if child.name == 'playcount'
+                @artist = Artist.new_from_libxml(child) if child.name == 'artist'
+                @album = Album.new_from_libxml(child) if child.name == 'album'
+            end
+        end
+        @info_loaded = true
+    end
+
+    def top_fans(force=false)
+      get_response('track.gettopfans', :fans, 'topfans', 'user', {:artist=>@artist.name, :track=>@name}, force)
+    end
+    
+    def top_tags(force=false)
+      get_response('track.gettoptags', :top_tags, 'toptags', 'tag', {:artist=>@artist.name.to_s, :track=>@name}, force)
+    end
+    
+    def ==(otherTrack)
+      if otherTrack.is_a?(Scrobbler::Track)
+        return ((@name == otherTrack.name) && (@artist == otherTrack.artist))
+      end
+      false
+    end
+  end
+end

data/lib/scrobbler/user.rb

@@ -0,0 +1,222 @@
+# Probably the most common use of this lib would be to get your most recent tracks or your top tracks. Below are some code samples.
+#   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}" }
+#   
+# Which would output something like:
+#
+#   jnunemaker's Recent Tracks
+#   ==========================
+#   Everything You Want
+#   You're a God
+#   Bitter Sweet Symphony [Original Version]
+#   Lord I Guess I'll Never Know
+#   Country Song
+#   Bitter Sweet Symphony (Radio Edit)
+# 
+# 
+#   jnunemaker's Top Tracks
+#   =======================
+#   (62) Probably Wouldn't Be This Way
+#   (55) Not Ready To Make Nice
+#   (45) Easy Silence
+#   (43) Song 2
+#   (40) Everybody Knows
+#   (39) Before He Cheats
+#   (39) Something's Gotta Give
+#   (38) Hips Don't Lie (featuring Wyclef Jean)
+#   (37) Unwritten
+#   (37) Move Along
+#   (37) Dance, Dance
+#   (36) We Belong Together
+#   (36) Jesus, Take the Wheel
+#   (36) Black Horse and the Cherry Tree (radio version)
+#   (35) Photograph
+#   (35) You're Beautiful
+#   (35) Walk Away
+#   (34) Stickwitu
+module Scrobbler  
+  class User < Base
+    # Load Helper modules
+    include ImageObjectFuncs
+    extend  ImageClassFuncs
+    
+    attr_reader :username, :url, :weight, :match, :realname, :name
+    
+    class << self
+      def new_from_libxml(xml)
+        data = {}
+        xml.children.each do |child|
+          data[:name] = child.content if child.name == 'name'
+          data[:url] = child.content if child.name == 'url'
+          data[:weight] = child.content.to_i if child.name == 'weight'
+          data[:match] = child.content if child.name == 'match'
+          data[:realname] = child.content if child.name == 'realname'
+          maybe_image_node(data, child)
+        end
+        User.new(data[:name], data)
+      end
+
+      def find(*args)
+        options = {:include_profile => false}
+        options.merge!(args.pop) if args.last.is_a?(Hash)
+        users = args.flatten.inject([]) { |users, u| users << User.new(u, options); users }
+        users.length == 1 ? users.pop : users
+      end
+    end
+    
+    def initialize(username, input={})
+      data = {:include_profile => false}.merge(input)
+      raise ArgumentError if username.empty?
+      @username = username
+      @name = @username
+      load_profile() if data[:include_profile]
+      populate_data(data)
+    end
+    
+    # Get a list of upcoming events that this user is attending. 
+    #
+    # Supports ical, ics or rss as its format  
+    def events(force=false)
+      get_response('user.getevents', :events, 'events', 'event', {'user'=>@username}, force)
+    end
+
+    # Get a list of the user's friends on Last.fm.    
+    def friends(force=false, page=1, limit=50)
+      get_response('user.getfriends', :friends, 'friends', 'user', {'user'=>@username, 'page'=>page.to_s, 'limit'=>limit.to_s}, force)
+    end
+    
+    # Get information about a user profile.
+    def load_info
+        # This function requires authentication, but SimpleAuth is not yet 2.0
+        raise NotImplementedError
+    end
+    
+    # Get the last 50 tracks loved by a user.
+    def loved_tracks(force=false)
+        get_response('user.getlovedtracks', :loved_tracks, 'lovedtracks', 'track', {'user'=>@username}, force)
+    end
+
+    # Get a list of a user's neighbours on Last.fm.
+    def neighbours(force=false)
+      get_response('user.getneighbours', :neighbours, 'neighbours', 'user', {'user'=>@username}, force)
+    end
+
+    # Get a paginated list of all events a user has attended in the past. 
+    def past_events(format=:ics)
+      # This needs a Event class, which is yet not available
+      raise NotImplementedError
+    end
+    
+    # Get a list of a user's playlists on Last.fm. 
+    def playlists(force=false)
+                          #(api_method, instance_name, parent, element, parameters, force=false)
+      get_response('user.getplaylists', :playlist, 'playlists', 'playlist', {'user'=>@username}, force)
+    end
+    
+    # Get a list of the recent tracks listened to by this user. Indicates now 
+    # playing track if the user is currently listening.
+    #
+    # Possible parameters:
+    #   - limit: An integer used to limit the number of tracks returned.
+    def recent_tracks(force=false, parameters={})
+      parameters.merge!({'user' => @username})
+      get_response('user.getrecenttracks', :recent_tracks, 'recenttracks', 'track', parameters, force)
+    end
+    
+    # Get Last.fm artist recommendations for a user
+    def recommended_artists
+        # This function require authentication, but SimpleAuth is not yet 2.0
+        raise NotImplementedError
+    end
+    
+    # Get a paginated list of all events recommended to a user by Last.fm, 
+    # based on their listening profile. 
+    def recommended_events
+        # This function require authentication, but SimpleAuth is not yet 2.0
+        raise NotImplementedError
+    end
+    
+    # Get shouts for this user.
+    def shouts
+      # This needs a Shout class which is yet not available
+      raise NotImplementedError
+    end
+    
+    # Get the top albums listened to by a user. You can stipulate a time period. 
+    # Sends the overall chart by default. 
+    def top_albums(force=false, period='overall')
+      get_response('user.gettopalbums', :top_albums, 'topalbums', 'album', {'user'=>@username, 'period'=>period}, force)
+    end
+
+    # Get the top artists listened to by a user. You can stipulate a time 
+    # period. Sends the overall chart by default. 
+    def top_artists(force=false, period='overall')
+      get_response('user.gettopartists', :top_artists, 'topartists', 'artist', {'user' => @username, 'period'=>period}, force)
+    end
+
+    #  Get the top tags used by this user.
+    def top_tags(force=false)
+      get_response('user.gettoptags', :top_tags, 'toptags', 'tag', {'user'=>@username}, force)
+    end
+
+    # Get the top tracks listened to by a user. You can stipulate a time period. 
+    # Sends the overall chart by default. 
+    def top_tracks(force=false, period='overall')
+      get_response('user.gettoptracks', :top_tracks, 'toptracks', 'track', {'user'=>@username, 'period'=>period}, force)
+    end
+
+    # Get an album chart for a user profile, for a given date range. If no date 
+    # range is supplied, it will return the most recent album chart for this 
+    # user. 
+    def weekly_album_chart(from=nil, to=nil)
+      parameters = {'user' => @username}
+      parameters['from'] = from unless from.nil?
+      parameters['to'] = to unless to.nil?
+      get_response('user.getweeklyalbumchart', nil, 'weeklyalbumchart', 'album', parameters, true)
+    end
+    
+    # Get an artist chart for a user profile, for a given date range. If no date
+    # range is supplied, it will return the most recent artist chart for this 
+    # user. 
+    def weekly_artist_chart(from=nil, to=nil)
+      parameters = {'user' => @username}
+      parameters['from'] = from unless from.nil?
+      parameters['to'] = to unless to.nil?
+      get_response('user.getweeklyartistchart', nil, 'weeklyartistchart', 'artist', parameters, true)
+    end
+    
+    # Get a list of available charts for this user, expressed as date ranges 
+    # which can be sent to the chart services. 
+    def weekly_chart_list(force=false)
+      # @todo
+      raise NotImplementedError
+    end
+
+    # Get a track chart for a user profile, for a given date range. If no date 
+    # range is supplied, it will return the most recent track chart for this 
+    # user. 
+    def weekly_track_chart(from=nil, to=nil)
+      parameters = {'user' => @username}
+      parameters['from'] = from unless from.nil?
+      parameters['to'] = to unless to.nil?
+      get_response('user.getweeklytrackchart', nil, 'weeklytrackchart', 'track', parameters, true)
+    end
+    
+    # Shout on this user's shoutbox
+    def shout(message)
+      # This function require authentication, but SimpleAuth is not yet 2.0
+      raise NotImplementedError
+    end
+    
+  end
+end