spotify 12.5.3 → 12.6.0

data/examples/example-loading_object.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require_relative "support"
+
+session = Support.initialize_spotify!
+
+track_uri = Support.prompt("Please enter a track URI", "spotify:track:1612JQ4JxS8bm5ky53N3bH")
+link = Spotify.link_create_from_string(track_uri)
+
+if link.nil?
+  $logger.error "Invalid URI. Aborting."
+  abort
+elsif (link_type = Spotify.link_type(link)) != :track
+  $logger.error "Was #{link_type} URI. Needs track. Aborting."
+  abort
+else
+  track = Spotify.link_as_track(link)
+end
+
+$logger.info "Attempting to load track. Waiting forever until successful."
+Support.poll(session) { Spotify.track_is_loaded(track) }
+$logger.info "Track loaded."
+
+puts Spotify.track_name(track)

data/examples/example-random_related_artists.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require_relative "support"
+
+session = Support.initialize_spotify!
+
+artist_uri = Support.prompt("Please enter an artist URI to start with", "spotify:artist:7sVQKNtdP2NylxMgbNOJMM")
+link = Spotify.link_create_from_string(artist_uri)
+
+if link.null?
+  $logger.error "Invalid URI. Aborting."
+  abort
+elsif (link_type = Spotify.link_type(link)) != :artist
+  $logger.error "Was #{link_type} URI. Needs artist. Aborting."
+  abort
+end
+
+target = Spotify.link_as_artist(link)
+
+# Spotify.enum & :no_tracks & :no_albums
+no_tracks = Spotify::Util.enum_value!(:no_tracks, "album type")
+no_albums = Spotify::Util.enum_value!(:no_albums, "album type")
+$dummy_callback = proc { }
+
+artists = Set.new
+count = 0
+
+while target
+  $logger.info "Stats: #{artists.length} artists, #{count} browses."
+
+  browser = Spotify.artistbrowse_create(session, target, no_tracks | no_albums, $dummy_callback, nil)
+
+  Support.poll(session) do
+    begin
+      Spotify.try(:artistbrowse_error, browser)
+    rescue Spotify::IsLoadingError
+      # Ignore it
+    end
+
+    Spotify.artistbrowse_is_loaded(browser)
+  end
+
+  similar_artists = Spotify.artistbrowse_num_similar_artists(browser).times.map do |index|
+    Spotify.artistbrowse_similar_artist(browser, index)
+  end
+
+  similar_artists_names = similar_artists.map { |artist| Spotify.artist_name(artist) }
+
+  target = similar_artists.sample
+  artists << Spotify.artist_name(target)
+  count += 1
+end

data/examples/support.rb

@@ -0,0 +1,106 @@
+require "bundler/setup"
+require "spotify"
+require "logger"
+require "pry"
+require "io/console"
+
+# Kill main thread if any other thread dies.
+Thread.abort_on_exception = true
+
+# We use a logger to print some information on when things are happening.
+$stderr.sync = true
+$logger = Logger.new($stderr)
+$logger.level = Logger::INFO
+$logger.formatter = proc do |severity, datetime, progname, msg|
+  progname = if progname
+    " (#{progname}) "
+  else
+    " "
+  end
+  "\n[#{severity} @ #{datetime.strftime("%H:%M:%S")}]#{progname}#{msg}"
+end
+
+#
+# Some utility.
+#
+
+module Support
+  module_function
+
+  DEFAULT_CONFIG = {
+    api_version: Spotify::API_VERSION.to_i,
+    application_key: File.binread("./spotify_appkey.key"),
+    cache_location: ".spotify/",
+    settings_location: ".spotify/",
+    user_agent: "spotify for ruby",
+    callbacks: Spotify::SessionCallbacks.new
+  }
+
+  def logger
+    $logger
+  end
+
+  class << self
+    attr_accessor :silenced
+  end
+
+  # libspotify supports callbacks, but they are not useful for waiting on
+  # operations (how they fire can be strange at times, and sometimes they
+  # might not fire at all). As a result, polling is the way to go.
+  def poll(session, idle_time = 0.05)
+    until yield
+      print "." unless silenced
+      process_events(session)
+      sleep(idle_time)
+    end
+  end
+
+  # Process libspotify events once.
+  def process_events(session)
+    Spotify.session_process_events(session)
+  end
+
+  # Ask the user for input with a prompt explaining what kind of input.
+  def prompt(message, default = nil)
+    if default
+      print "\n#{message} [#{default}]: "
+      input = gets.chomp
+
+      if input.empty?
+        default
+      else
+        input
+      end
+    else
+      print "\n#{message}: "
+      gets.chomp
+    end
+  end
+
+  def initialize_spotify!(config = DEFAULT_CONFIG)
+    error, session = Spotify.session_create(config)
+    raise error if error.is_a?(Spotify::APIError)
+
+    if username = Spotify.session_remembered_user(session)
+      logger.info "Using remembered login for: #{username}."
+      Spotify.try(:session_relogin, session)
+    else
+      username = prompt("Spotify username, or Facebook e-mail")
+      password = $stdin.noecho { prompt("Spotify password, or Facebook password") }
+
+      logger.info "Attempting login with #{username}."
+      Spotify.try(:session_login, session, username, password, true, nil)
+    end
+
+    logger.info "Log in requested. Waiting forever until logged in."
+    Support.poll(session) { Spotify.session_connectionstate(session) == :logged_in }
+
+    at_exit do
+      logger.info "Logging out."
+      Spotify.session_logout(session)
+      Support.poll(session) { Spotify.session_connectionstate(session) != :logged_in }
+    end
+
+    session
+  end
+end

data/lib/spotify.rb

@@ -1,8 +1,15 @@
 # encoding: utf-8
 require 'ffi'
 require 'spotify/monkey_patches/ffi_pointer'
+require 'spotify/monkey_patches/ffi_buffer'
+require 'spotify/monkey_patches/ffi_enums'
+
 require 'libspotify'
-require 'monitor'
+require 'performer'
+
+require 'spotify/version'
+require 'spotify/util'
+require 'spotify/api'
 
 # Spotify module allows you to place calls against the Spotify::API.
 #
@@ -10,61 +17,38 @@ require 'monitor'
 # @see Spotify::API Spotify::API on available libspotify methods
 # @see http://developer.spotify.com/en/libspotify/docs/ official libspotify documentation
 module Spotify
-  # API is the class which has all libspotify functions attached.
-  #
-  # All functions are attached as both instance methods and class methods, mainly
-  # because that’s how FFI works it’s magic with attach_function. However, as this
-  # is a class it allows to be instantiated.
-  #
-  # @note The API is private because this class is an implementation detail.
-  #
-  # @note You should never call any Spotify::API.method() directly, but instead
-  #       you should call them via Spotify.method(). libspotify is not thread-safe,
-  #       but it is documented to be okay to call the API from multiple threads *if*
-  #       you only call one function at a time, which is ensured by the lock in the
-  #       Spotify module.
-  #
-  # @api private
-  class API
-    extend FFI::Library
-
-    begin
-      ffi_lib [LIBSPOTIFY_BIN, 'spotify', 'libspotify', '/Library/Frameworks/libspotify.framework/libspotify']
-      ffi_convention :stdcall if FFI::Platform.windows?
-    rescue LoadError
-      puts <<-ERROR.gsub(/^ */, '')
-        Failed to load the `libspotify` library. It is possible that the libspotify gem
-        does not exist for your platform, in which case you’ll need to install it manually.
+  # @return [String] libspotify build ID.
+  API_BUILD = Spotify::API.build_id
 
-        For manual installation instructions, please see:
-          https://github.com/Burgestrand/Hallon/wiki/How-to-install-libspotify
-      ERROR
-      raise
-    end
+  unless API_BUILD.include?(Spotify::API_VERSION)
+    warn "[WARNING:#{__FILE__}] libspotify v#{build_id} might be incompatible with ruby spotify v#{VERSION}(#{API_VERSION})"
   end
 
+  @performer = Performer.new
   @__api__ = Spotify::API
-  @__api__.extend(MonitorMixin)
 
   class << self
+    # @see https://rubygems.org/gems/performer
+    # @return [Performer]
+    attr_reader :performer
+
     # Like send, but raises an error if the method returns a non-OK error.
     #
     # @example calling a method that returns an error
     #   Spotify.relogin(session) # => :invalid_indata
-    #   Spotify.try(:relogin, session) # => raises Spotify::Error
+    #   Spotify.try(:relogin, session) # => raises APIError
     #
     # @note Works for non-error returning methods as well, it just does
     #       not do anything interesting.
     #
     # @param [#to_s] name
     # @param args
-    # @raise [Spotify::Error] if an error other than :ok is returned
+    # @raise [APIError] if an error other than :ok is returned
     def try(name, *args, &block)
       public_send(name, *args, &block).tap do |error|
-        error, symbol = Spotify::Error.disambiguate(error)
-        next if symbol.nil?
-        next if symbol == :ok
-        raise Error.new(symbol)
+        if error.is_a?(APIError)
+          raise error unless error.is_a?(IsLoadingError)
+        end
       end
     end
 
@@ -80,9 +64,7 @@ module Spotify
     # @param [Boolean] include_private
     # @return [Boolean] true if the API supports the given method.
     def respond_to_missing?(name, include_private = false)
-      @__api__.synchronize do
-        @__api__.respond_to?(name, include_private)
-      end
+      @__api__.respond_to?(name, include_private)
     end
 
     # Calls the any method on the underlying {Spotify::API}.
@@ -90,25 +72,24 @@ module Spotify
     # @example calling the API
     #    Spotify.link_create_from_string("spotify:user:burgestrand") # => #<Spotify::Link address=0x0deadbeef>
     #
-    # @note Spotify protects all calls to {Spotify::API} with a lock, so it is
-    #       considered safe to call the API from different threads. The lock
-    #       is re-entrant.
+    # @note Spotify protects all calls to {Spotify::API} by calling all
+    #       API methods in the {.performer} thread.
     #
     # @param [Symbol, String] name
     # @param [Object, …] args
     def method_missing(name, *args, &block)
-      @__api__.synchronize do
-        @__api__.send(name, *args, &block)
+      if respond_to?(name)
+        performer.sync { @__api__.public_send(name, *args, &block) }
+      else
+        super
       end
     end
+
+    # Print debug messages, if $DEBUG is true.
+    #
+    # @param [String] message
+    def log(message)
+      $stdout.puts "[#{caller[0]}] #{message}" if $DEBUG
+    end
   end
 end
-
-require 'spotify/version'
-require 'spotify/util'
-require 'spotify/types'
-require 'spotify/error'
-require 'spotify/objects'
-require 'spotify/defines'
-require 'spotify/structs'
-require 'spotify/api'

data/lib/spotify/api.rb

@@ -1,49 +1,77 @@
 module Spotify
+  # API is the class which has all libspotify functions attached.
+  #
+  # All functions are attached as both instance methods and class methods, mainly
+  # because that’s how FFI works it’s magic with attach_function. However, as this
+  # is a class it allows to be instantiated.
+  #
+  # @note The API is private because this class is an implementation detail.
+  #
+  # @note You should never call any Spotify::API.method() directly, but instead
+  #       you should call them via Spotify.method(). libspotify is not thread-safe,
+  #       but it is documented to be okay to call the API from multiple threads *if*
+  #       you only call one function at a time, which is ensured by the lock in the
+  #       Spotify module.
+  #
+  # @api private
   class API
-    # @!macro [attach] attach_function
-    #   @!method $1(…)
-    #     @!scope class
-    #     @!scope instance
-    #     @example method signature (shows arguments)
-    #       $*
-    #     @return [${-1}]
-    #
+    extend FFI::Library
+
+    begin
+      ffi_lib [LIBSPOTIFY_BIN, 'spotify', 'libspotify', '/Library/Frameworks/libspotify.framework/libspotify']
+      ffi_convention :stdcall if FFI::Platform.windows?
+    rescue LoadError
+      $stderr.puts <<-ERROR.gsub(/^ */, '')
+        Failed to load the `libspotify` library. It is possible that the libspotify gem
+        does not exist for your platform, in which case you'll need to install it manually.
+
+        For manual installation instructions, please see:
+          https://github.com/Burgestrand/Hallon/wiki/How-to-install-libspotify
+      ERROR
+      raise
+    end
+
     # Overloaded to ensure all methods are defined as blocking,
     # and they return a managed pointer with the correct refcount.
     #
     # @param [#to_s] name function name sans `sp_` prefix.
     # @param [Array] args
     # @param [Object] returns
-    def self.attach_function(c_name = nil, name, args, returns)
+    def self.attach_function(c_name = nil, name, args, returns, &block)
       if returns.respond_to?(:retaining_class) && name !~ /create/
         returns = returns.retaining_class
       end
 
-      options  = { :blocking => true }
-      c_name ||= "sp_#{name}"
+      options  = { blocking: true }
+      name = name.to_sym
+      c_name ||= :"sp_#{name}"
       super(name, c_name, args, returns, options)
-    end
 
-    # Now, make sure we have the right libspotify version.
+      if block_given?
+        alias_method c_name, name
+        define_method name, &block
 
-    # @!group Miscellaneous
+        singleton_class.instance_eval do
+          alias_method c_name, name
+          define_method name, &block
+        end
 
-    # @see Spotify::API_BUILD
-    attach_function :build_id, [], UTF8String
-
-    # @!endgroup
-  end
-
-  # @return [String] libspotify build ID.
-  API_BUILD = Spotify.build_id
+        name
+      end
+    end
 
-  # No support yet for "similar" versions, so it’s a hard requirement
-  # on the libspotify version. It *must* be the same, even patch version.
-  unless API_BUILD.include?(Spotify::API_VERSION)
-    raise LoadError, "libspotify v#{build_id} is incompatible with ruby spotify v#{VERSION}(#{API_VERSION})"
+    require "spotify/api_helpers"
+    extend APIHelpers
+    include APIHelpers
   end
 end
 
+require 'spotify/error'
+require 'spotify/data_converters'
+require 'spotify/types'
+require 'spotify/structs'
+
+require 'spotify/api/miscellaneous'
 require 'spotify/api/album'
 require 'spotify/api/album_browse'
 require 'spotify/api/artist'

data/lib/spotify/api/album.rb

@@ -1,14 +1,57 @@
 module Spotify
   class API
     # @!group Album
+
+    # @param [Album] album
+    # @return [Boolean] true if the album is populated with data
+    # @method album_is_loaded(album)
     attach_function :album_is_loaded, [ Album ], :bool
+
+    # @see #album_is_loaded
+    # @note the album must be loaded, or this function always return false.
+    # @param [Album] album
+    # @return [Boolean] true if the album is available for playback
+    # @method album_is_available(album)
     attach_function :album_is_available, [ Album ], :bool
+
+    # @see #album_is_loaded
+    # @note the album must be loaded, or this function always return nil.
+    # @param [Album] album
+    # @return [Artist, nil] authoring artist of the album
+    # @method album_artist(album)
     attach_function :album_artist, [ Album ], Artist
+
+    # @see #image_create
+    # @see #album_is_loaded
+    # @note the album must be loaded, or this function always return nil.
+    # @param [Album] album
+    # @param [Symbol] image_size one of :normal, :small, :large
+    # @return [String, nil] image ID to pass to {#image_create}, or nil if the album has no image
+    # @method album_cover(album, image_size)
     attach_function :album_cover, [ Album, :image_size ], ImageID
+
+    # @see #album_is_loaded
+    # @note the album must be loaded, or this function always return an empty string.
+    # @param [Album] album
+    # @return [String] name of the album
+    # @method album_name(album)
     attach_function :album_name, [ Album ], UTF8String
+
+    # @see #album_is_loaded
+    # @note the album must be loaded, or this function always return 0.
+    # @param [Album] album
+    # @return [String] release year of the album
+    # @method album_year(album)
     attach_function :album_year, [ Album ], :int
+
+    # @see #album_is_loaded
+    # @note the album must be loaded, or this function always return :unknown.
+    # @param [Album] album
+    # @return [Symbol] album type, one of :album, :single, :compilation, :unknown
+    # @method album_type(album)
     attach_function :album_type, [ Album ], :albumtype
-    attach_function :album_add_ref, [ Album ], :error
-    attach_function :album_release, [ Album ], :error
+
+    attach_function :album_add_ref, [ Album ], APIError
+    attach_function :album_release, [ Album ], APIError
   end
 end