hallon 0.4.0 → 0.8.0

data/lib/hallon/player.rb

@@ -0,0 +1,130 @@
+module Hallon
+  # A wrapper around Session for playing, stopping and otherwise
+  # controlling the playback features of libspotify.
+  #
+  # @note This is very much a work in progress. Given Session still
+  #       takes care of all callbacks, and the callbacks themselves
+  #       must still be handled by means of Ruby FFI.
+  # @see Session
+  class Player
+    include Observable
+
+    # @return [Array<Symbol>] a list of available playback bitrates.
+    def self.bitrates
+      Spotify.enum_type(:bitrate).symbols.sort_by do |sym|
+        # sort by bitrate quality
+        sym.to_s.to_i
+      end
+    end
+
+    # Constructs a Player, given a Session.
+    #
+    # @example
+    #   Hallon::Player.new(session) do
+    #     on(:music_delivery) do |*frames|
+    #     end
+    #
+    #     on(:start_playback) do
+    #     end
+    #
+    #     on(:stop_playback) do
+    #     end
+    #
+    #     on(:play_token_lost) do
+    #     end
+    #
+    #     on(:end_of_track) do
+    #     end
+    #
+    #     on(:streaming_error) do |error|
+    #     end
+    #
+    #     on(:buffer_size?) do
+    #       # return the pair of [samples, dropouts] of your audiobuffer
+    #     end
+    #   end
+    #
+    # @param [Session] session
+    # @yield instance_evals itself, allowing you to define callbacks using `on`
+    def initialize(session, &block)
+      instance_eval(&block) if block_given?
+
+      @session = session
+      @pointer = @session.pointer
+
+      %w[start_playback stop_playback play_token_lost end_of_track streaming_error].each do |cb|
+        @session.on(cb) { |*args| trigger(cb, *args) }
+      end
+
+      @session.on(:audio_buffer_stats) do |stats_ptr|
+        stats = Spotify::AudioBufferStats.new(stats_ptr)
+        samples, dropouts = trigger(:buffer_size?)
+        stats[:samples]  = samples || 0
+        stats[:dropouts] = dropouts || 0
+      end
+
+      @session.on(:music_delivery) do |format, frames, num_frames|
+        trigger(:music_delivery, format, frames, num_frames)
+        num_frames # assume we consume all data
+      end
+    end
+
+    # Set preferred playback bitrate.
+    #
+    # @param [Symbol] bitrate one of :96k, :160k, :320k
+    # @return [Symbol]
+    def bitrate=(bitrate)
+      Spotify.session_preferred_bitrate(@pointer, bitrate)
+    end
+
+    # Loads a Track for playing.
+    #
+    # @param [Track] track
+    # @return [Player]
+    # @raise [Error] if the track could not be loaded
+    def load(track)
+      error = Spotify.session_player_load(@pointer, track.pointer)
+      tap { Error.maybe_raise(error) }
+    end
+
+    # Prepares a Track for playing, without loading it.
+    #
+    # @note You can only prefetch if caching is on.
+    # @param [Track] track
+    # @return [Player]
+    def prefetch(track)
+      error = Spotify.session_player_prefetch(@pointer, track.pointer)
+      tap { Error.maybe_raise(error) }
+    end
+
+    # Starts playing a Track by feeding data to your application.
+    #
+    # @return [Player]
+    def play(track = nil)
+      load(track) unless track.nil?
+      tap { Spotify.session_player_play(@pointer, true) }
+    end
+
+    # Pause playback of a Track.
+    #
+    # @return [Player]
+    def pause
+      tap { Spotify.session_player_play(@pointer, false) }
+    end
+
+    # Stop playing current track and unload it.
+    #
+    # @return [Player]
+    def stop
+      tap { Spotify.session_player_unload(@pointer) }
+    end
+
+    # Seek to the desired position of the currently loaded Track.
+    #
+    # @param [Numeric] seconds offset position in seconds
+    # @return [Player]
+    def seek(seconds)
+      tap { Spotify.session_player_seek(@pointer, seconds * 1000) }
+    end
+  end
+end

data/lib/hallon/search.rb

@@ -0,0 +1,128 @@
+# coding: utf-8
+module Hallon
+  # Search allows you to search Spotify for tracks, albums
+  # and artists, just like in the client.
+  #
+  # @see http://developer.spotify.com/en/libspotify/docs/group__search.html
+  class Search < Base
+    include Observable
+
+    # @return [Array<Symbol>] a list of radio genres available for search
+    def self.genres
+      Spotify.enum_type(:radio_genre).symbols
+    end
+
+    # @param [Range<Integer>] range (from_year..to_year)
+    # @param [Symbol, …] genres
+    # @return [Search] radio search in given period and genres
+    def self.radio(range, *genres)
+      from_year, to_year = range.begin, range.end
+      genres = genres.reduce(0) do |mask, genre|
+        mask | (Spotify.enum_value(genre) || 0)
+      end
+
+      search = allocate
+      search.instance_eval do
+        @callback = proc { search.trigger(:load) }
+        pointer   = Spotify.radio_search_create(session.pointer, from_year, to_year, genres, @callback, nil)
+        @pointer  = Spotify::Pointer.new(pointer, :search, false)
+
+        self
+      end
+    end
+
+    # Construct a new search with given query.
+    #
+    # @param [String] query search query
+    # @param [Hash] options additional search options
+    # @option options [#to_i] :tracks (25) max number of tracks you want in result
+    # @option options [#to_i] :albums (25) max number of albums you want in result
+    # @option options [#to_i] :artists (25) max number of artists you want in result
+    # @option options [#to_i] :tracks_offset (0) offset of tracks in search result
+    # @option options [#to_i] :albums_offset (0) offset of albums in search result
+    # @option options [#to_i] :artists_offset (0) offset of artists in search result
+    # @see http://developer.spotify.com/en/libspotify/docs/group__search.html#gacf0b5e902e27d46ef8b1f40e332766df
+    def initialize(query, options = {})
+      o = {
+        :tracks  => 25,
+        :albums  => 25,
+        :artists => 25,
+        :tracks_offset  => 0,
+        :albums_offset  => 0,
+        :artists_offset => 0
+      }.merge(options)
+
+      @callback = proc { trigger(:load) }
+      pointer   = Spotify.search_create(session.pointer, query, o[:tracks_offset].to_i, o[:tracks].to_i, o[:albums_offset].to_i, o[:albums].to_i, o[:artists_offset].to_i, o[:artists].to_i, @callback, nil)
+      @pointer  = Spotify::Pointer.new(pointer, :search, false)
+    end
+
+    # @return [Boolean] true if the search has been fully loaded
+    def loaded?
+      Spotify.search_is_loaded(@pointer)
+    end
+
+    # @return [Symbol] error status
+    def error
+      Spotify.search_error(@pointer)
+    end
+
+    # @return [String] search query this search was created with
+    def query
+      Spotify.search_query(@pointer)
+    end
+
+    # @return [String] “did you mean?” suggestion for current search
+    def did_you_mean
+      Spotify.search_did_you_mean(@pointer)
+    end
+
+    # @return [Enumerator<Track>] enumerate over all tracks in the search result
+    def tracks
+      size = Spotify.search_num_tracks(@pointer)
+      Enumerator.new(size) do |i|
+        track = Spotify.search_track(@pointer, i)
+        Track.new(track) unless track.null?
+      end
+    end
+
+    # @return [Integer] total tracks available for this search query
+    def total_tracks
+      Spotify.search_total_tracks(@pointer)
+    end
+
+    # @return [Enumerator<Album>] enumerate over all albums in the search result
+    def albums
+      size  = Spotify.search_num_albums(@pointer)
+      Enumerator.new(size) do |i|
+        album = Spotify.search_album(@pointer, i)
+        Album.new(album) unless album.null?
+      end
+    end
+
+    # @return [Integer] total tracks available for this search query
+    def total_albums
+      Spotify.search_total_albums(@pointer)
+    end
+
+    # @return [Enumerator<Artist>] enumerate over all artists in the search result
+    def artists
+      size = Spotify.search_num_artists(@pointer)
+      Enumerator.new(size) do |i|
+        artist = Spotify.search_artist(@pointer, i)
+        Artist.new(artist) unless artist.null?
+      end
+    end
+
+    # @return [Integer] total tracks available for this search query
+    def total_artists
+      Spotify.search_total_artists(@pointer)
+    end
+
+    # @return [Link] link for this search query
+    def to_link
+      pointer = Spotify.link_create_from_search(@pointer)
+      Link.new(pointer) unless pointer.null?
+    end
+  end
+end

data/lib/hallon/session.rb

@@ -15,6 +15,15 @@ module Hallon
     # @return [Hash]
     attr_reader :options
 
+    # The current session cache size (in megabytes).
+    #
+    # @note This is not provided by libspotify, and the value is only valid
+    #       as long as the cache size is only adjusted through {#cache_size=}
+    #       and not the Spotify FFI interface.
+    #
+    # @return [Integer]
+    attr_reader :cache_size
+
     # libspotify only allows one session per process.
     include Singleton
     class << self
@@ -22,16 +31,38 @@ module Hallon
     end
 
     # Session allows you to define your own callbacks.
-    include Hallon::Observable
+    include Observable
 
-    # Allows you to create a Spotify session. Subsequent calls to this method
-    # will return the previous instance, ignoring any passed arguments.
+    # Initializes the Spotify session. If you need to access the
+    # instance at a later time, you can use {instance}.
     #
-    # @param (see Session#initialize)
+    # @see Session.instance
     # @see Session#initialize
+    #
+    # @param (see Session#initialize)
+    # @return [Session]
+    def Session.initialize(*args, &block)
+      raise "Session has already been initialized" if @__instance__
+      @__instance__ = new(*args, &block)
+    end
+
+    # Returns the previously initialized Session.
+    #
+    # @see Session.instance
+    #
     # @return [Session]
-    def Session.instance(*args, &block)
-      @__instance__ ||= new(*args, &block)
+    def Session.instance
+      @__instance__ or raise "Session has not been initialized"
+    end
+
+    # @return [Array<Symbol>] list of available connection types.
+    def self.connection_types
+      Spotify.enum_type(:connection_type).symbols
+    end
+
+    # @return [Array<Symbol>] list of available connection rules
+    def self.connection_rules
+      Spotify.enum_type(:connection_rules).symbols
     end
 
     # Create a new Spotify session.
@@ -49,7 +80,6 @@ module Hallon
     # @raise [Hallon::Error] if `sp_session_create` fails
     # @see http://developer.spotify.com/en/libspotify/docs/structsp__session__config.html
     def initialize(appkey, options = {}, &block)
-      @appkey  = appkey.to_s
       @options = {
         :user_agent => "Hallon",
         :settings_path => "tmp",
@@ -66,15 +96,18 @@ module Hallon
       # Set configuration, as well as callbacks
       config  = Spotify::SessionConfig.new
       config[:api_version]   = Hallon::API_VERSION
-      config.application_key = @appkey
+      config.application_key = appkey
       @options.each { |(key, value)| config.send(:"#{key}=", value) }
       config[:callbacks]     = Spotify::SessionCallbacks.new(self, @sp_callbacks = {})
 
+      # Default cache size is 0 (automatic)
+      @cache_size = 0
+
       instance_eval(&block) if block_given?
 
       # You pass a pointer to the session pointer to libspotify >:)
       FFI::MemoryPointer.new(:pointer) do |p|
-        Hallon::Error::maybe_raise Spotify::session_create(config, p)
+        Error::maybe_raise Spotify.session_create(config, p)
         @pointer = p.read_pointer
       end
     end
@@ -84,20 +117,22 @@ module Hallon
     # @return [Fixnum] minimum time until it should be called again
     def process_events
       FFI::MemoryPointer.new(:int) do |p|
-        Spotify::session_process_events(@pointer, p)
+        Spotify.session_process_events(@pointer, p)
         return p.read_int
       end
     end
 
     # Wait for the given callbacks to fire until the block returns true
     #
+    # @note Given block will be called once instantly without parameters.
+    # @note If no events happen for 0.25 seconds, the given block will be called
+    #       with `:timeout` as parameter.
     # @param [Symbol, ...] *events list of events to wait for
     # @yield [Symbol, *args] name of the callback that fired, and its’ arguments
     # @return [Hash<Event, Arguments>]
-    def process_events_on(*events, &block)
-      channel = SizedQueue.new(1)
-
-      protecting_handlers do
+    def process_events_on(*events)
+      yield or protecting_handlers do
+        channel = SizedQueue.new(1)
         on(*events) { |*args| channel << args }
         on(:notify_main_thread) { channel << :notify }
 
@@ -107,10 +142,10 @@ module Hallon
             params = Timeout::timeout(0.25) { channel.pop }
             redo if params == :notify
           rescue Timeout::Error
-            params = nil
+            params = :timeout
           end
 
-          if result = block.call(*params)
+          if result = yield(*params)
             return result
           end
         end
@@ -122,39 +157,187 @@ module Hallon
     #
     # @param [String] username
     # @param [String] password
+    # @param [Boolean] remember_me have libspotify remember credentials for {#relogin}
+    # @return [self]
+    def login(username, password, remember_me = false)
+      tap { Spotify.session_login(@pointer, username, password, @remembered = remember_me) }
+    end
+
+    # Login the remembered user (see {#login}).
+    #
+    # @raise [Hallon::Error] if no credentials are stored in libspotify
+    def relogin
+      Error.maybe_raise Spotify.session_relogin(@pointer)
+    end
+
+    # Username of the user stored in libspotify-remembered credentials.
+    #
+    # @return [String]
+    def remembered_user
+      bufflen = Spotify.session_remembered_user(@pointer, nil, 0)
+      FFI::Buffer.alloc_out(bufflen + 1) do |b|
+        Spotify.session_remembered_user(@pointer, b, b.size)
+        return b.get_string(0)
+      end if bufflen > 0
+    end
+
+    # Remove stored login credentials in libspotify.
+    #
+    # @note If no credentials are stored nothing’ll happen.
     # @return [self]
-    def login(username, password)
-      Spotify::session_login(@pointer, username, password)
-      self
+    def forget_me!
+      tap { Spotify.session_forget_me(@pointer) }
     end
 
     # Logs out of Spotify. Does nothing if not logged in.
     #
     # @return [self]
     def logout
-      Spotify::session_logout(@pointer) if logged_in?
-      self
+      tap { Spotify.session_logout(@pointer) if logged_in? }
     end
 
     # Retrieve the currently logged in {User}.
     #
     # @return [User]
     def user
-      User.new Spotify::session_user(@pointer)
+      User.new Spotify.session_user(@pointer)
     end
 
     # Retrieve the relation type between logged in {User} and `user`.
     #
     # @return [Symbol] :unknown, :none, :unidirectional or :bidirectional
     def relation_type?(user)
-      Spotify::user_relation_type(@pointer, user.pointer)
+      Spotify.user_relation_type(@pointer, user.pointer)
     end
 
     # Retrieve current connection status.
     #
     # @return [Symbol]
     def status
-      Spotify::session_connectionstate(@pointer)
+      Spotify.session_connectionstate(@pointer)
+    end
+
+    # Set session cache size in megabytes.
+    #
+    # @param [Integer]
+    # @return [Integer]
+    def cache_size=(size)
+      Spotify.session_set_cache_size(@pointer, @cache_size = size)
+    end
+
+    # @return [String] Currently logged in users’ country.
+    def country
+      coded = Spotify.session_user_country(@pointer)
+      country = ((coded >> 8) & 0xFF).chr
+      country << (coded & 0xFF).chr
+    end
+
+    # Star the given tracks.
+    #
+    # @example
+    #   track = Hallon::Track.new("spotify:track:2LFQV2u6wXZmmySCWBkYGu")
+    #   session.star(track)
+    #
+    # @param [Track…]
+    # @return [Session]
+    def star(*tracks)
+      tap { tracks_starred(tracks, true) }
+    end
+
+    # Unstar the given tracks.
+    #
+    # @example
+    #   track = Hallon::Track.new("spotify:track:2LFQV2u6wXZmmySCWBkYGu")
+    #   session.unstar(track)
+    #
+    # @param [Track…]
+    # @return [Session]
+    def unstar(*tracks)
+      tap { tracks_starred(tracks, false) }
+    end
+
+    # @note This will be 0 if not logged in.
+    # @note As of current writing, I am unsure if there’s a good way to find out
+    #       when this enumerator will be populated. No callbacks or other status
+    #       field can tell you when the current sessions’ friends are available.
+    # @return [Enumerator<User>] friends of currently logged in user
+    def friends
+      size = if logged_in?
+        # segfaults unless logged in
+        Spotify.session_num_friends(@pointer)
+      else
+        0
+      end
+
+      Enumerator.new(size) do |i|
+        friend = Spotify.session_friend(@pointer, i)
+        User.new(friend)
+      end
+    end
+
+    # Set the connection rules for this session.
+    #
+    # @param [Symbol, …] connection_rules
+    # @see Session.connection_rules
+    def connection_rules=(connection_rules)
+      rules = Array(connection_rules).reduce(0) do |mask, rule|
+        mask | (Spotify.enum_value(rule) || 0)
+      end
+
+      Spotify.session_set_connection_rules(@pointer, rules)
+    end
+
+    # Set the connection type for this session.
+    #
+    # @param [Symbol] connection_type
+    # @see Session.connection_types
+    def connection_type=(connection_type)
+      Spotify.session_set_connection_type(@pointer, connection_type)
+    end
+
+    # Remaining time left you can stay offline before needing to relogin.
+    #
+    # @return [Integer] offline time left in seconds
+    def offline_time_left
+      Spotify.offline_time_left(@pointer)
+    end
+
+    # Offline synchronization status.
+    #
+    # @return [Hash, nil] sync status, or nil if not applicable
+    # @see http://developer.spotify.com/en/libspotify/docs/structsp__offline__sync__status.html
+    def offline_sync_status
+      struct = Spotify::OfflineSyncStatus.new
+      if Spotify.offline_sync_get_status(@pointer, struct.pointer)
+        Hash[struct.members.zip(struct.values)]
+      end
+    end
+
+    # Number of playlists marked for offline sync.
+    #
+    # @return [Integer]
+    def offline_playlists_count
+      Spotify.offline_num_playlists(@pointer)
+    end
+
+    # Number of offline tracks left to sync for offline mode.
+    #
+    # @return [Integer]
+    def offline_tracks_to_sync
+      Spotify.offline_tracks_to_sync(@pointer)
+    end
+
+    # Set preferred offline bitrate.
+    #
+    # @example
+    #   session.offline_bitrate = :'96k', true
+    #
+    # @param [Symbol] bitrate
+    # @param [Boolean] resync (default: false)
+    # @see Player.bitrates
+    def offline_bitrate=(bitrate)
+      bitrate, resync = Array(bitrate)
+      Spotify.session_preferred_offline_bitrate(@pointer, bitrate, !! resync)
     end
 
     # True if currently logged in.
@@ -175,11 +358,29 @@ module Hallon
       status == :disconnected
     end
 
+    # True if offline.
+    # @see #status
+    def offline?
+      status == :offline
+    end
+
     # String representation of the Session.
     #
     # @return [String]
     def to_s
-      "<#{self.class.name}>"
+      "<#{self.class.name}:0x#{object_id.to_s(16)} status=#{status} @options=#{options.inspect}>"
     end
+
+    private
+      # Set starred status of given tracks.
+      #
+      # @param [Array<Track>] tracks
+      # @param [Boolean] starred
+      def tracks_starred(tracks, starred)
+        FFI::MemoryPointer.new(:pointer, tracks.size) do |ptr|
+          ptr.write_array_of_pointer tracks.map(&:pointer)
+          Spotify.track_set_starred(pointer, ptr, tracks.size, starred)
+        end
+      end
   end
 end