hallon 0.17.0 → 0.18.0

data/CHANGELOG.md

@@ -4,6 +4,19 @@ Hallon’s Changelog
 [HEAD][]
 ------------------
 
+[v0.18.0][]
+------------------
+This issue is to plug a bug of libspotify on Linux (see issue #125). The reason that
+the minor version is increased is because of the update to libspotify v12.1.51.
+
+__Changed__
+- Upgrade to libspotify v12.1.51 [7c72ead7]
+- All custom Hallon errors now inherit from Hallon::Error [950cf01]
+
+__Fixed__
+- Update documentation for observable hooks to not say they yield themselves [8c85c5e]
+- Fixed race condition in audio format change [a5decb1]
+
 [v0.17.0][]
 ------------------
 Updated to libspotify v12.1.45, with all the good parts included!
@@ -382,4 +395,5 @@ easier to handle.
 [v0.15.0]: https://github.com/Burgestrand/Hallon/compare/v0.14.0...v0.15.0
 [v0.16.0]: https://github.com/Burgestrand/Hallon/compare/v0.15.0...v0.16.0
 [v0.17.0]: https://github.com/Burgestrand/Hallon/compare/v0.16.0...v0.17.0
+[v0.18.0]: https://github.com/Burgestrand/Hallon/compare/v0.17.0...v0.18.0
 [HEAD]: https://github.com/Burgestrand/Hallon/compare/v0.17.0...HEAD

data/Gemfile

@@ -1,6 +1,11 @@
 source :rubygems
 gemspec
 
+# Useful for testing out audio.
+unless ENV["TRAVIS"] # does not build on travis
+  gem 'hallon-openal'
+end
+
 gem 'ruby_parser', '>= 3.0.0.a1', '< 4.0'
 gem 'pry'
 gem 'simplecov'

data/README.markdown

@@ -15,7 +15,7 @@ Before you start using Hallon you’ll need to complete the following steps.
 2. [Download your application key from developer.spotify.com](https://developer.spotify.com/en/libspotify/application-key/),
    and place it in a known location. You’ll have the option of downloading it either in **binary** or c-code. You want the
    **binary** one. If you do not have an application key already, you will be asked to create one.
-3. Install libspotify. Hallon always aims to support to most recent version, which is currently **v10.1.16**. Older
+3. Install libspotify. Hallon always aims to support to most recent version, which is currently **v12.1.51**. Older
    versions are not supported. For help installing libspotify, please see the wiki on [How to install libspotify][].
 4. Once the above are done, you are ready to try out Hallon.
 

data/examples/nordic_ruby_2012.rb

@@ -0,0 +1,24 @@
+# coding: utf-8
+
+# Require support code, used by all the examples.
+require_relative 'example_support'
+session = Hallon::Session.instance
+
+require 'pry'
+
+begin
+  require 'hallon/openal'
+rescue LoadError => e
+  puts e.message
+  abort "[ERROR] Could not load gem 'hallon-openal', please install with 'gem install hallon-openal'"
+end
+
+puts "Creating Player."
+player = Hallon::Player.new(Hallon::OpenAL)
+
+puts "Loading track."
+track  = Hallon::Track.new("spotify:track:7Az9kfq4JLD8auD1xoErrP").load
+player.load(track)
+player.seek(9.8)
+
+binding.pry

data/hallon.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |gem|
   gem.required_ruby_version = '>= 1.9'
 
   gem.add_dependency 'ref', '~> 1.0'
-  gem.add_dependency 'spotify', '~> 12.0.2'
+  gem.add_dependency 'spotify', '~> 12.2.0'
   gem.add_development_dependency 'rake', '~> 0.8'
   gem.add_development_dependency 'rspec', '~> 2'
   gem.add_development_dependency 'yard'

data/lib/hallon.rb

@@ -73,14 +73,14 @@ module Hallon
   TimeoutError = Class.new(Hallon::Error)
 
   # Raised by Session.instance
-  NoSessionError = Class.new(StandardError)
+  NoSessionError = Class.new(Hallon::Error)
 
   # Raised by Session#login! and Session#relogin!
-  LoginError = Class.new(StandardError)
+  LoginError = Class.new(Hallon::Error)
 
   # 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)
+  OperationFailedError = Class.new(Hallon::Error)
 
   class << self
     # @return [Numeric] default load timeout in seconds, used in {Loadable#load}.

data/lib/hallon/audio_queue.rb

@@ -12,56 +12,81 @@ module Hallon
   #
   # Hallon::AudioQueue is useful for handling {Hallon::Observable::Session#music_delivery_callback}.
   #
-  # @example
+  # @example filling the buffer
   #   queue = Hallon::AudioQueue.new(4)
-  #   queue.push([1, 2]) # => 2
-  #   queue.push([3]) # => 1
-  #   queue.push([4, 5, 6]) # => 1
-  #   queue.push([5, 6]) # => 0
-  #   queue.pop(1) # => [1]
-  #   queue.push([5, 6]) # => 1
-  #   queue.pop # => [2, 3, 4, 5]
+  #   format = { :rate => 44100, :channels => 2 }
+  #   queue.push(format, [1, 2]) # => 2
+  #   queue.push(format, [3]) # => 1
+  #   queue.push(format, [4, 5, 6]) # => 1
+  #   queue.push(format, [5, 6]) # => 0
+  #   queue.pop(format, 1) # => [1]
+  #   queue.push(format, [5, 6]) # => 1
+  #   queue.pop(format) # => [2, 3, 4, 5]
+  #
+  # @example changing the format
+  #   queue  = Hallon::AudioQueue.new(4)
+  #   queue.format # => nil
+  #   queue.push(:initial_format, [1, 2, 3, 4]) # => 4
+  #   queue.size # => 4
+  #   queue.format # => :initial_format
+  #   queue.push(:new_format, [1, 2]) # => 2
+  #   queue.size # => 2
+  #   queue.format # => :new_format
   #
   # @private
   class AudioQueue
     attr_reader :max_size
 
-    # @param [Integer] max_size
+    # @param [Integer] max_size how many frames
     def initialize(max_size)
       @max_size = max_size
-      @samples  = []
+      @frames  = []
 
-      @samples.extend(MonitorMixin)
-      @condvar  = @samples.new_cond
+      @frames.extend(MonitorMixin)
+      @condvar  = @frames.new_cond
     end
 
-    # @param [#take] samples
+    # @note If the format is not the same as the current format, the queue is
+    #       emptied before appending the new data. In this case, {#format} will
+    #       be assigned to the new format as well.
+    #
+    # @param [Hash] format format of the audio frames given
+    # @param [#take] frames
     # @return [Integer] how much of the data that was added to the queue
-    def push(samples)
+    def push(format, frames)
       synchronize do
+        unless format == @format
+          @format = format
+          clear
+        end
+
         can_accept  = max_size - size
-        new_samples = samples.take(can_accept)
+        new_frames = frames.take(can_accept)
 
-        @samples.concat(new_samples)
+        @frames.concat(new_frames)
         @condvar.signal
 
-        new_samples.size
+        new_frames.size
       end
     end
 
     # @note If the queue is empty, this operation will block until data is available.
-    # @param [Integer] num_samples max number of samples to pop off the queue
-    # @return [Array] data, where data.size might be less than num_samples but never more
-    def pop(num_samples = max_size)
+    # @note When data is available, if it’s not in the same format as the format requested
+    #       the return value will be nil. This is to avoid the format changing during wait.
+    #
+    # @param [Hash] format requested format
+    # @param [Integer] num_frames max number of frames to pop off the queue
+    # @return [Array, nil] array of data, but no longer than `num_frames`
+    def pop(format, num_frames = max_size)
       synchronize do
         @condvar.wait_while { empty? }
-        @samples.shift(num_samples)
+        @frames.shift(num_frames) if format == @format
       end
     end
 
-    # @return [Integer] number of samples in buffer.
+    # @return [Integer] number of frames in buffer.
     def size
-      synchronize { @samples.size }
+      synchronize { @frames.size }
     end
 
     # @return [Boolean] true if the queue has a {#size} of 0.
@@ -71,18 +96,7 @@ module Hallon
 
     # Clear all data from the AudioQueue.
     def clear
-      synchronize { @samples.clear }
-    end
-
-    # Attach format metadata to the queue.
-    #
-    # @note this will clear the queue of all audio data!
-    # @param format new audio format
-    def format=(format)
-      synchronize do
-        @format = format
-        clear
-      end
+      synchronize { @frames.clear }
     end
 
     # Returns the format previously set by #format=.
@@ -95,7 +109,7 @@ module Hallon
     # @yield exclusive section around the queue contents
     # @return whatever the given block returns
     def synchronize
-      @samples.synchronize { return yield }
+      @frames.synchronize { return yield }
     end
 
     # Create a condition variable bound to this AudioQueue.
@@ -104,7 +118,7 @@ module Hallon
     # @return [MonitorMixin::ConditionVariable]
     # @see monitor.rb (ruby stdlib)
     def new_cond
-      @samples.new_cond
+      @frames.new_cond
     end
   end
 end

data/lib/hallon/observable/album_browse.rb

@@ -21,8 +21,7 @@ module Hallon::Observable
     #     puts "Album browser has loaded!"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [AlbumBrowse] self
+    # @yield []
     def load_callback(pointer, userdata)
       trigger(pointer, :load)
     end

data/lib/hallon/observable/artist_browse.rb

@@ -21,8 +21,7 @@ module Hallon::Observable
     #     puts "Artist browser has loaded!"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [ArtistBrowse] self
+    # @yield []
     def load_callback(pointer, userdata)
       trigger(pointer, :load)
     end

data/lib/hallon/observable/image.rb

@@ -21,8 +21,7 @@ module Hallon::Observable
     #     puts "Image has loaded"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Image] self
+    # @yield []
     def load_callback(pointer, userdata)
       trigger(pointer, :load)
     end

data/lib/hallon/observable/player.rb

@@ -10,20 +10,20 @@ module Hallon::Observable
 
     protected
 
-    # @return nil
+    # @return [Array<Method>] array of callback methods
     def initialize_callbacks
       %w(end_of_track streaming_error play_token_lost).map { |m| callback_for(m) }
     end
 
-    # Dummy callback. See Session#end_of_track_callback.
+    # Dummy callback. See {Session#end_of_track_callback}.
     def end_of_track_callback(session)
     end
 
-    # Dummy callback. See Session#streaming_error_callback.
+    # Dummy callback. See {Session#streaming_error_callback}.
     def streaming_error_callback(session, error)
     end
 
-    # Dummy callback. See Session#play_token_lost_callback.
+    # Dummy callback. See {Session#play_token_lost_callback}.
     def play_token_lost_callback(session)
     end
   end

data/lib/hallon/observable/playlist.rb

@@ -22,10 +22,9 @@ module Hallon::Observable
     #     puts "#{tracks.map(&:name).join(', ')} added at #{position} to #{playlist.name}"
     #   end
     #
-    # @yield [tracks, position, self] tracks_added
+    # @yield [tracks, position] tracks_added
     # @yieldparam [Array<Track>] tracks
     # @yieldparam [Integer] position
-    # @yieldparam [Playlist] self
     def tracks_added_callback(pointer, tracks, num_tracks, position, userdata)
       tracks_ary = tracks.read_array_of_pointer(num_tracks).map do |track|
         ptr = Spotify::Pointer.new(track, :track, true)
@@ -40,9 +39,8 @@ module Hallon::Observable
     #     puts "#{tracks.map(&:name).join(', ') removed from #{playlist.name}"
     #   end
     #
-    # @yield [tracks, self] tracks_removed
+    # @yield [tracks] tracks_removed
     # @yieldparam [Array<Track>] tracks
-    # @yieldparam [Playlist] self
     def tracks_removed_callback(pointer, track_indices, num_indices, userdata)
       trigger(pointer, :tracks_removed, track_indices.read_array_of_int(num_indices))
     end
@@ -52,10 +50,9 @@ module Hallon::Observable
     #     puts "#{tracks.map(&:name).join(', ')} moved to #{new_position} to #{playlist.name}"
     #   end
     #
-    # @yield [tracks, new_position, self] tracks_moved
+    # @yield [tracks, new_position] tracks_moved
     # @yieldparam [Array<Track>] tracks
     # @yieldparam [Integer] new_position
-    # @yieldparam [Playlist] self
     def tracks_moved_callback(pointer, track_indices, num_indices, new_position, userdata)
       trigger(pointer, :tracks_moved, track_indices.read_array_of_int(num_indices), new_position)
     end
@@ -65,8 +62,7 @@ module Hallon::Observable
     #     puts "#{playlist.name} was now previously named something else \o/"
     #   end
     #
-    # @yield [self] playlist_renamed
-    # @yieldparam [Playlist] self
+    # @yield [] playlist_renamed
     def playlist_renamed_callback(pointer, userdata)
       trigger(pointer, :playlist_renamed)
     end
@@ -76,8 +72,7 @@ module Hallon::Observable
     #     puts "playlist state changed… to what? from what? D:"
     #   end
     #
-    # @yield [self] playlist_state_changed
-    # @yieldparam [Playlist] self
+    # @yield [] playlist_state_changed
     def playlist_state_changed_callback(pointer, userdata)
       trigger(pointer, :playlist_state_changed)
     end
@@ -87,9 +82,8 @@ module Hallon::Observable
     #     puts(is_done ? "DONE!" : "not done :(")
     #   end
     #
-    # @yield [is_done, self] playlist_update_in_progress
+    # @yield [is_done] playlist_update_in_progress
     # @yieldparam [Boolean] is_done
-    # @yieldparam [Playlist] self
     def playlist_update_in_progress_callback(pointer, done, userdata)
       trigger(pointer, :playlist_update_in_progress, done)
     end
@@ -99,8 +93,7 @@ module Hallon::Observable
     #     puts "#{playlist.name} metadata updated"
     #   end
     #
-    # @yield [self] playlist_metadata_updated
-    # @yieldparam [Playlist] self
+    # @yield [] playlist_metadata_updated
     def playlist_metadata_updated_callback(pointer, userdata)
       trigger(pointer, :playlist_metadata_updated)
     end
@@ -111,11 +104,10 @@ module Hallon::Observable
     #     puts "#{track.name} created-info changed"
     #   end
     #
-    # @yield [position, user, created_at, self] track_created_changed
+    # @yield [position, user, created_at] track_created_changed
     # @yieldparam [Integer] position
     # @yieldparam [User] user
     # @yieldparam [Time] created_at
-    # @yieldparam [Playlist] self
     def track_created_changed_callback(pointer, position, user, created_at, userdata)
       user = Spotify::Pointer.new(user, :user, true)
       trigger(pointer, :track_created_changed, position, Hallon::User.new(user), Time.at(created_at))
@@ -127,10 +119,9 @@ module Hallon::Observable
     #     puts "#{track.name}#seen? is #{seen}"
     #   end
     #
-    # @yield [position, is_seen, self] track_seen_changed
+    # @yield [position, is_seen] track_seen_changed
     # @yieldparam [Integer] position
     # @yieldparam [Boolean] is_seen
-    # @yieldparam [Playlist] self
     def track_seen_changed_callback(pointer, position, seen, userdata)
       trigger(pointer, :track_seen_changed, position, seen)
     end
@@ -141,10 +132,9 @@ module Hallon::Observable
     #     puts "#{track.name} new message: #{message}"
     #   end
     #
-    # @yield [position, message, self] track_message_changed
+    # @yield [position, message] track_message_changed
     # @yieldparam [Integer] position
     # @yieldparam [String] message
-    # @yieldparam [Playlist] self
     def track_message_changed_callback(pointer, position, message, userdata)
       trigger(pointer, :track_message_changed, position, message)
     end
@@ -154,9 +144,8 @@ module Hallon::Observable
     #     puts "#{playlist.name} new description: #{description}"
     #   end
     #
-    # @yield [description, self] description_changed
+    # @yield [description] description_changed
     # @yieldparam [String] description
-    # @yieldparam [Playlist] self
     def description_changed_callback(pointer, description, userdata)
       trigger(pointer, :description_changed, description)
     end
@@ -166,9 +155,8 @@ module Hallon::Observable
     #     puts "#{playlist.name} has got a new image: #{image.to_link}"
     #   end
     #
-    # @yield [image, self] image_changed
+    # @yield [image] image_changed
     # @yieldparam [Image, nil] image or nil
-    # @yieldparam [Playlist] self
     def image_changed_callback(pointer, image, userdata)
       image = Hallon::Image.from(image)
       trigger(pointer, :image_changed, image)
@@ -179,8 +167,7 @@ module Hallon::Observable
     #     puts "#{playlist.name} updated its’ subscribers"
     #   end
     #
-    # @yield [self] subscribers_changed
-    # @yieldparam [Playlist] self
+    # @yield [] subscribers_changed
     def subscribers_changed_callback(pointer, userdata)
       trigger(pointer, :subscribers_changed)
     end

data/lib/hallon/observable/playlist_container.rb

@@ -22,10 +22,9 @@ module Hallon::Observable
     #     puts playlist.name + " added at #{position}."
     #   end
     #
-    # @yield [playlist, position, self] playlist_added
+    # @yield [playlist, position] playlist_added
     # @yieldparam [Playlist] playlist
     # @yieldparam [Integer] position
-    # @yieldparam [PlaylistContainer] self
     def playlist_added_callback(pointer, playlist, position, userdata)
       trigger(pointer, :playlist_added, playlist_from(playlist), position)
     end
@@ -35,10 +34,9 @@ module Hallon::Observable
     #     puts playlist.name + " removed from #{position}."
     #   end
     #
-    # @yield [playlist, position, self] playlist_removed
+    # @yield [playlist, position] playlist_removed
     # @yieldparam [Playlist] playlist
     # @yieldparam [Integer] position
-    # @yieldparam [PlaylistContainer] self
     def playlist_removed_callback(pointer, playlist, position, userdata)
       trigger(pointer, :playlist_removed, playlist_from(playlist), position)
     end
@@ -48,11 +46,10 @@ module Hallon::Observable
     #     puts "moved #{playlist.name} from #{position} to #{new_position}"
     #   end
     #
-    # @yield [playlist, position, new_position, self] playlist_moved
+    # @yield [playlist, position, new_position] playlist_moved
     # @yieldparam [Playlist] playlist
     # @yieldparam [Integer] position
     # @yieldparam [Integer] new_position
-    # @yieldparam [PlaylistContainer] self
     def playlist_moved_callback(pointer, playlist, position, new_position, userdata)
       trigger(pointer, :playlist_moved, playlist_from(playlist), position, new_position)
     end
@@ -62,8 +59,7 @@ module Hallon::Observable
     #     puts "#{container.owner.name}s container loaded!"
     #   end
     #
-    # @yield [self] container_loaded
-    # @yieldparam [PlaylistContainer] self
+    # @yield [] container_loaded
     def container_loaded_callback(pointer, userdata)
       trigger(pointer, :container_loaded)
     end

data/lib/hallon/observable/post.rb

@@ -21,8 +21,7 @@ module Hallon::Observable
     #     puts "ze user be havin’ sum posts"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [User::Post] self
+    # @yield []
     def complete_callback(pointer, userdata)
       trigger(pointer, :complete)
     end

data/lib/hallon/observable/search.rb

@@ -20,8 +20,7 @@ module Hallon::Observable
     #     puts "search for #{search.query} is complete!"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Search] self
+    # @yield []
     def load_callback(pointer, userdata)
       trigger(pointer, :load)
     end

data/lib/hallon/observable/session.rb

@@ -23,9 +23,8 @@ module Hallon::Observable
     #     puts "Logged in: " + Hallon::Error.explain(error)
     #   end
     #
-    # @yield [error, self] logged_in
+    # @yield [error] logged_in
     # @yieldparam [Symbol] error
-    # @yieldparam [Session] self
     # @see Error
     def logged_in_callback(pointer, error)
       trigger(pointer, :logged_in, error)
@@ -36,8 +35,7 @@ module Hallon::Observable
     #     puts "AHHH!"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Session] self
+    # @yield []
     def logged_out_callback(pointer)
       trigger(pointer, :logged_out)
     end
@@ -47,8 +45,7 @@ module Hallon::Observable
     #     puts "wut wut"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Session] self
+    # @yield []
     def metadata_updated_callback(pointer)
       trigger(pointer, :metadata_updated)
     end
@@ -58,9 +55,8 @@ module Hallon::Observable
     #     puts "Oh noes: " + Hallon::Error.explain(error)
     #   end
     #
-    # @yield [error, self]
+    # @yield [error]
     # @yieldparam [Symbol] error
-    # @yieldparam [Session] self
     # @see Error
     def connection_error_callback(pointer, error)
       trigger(pointer, :connection_error, error)
@@ -71,9 +67,8 @@ module Hallon::Observable
     #     puts "OH HAI: #{message}"
     #   end
     #
-    # @yield [message, self]
+    # @yield [message]
     # @yieldparam [String] message
-    # @yieldparam [Session] self
     def message_to_user_callback(pointer, message)
       trigger(pointer, :message_to_user, message)
     end
@@ -83,8 +78,7 @@ module Hallon::Observable
     #     puts "main thread turn on"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Session] self
+    # @yield []
     def notify_main_thread_callback(pointer)
       trigger(pointer, :notify_main_thread)
     end
@@ -94,10 +88,9 @@ module Hallon::Observable
     #     puts ""
     #   end
     #
-    # @yield [format, frames, self]
+    # @yield [format, frames]
     # @yieldparam [Hash] format (contains :type, :rate, :channels)
     # @yieldparam [Enumerator<[Integer...]>] frames (each frame is an array containing format[:channels] integers of format[:type])
-    # @yieldparam [Session] self
     def music_delivery_callback(pointer, format, frames, num_frames)
       struct = Spotify::AudioFormat.new(format)
 
@@ -125,8 +118,7 @@ module Hallon::Observable
     #     puts "another user set us up the bomb!"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Session] self
+    # @yield []
     def play_token_lost_callback(pointer)
       trigger(pointer, :play_token_lost)
     end
@@ -136,8 +128,7 @@ module Hallon::Observable
     #     puts "all your base are belong to us"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Session] self
+    # @yield []
     def end_of_track_callback(pointer)
       trigger(pointer, :end_of_track)
     end
@@ -147,8 +138,7 @@ module Hallon::Observable
     #     puts "dum dum tiss"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Session] self
+    # @yield []
     def start_playback_callback(pointer)
       trigger(pointer, :start_playback)
     end
@@ -158,8 +148,7 @@ module Hallon::Observable
     #     puts "dum dum tiss"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Session] self
+    # @yield []
     def stop_playback_callback(pointer)
       trigger(pointer, :stop_playback)
     end
@@ -169,8 +158,7 @@ module Hallon::Observable
     #     puts "que?"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Session] self
+    # @yield []
     # @yieldreturn an integer pair, [samples, dropouts]
     def get_audio_buffer_stats_callback(pointer, stats)
       stats = Spotify::AudioBufferStats.new(stats)
@@ -184,9 +172,8 @@ module Hallon::Observable
     #     puts "boo: " + Hallon::Error.explain(error)
     #   end
     #
-    # @yield [error, self]
+    # @yield [error]
     # @yieldparam [Symbol] error
-    # @yieldparam [Session] self
     def streaming_error_callback(pointer, error)
       trigger(pointer, :streaming_error, error)
     end
@@ -196,8 +183,7 @@ module Hallon::Observable
     #     puts "who am I?!"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Session] self
+    # @yield []
     def userinfo_updated_callback(pointer)
       trigger(pointer, :userinfo_updated)
     end
@@ -207,9 +193,8 @@ module Hallon::Observable
     #     puts "for great justice: #{message}"
     #   end
     #
-    # @yield [message, self]
+    # @yield [message]
     # @yieldparam [String] message
-    # @yieldparam [Session] self
     def log_message_callback(pointer, message)
       trigger(pointer, :log_message, message)
     end
@@ -219,8 +204,7 @@ module Hallon::Observable
     #     puts "All systems: #{session.status}"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Session] self
+    # @yield []
     def offline_status_updated_callback(pointer)
       trigger(pointer, :offline_status_updated)
     end
@@ -230,9 +214,8 @@ module Hallon::Observable
     #     puts "FAIL: " + Hallon::Error.explain(error)
     #   end
     #
-    # @yield [error, self]
+    # @yield [error]
     # @yieldparam [Symbol] error
-    # @yieldparam [Session] self
     def offline_error_callback(pointer, error)
       trigger(pointer, :offline_error, error)
     end
@@ -243,9 +226,8 @@ module Hallon::Observable
     #     File.open('.spotify-credentials', 'w') { |io| io.write(credentials) }
     #   end
     #
-    # @yield [credentials, self]
+    # @yield [credentials]
     # @yieldparam [String] credentials
-    # @yieldparam [Session] self
     def credentials_blob_updated_callback(pointer, credentials)
       trigger(pointer, :credentials_blob_updated, credentials)
     end

data/lib/hallon/observable/toplist.rb

@@ -20,8 +20,7 @@ module Hallon::Observable
     #     puts "the toplist has loaded!"
     #   end
     #
-    # @yield [self]
-    # @yieldparam [Toplist] self
+    # @yield []
     def load_callback(pointer, userdata)
       trigger(pointer, :load)
     end

data/lib/hallon/player.rb

@@ -41,7 +41,7 @@ module Hallon
       # we keep an audio queue that can store 3s of audio
       @queue  = AudioQueue.new(44100)
       @driver = driver.new
-      @queue.format = @driver.format = { rate: 44100, channels: 2, type: :int16 }
+      @driver.format = { rate: 44100, channels: 2, type: :int16 }
 
       # used for feeder thread to know if it should stream
       # data to the driver or not (see #status=)
@@ -54,14 +54,15 @@ module Hallon
       @thread = Thread.start(@driver, @queue, @status_c) do |output, queue, cond|
         output.stream do |num_frames|
           queue.synchronize do
-            cond.wait_until { status == :playing }
+            frames = queue.pop(output.format, *num_frames)
 
-            if output.format != queue.format
+            if frames.nil?
+              # if we received no frames, it means the audio format changed
               output.format = queue.format
-              next # format changed, so we return nil
             end
 
-            queue.pop(*num_frames)
+            # frames is either nil, or an array of audio frames
+            frames
           end
         end
       end
@@ -99,13 +100,8 @@ module Hallon
     # a hash of (sample) rate, channels and (sample) type.
     def music_delivery(format, frames)
       @queue.synchronize do
-        if frames.none?
-          @queue.clear
-        elsif @queue.format != format
-          @queue.format = format
-        end
-
-        @queue.push(frames)
+        @queue.clear if frames.none?
+        @queue.push(format, frames)
       end
     end
 
@@ -134,6 +130,10 @@ module Hallon
         when :paused
           @driver.pause
         when :stopped
+          # TODO: even if we clear and stop here, the music_delivery
+          # callback might be waiting for ruby to allow it to callback,
+          # which will result in us getting old audio frames when we
+          # play the next song. I don’t have a good solution yet.
           @queue.clear
           @driver.stop
         else

data/lib/hallon/session.rb

@@ -76,6 +76,9 @@ module Hallon
 
     # Create a new Spotify session.
     #
+    # @example using a https-proxy
+    #   session = Hallon::Session.initialize(appkey, proxy: 'https://user@password:hostname')
+    #
     # @param [#to_s] appkey
     # @param [Hash] options
     # @option options [String] :user_agent ("Hallon") User-Agent to use (length < `256`)

data/lib/hallon/version.rb

@@ -3,5 +3,5 @@ module Hallon
   # Current release version of Hallon
   #
   # @see http://semver.org/
-  VERSION = [0, 17, 0].join('.')
+  VERSION = [0, 18, 0].join('.')
 end

data/spec/hallon/audio_queue_spec.rb

@@ -3,24 +3,37 @@ require 'timeout'
 
 describe Hallon::AudioQueue do
   let(:queue) { Hallon::AudioQueue.new(4) }
+  let(:format) { { :rate => 44100, :channels => 2, :type => :int16 } }
   subject { queue }
 
-  it "should conform to the example specification of its’ documentation" do
-    queue.push([1, 2]).should eq 2
-    queue.push([3]).should eq 1
-    queue.push([4, 5, 6]).should eq 1
-    queue.push([5, 6]).should eq 0
-    queue.pop(1).should eq [1]
-    queue.push([5, 6]).should eq 1
-    queue.pop.should eq [2, 3, 4, 5]
+  it "should conform to “filling the buffer” example" do
+    format = {:rate => 44100, :channels => 2, :type => :int16}
+    queue.push(format, [1, 2]).should eq 2
+    queue.push(format, [3]).should eq 1
+    queue.push(format, [4, 5, 6]).should eq 1
+    queue.push(format, [5, 6]).should eq 0
+    queue.pop(format, 1).should eq [1]
+    queue.push(format, [5, 6]).should eq 1
+    queue.pop(format).should eq [2, 3, 4, 5]
+  end
+
+  it "should conform to the “changing the format” example" do
+    queue  = Hallon::AudioQueue.new(4)
+    queue.format.should eq nil
+    queue.push(:initial_format, [1, 2, 3, 4, 5]).should eq 4
+    queue.size.should eq 4
+    queue.format.should eq :initial_format
+    queue.push(:new_format, [1, 2]).should eq 2
+    queue.size.should eq 2
+    queue.format.should eq :new_format
   end
 
   describe "#pop" do
     it "should not block if the queue is not empty" do
-      queue.push([1, 2])
+      queue.push(format, [1, 2])
 
       start = Time.now
-      queue.pop.should eq [1, 2]
+      queue.pop(format).should eq [1, 2]
       (Time.now - start).should be_within(0.001).of(0)
     end
 
@@ -29,15 +42,21 @@ describe Hallon::AudioQueue do
 
       # I could mock out ConditionVariable and Mutex, but where’s the fun in that?
       start = Time.now
-      Thread.start { sleep 0.2; queue.push([1]) }
-      queue.pop.should eq [1]
+      Thread.start { sleep 0.2; queue.push(format, [1]) }
+      queue.pop(format).should eq [1]
       (Time.now - start).should be_within(0.08).of(0.2)
     end
+
+    it "returns does nothing if the format does not match" do
+      queue.push(:one_format, [1, 2, 3, 4])
+      queue.pop(:another_format).should eq nil
+      queue.pop(:one_format).should eq [1, 2, 3, 4]
+    end
   end
 
   describe "#clear" do
     it "should clear the queue" do
-      queue.push([1, 2])
+      queue.push(format, [1, 2])
       queue.should_not be_empty
       queue.clear
       queue.should be_empty
@@ -45,17 +64,11 @@ describe Hallon::AudioQueue do
   end
 
   describe "#format" do
-    it "should clear the queue when setting the format" do
-      queue.push([1, 2])
-      queue.should_not be_empty
-      queue.format = :new_format
-      queue.should be_empty
-    end
-
-    it "should allow setting and retrieving the format" do
-      queue.format.should_not be :new_format
-      queue.format = :new_format
-      queue.format.should be :new_format
+    it "is determined by the format of the audio samples" do
+      queue.push(:one_format, [1, 2, 3])
+      queue.format.should eq :one_format
+      queue.push(:another_format, [4, 5, 6])
+      queue.format.should eq :another_format
     end
   end
 

data/spec/hallon/player_spec.rb

@@ -131,20 +131,16 @@ describe Hallon::Player do
       player.stop
     end
 
-    it "should not set the format on music delivery if it’s the same" do
-      queue.should_not_receive(:format=)
-      session.trigger(:music_delivery, queue.format, [1, 2, 3])
-    end
-
     it "should set the format on music delivery if format changes" do
-      queue.should_receive(:format=).with(:new_format)
+      queue.format.should_not eq :new_format
       session.trigger(:music_delivery, :new_format, [1, 2, 3])
+      queue.format.should eq :new_format
     end
 
     # why? it says so in the docs!
     it "should clear the audio queue when receiving 0 audio frames" do
       queue.should_receive(:clear)
-      session.trigger(:music_delivery, driver.format, [])
+      session.trigger(:music_delivery, queue.format, [])
     end
 
     context "the output streaming" do
@@ -152,7 +148,7 @@ describe Hallon::Player do
         Thread.stub(:start).and_return{ |*args, &block| block[*args] }
 
         player # create the Player
-        session.trigger(:music_delivery, queue.format, [1, 2, 3])
+        session.trigger(:music_delivery, driver.format, [1, 2, 3])
 
         # it should block while player is stopped
         begin
@@ -183,11 +179,10 @@ describe Hallon::Player do
         driver.stream.call.should eq [1, 2, 3]
       end
 
-      it "should set the format on initialization" do
+      it "should set the driver format on initialization" do
         Thread.stub(:start).and_return{ |*args, &block| block[*args] }
 
         AudioDriverMock.any_instance.should_receive(:format=)
-        Hallon::AudioQueue.any_instance.should_receive(:format=)
         player
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hallon
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.18.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-15 00:00:00.000000000 Z
+date: 2012-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ref
@@ -34,7 +34,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 12.0.2
+        version: 12.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -42,7 +42,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 12.0.2
+        version: 12.2.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -145,6 +145,7 @@ files:
 - dev/login.rb
 - examples/adding_tracks_to_playlist.rb
 - examples/example_support.rb
+- examples/nordic_ruby_2012.rb
 - examples/playing_audio.rb
 - examples/show_published_playlists_of_user.rb
 - hallon.gemspec
@@ -292,7 +293,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 995209467900648626
+      hash: 228682146525853245
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24