sundawg_music_rec 0.0.1

data/Manifest

@@ -0,0 +1,16 @@
+Manifest
+README
+Rakefile
+lib/artist.rb
+lib/base_entity.rb
+lib/last_fm_client.rb
+lib/track.rb
+lib/util.rb
+lib/yahoo_music_client.rb
+test/files/last_fm/get_similar_artists.xml
+test/files/last_fm/get_similar_tracks.xml
+test/files/yahoo_music/artist_search.xml
+test/files/yahoo_music/artist_similar.xml
+test/last_fm_client_test.rb
+test/test_helper.rb
+test/yahoo_music_client_test.rb

data/README

@@ -0,0 +1,60 @@
+ABOUT
+-----
+This Ruby gem wraps small RESTful clients to hit popular music APIs to find recommended music. Current clients include last.fm and Yahoo! Music.
+
+http://www.last.fm/api
+http://developer.yahoo.com/music/
+
+TEST
+----
+Tests can be run by running:
+
+rake test
+
+To run actual integration tests against RESTful services, you will need to provide an API key for last.fm and Yahoo! Music.
+
+SAMPLE USAGE
+------------
+To find similar songs via last.fm:
+
+last_fm_client = SunDawg::LastFmClient.new
+last_fm_client.api_key = "abcdefg" # YOUR KEY
+tracks = last_fm_client.get_similar_tracks("Creep", "Radiohead")
+tracks.each { |t|
+  puts "TRACK [#{t}]"
+}
+
+To find similar artists via last.fm:
+
+artists = last_fm_client.get_similar_artists("Bob Dylan")
+
+To find similar artists via Yahoo Music!:
+yahoo_music_client = SunDawg::YahooMusicClient.new
+yahoo_music_client.app_id = "abcdefg" # YOUR KEY
+artists = yahoo_music_client.get_similar_artists("The Killers")
+
+Note: The Yahoo! Music API requires that two RESTful calls, one to search for the artist by name to receive the artist ID, then a second call to find similar artists. The get_similar_artists call will implicitly take the first result from the artist search service when finding similar artists. For more granularity, the following methods are supported:
+
+get_artists(name)
+get_similar_artists_by_id(id, options)
+
+GEM INSTALL
+-----------
+This gem is hosted gemcutter.org. To install the gem, you should install gemcutter as so:
+
+sudo gem install gemcutter
+gem tumble
+
+This will add gemcutter to your gem repository for downloading the country_codes gem.
+
+RAILS INSTALL
+-------------
+config.gem 'sundawg_music_rec', :lib => 'last_fm_client'
+config.gem 'sundawg_music_rec', :lib => 'yahoo_music_client'
+
+TO DO
+-----
+- Integrate more recommendation engines.
+- Build a meta-client that calls all API clients.
+- Code improvement.
+

data/Rakefile

@@ -0,0 +1,12 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('sundawg_music_rec', '0.0.1') do |p|
+  p.description    = "Generic API Client for Music Recommendations."
+  p.url            = "http://github.com/SunDawg/music_rec"
+  p.author         = "Christopher Sun"
+  p.email          = "christopher.sun@gmail.com"
+  p.ignore_pattern = ["tmp/*", "script/*"]
+  p.development_dependencies = ['mocha']
+end

data/lib/artist.rb

@@ -0,0 +1,5 @@
+require 'base_entity'
+module SunDawg
+  class Artist < SunDawg::BaseEntity
+  end
+end

data/lib/base_entity.rb

@@ -0,0 +1,5 @@
+module SunDawg
+  class BaseEntity
+    attr_accessor :name, :match, :mbid, :yahoo_id
+  end
+end

data/lib/last_fm_client.rb

@@ -0,0 +1,45 @@
+require 'rexml/document'
+require 'artist'
+require 'track'
+require 'util'
+
+module SunDawg
+  class LastFmClient 
+    attr_accessor :service_host, :api_key
+    
+    def initialize
+      @service_host = "http://ws.audioscrobbler.com"
+    end
+
+    def get_similar_tracks(name, artist)
+      endpoint = "/2.0/" + SunDawg::Util::build_query_string({"method" => "track.getsimilar", "artist" => artist, "track" => name, "api_key" => @api_key})
+      xml = SunDawg::Util.do_http_get(service_host, endpoint)
+      doc = REXML::Document.new(xml)
+      tracks = []
+      doc.elements.each("/lfm/similartracks/track") { |e|
+        tracks << parse_element(SunDawg::Track.new, e) 
+        tracks.last.artist = parse_element(SunDawg::Artist.new, e.elements["artist"])
+      }
+      tracks
+    end
+
+    def get_similar_artists(name, limit = 20)
+      xml = SunDawg::Util.do_http_get(service_host, "/2.0/" + SunDawg::Util::build_query_string({"method" => "artist.getsimilar", "artist" => name, "api_key" => @api_key}))
+      doc = REXML::Document.new(xml)
+      artists = []
+      doc.elements.each("/lfm/similarartists/artist") { |e|
+        artists << parse_element(SunDawg::Artist.new, e)
+      }
+      artists
+    end
+  
+    protected
+
+    def parse_element(model, e)
+      model.name = e.elements["name"].text
+      model.match = e.elements["match"].text.to_f unless e.elements["match"].nil?
+      model.mbid = e.elements["mbid"].text
+      model
+    end
+  end
+end

data/lib/track.rb

@@ -0,0 +1,7 @@
+require 'base_entity'
+
+module SunDawg
+  class Track < BaseEntity
+    attr_accessor :artist
+  end
+end

data/lib/util.rb

@@ -0,0 +1,24 @@
+require 'net/http'
+require 'uri'
+require 'cgi'
+
+module SunDawg
+  module Util
+    def self.build_query_string(params) 
+      s = "?"
+      params.each { |k, v|
+        s += "#{k}=#{CGI.escape(v)}&" unless v.nil?
+      } 
+      s
+    end
+
+    def self.do_http_get(url, endpoint)
+      url = URI.parse("#{url}#{endpoint}")
+      req = Net::HTTP::Get.new(endpoint)
+      res = Net::HTTP.start(url.host, url.port) { |http|
+        http.request(req)
+      }
+      res.body
+    end
+  end
+end

data/lib/yahoo_music_client.rb

@@ -0,0 +1,48 @@
+require 'util'
+require 'cgi'
+require 'rexml/document'
+
+module SunDawg
+  class YahooMusicClient
+    attr_accessor :app_id, :service_host
+
+    def initialize
+      @service_host =  "http://us.music.yahooapis.com"
+    end
+
+    def get_artists(name)
+      endpoint = "/artist/v1/list/search/artist/#{CGI.escape(name)}"
+      endpoint += SunDawg::Util.build_query_string("appid" => app_id)
+      xml = SunDawg::Util.do_http_get(service_host, endpoint)      
+      doc = REXML::Document.new(xml)
+      parse_artists(doc)
+    end
+
+    def get_similar_artists(name) 
+      artists = get_artists(name)
+      get_similar_artists_by_id(artists.first.yahoo_id)
+    end
+
+    def get_similar_artists_by_id(yahoo_id, options = {})
+      endpoint = "/artist/v1/list/similar/#{yahoo_id}"
+      endpoint += SunDawg::Util.build_query_string(options.merge("appid" => app_id))
+      xml = SunDawg::Util.do_http_get(service_host, endpoint)
+      doc = REXML::Document.new(xml)
+      parse_artists(doc)
+    end
+
+    protected
+
+    def parse_artists(doc)
+      artists = []
+      doc.elements.each("/Artists/Artist") { |e|
+        artist = SunDawg::Artist.new
+        artist.yahoo_id = e.attributes["id"]
+        artist.name = e.attributes["name"]
+        artist.match = e.elements["ItemInfo/Relevancy"].attributes["index"].to_i unless e.elements["ItemInfo/Relevancy"].nil?
+        artists << artist
+      }
+      artists
+    end
+  end
+end

data/sundawg_music_rec.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{sundawg_music_rec}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Christopher Sun"]
+  s.date = %q{2009-12-08}
+  s.description = %q{Generic API Client for Music Recommendations.}
+  s.email = %q{christopher.sun@gmail.com}
+  s.extra_rdoc_files = ["README", "lib/artist.rb", "lib/base_entity.rb", "lib/last_fm_client.rb", "lib/track.rb", "lib/util.rb", "lib/yahoo_music_client.rb"]
+  s.files = ["Manifest", "README", "Rakefile", "lib/artist.rb", "lib/base_entity.rb", "lib/last_fm_client.rb", "lib/track.rb", "lib/util.rb", "lib/yahoo_music_client.rb", "test/files/last_fm/get_similar_artists.xml", "test/files/last_fm/get_similar_tracks.xml", "test/files/yahoo_music/artist_search.xml", "test/files/yahoo_music/artist_similar.xml", "test/last_fm_client_test.rb", "test/test_helper.rb", "test/yahoo_music_client_test.rb", "sundawg_music_rec.gemspec"]
+  s.homepage = %q{http://github.com/SunDawg/music_rec}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Sundawg_music_rec", "--main", "README"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{sundawg_music_rec}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Generic API Client for Music Recommendations.}
+  s.test_files = ["test/last_fm_client_test.rb", "test/test_helper.rb", "test/yahoo_music_client_test.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<mocha>, [">= 0"])
+    else
+      s.add_dependency(%q<mocha>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<mocha>, [">= 0"])
+  end
+end

data/test/files/last_fm/get_similar_artists.xml

@@ -0,0 +1,16 @@
+<lfm>
+  <similarartists>
+    <artist>
+      <name>LOLZ SunDawg</name>
+      <mbid>3dc00dcb-6106-43d1-b48d-21d236f53983</mbid>
+      <match>48.39</match>
+      <url>www.last.fm/music/People+Under+the+Stairs</url>
+      <image size="small">http://userserve-ak.last.fm/serve/34/50908.jpg</image>
+      <image size="medium">http://userserve-ak.last.fm/serve/64/50908.jpg</image>
+      <image size="large">http://userserve-ak.last.fm/serve/126/50908.jpg</image>
+      <image size="extralarge">http://userserve-ak.last.fm/serve/252/50908.jpg</image>
+      <image size="mega">http://userserve-ak.last.fm/serve/500/50908/People+Under+the+Stairs.jpg</image>
+      <streamable>1</streamable>
+    </artist>
+  </similarartists>
+</lfm>

data/test/files/last_fm/get_similar_tracks.xml

@@ -0,0 +1,22 @@
+<lfm>
+  <similartracks>
+    <track>
+      <name>House of SunDawg</name>
+      <playcount></playcount>
+      <mbid>abcdefg</mbid>
+      <match>0.22</match>
+      <url>http://www.last.fm/music/Mother+Tongue/_/That+Man</url>
+      <streamable fulltrack="1">1</streamable>
+      <duration>237000</duration>
+      <artist>
+        <name>SunDawg</name>
+        <mbid>6fefd5f2-477e-4225-bb8f-77c6befecd83</mbid>
+        <url>http://www.last.fm/music/Mother+Tongue</url>
+      </artist>
+      <image size="small">http://userserve-ak.last.fm/serve/34s/8711423.jpg</image>
+      <image size="medium">http://userserve-ak.last.fm/serve/64s/8711423.jpg</image>
+      <image size="large">http://userserve-ak.last.fm/serve/126/8711423.jpg</image>
+      <image size="extralarge">http://userserve-ak.last.fm/serve/300x300/8711423.jpg</image>
+    </track>
+  </similartracks>
+</lfm>

data/test/files/yahoo_music/artist_search.xml

@@ -0,0 +1,7 @@
+<Artists start="1" count="23" total="23" errorCount="0">
+  <Artist id="123" rating="-1" name="The SunDawgs" catzillaID="0" hotzillaID="1800038606" trackCount="2887" website="http://www.madonna.com/" url="http://new.music.yahoo.com/madonna/" flags="124611">
+    <ItemInfo>
+      <Relevancy index="722"/>
+    </ItemInfo>
+  </Artist>
+</Artists>

data/test/files/yahoo_music/artist_similar.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Artists  start="1" count="25" total="100" errorCount="0"  >
+  <Artist id="294026" rating="-1" name="Anastacia" catzillaID="1927421443" hotzillaID="1804649855" trackCount="714" website="http://www.anastacia.com" url="http://new.music.yahoo.com/anastacia/" flags="124547">
+  </Artist>
+  <Artist id="254729" rating="-1" name="La Fred" catzillaID="1927036213" hotzillaID="1802474071" trackCount="366" website="" url="http://new.music.yahoo.com/union/" flags="57475">
+  </Artist>
+</Artists>

data/test/last_fm_client_test.rb

@@ -0,0 +1,65 @@
+require 'test_helper'
+require 'last_fm_client'
+
+class LastFmClientTest < Test::Unit::TestCase 
+
+  INTEGRATION = false 
+
+  include TestHelper
+
+  def setup
+    # TODO: Add Your Last.fm API-KEY 
+    client.api_key = 'abcdef'
+  end
+
+  def test_get_similar_tracks
+    setup_http_get_mock(read_file('test/files/last_fm//get_similar_tracks.xml'))
+    tracks = client.get_similar_tracks("Creep", "Radiohead")
+    assert_equal tracks.size, 1
+    assert_equal tracks.first.name, "House of SunDawg"
+    assert_equal tracks.first.mbid, "abcdefg"
+    assert_equal tracks.first.match, 0.22 
+    assert_equal tracks.first.artist.name, "SunDawg"
+    assert_equal tracks.first.artist.mbid, "6fefd5f2-477e-4225-bb8f-77c6befecd83"
+  end
+
+  def test_get_similar_artists
+    setup_http_get_mock(read_file('test/files/last_fm/get_similar_artists.xml'))
+    artists = client.get_similar_artists("Creep")
+    assert_equal artists.size, 1
+    assert_equal artists.first.name, "LOLZ SunDawg"
+    assert_equal artists.first.mbid, "3dc00dcb-6106-43d1-b48d-21d236f53983"
+    assert_equal artists.first.match, 48.39
+  end
+
+  def test_get_similar_tracks_integration
+    return if !INTEGRATION
+    tracks = client.get_similar_tracks("Creep", "Radiohead")
+    assert_not_nil tracks
+    tracks.each { |t| 
+      assert_not_nil t.name
+      assert_not_nil t.match
+      assert_not_nil t.artist
+      assert_not_nil t.artist.name
+    } 
+  end
+
+  def test_get_similar_artists_integration
+    return if !INTEGRATION
+    artists = client.get_similar_artists("A Tribe Called Quest")
+    assert_not_nil artists
+    artists.each { |a| 
+      assert_not_nil a.name
+      assert_not_nil a.match
+    } 
+  end
+
+  protected
+
+  def client
+    if @client.nil?
+      @client = SunDawg::LastFmClient.new
+    end
+    @client 
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,22 @@
+require 'test/unit'
+require 'rubygems'
+require 'mocha'
+
+module TestHelper
+  def setup_http_get_mock(xml)
+    SunDawg::Util.stubs(:do_http_get).returns(xml)
+  end
+
+  def read_file(name)
+    begin
+      file = File.new(name, "r")
+      content = ""
+      while (line = file.gets)
+        content += line
+      end
+      return content
+    ensure
+      file.close unless file.nil?
+    end
+  end
+end

data/test/yahoo_music_client_test.rb

@@ -0,0 +1,62 @@
+require 'test_helper'
+require 'yahoo_music_client'
+
+class YahooMusicClientTest < Test::Unit::TestCase 
+
+  include TestHelper
+
+  INTEGRATION = false
+
+  def setup
+    # TODO: Add Your Yahoo! Music APP-ID
+    client.app_id = 'ABCDEF'
+  end
+
+  def test_get_artists
+    setup_http_get_mock(read_file('test/files/yahoo_music/artist_search.xml'))
+    artists = client.get_similar_artists("The Killers")
+    assert_equal artists.size, 1
+    assert_equal artists.first.name, "The SunDawgs"
+    assert_equal artists.first.match, 722
+    assert_equal artists.first.yahoo_id, "123"
+  end
+
+  def test_get_similar_artists
+    setup_http_get_mock(read_file('test/files/yahoo_music/artist_similar.xml'))
+    artists = client.get_similar_artists("The Killers")
+    assert_equal artists.size, 2
+    assert_equal artists.first.name, "Anastacia"
+    assert_equal artists.first.yahoo_id, "294026"
+    assert_equal artists.last.name, "La Fred"
+    assert_equal artists.last.yahoo_id, "254729"
+  end
+
+  def test_get_similar_artists_integration
+    return if !INTEGRATION
+    artists = client.get_similar_artists("Bob Marley")
+    assert_not_nil artists
+    artists.each { |a|
+      assert_not_nil a.name
+    }
+  end
+
+  def test_get_artists_integration
+    return if !INTEGRATION
+    artists = client.get_artists("The Rolling Stones")
+    assert_not_nil artists
+    artists.each { |a|
+      assert_not_nil a.name
+      assert_not_nil a.yahoo_id
+      assert_not_nil a.match
+    }
+  end
+
+  protected
+
+  def client
+    if @client.nil?
+      @client = SunDawg::YahooMusicClient.new
+    end
+    @client
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification 
+name: sundawg_music_rec
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Christopher Sun
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-08 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Generic API Client for Music Recommendations.
+email: christopher.sun@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- lib/artist.rb
+- lib/base_entity.rb
+- lib/last_fm_client.rb
+- lib/track.rb
+- lib/util.rb
+- lib/yahoo_music_client.rb
+files: 
+- Manifest
+- README
+- Rakefile
+- lib/artist.rb
+- lib/base_entity.rb
+- lib/last_fm_client.rb
+- lib/track.rb
+- lib/util.rb
+- lib/yahoo_music_client.rb
+- test/files/last_fm/get_similar_artists.xml
+- test/files/last_fm/get_similar_tracks.xml
+- test/files/yahoo_music/artist_search.xml
+- test/files/yahoo_music/artist_similar.xml
+- test/last_fm_client_test.rb
+- test/test_helper.rb
+- test/yahoo_music_client_test.rb
+- sundawg_music_rec.gemspec
+has_rdoc: true
+homepage: http://github.com/SunDawg/music_rec
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Sundawg_music_rec
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: sundawg_music_rec
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Generic API Client for Music Recommendations.
+test_files: 
+- test/last_fm_client_test.rb
+- test/test_helper.rb
+- test/yahoo_music_client_test.rb