hallon 0.12.0 → 0.13.0

data/lib/hallon/audio_driver.rb

@@ -0,0 +1,138 @@
+# coding: utf-8
+module Hallon
+  # This is an implementation of a fictionary audio driver for Hallon. Each method is
+  # documented with expectations, parameters and other details. This class should serve
+  # as a guide on how to write your own audio driver with Hallon.
+  #
+  # @note this class is not used by Hallon, and is only here for documentation purposes.
+  class ExampleAudioDriver
+    # Here you can do your initialization of your audio driver. No
+    # parameters are given, and at this point no information of the
+    # audio format (or similar) is given.
+    def initialize
+    end
+
+    # Called when the audio playback should start. ie. when buffered
+    # audio previously retrieved from #stream should start blasting
+    # from the speakers.
+    #
+    # This method is only called as a direct result of the libspotify
+    # `start_playback` callback. It is recommended for this method to
+    # be thread-safe.
+    #
+    # Once called, audio playback is expected continue until either
+    # {#pause} or {#stop} is called.
+    #
+    # It is very important that this method does not block!
+    #
+    # Return value is ignored.
+    def play
+    end
+
+    # Called when the audio playback should be paused; often this is
+    # called as a direct result of {Player#pause}.
+    #
+    # It may also be called if the audio is stuttering, to allow spotify
+    # to buffer up more data before continuing playback. Because of this,
+    # this method is recommended to be thread-safe.
+    #
+    # It is very important that this method does not block!
+    #
+    # Return value is ignored.
+    def pause
+    end
+
+    # Called when audio playback should be stopped. Audio buffers can
+    # be cleared and any grip around the users’ speakers should also
+    # be released.
+    #
+    # This is only ever called as a direct result of the user manually
+    # stopping the player with {Player#stop}.
+    #
+    # Return value is ignored.
+    def stop
+    end
+
+    # Sets the current audio format.
+    #
+    # This is only ever called from inside the block given to {#stream}. It
+    # should be safe to recreate any existing audio buffers to fit the new
+    # audio format, as no frames will be delivered to the audio driver before
+    # this call returns.
+    #
+    # @note see `Spotify.enum_type(:sampletype).symbols` for a list of possible sample types
+    # @param [Hash] new_format
+    # @option new_format [Integer] :rate sample rate (eg. 44100)
+    # @option new_format [Integer] :channels number of audio channels (eg. 2)
+    # @option new_format [Symbol] :type sample type (eg. :int16)
+    def format=(new_format)
+      @format = new_format
+    end
+
+    # This method is expected to return the currently set format, which
+    # has been previously set by {#format=}.
+    #
+    # The player will only ever call this after previously setting the
+    # format through {#format=}.
+    #
+    # It is important that this always returns the same value that was
+    # given to {#format=}!
+    def format
+      @format
+    end
+
+    # Called *once* by the player, to initiate audio streaming to this driver.
+    # This method is expected to run indefinitely, and is run inside a separate
+    # thread.
+    #
+    # It is given a block that takes an integer as an argument, which specifies
+    # how many audio frames the player may give the driver for audio playback.
+    # If the block is given no arguments, the audio driver is expected to be able
+    # to consume any number of audio frames for the given call.
+    #
+    # When the audio driver is ready to consume audio, it should yield to the given
+    # block. If it can take only a finite number of audio frames it should be specified
+    # in the parameter.
+    #
+    # Upon yielding to the given block, the player will:
+    #
+    # - if the player is currently not playing, wait until it is
+    # - inspect the format of the audio driver
+    # - if the format has changed, set the new format on the driver __and return nil__
+    # - if the format has not changed, return an array of audio frames
+    #
+    # The number of frames returned upon yielding will be less than or equal to
+    # the number of frames requested when calling yield.
+    #
+    # The format of the audio frames can be determined by inspecting {#format} once
+    # the yield has returned. It is safe to inspect this format at any point within
+    # this method.
+    #
+    # The audio frames is a ruby array, grouped by channels. So for 2-channeled audio
+    # the returned array from a yield will look similar to this:
+    #
+    #     [[1239857, -123087], [34971, 123084], …]
+    #
+    # Also see the implementation for this method on a more concise explanation.
+    #
+    # @yield [num_frames] to retrieve audio frames for playback buffering
+    # @yieldparam [Integer] num_frames maximum number of frames that should be returned
+    # @yieldreturn [Array<[]>, nil] an array of audio frames, or nil if audio format has changed
+    def stream
+      loop do
+        # set up internal buffers for current @format
+        loop do
+          # calculate size of internal buffers
+          audio_data = yield(4048) # can only take 4048 frames of 2-channeled int16ne data
+
+          if audio_data.nil?
+            # audio format has changed, reinitialize buffers
+            break
+          else
+            # playback the audio data
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hallon/audio_queue.rb

@@ -0,0 +1,110 @@
+# coding: utf-8
+require 'monitor'
+
+module Hallon
+  # Hallon::AudioQueue is a non-blocking (well, not entirely) sized FIFO queue.
+  #
+  # You initialize the queue with a `max_size`, and then push data to it.
+  # For every push operation, the AudioQueue will tell you how much of your data
+  # it could consume. If the queue becomes full, it won’t accept any more
+  # data (and will return 0 on the #push operation) until you pull some data
+  # out of it with #pop.
+  #
+  # Hallon::AudioQueue is useful for handling {Hallon::Observable::Session#music_delivery_callback}.
+  #
+  # @example
+  #   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]
+  #
+  # @private
+  class AudioQueue
+    attr_reader :max_size
+
+    # @param [Integer] max_size
+    def initialize(max_size)
+      @max_size = max_size
+      @samples  = []
+
+      @samples.extend(MonitorMixin)
+      @condvar  = @samples.new_cond
+    end
+
+    # @param [#take] data
+    # @return [Integer] how much of the data that was added to the queue
+    def push(samples)
+      synchronize do
+        can_accept  = max_size - size
+        new_samples = samples.take(can_accept)
+
+        @samples.concat(new_samples)
+        @condvar.signal
+
+        new_samples.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)
+      synchronize do
+        @condvar.wait_while { empty? }
+        @samples.shift(num_samples)
+      end
+    end
+
+    # @return [Integer] number of samples in buffer.
+    def size
+      synchronize { @samples.size }
+    end
+
+    # @return [Boolean] true if the queue has a {#size} of 0.
+    def empty?
+      size.zero?
+    end
+
+    # 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
+    end
+
+    # Returns the format previously set by #format=.
+    attr_reader :format
+
+    # Use this if you wish to perform multiple operations on
+    # the AudioQueue atomicly.
+    #
+    # @note this lock is re-entrant, you can nest it in itself
+    # @yield exclusive section around the queue contents
+    # @return whatever the given block returns
+    def synchronize
+      @samples.synchronize { return yield }
+    end
+
+    # Create a condition variable bound to this AudioQueue.
+    # Should be used if you want to wait inside {#synchronize}.
+    #
+    # @return [MonitorMixin::ConditionVariable]
+    # @see monitor.rb (ruby stdlib)
+    def new_cond
+      @samples.new_cond
+    end
+  end
+end

data/lib/hallon/enumerator.rb

@@ -8,29 +8,66 @@ module Hallon
   class Enumerator
     include Enumerable
 
-    # @return [Integer] number of items this enumerator can yield
-    attr_reader :size
+    # @return [Spotify::Pointer]
+    attr_reader :pointer
 
-    # Construct an enumerator of `size` elements.
+    # @macro [attach] size
+    #   @method size
+    #   @return [Integer] size of this enumerator
     #
-    # @param [Integer] size
-    # @yield to the given block when an item is requested (through #each, #[] etc)
-    # @yieldparam [Integer] index item to retrieve
-    def initialize(size, &yielder)
-      @size  = size
-      @items = Array.new(size) do |i|
-        lambda { yielder[i] }
+    # @param [String, Symbol] method
+    def self.size(method)
+      # this method is about twice as fast as define_method/public_send
+      class_eval <<-SIZE, __FILE__, __LINE__ + 1
+        def size
+          Spotify.#{method}(pointer)
+        end
+      SIZE
+    end
+
+    # @example modifying result with a block
+    #   item :playlist_track! do |track|
+    #     Track.from(track)
+    #   end
+    #
+    # @note block passed is used to modify return value from Spotify#item_method
+    # @param [Symbol, String] method
+    # @yield [item, index, pointer] item from calling Spotify#item_method
+    # @yieldparam item
+    # @yieldparam [Integer] index
+    # @yieldparam [Spotify::Pointer] pointer
+    #
+    # @macro [attach] item
+    #   @method at(index)
+    def self.item(method, &block)
+      define_method(:at) do |index|
+        item = Spotify.public_send(method, pointer, index)
+        item = instance_exec(item, index, pointer, &block) if block_given?
+        item
       end
     end
 
+    # initialize the enumerator with `subject`.
+    #
+    # @param [#pointer] subject
+    def initialize(subject)
+      @pointer = subject.pointer
+    end
+
     # Yield each item out of the enumerator.
     #
     # @yield obj
-    # @return [Enumerator]
+    # @return [Enumerator] self
     def each
-      tap do
-        size.times { |i| yield(self[i]) }
+      index = 0
+
+      # check size on each iteration, in case it changes
+      while index < size
+        yield self[index]
+        index += 1
       end
+
+      self
     end
 
     # @overload [](index)
@@ -46,14 +83,16 @@ module Hallon
     #
     # @see http://rdoc.info/stdlib/core/1.9.2/Array:[]
     def [](*args)
-      result = @items[*args]
+      # crazy inefficient, but also crazy easy, don’t hate me :(
+      items  = [*0...size]
+      result = items[*args]
 
       if result.nil?
         nil
       elsif result.respond_to?(:map)
-        result.map(&:call)
+        result.map { |index| at(index) }
       else
-        result.call
+        at(result)
       end
     end
 

data/lib/hallon/error.rb

@@ -46,10 +46,17 @@ module Hallon
 
       # Raise an {Error} with the given errno, unless it is `nil`, `:timeout`, `0` or `:ok`.
       #
+      # @example
+      #
+      #   Hallon::Error.maybe_raise(error, ignore: :is_loading)
+      #
       # @param [Fixnum, Symbol] error
+      # @param [Hash] options
+      # @option options [Array] :ignore ([]) other values to ignore of error
       # @return [nil]
-      def maybe_raise(x)
-        return nil if [nil, :timeout, :is_loading].include?(x)
+      def maybe_raise(x, options = {})
+        ignore = [nil, :timeout] + Array(options[:ignore])
+        return nil if ignore.include?(x)
 
         error, symbol = disambiguate(x)
         return symbol if symbol == :ok

data/lib/hallon/image.rb

@@ -69,13 +69,14 @@ module Hallon
       end
     end
 
-    # @see Base#==
+    # Overridden to first and foremost compare by id if applicable.
+    #
     # @param [Object] other
-    # @return [Boolean] true if the images are the same object or have the same ID.
+    # @return [Boolean]
     def ==(other)
-      super or id(true) == other.id(true)
-    rescue NoMethodError, ArgumentError
-      false
+      super or if other.is_a?(Image)
+        id(true) == other.id(true)
+      end
     end
 
     protected

data/lib/hallon/link.rb

@@ -65,12 +65,15 @@ module Hallon
       "http://open.spotify.com/%s" % to_str[8..-1].gsub(':', '/')
     end
 
+    # Compare the Link to other. If other is a Link, also compare
+    # their `to_str` if necessary.
+    #
     # @param [Object] other
-    # @return [Boolean] true if this link equals `other.to_str`.
+    # @return [Boolean]
     def ==(other)
-      to_str == other.to_str
-    rescue NoMethodError
-      super
+      super or if other.is_a?(Link)
+        to_str == other.to_str
+      end
     end
 
     # @return [String] string representation of the Link.

data/lib/hallon/linkable.rb

@@ -100,5 +100,32 @@ module Hallon
 
     private :from_link
     private :to_link
+
+    def self.extended(other)
+      other.send(:include, InstanceMethods)
+    end
+
+    module InstanceMethods
+      # Converts the Linkable first to a Link, and then that link to a String.
+      #
+      # @note Returns an empty string if the #to_link call fails.
+      # @return [String]
+      def to_str
+        link = to_link
+        link &&= link.to_str
+        link.to_s
+      end
+
+      # Compare the Linkable to other. If other is a Linkable, also
+      # compare their `to_link` if necessary.
+      #
+      # @param [Object] other
+      # @return [Boolean]
+      def ===(other)
+        super or if other.respond_to?(:to_link)
+          to_link == other.to_link
+        end
+      end
+    end
   end
 end

data/lib/hallon/observable/player.rb

@@ -8,6 +8,23 @@ module Hallon::Observable
       other.send(:include, Hallon::Observable)
     end
 
-    include Hallon::Observable::Session
+    protected
+
+    # @return nil
+    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.
+    def end_of_track_callback(session)
+    end
+
+    # Dummy callback. See Session#streaming_error_callback.
+    def streaming_error_callback(session, error)
+    end
+
+    # Dummy callback. See Session#play_token_lost_callback.
+    def play_token_lost_callback(session)
+    end
   end
 end