hallon 0.15.0 → 0.16.0

data/CHANGELOG.md

@@ -4,6 +4,46 @@ Hallon’s Changelog
 [HEAD][]
 ------------------
 
+[v0.16.0][]
+------------------
+This release brings a lot of changes to the Hallon test suite, mainly to make
+it more readable and less of a mess.
+
+__Added__
+
+- ArtistBrowse#top_hits [5ef57a7]
+- Session#flush_caches [693567]
+- Track#playable_track [2d9cdfb]
+- Support for playlists in search results [05f49e4]
+- Support for suggestion search [1ae4b29]
+- Support for unseen tracks for playlists in playlist containers [4bf8496]
+- Support for login with credentials blob instead of password [61ffdf3]
+
+__Changed__
+
+- Removed the final `self` parameter of all libspotify events [d738a79]
+- Renamed Playlist::Track#create_time to added_at [1adc2d7]
+- Renamed Playlist::Track#creator to adder [1adc2d7]
+- Session#offline_sync_status now returns a hash always [c14d42ae]
+- Make AlbumBrowse#request_duration always return an integer [ee0697c2]
+- Make ArtistBrowse#request_duration always return an integer [ee0697c2]
+- Make Toplist#request_duration always return an integer [ebc64e1a]
+- Track#popularity now returns a value between 0 and 100 [cd85ae7f]
+- Move Session#wait_for onto Observable, now they all support it! [e14da3e]
+- Make Playlist#update rely solely on callbacks [e703c132]
+- Player.new no longer takes a session parameter [7508d18]
+- Session.instance now raises NoSessionError on missing session [3b47b7]
+- Observable#wait_for now calls original handler on events [be236bfd]
+
+__Fixed__
+
+- Have Playlist#subscribers always return an array [a8d26c9a]
+- Fix Image#data for images with no data [e7d8627]
+- Playlist::Track#message always return a string [72a644a]
+- Session#login! now raises when given the wrong password [f650a36]
+- Do not wrap the Session pointer in a Spotify pointer [9ae047d]
+- Link.valid? segfaulting if having no session [84c9f69c]
+
 [v0.15.0][]
 ------------------
 Updated to libspotify v11.1.60 [3c810b0], and improved the examples provided within Hallon codebase significantly.

data/README.markdown

@@ -64,7 +64,7 @@ For more information about audio support in Hallon, see the section "Audio suppo
 
 ### Contact details
 
-- __Got questions?__ Ask on the mailing list: <https://groups.google.com/d/forum/ruby-hallon>
+- __Got questions?__ Ask on the mailing list: <mailto:ruby-hallon@googlegroups.com> (<https://groups.google.com/d/forum/ruby-hallon>)
 - __Found a bug?__ Report an issue: <https://github.com/Burgestrand/Hallon/issues/new>
 - __Have feedback?__ I ❤ feedback! Please send it to the mailing list.
 

data/dev/application_key_converter.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+if ARGF.file == STDIN
+  puts "You forgot to give me a file!"
+  abort "Usage: ruby application_key_converter.rb spotify_appkey.key > new_spotify_appkey.key"
+end
+
+old_format = ARGF.read.split.join
+new_format = [old_format].pack("H*")
+
+print new_format

data/examples/example_support.rb

@@ -86,6 +86,10 @@ session = Hallon::Session.initialize(hallon_appkey) do
     puts "[LOG] #{message}"
   end
 
+  on(:credentials_blob_updated) do |blob|
+    puts "[BLOB] #{blob}"
+  end
+
   on(:connection_error) do |error|
     Hallon::Error.maybe_raise(error)
   end

data/examples/playing_audio.rb

@@ -11,7 +11,7 @@ rescue LoadError => e
   abort "[ERROR] Could not load gem 'hallon-openal', please install with 'gem install hallon-openal'"
 end
 
-player = Hallon::Player.new(session, Hallon::OpenAL)
+player = Hallon::Player.new(Hallon::OpenAL)
 
 # Program flow.
 

data/lib/hallon.rb

@@ -12,6 +12,7 @@ require 'hallon/error'
 require 'hallon/base'
 require 'hallon/enumerator'
 require 'hallon/audio_queue'
+require 'hallon/blob'
 
 require 'hallon/observable/album_browse'
 require 'hallon/observable/artist_browse'
@@ -70,6 +71,16 @@ module Hallon
   # Thrown by {Loadable#load} and {Playlist#update} on failure.
   TimeoutError = Class.new(Hallon::Error)
 
+  # Raised by Session.instance
+  NoSessionError = Class.new(StandardError)
+
+  # Raised by Session#login! and Session#relogin!
+  LoginError = Class.new(StandardError)
+
+  # Raised by PlaylistContainer#num_unseen_tracks_for and PlaylistContainer#unseen_tracks_for.
+  # @note most likely raised because of the playlist not being in the playlist container.
+  OperationFailedError = Class.new(StandardError)
+
   class << self
     # @return [Numeric] default load timeout in seconds, used in {Loadable#load}.
     attr_reader :load_timeout

data/lib/hallon/album_browse.rb

@@ -77,11 +77,11 @@ module Hallon
     end
 
     # @note If the object is not loaded, the result is undefined.
-    # @note Returns nil if the request was served from the local libspotify cache.
-    # @return [Rational, nil] time it took for the albumbrowse request to complete (in seconds).
+    # @return [Rational] time it took for the albumbrowse request to complete (in seconds).
     def request_duration
       duration = Spotify.albumbrowse_backend_request_duration(pointer)
-      Rational(duration, 1000) if duration > 0
+      duration = 0 if duration < 0
+      Rational(duration, 1000)
     end
 
     # @return [Copyrights] enumerator of copyright notices.

data/lib/hallon/artist_browse.rb

@@ -1,6 +1,7 @@
 # coding: utf-8
 module Hallon
-  # ArtistBrowse is like AlbumBrowse, only that it’s for {Track}s.
+  # An ArtistBrowse object is for retrieving details about a given artist, such
+  # as it’s tracks, albums, similar artists and more.
   #
   # @see Artist
   # @see http://developer.spotify.com/en/libspotify/docs/group__artistbrowse.html
@@ -55,6 +56,16 @@ module Hallon
       end
     end
 
+    # Enumerates through all tophit tracks of an album browsing object.
+    class TopHits < Enumerator
+      size :artistbrowse_num_tophit_tracks
+
+      # @return [Track, nil]
+      item :artistbrowse_tophit_track! do |track|
+        Track.from(track)
+      end
+    end
+
     extend Observable::ArtistBrowse
     include Loadable
 
@@ -107,11 +118,11 @@ module Hallon
     end
 
     # @note If the object is not loaded, the result is undefined.
-    # @note Returns nil if the request was served from the local libspotify cache.
-    # @return [Rational, nil] time it took for the albumbrowse request to complete (in seconds).
+    # @return [Rational] time it took for the albumbrowse request to complete (in seconds).
     def request_duration
       duration = Spotify.artistbrowse_backend_request_duration(pointer)
-      Rational(duration, 1000) if duration > 0
+      duration = 0 if duration < 0
+      Rational(duration, 1000)
     end
 
     # @return [Portraits] artist portraits as {Image}s.
@@ -138,5 +149,10 @@ module Hallon
     def similar_artists
       SimilarArtists.new(self)
     end
+
+    # @return [TopHits] enumerator of the artist’s most popular tracks.
+    def top_hits
+      TopHits.new(self)
+    end
   end
 end

data/lib/hallon/blob.rb

@@ -0,0 +1,11 @@
+module Hallon
+  # Dummy module, allows for infecting strings
+  # with a Hallon::Blob to check for if they are
+  # blobs or not.
+  module Blob
+  end
+
+  def self.Blob(string)
+    string.extend(Blob)
+  end
+end

data/lib/hallon/enumerator.rb

@@ -70,6 +70,11 @@ module Hallon
       self
     end
 
+    # @return [Boolean] true if the size is zero.
+    def empty?
+      size.zero?
+    end
+
     # @overload [](index)
     #   @return [Object, nil]
     #

data/lib/hallon/ext/spotify.rb

@@ -46,6 +46,7 @@ module Spotify
   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
 
@@ -59,6 +60,7 @@ module Spotify
   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

data/lib/hallon/image.rb

@@ -71,7 +71,13 @@ module Hallon
     def data
       FFI::MemoryPointer.new(:size_t) do |size|
         data = Spotify.image_data(pointer, size)
-        return data.read_bytes(size.read_size_t)
+        size = size.read_size_t
+
+        if size > 0
+          return data.read_bytes(size)
+        else
+          return "".force_encoding("BINARY")
+        end
       end
     end
 

data/lib/hallon/link.rb

@@ -9,6 +9,10 @@ module Hallon
     # @param [#to_s] spotify_uri
     # @return [Boolean]
     def self.valid?(spotify_uri)
+      unless Session.instance?
+        raise NoSessionError, "You must have initialized a session to create links"
+      end
+
       if spotify_uri.is_a?(Link)
         return true
       elsif spotify_uri.to_s["\x00"] # image ids
@@ -25,9 +29,8 @@ module Hallon
     # @param [#to_str] uri
     # @raise [ArgumentError] link could not be parsed
     def initialize(uri)
-      # if no session instance exists, libspotify segfaults, so assert that we have one
       unless Session.instance?
-        raise "Link.new requires an existing Session instance"
+        raise NoSessionError, "You must have initialized a session to create links"
       end
 
       # we support any #to_link’able object

data/lib/hallon/observable.rb

@@ -111,6 +111,53 @@ module Hallon
       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 block will be called without parameters.
+    # @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)
+      channel = SizedQueue.new(10) # sized just to be safe
+
+      old_handlers = events.each_with_object({}) do |event, hash|
+        hash[event] = on(event) do |*args|
+          channel << [event, *args]
+          hash[event].call(*args)
+        end
+      end
+
+      old_notify = session.on(:notify_main_thread) do
+        channel << :notify
+      end
+
+      if result = yield
+        return result
+      end
+
+      loop do
+        begin
+          timeout = [session.process_events.fdiv(1000), 2].min # scope to two seconds
+          timeout = timeout + 0.010 # minimum of ten miliseconds timeout
+          params = Timeout::timeout(timeout) { channel.pop }
+          redo if params == :notify
+        rescue Timeout::Error
+          params = nil
+        end
+
+        if result = yield(*params)
+          return result
+        end
+      end
+    ensure
+      old_handlers.each_pair do |event, handler|
+        on(event, &handler)
+      end unless old_handlers.nil?
+      session.on(:notify_main_thread, &old_notify) unless old_notify.nil?
+    end
+
+
     # @param [#to_s] name
     # @return [Boolean] true if a callback with `name` exists.
     def has_callback?(name)
@@ -149,7 +196,7 @@ module Hallon
     # @return whatever the handler returns
     def trigger(name, *arguments, &block)
       if handler = handlers[name.to_s]
-        handler.call(*arguments, self, &block)
+        handler.call(*arguments, &block)
       end
     end
 

data/lib/hallon/player.rb

@@ -6,7 +6,7 @@ module Hallon
   # controlling the playback features of libspotify.
   #
   # @see Session
-  class Player
+  class Player < Base
     # meep?
     extend Observable::Player
 
@@ -24,18 +24,17 @@ module Hallon
       end
     end
 
-    # Constructs a Player, given a Session and an audio driver.
+    # Constructs a Player, given an audio driver.
     #
     # @example
-    #   player = Hallon::Player.new(session, Hallon::OpenAL)
+    #   player = Hallon::Player.new(Hallon::OpenAL)
     #   player.play(track)
     #
     # @note for instructions on how to write your own audio driver, see Hallons’ README
-    # @param [Session] session
     # @param [AudioDriver] driver
     # @yield instance_evals itself, allowing you to define callbacks using `on`
-    def initialize(session, driver, &block)
-      @session = session
+    def initialize(driver, &block)
+      @session = Hallon::Session.instance
       @pointer = @session.pointer
 
       # sample rate is often (if not always) 44.1KHz, so
@@ -85,20 +84,20 @@ module Hallon
     #
     # Will be called after calling our buffers are full enough to support
     # continous playback.
-    def start_playback(session)
+    def start_playback
       self.status = :playing
     end
 
     # Called by libspotify when the driver should pause audio playback.
     #
     # Might happen if we’re playing audio faster than we can stream it.
-    def stop_playback(session)
+    def stop_playback
       self.status = :paused
     end
 
     # Called by libspotify on music delivery; format is
     # a hash of (sample) rate, channels and (sample) type.
-    def music_delivery(format, frames, session)
+    def music_delivery(format, frames)
       @queue.synchronize do
         if frames.none?
           @queue.clear
@@ -113,7 +112,7 @@ module Hallon
     # Called by libspotify to request information about our
     # audio buffer. Required if we want libspotify to tell
     # us when we should start and stop playback.
-    def get_audio_buffer_stats(session)
+    def get_audio_buffer_stats
       drops = @driver.drops if @driver.respond_to?(:drops)
       [@queue.size, drops.to_i]
     end
@@ -192,22 +191,12 @@ module Hallon
     # @param (see #play)
     # @return (see #play)
     def play!(track = nil)
-      monitor = Monitor.new
-      condvar = monitor.new_cond
-
-      monitor.synchronize do
-        end_of_track = false
-
-        on(:end_of_track) do
-          monitor.synchronize do
-            end_of_track = true
-            condvar.signal
-          end
-        end
-
-        play(track)
-        condvar.wait_until { end_of_track }
-      end
+      end_of_track = false
+      old_callback = on(:end_of_track) { end_of_track = true }
+      play(track)
+      wait_for(:end_of_track) { end_of_track }
+    ensure
+      on(:end_of_track, &old_callback)
     end
 
     # Set preferred playback bitrate.

data/lib/hallon/playlist.rb

@@ -29,10 +29,10 @@ module Hallon
 
         @index        = index
         @playlist_ptr = playlist_pointer
-        @create_time  = Time.at Spotify.playlist_track_create_time(playlist_ptr, index)
-        @message      = Spotify.playlist_track_message(playlist_ptr, index)
+        @message      = Spotify.playlist_track_message(playlist_ptr, index).to_s
         @seen         = Spotify.playlist_track_seen(playlist_ptr, index)
-        @creator      = begin
+        @added_at     = Time.at(Spotify.playlist_track_create_time(playlist_ptr, index)).utc
+        @adder        = begin
           creator = Spotify.playlist_track_creator!(playlist_ptr, index)
           User.from(creator)
         end
@@ -46,11 +46,11 @@ module Hallon
       # @return [Integer] index this track was created with.
       attr_reader :index
 
-      # @return [Time] time when track at {#index} was added to playlist.
-      attr_reader :create_time
+      # @return [Time, nil] time when track at {#index} was added to playlist.
+      attr_reader :added_at
 
       # @return [User, nil] person who added track at {#index} to this playlist.
-      attr_reader :creator
+      attr_reader :adder
 
       # @return [String] message attached to this track at {#index}.
       attr_reader :message
@@ -150,24 +150,14 @@ module Hallon
       Spotify.playlist_set_collaborative(pointer, !!collaborative)
     end
 
-    # Allow the playlist time to update itself and the Spotify backend.
-    # This method will block until libspotify says the playlist no longer
-    # has pending changes.
+    # Waits for the playlist to begin updating and blocks until it is done.
     #
     # @return [Playlist]
     def upload(timeout = Hallon.load_timeout)
-      unless pending?
-        # libspotify has this bug where pending? returns false directly after
-        # adding tracks to a playlist; processing events once usually toggles
-        # the playlist into pending? mode
-        session.process_events
-      end
-
       Timeout.timeout(timeout, Hallon::TimeoutError) do
-        session.wait_for { not pending? }
+        wait_for(:playlist_update_in_progress) { |done| done }
+        self
       end
-
-      self
     end
 
     # @return [Boolean] true if playlist has pending changes
@@ -215,7 +205,7 @@ module Hallon
       Spotify.playlist_set_offline_mode(session.pointer, pointer, !! available_offline)
     end
 
-    # @return [String]
+    # @return [String] playlist name, or an empty string if unavailable.
     def name
       Spotify.playlist_name(pointer)
     end
@@ -258,17 +248,18 @@ module Hallon
     def subscribers
       ptr = Spotify.playlist_subscribers(pointer)
 
-      begin
+      if ptr.null?
+        []
+      else
         struct = Spotify::Subscribers.new(ptr)
-
         if struct[:count].zero?
           []
         else
           struct[:subscribers].map(&:read_string)
         end
-      ensure
-        Spotify.playlist_subscribers_free(ptr)
-      end unless ptr.null?
+      end
+    ensure
+      Spotify.playlist_subscribers_free(ptr) unless ptr.null?
     end
 
     # @return [Integer] total number of subscribers.