audioscrobbler 0.0.1

data/MANIFEST

@@ -0,0 +1,9 @@
+audioscrobbler.gemspec
+COPYING
+INSTALL
+lib/audioscrobbler.rb
+MANIFEST
+README
+setup.rb
+test/test_audioscrobbler.rb
+test/test_queue.rb

data/README

@@ -0,0 +1,6 @@
+This package contains an Audioscrobbler class for Ruby that implements the
+Audioscrobbler plugin protocol, used to submit playlist history to Last.fm.
+The INSTALL file contains installation instructions.
+
+Daniel Erat <dan-ruby@erat.org>
+http://www.erat.org/ruby/

data/audioscrobbler.gemspec

@@ -0,0 +1,16 @@
+require 'rubygems'
+SPEC = Gem::Specification.new do |s|
+  s.name          = "audioscrobbler"
+  s.version       = "0.0.1"
+  s.author        = "Daniel Erat"
+  s.email         = "dan-ruby@erat.org"
+  s.homepage      = "http://www.erat.org/ruby/"
+  s.platform      = Gem::Platform::RUBY
+  s.summary       = "Library to submit music playlists to Last.fm"
+  candidates      = Dir.glob("{*,{lib,test}/*}")
+  s.files         = candidates.delete_if {|i| i =~ /CVS/ }
+  s.require_path  = "lib"
+  s.autorequire   = "audioscrobbler"
+  s.test_files    = Dir.glob("test/test_{audioscrobbler,queue}.rb")
+  s.has_rdoc      = true
+end

data/lib/audioscrobbler.rb

@@ -0,0 +1,475 @@
+#!/usr/bin/ruby -w
+#
+# = Name
+# Audioscrobbler
+#
+# == Description
+# This file contains an implementation of the Audioscrobbler plugin
+# protocol, used to submit playlist history to Last.fm.  The protocol
+# description is located at http://www.audioscrobbler.net/wiki/Protocol1.1 .
+#
+# == Version
+# 0.0.1
+#
+# == Author
+# Daniel Erat <dan-ruby@erat.org>
+#
+# == Copyright
+# Copyright 2005 Daniel Erat
+#
+# == License
+# GNU GPL; see COPYING
+#
+# == Changes
+# 0.0.1  Initial release
+
+require "cgi"
+require "md5"
+require "net/http"
+require "thread"
+require "uri"
+
+# = Audioscrobbler
+#
+# == Description
+# Queue music tracks as they are played and submit the track information to
+# Last.fm (http://www.last.fm) using the Audioscrobbler plugin protocol
+# (http://www.audioscrobbler.net/).
+#
+# Version 1.1 of the plugin protocol
+# (http://www.audioscrobbler.net/wiki/Protocol1.1) is currently used.
+#
+# == Usage
+#  require "audioscrobbler"
+#  scrob = Audioscrobbler.new("user",       # Audioscrobbler username
+#                             "pass",       # Audioscrobbler password
+#                             "queue.txt",  # file for storing queue
+#                            )
+#
+#  # Replace these with the client ID that's been assigned to your
+#  # plugin by the Audioscrobbler folks and your plugin's version number.
+#  scrob.client = "tst"
+#  scrob.version = "1.0"
+#
+#  # If you don't start the submitter, tracks will just pile up in the
+#  # submission queue.
+#  scrob.start_submitter_thread
+#
+#  # Now wait until the Audioscrobbler submission criteria has been met.
+#
+#  # And then queue the track for submission:
+#  scrob.enqueue("Beach Boys",      # artist
+#                "God Only Knows",  # title
+#                175,               # track length, in seconds
+#                1125378558,        # track start time
+#                "Pet Sounds",      # album (optional)
+#                "",                # MusicBrainzID (optional)
+#               )
+class Audioscrobbler
+  # Default URI to connect to for the handshake.
+  DEFAULT_HANDSHAKE_URI = "http://post.audioscrobbler.com/"
+
+  # Default minimum interval to wait between successful submissions.
+  # This will be overriden if the server supplies an interval.
+  DEFAULT_SUBMIT_INTERVAL_SEC = 5
+
+  # Default plugin name and version to report to the server.
+  # You MUST set these to the values that you've registered before
+  # you can distribute your plugin to anyone (including beta testers).
+  DEFAULT_CLIENT = "tst"
+  DEFAULT_VERSION = "1.0"
+
+  # Maximum number of tracks that will be accepted in a single
+  # submission.  This is a server-imposed limit.
+  MAX_TRACKS_IN_SUBMISSION = 10
+
+  ##
+  # Create a new Audioscrobbler object.
+  #
+  # @param username  Audioscrobbler account username
+  # @param password  Audioscrobbler account password
+  # @param filename  file used for on-disk storage of not-yet-submitted
+  #                  tracks
+  #
+  def initialize(username, password, filename=nil)
+    @username = username
+    @password = password
+    @queue = SubmissionQueue.new(filename)
+    @verbose = false
+    @client = DEFAULT_CLIENT
+    @version = DEFAULT_VERSION
+
+    @handshake_uri = DEFAULT_HANDSHAKE_URI
+    @last_handshake_time = nil
+    @handshake_backoff_sec = 0
+
+    @md5_resp = nil
+    @submit_uri = nil
+    @submit_interval_sec = DEFAULT_SUBMIT_INTERVAL_SEC
+  end
+  attr_accessor :username, :password, :verbose
+  attr_accessor :client, :version, :handshake_uri
+
+  ##
+  # Update the backoff interval after handshake failure.  If we haven't
+  # failed yet, we wait a minute; otherwise, we wait twice as long as last
+  # time, up to a maximum of two hours.
+  #
+  # @param message  string logged to stderr if verbose logging is enabled
+  #
+  def handle_handshake_failure(message)
+    vlog(message)
+    if @handshake_backoff_sec < 60
+      @handshake_backoff_sec = 60
+    elsif @handshake_backoff_sec < 2 * 60 * 60
+      @handshake_backoff_sec *= 2
+    else
+      @handshake_backoff_sec = 2 * 60 * 60
+    end
+  end
+  private :handle_handshake_failure
+
+  ##
+  # Attempt to handshake with the server.
+  # Returns true on success and false on failure.
+  # If the connection fails, @handshake_backoff_sec is also updated
+  # appropriately.  Wait this long before trying to handshake again.
+  #
+  def do_handshake
+    # Sleep before trying again if needed.
+    if @last_handshake_time != nil and \
+        @last_handshake_time + @handshake_backoff_sec > Time.now
+      sleep(@last_handshake_time + @handshake_backoff_sec - Time.now)
+    end
+
+    @last_handshake_time = Time.now
+
+    args = {
+      "hs" => "true",
+      "p"  => "1.1",
+      "c"  => @client,
+      "v"  => @version,
+      "u"  => @username,
+    }
+    uri = @handshake_uri + '?' + args.collect {|attr, value|
+      CGI.escape(attr.to_s) + '=' + CGI.escape(value.to_s)
+    }.join('&')
+
+    vlog("Beginning handshake with #@handshake_uri")
+
+    begin
+      data = Net::HTTP.get_response(URI.parse(uri)).body
+    rescue Exception
+      handle_handshake_failure(
+        "Read of #@handshake_uri for handshake failed: #{$!}")
+      return false
+    end
+
+    # Make sure that we got something back.
+    if not data
+      handle_handshake_failure(
+        "Got empty response from server during handshake")
+      return false
+    end
+
+    lines = data.split("\n")
+
+    # Check whether the server says we can talk to it.
+    # INTERVAL is supposed to be returned even on failure, but we don't
+    # bother looking at it in this case because we already back off
+    # extremely aggressively from handshake failures, and we'll end up
+    # getting a new submission interval when we handshake successfully.
+    response = lines[0].split[0]
+    if response != "UPTODATE" and response != "UPDATE"
+      handle_handshake_failure("Got \"#{lines[0]}\" from server during " \
+                               "handshake (expected UPTODATE or UPDATE)")
+      return false
+    end
+
+    # The expected response is something along the lines of:
+    # UPTODATE or UPDATE <plugin uri>
+    # <md5 challenge>
+    # <uri to submit script>
+    # INTERVAL <num>
+    if lines.length < 3
+      handle_handshake_failure(
+        "Got #{lines.length} during handshake (expected >=3)")
+      return false
+    end
+
+    # Create our response based on the server's challenge and
+    # save the submission URI.
+    @md5_resp = MD5.hexdigest(MD5.hexdigest(@password) + lines[1])
+    @submit_uri = lines[2]
+    vlog("Using MD5 response #@md5_resp")
+    vlog("Got submission URI #@submit_uri")
+
+    # Get submission interval.
+    if lines.length < 4 or lines[3].split.length != 2 or \
+        lines[3].split[0] != "INTERVAL"
+      vlog("Didn't get submission interval; using #@submit_interval_sec sec")
+    else
+      @submit_interval_sec = lines[3].split[0].to_i
+      vlog("Got submission interval of #@submit_interval_sec sec")
+    end
+
+    return true
+  end
+  private :do_handshake
+
+  ##
+  # Start the submitter thread and return.
+  #
+  def start_submitter_thread
+    @submit_thread = Thread.new do
+      while true
+        # Wait until there are some tracks in the queue.
+        tracks = @queue.peek(MAX_TRACKS_IN_SUBMISSION)
+
+        # Keep trying to handshake until we're successful.
+        do_handshake while not @md5_resp
+
+        # Might as well re-check in case more tracks have shown up
+        # during the handshaking.
+        tracks = @queue.peek(MAX_TRACKS_IN_SUBMISSION)
+        vlog("Submitting #{tracks.length} track(s)")
+
+        # Construct our argument list.
+        args = {
+          "u" => @username,
+          "s" => @md5_resp,
+        }
+        for i in 0..tracks.length-1
+          args.update({
+            "a[#{i}]" => tracks[i].artist,
+            "t[#{i}]" => tracks[i].title,
+            "b[#{i}]" => tracks[i].album,
+            "m[#{i}]" => tracks[i].mbid,
+            "l[#{i}]" => tracks[i].length.to_s,
+            "i[#{i}]" => Time.at(tracks[i].start_time).utc.
+                         strftime('%Y-%m-%d %H:%M:%S')
+          })
+        end
+        # Convert it into a single escaped string for the body.
+        body = args.collect {|k, v| "#{k}=" + CGI.escape(v.to_s) }.join('&')
+
+        success = false
+
+        begin
+          uri = URI.parse(@submit_uri)
+          data = Net::HTTP.start(uri.host, uri.port) do |http|
+            http.post(uri.path, body).body
+          end
+        rescue Exception
+          vlog("Submission failed -- couldn't read #@submit_uri: #{$!}")
+        else
+          # Check whether the submission was successful.
+          lines = data.split("\n")
+          if not lines[0]
+            vlog("Submission failed -- got empty response")
+          elsif lines[0] == "OK"
+            vlog("Submission was successful")
+            @queue.delete(tracks.length)
+            success = true
+          elsif lines[0] == "BADAUTH"
+            vlog("Submission failed -- authorization failed")
+            # Unset the hash so we'll re-handshake.
+            @md5_resp = nil
+          else
+            vlog("Submission failed -- got unknown response \"#{lines[0]}\"")
+          end
+
+          # Use the server-supplied submission interval, or our default
+          # if the server didn't supply one.
+          if lines.length > 1 and lines[1].split[0] and \
+              lines[1].split[0] == "INTERVAL" and lines[1].split[1]
+            @submit_interval_sec = lines[1].split[1].to_i
+          else
+            @submit_interval_sec = DEFAULT_SUBMIT_INTERVAL_SEC
+          end
+        end
+
+        # If we failed, do exponential backoff starting at 60 seconds.
+        # Better safe than blocked!
+        if not success
+          if @submit_interval_sec < 60
+            @submit_interval_sec = 60
+          else
+            @submit_interval_sec *= 2
+          end
+          vlog("Because of failure, backing off to #@submit_interval_sec sec")
+        end
+
+        vlog("Sleeping #@submit_interval_sec sec before checking for " \
+            "more tracks")
+        sleep(@submit_interval_sec)
+      end
+    end
+  end
+
+  ##
+  # Enqueue a track for submission.
+  #
+  # @param artist      artist name
+  # @param title       track name
+  # @param length      track length
+  # @param start_time  track start time, as UTC unix time
+  # @param album       album name
+  # @param mbid        MusicBrainz ID
+  #
+  def enqueue(artist, title, length, start_time, album="", mbid="")
+    @queue.append(artist, title, length, start_time, album, mbid)
+  end
+
+  ##
+  # Log a message, along with the current time, to stderr.
+  #
+  # @param message  message to log
+  #
+  def log(message)
+    STDERR.puts(Time.now.strftime("%Y-%m-%d %H:%M:%S") + " " + message.to_s)
+  end
+  private :log
+
+  ##
+  # Only log if verbose logging is enabled.
+  #
+  # @param message  message to log
+  #
+  def vlog(message)
+    log(message) if @verbose
+  end
+  private :vlog
+
+  ##
+  # A synchronized, backed-up-to-disk queue holding tracks for submission.
+  # The synchronization is only sufficient for a single reader and writer.
+  #
+  class SubmissionQueue
+    ##
+    # constructor
+    # If a filename is supplied, it will be used to:
+    # a) load tracks that were previously played but not submitted
+    # b) save the state of the queue for later use in a)
+    #
+    # @param filename  queue filename (optional)
+    #
+    def initialize(filename=nil)
+      @filename = filename
+      @queue = Array.new
+      @mutex = Mutex.new
+      @condvar = ConditionVariable.new
+      if @filename and File.exist?(@filename)
+        File.open(@filename, "r").each do |line|
+          @queue.push(PlayedTrack.deserialize(line.chomp))
+        end
+      end
+    end
+
+    ##
+    # Append a played track to the submission queue.
+    #
+    # @param artist      artist name
+    # @param title       track name
+    # @param length      track length
+    # @param start_time  track start time, as UTC unix time
+    # @param album       album name
+    # @param mbid        MusicBrainz ID
+    #
+    def append(artist, title, length, start_time, album="", mbid="")
+      @mutex.synchronize do
+        track = PlayedTrack.new(artist, title, length, start_time, album, mbid)
+        File.open(@filename, "a") {|f| f.puts(track.serialize) } if @filename
+        @queue.push(track)
+        @condvar.signal
+      end
+      self
+    end
+
+    ##
+    # Get tracks from the beginning of the queue.
+    # An array of PlayedTrack objects is returned.  The tracks are _not_
+    # removed from the queue.  If the queue is empty, the method blocks
+    # until a track is placed on the queue.
+    #
+    # @param max_tracks  maximum number of tracks to return
+    #
+    def peek(max_tracks=1)
+      @mutex.synchronize do
+        @condvar.wait(@mutex) if @queue.empty?
+        @queue[0, max_tracks]
+      end
+    end
+
+    ##
+    # Delete tracks from the beginning of the queue.
+    # If more tracks are requested than are in the queue, the queue is
+    # cleared.
+    #
+    # @param num_tracks  number of tracks to delete
+    #
+    def delete(num_tracks)
+      if not @queue.empty?
+        @mutex.synchronize do
+          @queue = @queue[num_tracks..@queue.length-1]
+          if @filename
+            file = File.open(@filename, "w")
+            @queue.each {|track| file.puts(track.serialize) }
+            file.close
+          end
+        end
+      end
+      self
+    end
+
+    # A track that's been played.
+    class PlayedTrack
+      ##
+      # constructor
+      #
+      # @param artist      artist name
+      # @param title       track name
+      # @param length      track length
+      # @param start_time  track start time, as UTC unix time
+      # @param album       album name
+      # @param mbid        MusicBrainz ID
+      #
+      def initialize(artist, title, length, start_time, album="", mbid="")
+        @artist = artist.to_s
+        @title = title.to_s
+        @length = length.to_i
+        @start_time = start_time.to_i
+        @album = album ? album.to_s : ""
+        @mbid = mbid ? mbid.to_s : ""
+      end
+      attr_reader :artist, :title, :length, :start_time, :album, :mbid
+
+      ##
+      # Convert this track's information into a form suitable for writing to
+      # a text file.  Returns a string.
+      #
+      def serialize
+        [@artist, @title, @length.to_s, @start_time.to_s,
+          @album, @mbid].collect {|x| x ? CGI.escape(x) : "" }.join("\t")
+      end
+
+      ##
+      # Undo the operation performed by serialize(), returning a new
+      # PlayedTrack object (class method).
+      #
+      # @param str  serialized PlayedTrack to deserialize (string)
+      #
+      def self.deserialize(str)
+        PlayedTrack.new(*str.split("\t", 6).collect {|x|
+          x ? CGI.unescape(x) : "" })
+      end
+
+      def ==(other)
+        other.class == PlayedTrack and @artist == other.artist and
+          @title == other.title and @length == other.length and
+          @start_time == other.start_time and @album == other.album and
+          @mbid == other.mbid
+      end
+    end  # class PlayedTrack
+  end  # class SubmissionQueue
+end  # class Audioscrobbler