hallon 0.12.0 → 0.13.0

data/lib/hallon/observable/session.rb

@@ -107,7 +107,11 @@ module Hallon::Observable
       format[:type] = struct[:sample_type]
 
       # read the frames of the given type
-      frames = frames.public_send("read_array_of_#{format[:type]}", num_frames * format[:channels])
+      frames = unless num_frames.zero?
+        frames.public_send("read_array_of_#{format[:type]}", num_frames * format[:channels])
+      else
+        [] # when seeking, for example, num_frames will be zero and frames will be nil
+      end
 
       # pass the frames to the callback, allowing it to do whatever
       consumed_frames = trigger(pointer, :music_delivery, format, frames.each_slice(format[:channels]))

data/lib/hallon/player.rb

@@ -1,9 +1,10 @@
 # coding: utf-8
+require 'monitor'
+
 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.
   # @see Session
   class Player
     # meep?
@@ -12,6 +13,9 @@ module Hallon
     # @return [Spotify::Pointer<Session>] session pointer
     attr_reader :pointer
 
+    # @return [Symbol] one of :playing, :paused, :stopped
+    attr_reader :status
+
     # @return [Array<Symbol>] a list of available playback bitrates.
     def self.bitrates
       Spotify.enum_type(:bitrate).symbols.sort_by do |sym|
@@ -20,46 +24,189 @@ module Hallon
       end
     end
 
-    # Constructs a Player, given a Session.
+    # Constructs a Player, given a Session and an audio driver.
     #
     # @example
-    #   Hallon::Player.new(session) do
-    #     on(:music_delivery) do |format, frames|
-    #     end
+    #   player = Hallon::Player.new(session, 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
+      @pointer = @session.pointer
+
+      # sample rate is often (if not always) 44.1KHz, so
+      # 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 }
+
+      # used for feeder thread to know if it should stream
+      # data to the driver or not (see #status=)
+      @status_c = @queue.new_cond
+      # set initial status (we assume stopped)
+      self.status = @status = :stopped
+
+      # this thread feeds the audio driver with data, but
+      # if we are not playing it’ll wait until we are
+      @thread = Thread.start(@driver, @queue, @status_c) do |output, queue, cond|
+        output.stream do |num_frames|
+          queue.synchronize do
+            cond.wait_until { status == :playing }
+
+            if output.format != queue.format
+              output.format = queue.format
+              next # format changed, so we return nil
+            end
+
+            queue.pop(*num_frames)
+          end
+        end
+      end
+
+      @session.on(:start_playback, &method(:start_playback))
+      @session.on(:stop_playback,  &method(:stop_playback))
+      @session.on(:music_delivery, &method(:music_delivery))
+      @session.on(:get_audio_buffer_stats, &method(:get_audio_buffer_stats))
+
+      @session.on(:end_of_track)    { |*args| trigger(:end_of_track, *args) }
+      @session.on(:streaming_error) { |*args| trigger(:streaming_error, *args) }
+      @session.on(:play_token_lost) { |*args| trigger(:play_token_lost, *args) }
+
+      instance_eval(&block) if block_given?
+    end
+
+    protected
+
+    # Called by libspotify when the driver should start audio playback.
     #
-    #     on(:start_playback) do
-    #     end
+    # Will be called after calling our buffers are full enough to support
+    # continous playback.
+    def start_playback(session)
+      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)
+      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)
+      @queue.synchronize do
+        if frames.none?
+          @queue.clear
+        elsif @queue.format != format
+          @queue.format = format
+        end
+
+        @queue.push(frames)
+      end
+    end
+
+    # 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)
+      drops = @driver.drops if @driver.respond_to?(:drops)
+      [@queue.size, drops.to_i]
+    end
+
+    # This is essentially a mini state machine. Setting the
+    # status will also put the driver in the correct mode, as
+    # well as allow audio data to stream through the feeder
+    # thread.
     #
-    #     on(:stop_playback) do
-    #     end
+    # @param [Symbol] status one of :playing, :paused, :stopped
+    # @raise [ArgumentError] if given an invalid status
+    def status=(status)
+      @queue.synchronize do
+        old_status, @status = @status, status
+
+        case status
+        when :playing
+          @driver.play
+        when :paused
+          @driver.pause
+        when :stopped
+          @queue.clear
+          @driver.stop
+        else
+          @status = old_status
+          raise ArgumentError, "invalid status"
+        end
+
+        @status_c.signal
+      end
+    end
+
+    public
+
+    # @note default output also shows all our instance variables, that
+    #       is kind of unnecessary and might take some time to display,
+    #       for example if the audio queue is full
+    # @return [String]
+    def to_s
+      name    = self.class.name
+      address = pointer.address.to_s(16)
+      "<#{name} session=0x#{address} driver=#{@driver.class} status=#{status}>"
+    end
+
+    # Start playing the currently loaded, or given, Track.
     #
-    #     on(:play_token_lost) do
-    #     end
+    # @example
+    #   player.play("spotify:track:44FHDONpdYeDpmqyS3BLRP")
     #
-    #     on(:end_of_track) do
-    #     end
+    # @note If no track is given, will try to play currently {#load}ed track.
+    # @param [Track, Link, String, nil] track
+    # @return [Player]
+    def play(track = nil)
+      load(track) unless track.nil?
+      tap { Spotify.session_player_play(pointer, true) }
+    end
+
+    # Pause playback of a Track.
     #
-    #     on(:streaming_error) do |error|
-    #     end
+    # @return nothing
+    def pause
+      self.status = :paused
+      Spotify.session_player_play(pointer, false)
+    end
+
+    # Stop playing current track and unload it.
     #
-    #     on(:buffer_size?) do
-    #       # return the pair of [samples, dropouts] of your audiobuffer
-    #     end
-    #   end
+    # @return nothing
+    def stop
+      self.status = :stopped
+      Spotify.session_player_unload(pointer)
+    end
+
+    # Like {#play}, but blocks until the track has finished playing.
     #
-    # @param [Session] session
-    # @yield instance_evals itself, allowing you to define callbacks using `on`
-    def initialize(session, &block)
-      instance_eval(&block) if block_given?
+    # @param (see #play)
+    # @return (see #play)
+    def play!(track = nil)
+      monitor = Monitor.new
+      condvar = monitor.new_cond
 
-      @session = session
-      @pointer = @session.pointer
+      monitor.synchronize do
+        end_of_track = false
+
+        on(:end_of_track) do
+          monitor.synchronize do
+            end_of_track = true
+            condvar.signal
+          end
+        end
 
-      %w[
-        start_playback stop_playback play_token_lost end_of_track
-        streaming_error get_audio_buffer_stats music_delivery
-      ].each do |cb|
-        @session.on(cb) { |*args| trigger(cb, *args) }
+        play(track)
+        condvar.wait_until { end_of_track }
       end
     end
 
@@ -73,15 +220,16 @@ module Hallon
 
     # Loads a Track for playing.
     #
-    # @param [Track] track
+    # @param [Track, Link, String] track
     # @return [Player]
     # @raise [Error] if the track could not be loaded
     def load(track)
+      track = Track.new(track) unless track.is_a?(Track)
       error = Spotify.session_player_load(pointer, track.pointer)
       tap { Error.maybe_raise(error) }
     end
 
-    # Prepares a Track for playing, without loading it.
+    # Prepares a Track for playing, without {#load}ing it.
     #
     # @note You can only prefetch if caching is on.
     # @param [Track] track
@@ -91,28 +239,6 @@ module Hallon
       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

data/lib/hallon/playlist.rb

@@ -6,6 +6,16 @@ module Hallon
   #
   # @see http://developer.spotify.com/en/libspotify/docs/group__playlist.html
   class Playlist < Base
+    # Enumerates through all tracks of a playlist.
+    class Tracks < Enumerator
+      size :playlist_num_tracks
+
+      # @return [Track, nil]
+      item :playlist_track! do |track, index, pointer|
+        Playlist::Track.from(track, pointer, index)
+      end
+    end
+
     # Playlist::Track is a {Track} with additional information attached to it,
     # that is specific to the playlist it was created from. The returned track
     # is a snapshot of the information, so even if the underlying track moves,
@@ -14,27 +24,28 @@ module Hallon
     # There is no way to refresh the information. You’ll have to retrieve the
     # track again.
     class Track < Hallon::Track
-      def initialize(pointer, playlist, index)
+      def initialize(pointer, playlist_pointer, index)
         super(pointer)
 
-        @index       = index
-        @playlist    = playlist
-        @create_time = Time.at Spotify.playlist_track_create_time(playlist.pointer, index)
-        @message     = Spotify.playlist_track_message(playlist.pointer, index)
-        @seen        = Spotify.playlist_track_seen(playlist.pointer, index)
-        @creator     = begin
-          creator = Spotify.playlist_track_creator!(playlist.pointer, index)
+        @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)
+        @seen         = Spotify.playlist_track_seen(playlist_ptr, index)
+        @creator      = begin
+          creator = Spotify.playlist_track_creator!(playlist_ptr, index)
           User.from(creator)
         end
       end
 
+      # @return [Spotify::Pointer<Playlist>] playlist pointer this track was created from.
+      attr_reader :playlist_ptr
+      private :playlist_ptr
+
       # @note this value never changes, even if the original track is moved/removed
       # @return [Integer] index this track was created with.
       attr_reader :index
 
-      # @return [Playlist] playlist this track was created from.
-      attr_reader :playlist
-
       # @return [Time] time when track at {#index} was added to playlist.
       attr_reader :create_time
 
@@ -44,6 +55,11 @@ module Hallon
       # @return [String] message attached to this track at {#index}.
       attr_reader :message
 
+      # @return [Playlist] playlist this track was created from.
+      def playlist
+        Playlist.new(playlist_ptr)
+      end
+
       # @see Playlist#seen
       # @return [Boolean] true if track at {#index} has been seen.
       def seen?
@@ -64,16 +80,16 @@ module Hallon
           raise IndexError, "track has moved from #{index}"
         end
 
-        error = Spotify.playlist_track_set_seen(playlist.pointer, index, !! seen)
+        error = Spotify.playlist_track_set_seen(playlist_ptr, index, !! seen)
         Error.maybe_raise(error)
-        @seen = Spotify.playlist_track_seen(playlist.pointer, index)
+        @seen = Spotify.playlist_track_seen(playlist_ptr, index)
       end
 
       # @return [Boolean] true if the track has not yet moved.
       def moved?
         # using non-GC version deliberately; no need to keep a reference to
         # this pointer once we’re done here anyway
-        Spotify.playlist_track(playlist.pointer, index) != pointer
+        Spotify.playlist_track(playlist_ptr, index) != pointer
       end
     end
 
@@ -229,7 +245,7 @@ module Hallon
     #
     # @return [Playlist]
     def update_subscribers
-      Spotify.playlist_update_subscribers(session.pointer, pointer)
+      tap { Spotify.playlist_update_subscribers(session.pointer, pointer) }
     end
 
     # @note only applicable if {#offline_status} is `:downloading`
@@ -253,12 +269,9 @@ module Hallon
     #   track = playlist.tracks[3]
     #   puts track.name
     #
-    # @return [Enumerable<Playlist::Track>] a list of playlist tracks.
+    # @return [Tracks] a list of playlist tracks.
     def tracks
-      Enumerator.new(size) do |index|
-        track = Spotify.playlist_track!(pointer, index)
-        Playlist::Track.from(track, self, index)
-      end
+      Tracks.new(self)
     end
 
     # Add a list of tracks to the playlist starting at given position.

data/lib/hallon/playlist_container.rb

@@ -1,4 +1,6 @@
 # coding: utf-8
+require 'ostruct'
+
 module Hallon
   # PlaylistContainers are the objects that hold playlists. Each User
   # in libspotify has a container for its’ starred and published playlists,
@@ -6,13 +8,58 @@ module Hallon
   #
   # @see http://developer.spotify.com/en/libspotify/docs/group__playlist.html
   class PlaylistContainer < Base
+    # Enumerates through all playlists and folders of a container.
+    class Contents < Enumerator
+      size :playlistcontainer_num_playlists
+
+      # @return [Playlist, Folder, nil]
+      item :playlistcontainer_playlist_type do |type, index, pointer|
+        case type
+        when :playlist
+          playlist = Spotify.playlistcontainer_playlist!(pointer, index)
+          Playlist.from(playlist)
+        when :start_folder, :end_folder
+          Folder.new(pointer, folder_range(index, type))
+        else # :unknown
+        end
+      end
+
+      protected
+
+      # Given an index, find out the starting point and ending point
+      # of the folder at that index.
+      #
+      # @param [Integer] index
+      # @param [Symbol] type
+      # @return [Range] begin..end
+      def folder_range(index, type)
+        id      = folder_id(index)
+        same_id = proc { |idx| folder_id(idx) == id }
+
+        case type
+        when :start_folder
+          beginning = index
+          ending    = (index + 1).upto(size - 1).find(&same_id)
+        when :end_folder
+          ending    = index
+          beginning = (index - 1).downto(0).find(&same_id)
+        end
+
+        if beginning and ending and beginning != ending
+          beginning..ending
+        end
+      end
+
+      # @return [Integer] folder ID of folder at `index`.
+      def folder_id(index)
+        Spotify.playlistcontainer_playlist_folder_id(pointer, index)
+      end
+    end
+
     # Folders are parts of playlist containers in that they surround playlists
     # with a beginning marker and an ending marker. The playlists between these
     # markers are considered "inside the playlist".
     class Folder
-      # @return [PlaylistContainer] playlistcontainer this folder was created from.
-      attr_reader :container
-
       # @return [Integer] index this folder starts at in the container.
       attr_reader :begin
 
@@ -25,6 +72,15 @@ module Hallon
       # @return [String]
       attr_reader :name
 
+      # @return [Spotify::Pointer<Container>]
+      attr_reader :container_ptr
+      private :container_ptr
+
+      # @return [PlaylistContainer] playlistcontainer this folder was created from.
+      def container
+        PlaylistContainer.new(container_ptr)
+      end
+
       # Rename the folder.
       #
       # @note libspotify has no actual folder rename; what happens is that
@@ -42,14 +98,14 @@ module Hallon
 
       # @param [PlaylistContainer] container
       # @param [Range] indices
-      def initialize(container, indices)
-        @container = container
-        @begin     = indices.begin
-        @end       = indices.end
+      def initialize(container_pointer, indices)
+        @container_ptr = container_pointer
 
-        @id   = Spotify.playlistcontainer_playlist_folder_id(container.pointer, @begin)
+        @begin = indices.begin
+        @end   = indices.end
+        @id    = Spotify.playlistcontainer_playlist_folder_id(container_ptr, @begin)
         FFI::Buffer.alloc_out(256) do |buffer|
-          error = Spotify.playlistcontainer_playlist_folder_name(container.pointer, @begin, buffer, buffer.size)
+          error = Spotify.playlistcontainer_playlist_folder_name(container_ptr, @begin, buffer, buffer.size)
           Error.maybe_raise(error) # should not fail, but just to be safe!
 
           @name = buffer.get_string(0)
@@ -59,20 +115,21 @@ module Hallon
       # @param [Folder] other
       # @return [Boolean] true if the two folders are the same (same indices, same id).
       def ==(other)
-        !! [:id, :container, :begin, :end].all? do |attr|
-          public_send(attr) == other.public_send(attr)
+        !! [:id, :container_ptr, :begin, :end].all? do |attr|
+          send(attr) == other.send(attr)
         end if other.is_a?(Folder)
       end
 
-      # @return [Enumerator<Playlist, Folder>] contents of this folder
+      # @return [Array<Playlist, Folder>] contents of this folder
       def contents
-        container.contents[(@begin + 1)..(@end - 1)]
+        container = OpenStruct.new(:pointer => container_ptr)
+        Contents.new(container)[(@begin + 1)..(@end - 1)]
       end
 
       # @return [Boolean] true if the folder has moved.
       def moved?
-        Spotify.playlistcontainer_playlist_folder_id(container.pointer, @begin) != id or
-        Spotify.playlistcontainer_playlist_folder_id(container.pointer, @end) != id
+        Spotify.playlistcontainer_playlist_folder_id(container_ptr, @begin) != id or
+        Spotify.playlistcontainer_playlist_folder_id(container_ptr, @end) != id
       end
     end
 
@@ -106,18 +163,9 @@ module Hallon
       Spotify.playlistcontainer_num_playlists(pointer)
     end
 
-    # @return [Enumerator<Playlist, Folder, nil>] an enumerator of folders and playlists.
+    # @return [Contents] an enumerator of folders and playlists.
     def contents
-      Enumerator.new(size) do |i|
-        case playlist_type(i)
-        when :playlist
-          playlist = Spotify.playlistcontainer_playlist!(pointer, i)
-          Playlist.new(playlist)
-        when :start_folder, :end_folder
-          Folder.new(self, folder_range(i))
-        else # :unknown
-        end
-      end
+      Contents.new(self)
     end
 
     # Add the given playlist to the end of the container.
@@ -185,12 +233,12 @@ module Hallon
     def remove(index)
       remove = proc { |idx| Spotify.playlistcontainer_remove_playlist(pointer, idx) }
 
-      error = case playlist_type(index)
+      error = case Spotify.playlistcontainer_playlist_type(pointer, index)
       when :start_folder, :end_folder
-        indices = folder_range(index)
+        folder = contents[index]
 
-        Error.maybe_raise(remove[indices.begin])
-        remove[indices.end - 1] # ^ everything moves down one step
+        Error.maybe_raise(remove[folder.begin])
+        remove[folder.end - 1] # ^ everything moves down one step
       else
         remove[index]
       end
@@ -245,39 +293,5 @@ module Hallon
         infront_of += 1 if from < infront_of
         Spotify.playlistcontainer_move_playlist(pointer, from, infront_of, dry_run)
       end
-
-      # Given an index, find out the starting point and ending point
-      # of the folder at that index.
-      #
-      # @param [Integer] index
-      # @return [Range] begin..end
-      def folder_range(index)
-        id      = folder_id(index)
-        type    = playlist_type(index)
-        same_id = proc { |idx| folder_id(idx) == id }
-
-        case type
-        when :start_folder
-          beginning = index
-          ending    = (index + 1).upto(size - 1).find(&same_id)
-        when :end_folder
-          ending    = index
-          beginning = (index - 1).downto(0).find(&same_id)
-        end
-
-        if beginning and ending and beginning != ending
-          beginning..ending
-        end
-      end
-
-      # @return [Symbol] playlist type
-      def playlist_type(index)
-        Spotify.playlistcontainer_playlist_type(pointer, index)
-      end
-
-      # @return [Integer] folder ID of folder at `index`.
-      def folder_id(index)
-        Spotify.playlistcontainer_playlist_folder_id(pointer, index)
-      end
   end
 end