hallon 0.16.0 → 0.17.0

data/lib/hallon/ext/spotify.rb

@@ -4,154 +4,9 @@
 #
 # @see https://github.com/Burgestrand/libspotify-ruby
 module Spotify
-  # Fetches the associated value of an enum from a given symbol.
-  #
-  # @param [Symbol] symbol
-  # @param [#to_s] type
-  # @raise ArgumentError on failure
-  def self.enum_value!(symbol, type)
-    enum_value(symbol) or raise ArgumentError, "invalid #{type}: #{symbol}"
-  end
-
-  # Wraps the function `function` so that it always returns
-  # a Spotify::Pointer with correct refcount. Functions that
-  # contain the word `create` are assumed to start out with
-  # a refcount of `+1`.
-  #
-  # @param [#to_s] function
-  # @param [#to_s] return_type
-  # @raise [NoMethodError] if `function` is not defined
-  # @see Spotify::Pointer
-  def self.wrap_function(function, return_type)
-    method(function)
-    define_singleton_method("#{function}!") do |*args|
-      pointer = public_send(function, *args)
-      Spotify::Pointer.new(pointer, return_type, function !~ /create/)
-    end
-  end
-
-  # @macro [attach] wrap_function
-  #   Same as {Spotify}.`$1`, but wraps result in a {Spotify::Pointer}.
-  #
-  #   @method $1!
-  #   @return [Spotify::Pointer<$2>]
-  #   @see #$1
-  wrap_function :session_user, :user
-  wrap_function :session_playlistcontainer, :playlistcontainer
-  wrap_function :session_inbox_create, :playlist
-  wrap_function :session_starred_create, :playlist
-  wrap_function :session_starred_for_user_create, :playlist
-  wrap_function :session_publishedcontainer_for_user_create, :playlistcontainer
-
-  wrap_function :track_artist, :artist
-  wrap_function :track_album, :album
-  wrap_function :localtrack_create, :track
-  wrap_function :track_get_playable, :track
-
-  wrap_function :album_artist, :artist
-
-  wrap_function :albumbrowse_create, :albumbrowse
-  wrap_function :albumbrowse_album, :album
-  wrap_function :albumbrowse_artist, :artist
-  wrap_function :albumbrowse_track, :track
-
-  wrap_function :artistbrowse_create, :artistbrowse
-  wrap_function :artistbrowse_artist, :artist
-  wrap_function :artistbrowse_track, :track
-  wrap_function :artistbrowse_album, :album
-  wrap_function :artistbrowse_similar_artist, :artist
-  wrap_function :artistbrowse_tophit_track, :track
-
-  wrap_function :image_create, :image
-  wrap_function :image_create_from_link, :image
-
-  wrap_function :link_as_track, :track
-  wrap_function :link_as_track_and_offset, :track
-  wrap_function :link_as_album, :album
-  wrap_function :link_as_artist, :artist
-  wrap_function :link_as_user, :user
-
-  wrap_function :link_create_from_string, :link
-  wrap_function :link_create_from_track, :link
-  wrap_function :link_create_from_album, :link
-  wrap_function :link_create_from_artist, :link
-  wrap_function :link_create_from_search, :link
-  wrap_function :link_create_from_playlist, :link
-  wrap_function :link_create_from_artist_portrait, :link
-  wrap_function :link_create_from_artistbrowse_portrait, :link
-  wrap_function :link_create_from_album_cover, :link
-  wrap_function :link_create_from_image, :link
-  wrap_function :link_create_from_user, :link
-
-  wrap_function :search_create, :search
-  wrap_function :search_track, :track
-  wrap_function :search_album, :album
-  wrap_function :search_artist, :artist
-
-  wrap_function :playlist_track, :track
-  wrap_function :playlist_track_creator, :user
-  wrap_function :playlist_owner, :user
-  wrap_function :playlist_create, :playlist
-
-  wrap_function :playlistcontainer_playlist, :playlist
-  wrap_function :playlistcontainer_add_new_playlist, :playlist
-  wrap_function :playlistcontainer_add_playlist, :playlist
-  wrap_function :playlistcontainer_owner, :user
-
-  wrap_function :toplistbrowse_create, :toplistbrowse
-  wrap_function :toplistbrowse_artist, :artist
-  wrap_function :toplistbrowse_album, :album
-  wrap_function :toplistbrowse_track, :track
-
-  wrap_function :inbox_post_tracks, :inbox
-
-  # The Pointer is a kind of AutoPointer specially tailored for Spotify
-  # objects, that releases the raw pointer on GC.
-  class Pointer < FFI::AutoPointer
-    attr_reader :type
-
-    # @param [FFI::Pointer] pointer
-    # @param [#to_s] type session, link, etc
-    # @param [Boolean] add_ref
-    # @return [FFI::AutoPointer]
-    def initialize(pointer, type, add_ref)
-      super pointer, self.class.releaser_for(@type = type.to_s)
-
-      unless pointer.null?
-        Spotify.send(:"#{type}_add_ref", pointer)
-      end if add_ref
-    end
-
-    # @return [String] representation of the spotify pointer
-    def to_s
-      "<#{self.class} address=0x#{address.to_s(16)} type=#{type}>"
-    end
-
-    # Create a proc that will accept a pointer of a given type and
-    # release it with the correct function if it’s not null.
-    #
-    # @param [Symbol]
-    # @return [Proc]
-    def self.releaser_for(type)
-      lambda do |pointer|
-        unless pointer.null?
-          $stdout.puts "Spotify::#{type}_release(#{pointer})" if $DEBUG
-          Spotify.send(:"#{type}_release", pointer)
-        end
-      end
-    end
-
-    # @param [Object] pointer
-    # @param [Symbol] type (optional, no type checking is done if not given)
-    # @return [Boolean] true if object is a spotify pointer and of correct type
-    def self.typechecks?(object, type)
-      !! (object.type == type.to_s) if object.is_a?(Spotify::Pointer)
-    end
-  end
-
   # Extensions to SessionConfig, allowing more sensible configuration names.
   SessionConfig.class_eval do
-    [:cache_location, :settings_location, :user_agent, :device_id, :tracefile].each do |field|
+    [:cache_location, :settings_location, :user_agent, :device_id, :proxy, :proxy_username, :proxy_password, :tracefile].each do |field|
       method = field.to_s.gsub('location', 'path')
 
       define_method(:"#{method}") { self[field].read_string }

data/lib/hallon/image.rb

@@ -15,6 +15,14 @@ module Hallon
     extend Observable::Image
     include Loadable
 
+    # A list of available image sizes.
+    #
+    # @see Album#cover
+    # @see Artist#portrait
+    def self.sizes
+      Spotify.enum_type(:image_size).symbols
+    end
+
     # Create a new instance of an Image.
     #
     # @example from a link

data/lib/hallon/linkable.rb

@@ -8,6 +8,9 @@ module Hallon
   #
   # @private
   module Linkable
+    # ClassMethods adds `#from_link` and `#to_link` DSL methods, which
+    # essentially are convenience methods for defining the way to convert
+    # a link to a pointer of a given Spotify object type.
     module ClassMethods
       # Defines `#from_link`, used in converting a link to a pointer. You
       # can either pass it a `method_name`, or a `type` and a block.
@@ -100,6 +103,9 @@ module Hallon
       end
     end
 
+    # Will extend `other` with ClassMethods on inclusion.
+    #
+    # @param [#extend] other
     def self.included(other)
       other.extend ClassMethods
     end

data/lib/hallon/loadable.rb

@@ -2,7 +2,13 @@
 require 'timeout'
 
 module Hallon
+  # Extends Hallon objects with a method that allows synchronous loading of objects.
   module Loadable
+    # Wait until the object has loaded.
+    #
+    # @example waiting for a track to load
+    #   track = Hallon::Track.new(track_uri).load
+    #
     # @param [Numeric] timeout after this time, if the object is not loaded, an error is raised.
     # @return [self]
     # @raise [Hallon::TimeoutError] after `timeout` seconds if the object does not load.

data/lib/hallon/observable.rb

@@ -115,7 +115,7 @@ module Hallon
     #
     # @note Given block will be called once instantly without parameters.
     # @note If no events happen for 0.25 seconds, the block will be called without parameters.
-    # @param [Symbol, ...] *events list of events to wait for
+    # @param [Symbol, ...] events list of events to wait for
     # @yield [Symbol, *args] name of the event that fired, and its’ arguments
     # @return whatever the block returns
     def wait_for(*events)

data/lib/hallon/observable/playlist_container.rb

@@ -72,8 +72,8 @@ module Hallon::Observable
 
       # @param [Spotify::Pointer] playlist
       # @return [Hallon::Playlist] a playlist for the given pointer.
-      def playlist_from(pointer)
-        pointer = Spotify::Pointer.new(pointer, :playlist, true)
+      def playlist_from(playlist)
+        pointer = Spotify::Pointer.new(playlist, :playlist, true)
         Hallon::Playlist.new(pointer)
       end
   end

data/lib/hallon/observable/session.rb

@@ -249,5 +249,39 @@ module Hallon::Observable
     def credentials_blob_updated_callback(pointer, credentials)
       trigger(pointer, :credentials_blob_updated, credentials)
     end
+
+    # @example listening to this event
+    #   session.on(:connectionstate_updated) do
+    #     puts "Yay! Connection state changed… hooray… wee… no?"
+    #   end
+    #
+    # @yield
+    def connectionstate_updated_callback(pointer)
+      trigger(pointer, :connectionstate_updated)
+    end
+
+    # @example listening to this event
+    #   session.on(:scrobble_error) do |error|
+    #     Hallon::Error.maybe_raise(error)
+    #   end
+    #
+    # @yield
+    def scrobble_error_callback(pointer, error)
+      trigger(pointer, :scrobble_error, error)
+    end
+
+    # @example listening to this event
+    #   session.on(:private_session_mode_changed) do |enabled|
+    #     if enabled
+    #       puts "Private session enabled!"
+    #     else
+    #       puts "Private session disabled!"
+    #     end
+    #   end
+    #
+    # @yield
+    def private_session_mode_changed_callback(pointer, enabled)
+      trigger(pointer, :private_session_mode_changed, enabled)
+    end
   end
 end

data/lib/hallon/player.rb

@@ -122,7 +122,7 @@ module Hallon
     # well as allow audio data to stream through the feeder
     # thread.
     #
-    # @param [Symbol] status one of :playing, :paused, :stopped
+    # @param [Symbol] new_status one of :playing, :paused, :stopped
     # @raise [ArgumentError] if given an invalid status
     def status=(new_status)
       @queue.synchronize do
@@ -201,10 +201,14 @@ module Hallon
 
     # Set preferred playback bitrate.
     #
+    # @note the double possible errors is a result of the same thing as for
+    #       {Session#offline_bitrate=}, see its documentation for further information.
+    #
+    # @raise [ArgumentError] if given invalid bitrate
+    # @raise [Spotify::Error] if libspotify does not accept the given bitrate
     # @param [Symbol] bitrate one of :96k, :160k, :320k
-    # @return [Symbol]
     def bitrate=(bitrate)
-      Spotify.session_preferred_bitrate(pointer, bitrate)
+      Spotify.session_preferred_bitrate!(pointer, bitrate)
     end
 
     # Loads a Track for playing.

data/lib/hallon/playlist.rb

@@ -72,7 +72,6 @@ module Hallon
       # @raise [IndexError] if the underlying track has moved
       # @raise [Error] if the operation could not be completed
       #
-      # @param [Integer] index
       # @param [Boolean] seen true if the track is now seen
       # @return [Playlist::Track] track at the given index
       def seen=(seen)
@@ -152,6 +151,11 @@ module Hallon
 
     # Waits for the playlist to begin updating and blocks until it is done.
     #
+    # @note this is done by waiting for the libspotify callback, where libspotify
+    #       tells Hallon the playlist update is done.
+    #
+    # @param [Integer] timeout time until the operation times out
+    # @raise [Hallon::TimeoutError] if the upload failed within the load timeout
     # @return [Playlist]
     def upload(timeout = Hallon.load_timeout)
       Timeout.timeout(timeout, Hallon::TimeoutError) do

data/lib/hallon/playlist_container.rb

@@ -96,7 +96,7 @@ module Hallon
         container.move(insert_at + 1, @end)
       end
 
-      # @param [PlaylistContainer] container
+      # @param [PlaylistContainer] container_pointer
       # @param [Range] indices
       def initialize(container_pointer, indices)
         @container_ptr = container_pointer
@@ -193,19 +193,19 @@ module Hallon
     # @param [String, Playlist, Link] playlist
     # @param [Boolean] force_create force creation of a new playlist
     # @return [Playlist, nil] the added playlist, or nil if the operation failed
-    def add(name, force_create = false)
-      playlist = if force_create or not Link.valid?(name) and name.is_a?(String)
-        unless error = Playlist.invalid_name?(name)
-          Spotify.playlistcontainer_add_new_playlist!(pointer, name)
+    def add(playlist, force_create = false)
+      resource = if force_create or not Link.valid?(playlist) and playlist.is_a?(String)
+        unless error = Playlist.invalid_name?(playlist)
+          Spotify.playlistcontainer_add_new_playlist!(pointer, playlist)
         else
           raise ArgumentError, error
         end
       else
-        link = Link.new(name)
+        link = Link.new(playlist)
         Spotify.playlistcontainer_add_playlist!(pointer, link.pointer)
       end
 
-      Playlist.from(playlist)
+      Playlist.from(resource)
     end
 
     # Create a new folder with the given name at the end of the container.
@@ -331,7 +331,8 @@ module Hallon
       # Wrapper for original API; adjusts indices accordingly.
       #
       # @param [Integer] from
-      # @param [Integer] from
+      # @param [Integer] infront_of
+      # @param [Boolean] dry_run
       # @return [Integer] error
       def move_playlist(from, infront_of, dry_run)
         infront_of += 1 if from < infront_of

data/lib/hallon/scrobbler.rb

@@ -0,0 +1,103 @@
+module Hallon
+  # The Hallon::Scrobbler is responsible for controlling play scrobbling.
+  #
+  # You can construct the scrobbler with different providers to control
+  # scrobbling for each one individually. The scrobbler includes a list
+  # of social providers, methods to adjust the scrobbling of libspotify,
+  # and methods to retrieve the current scrobbling state.
+  class Scrobbler
+    # @return [Array<Symbol>] list of available scrobbling providers
+    def self.providers
+      Spotify.enum_type(:social_provider).symbols
+    end
+
+    # @return [Symbol] social provider
+    attr_reader :provider
+
+    # Initialize the scrobbler with a social provider.
+    #
+    # @note it appears that in libspotify v12.1.56, the only valid provider
+    #       is :facebook — all other providers return errors
+    #
+    # @raise [ArgumentError] if the given provider is invalid
+    # @param [Symbol] provider
+    def initialize(provider)
+      provider_to_i = Spotify.enum_value!(provider, "social provider")
+      @provider = Spotify.enum_type(:social_provider)[provider_to_i]
+    end
+
+    # @note if this returns false, it usually means libspotify either has
+    #       no scrobbling credentials, or the user has disallowed spotify
+    #       from scrobbling to the given provider
+    #
+    # @note this method only works for the :facebook provider; for all other
+    #       providers it will always return true
+    #
+    # @return [Boolean] true if scrobbling is possible
+    def possible?
+      case provider
+      when :spotify, :lastfm
+        # libspotify v12.1.56 has a bug with all providers except for :facebook
+        # where the return value is always :invalid_indata; however, the devs
+        # also mentioned the function would always return true for all other
+        # providers anyway
+        true
+      else
+        FFI::Buffer.alloc_out(:bool) do |buffer|
+          Spotify.session_is_scrobbling_possible!(session.pointer, provider, buffer)
+          return ! buffer.read_uchar.zero?
+        end
+      end
+    end
+
+    # Sets the scrobbling credentials.
+    #
+    # @example setting username and password
+    #   scrobbling.credentials = 'kim', 'password'
+    #
+    # @param [Array<Username, Password>] credentials
+    def credentials=(credentials)
+      username, password = Array(credentials)
+      Spotify.session_set_social_credentials!(session.pointer, provider, username, password)
+    end
+
+    # Enables or disables the local scrobbling setting.
+    #
+    # @param [Boolean] scrobble true if you want scrobbling to be enabled
+    def enabled=(scrobble)
+      state = scrobble ? :local_enabled : :local_disabled
+      Spotify.session_set_scrobbling!(session.pointer, provider, state)
+    end
+
+    # @return [Boolean] true if scrobbling (global or local) is enabled.
+    def enabled?
+      FFI::Buffer.alloc_out(:int) do |buffer|
+        Spotify.session_is_scrobbling(session.pointer, provider, buffer)
+        state = read_state(buffer.read_uint)
+        return !! (state =~ /enabled/)
+      end
+    end
+
+    # Sets the local scrobbling state to the global state.
+    #
+    # @return [Scrobbler]
+    def reset
+      tap { Spotify.session_set_scrobbling!(session.pointer, provider, :use_global_setting) }
+    end
+
+    protected
+
+    # Convert an integer state to an actual state symbol.
+    #
+    # @param [Integer] state
+    # @return [Symbol] state as a symbol
+    def read_state(state)
+      Spotify.enum_type(:scrobbling_state)[state]
+    end
+
+    # @return [Hallon::Session]
+    def session
+      Session.instance
+    end
+  end
+end