hallon 0.12.0 → 0.13.0

data/CHANGELOG.md

@@ -1,6 +1,47 @@
 Hallon’s Changelog
 ==================
 
+[HEAD][]
+------------------
+
+__Added__
+
+__Changed__
+
+__Fixed__
+
+[v0.13.0][]
+------------------
+
+Hallon v0.13.0 brings support for using external audio drivers with
+the Hallon::Player API. The specification on how to write your own
+driver is in the README.
+
+An audio driver was also written as a separate gem:
+
+    https://rubygems.org/gems/hallon-openal
+
+__Added__
+
+- Linkable#to_str, all linkable objects can now easily be converted to a spotify URI [132981a9]
+- AudioQueue#clear/#synchronize/#new_cond (formerly Queue) [62bf4622, c2b14481, bb65cf28]
+- AudioQueue#format/format= [27084a3a]
+
+__Changed__
+
+- Rewritten Player API (now deals in audio drivers) [53cfac21]
+- Rewritten Enumerator system (Playlist#tracks, Search#albums et al) [676f7d1e]
+- Search#{tracks,albums,artists}_total removed in favor of Search#{tracks,albums,artists}.total [d5c2e7aa]
+- Image#== and Link#== [8a1e4a33]
+- Player#load now accepts a spotify uri [710baf34]
+- Renamed Queue to AudioQueue [c2b14481]
+- Error.mabe_raise no longer ignores :is_loading, and now takes an :ignores option [53ad65c8]
+
+__Fixed__
+
+- Enumerators now check size before each iteration [4ec24969]
+- Playlist#update_subscribers now returns the Playlist [86120836]
+
 [v0.12.0][]
 ------------------
 
@@ -217,3 +258,5 @@ easier to handle.
 [v0.10.1]: https://github.com/Burgestrand/Hallon/compare/v0.9.1...v0.10.1
 [v0.11.0]: https://github.com/Burgestrand/Hallon/compare/v0.10.1...v0.11.0
 [v0.12.0]: https://github.com/Burgestrand/Hallon/compare/v0.11.0...v0.12.0
+[v0.13.0]: https://github.com/Burgestrand/Hallon/compare/v0.12.0...v0.13.0
+[HEAD]: https://github.com/Burgestrand/Hallon/compare/v0.12.0...HEAD

data/Gemfile

@@ -4,4 +4,6 @@ gemspec
 gem 'ruby_parser'
 gem 'pry'
 gem 'cover_me', :platform => :ruby_19
-gem 'coreaudio' if RUBY_PLATFORM =~ /darwin/i
+gem 'coreaudio', :platform => :ruby_19 if RUBY_PLATFORM =~ /darwin/i
+gem 'hallon-openal'
+gem 'rb-readline'

data/README.markdown

@@ -1,9 +1,7 @@
 [What is Hallon?][] [![Build Status][]](http://travis-ci.org/Burgestrand/Hallon)
-===============
+===================
 
-We rubyists have this awesome [spotify gem][] allowing us to use [libspotify][] from within Ruby, but it has a significant drawback: the `libspotify` API is very hard to use. Now, we can’t have that, so what do we do? We make Hallon!
-
-Hallon is Swedish for “[Raspberry][]”, and has been written to satisfy my needs for API simplicity. Hallon is written on top of [Spotify for Ruby][], but with the goal of making the experience of using `libspotify` from Ruby much more enjoyable.
+Hallon — which is Swedish for “[Raspberry][]” — is a ruby gem for interacting with the official Spotify C API. It is written on top of [Spotify for Ruby][], with the goal of making the experience of using `libspotify` as enjoyable as it can be.
 
 Hallon would not have been possible if not for these people:
 
@@ -16,13 +14,42 @@ Also, these people are worthy of mention simply for their contribution:
 - Jesper Särnesjö, unknowingly providing me a starting point with [Greenstripes][]
 - Emil “@mrevilme” Palm, for his patience in helping me debug Hallon deadlock issues
 
-Code samples can be found under `examples/` directory.
+Code samples can be found under the `examples/` directory. An explanation on how to run them can be found on the [Hallon wiki on GitHub](https://github.com/Burgestrand/Hallon/wiki).
+
+Installation
+------------
+
+    gem install hallon
+
+If you want to play audio you’ll need to install an audio driver. As of current writing there is only one driver in existence. You can install it with:
+
+    gem install hallon-openal
+
+For more information about audio support in Hallon, see the section "Audio support" below.
+
+Audio support
+-------------
+Hallon supports streaming audio from Spotify via [Hallon::Player][]. When you create the player you give it your current session and an audio driver, which the player will then use for audio playback.
+
+```ruby
+player = Hallon::Player.new(session, Hallon::OpenAL)
+player.play(loaded_track)
+```
+
+Available drivers are:
+
+- [Hallon::OpenAL](https://rubygems.org/gems/hallon-openal)
+
+        gem install hallon-openal
+
+For information on how to write your own audio driver, see [Hallon::ExampleAudioDriver].
 
 You have any questions?
 -----------------------
-If you need to discuss issues or feature requests you can use [Hallons issue tracker](http://github.com/Burgestrand/Hallon/issues). For *anything* else you have to say or ask I can also be reached via [email (found on GitHub profile)](http://github.com/Burgestrand) or [@burgestrand on twitter](http://twitter.com/Burgestrand).
+I can be reached at my [email (found on GitHub profile)](http://github.com/Burgestrand) or [@burgestrand on twitter](http://twitter.com/Burgestrand). I’d be extremely happy to discuss Hallon with
+you if you have any feedback or thoughts.
 
-In fact, you can contact me via email or twitter even if it’s about features or issues. I’ll probably put them in the issue tracker myself after the discussion ;)
+For issues and feature requests, please use use [Hallons issue tracker](http://github.com/Burgestrand/Hallon/issues).
 
 This is awesome! I want to help!
 --------------------------------
@@ -34,20 +61,20 @@ Sweet! You contribute in more than one way!
 ### [Send me feedback and requests](http://github.com/Burgestrand/Hallon/issues)
 Really, I ❤ feedback! Suggestions on how to improve the API, tell me what is delicious about Hallon, tell me what is yucky about Hallon… anything! All feedback is useful in one way or another.
 
-Finally, here’s some important notes
-------------------------------------
+Finally, here are some important notes
+--------------------------------------
 
 ### Hallon is unstable
 The API is unstable, my code is likely unstable. Everything should be considered unstable!
 
 ### Hallon only supports one session per process
-You can only keep one session with Spotify alive at a time in the same process, due to a limitation of `libspotify`.
+You can only keep one session with Spotify alive at a time within the same process, due to a limitation of `libspotify`.
 
 ### You still have to worry about threads
 I have been doing my best at hiding the complexity in `libspotify`, but it’s still a work in progress. Despite my efforts, you’ll need to be familiar with concurrent programming to use Hallon properly.
 
 ### When forking, you need to be extra careful
-If you fork, you need to instantiate the session in the process you plan to use Hallon in. You want to use Hallon in the parent? Create the session in the parent. You want to use it in the child? Create the session in the child! This is a limitation of libspotify itself.
+If you fork, you need to instantiate the session within the process you plan to use Hallon in. You want to use Hallon in the parent? Create the session in the parent. You want to use it in the child? Create the session in the child! This is a limitation of libspotify itself.
 
 Versioning policy
 -----------------
@@ -66,3 +93,6 @@ Hallon is licensed under a 2-clause (Simplified) BSD license. More information c
 [Greenstripes]:     http://github.com/sarnesjo/greenstripes
 [What is Hallon?]:  http://burgestrand.se/articles/hallon-delicious-ruby-bindings-to-libspotify.html
 [Build Status]:     https://secure.travis-ci.org/Burgestrand/Hallon.png
+
+[Hallon::Player]:             http://rubydoc.info/github/Burgestrand/Hallon/Hallon/Player
+[Hallon::ExampleAudioDriver]: http://rubydoc.info/github/Burgestrand/Hallon/Hallon/ExampleAudioDriver

data/Rakefile

@@ -110,6 +110,18 @@ task 'spotify:coverage' do
     [method, "#{method}!"]
   end
 
+  # Hallon::Enumerator
+  no_receiver[:size] = proc do |recv, meth, (_, name)|
+    name.value if name.respond_to?(:value)
+  end
+
+  # Hallon::Enumerator
+  no_receiver[:item] = proc do |recv, meth, (_, name)|
+    next unless name.respond_to?(:value)
+    method = name.value.to_s
+    [method.delete("!"), method]
+  end
+
   fails = {}
   FileList['lib/**/*.rb'].each do |file|
     begin

data/examples/audio_driver.rb

@@ -0,0 +1,55 @@
+# coding: utf-8
+require 'monitor'
+
+begin
+  require 'coreaudio'
+rescue LoadError
+  abort <<-ERROR
+    This example requires the ruby-coreaudio gem.
+
+    See: http://rubygems.org/gems/coreaudio
+  ERROR
+end
+
+puts <<-INFO
+**************************************************************
+
+  Keep in mind, you’re now using the CoreAudio driver, part
+  of Hallon examples. This driver does not buffer data, so
+  even the slightest hickup in Ruby will make the playback
+  stutter. The reason is that this CoreAudio driver does not
+  buffer data internally.
+
+**************************************************************
+INFO
+
+module Hallon
+  class CoreAudio
+    attr_reader :output
+    protected :output
+
+    def initialize(format)
+      @device = ::CoreAudio.default_output_device
+      @output = @device.output_buffer(format[:rate] * 3)
+      @format = format
+    end
+
+    attr_accessor :format
+
+    def stream
+      loop { output << yield }
+    end
+
+    def play
+      output.start
+    end
+
+    def stop
+      output.stop
+    end
+
+    def pause
+      output.stop
+    end
+  end
+end

data/examples/playing_audio.rb

@@ -2,22 +2,20 @@
 
 $LOAD_PATH.unshift(File.expand_path('../lib', File.dirname(__FILE__)))
 
+require 'bundler/setup'
 require 'hallon'
-require_relative '../spec/support/config'
 
 begin
-  require 'coreaudio'
+  require 'hallon/openal'
 rescue LoadError
-  abort <<-ERROR
-    This example requires the ruby-coreaudio gem.
-
-    See: http://rubygems.org/gems/coreaudio
-  ERROR
+  require_relative 'audio_driver'
 end
 
+require_relative '../spec/support/config'
+
 # Utility
 def say(string)
-  system('say', string)
+  # system('say', string)
 end
 
 def tell(string)
@@ -34,16 +32,7 @@ end
 
 # Hallon set-up.
 
-sample_rate = 44100 # 44100 samples / second
-device      = CoreAudio.default_output_device
-output      = device.output_buffer(sample_rate * 3)
-audio_queue = Hallon::Queue.new(sample_rate)
-
 session = Hallon::Session.initialize IO.read(ENV['HALLON_APPKEY']) do
-  on(:log_message) do |message|
-    puts "[LOG] #{message}"
-  end
-
   on(:connection_error) do |error|
     Hallon::Error.maybe_raise(error)
   end
@@ -53,31 +42,8 @@ session = Hallon::Session.initialize IO.read(ENV['HALLON_APPKEY']) do
   end
 end
 
-end_of_track = false
-player = Hallon::Player.new(session) do
-  on(:music_delivery) do |format, frames|
-    audio_queue.push(frames)
-  end
-
-  on(:start_playback) do
-    puts "(start playback)"
-    output.start
-  end
-
-  on(:stop_playback) do
-    puts "(stop playback)"
-    output.stop
-  end
-
-  on(:get_audio_buffer_stats) do
-    [audio_queue.size, 0]
-  end
-
-  on(:end_of_track) do
-    puts "End of track!"
-    end_of_track = true
-  end
-end
+driver = defined?(Hallon::OpenAL) ? Hallon::OpenAL : Hallon::CoreAudio
+player = Hallon::Player.new(session, driver)
 
 # Program flow.
 
@@ -89,7 +55,7 @@ search = loop do
 
   tell "Searching for “#{search.query}”…"
   session.wait_for do
-    search.loaded? or Hallon::Error.maybe_raise(search.status)
+    search.loaded? or Hallon::Error.maybe_raise(search.status, ignore: :is_loading)
   end
 
   if search.tracks.size.zero?
@@ -119,12 +85,6 @@ track = loop do
   end
 end
 
-player.play(track)
-
 tell "Alright! Playing “#{track.name}” by “#{track.artist.name}”."
-
-until end_of_track
-  output << audio_queue.pop(sample_rate)
-end
-
+player.play!(track)
 tell "Done! This was “#{track.name}” by “#{track.artist.name}”. Bye bye!"

data/hallon.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |gem|
 
   gem.version     = Hallon::VERSION
   gem.platform    = Gem::Platform::RUBY
-  gem.required_ruby_version = '~> 1.8'
+  gem.required_ruby_version = '>= 1.9'
 
   gem.add_dependency 'ref', '~> 1.0'
   gem.add_dependency 'spotify', '~> 10.3.0'

data/lib/hallon.rb

@@ -9,8 +9,8 @@ require 'hallon/linkable'
 require 'hallon/version'
 require 'hallon/error'
 require 'hallon/base'
-require 'hallon/queue'
 require 'hallon/enumerator'
+require 'hallon/audio_queue'
 
 require 'hallon/observable/album_browse'
 require 'hallon/observable/artist_browse'

data/lib/hallon/album_browse.rb

@@ -7,6 +7,24 @@ module Hallon
   # @see Album
   # @see http://developer.spotify.com/en/libspotify/docs/group__albumbrowse.html
   class AlbumBrowse < Base
+    # Enumerates through all copyright notices of an album browsing object.
+    class Copyrights < Enumerator
+      size :albumbrowse_num_copyrights
+
+      # @return [String, nil]
+      item :albumbrowse_copyright
+    end
+
+    # Enumerates through all tracks of an album browsing object.
+    class Tracks < Enumerator
+      size :albumbrowse_num_tracks
+
+      # @return [Track, nil]
+      item :albumbrowse_track! do |track|
+        Track.from(track)
+      end
+    end
+
     extend Observable::AlbumBrowse
 
     # Creates an AlbumBrowse instance from an Album or an Album pointer.
@@ -65,21 +83,14 @@ module Hallon
       Rational(duration, 1000) if duration > 0
     end
 
-    # @return [Enumerator<String>] list of copyright notices.
+    # @return [Copyrights] enumerator of copyright notices.
     def copyrights
-      size = Spotify.albumbrowse_num_copyrights(pointer)
-      Enumerator.new(size) do |i|
-        Spotify.albumbrowse_copyright(pointer, i)
-      end
+      Copyrights.new(self)
     end
 
-    # @return [Enumerator<Track>] list of tracks.
+    # @return [Tracks] enumerator of tracks.
     def tracks
-      size = Spotify.albumbrowse_num_tracks(pointer)
-      Enumerator.new(size) do |i|
-        track = Spotify.albumbrowse_track!(pointer, i)
-        Track.new(track)
-      end
+      Tracks.new(self)
     end
   end
 end

data/lib/hallon/artist_browse.rb

@@ -5,6 +5,56 @@ module Hallon
   # @see Artist
   # @see http://developer.spotify.com/en/libspotify/docs/group__artistbrowse.html
   class ArtistBrowse < Base
+    # Enumerates through all portrait images of an artist browsing object.
+    class Portraits < Enumerator
+      size :artistbrowse_num_portraits
+
+      # @return [Image, nil]
+      item :artistbrowse_portrait do |portrait|
+        Image.new(portrait)
+      end
+    end
+
+    # Enumerates through all portrait links of an artist browsing object.
+    class PortraitLinks < Enumerator
+      size :artistbrowse_num_portraits
+
+      # @return [Link, nil]
+      item :link_create_from_artistbrowse_portrait! do |portrait|
+        Link.from(portrait)
+      end
+    end
+
+    # Enumerates through all tracks of an artist browsing object.
+    class Tracks < Enumerator
+      size :artistbrowse_num_tracks
+
+      # @return [Track, nil]
+      item :artistbrowse_track! do |track|
+        Track.from(track)
+      end
+    end
+
+    # Enumerates through all albums of an artist browsing object.
+    class Albums < Enumerator
+      size :artistbrowse_num_albums
+
+      # @return [Album, nil]
+      item :artistbrowse_album! do |album|
+        Album.from(album)
+      end
+    end
+
+    # Enumerates through all similar artists of an artist browsing object.
+    class SimilarArtists < Enumerator
+      size :artistbrowse_num_similar_artists
+
+      # @return [Artist, nil]
+      item :artistbrowse_similar_artist! do |artist|
+        Artist.from(artist)
+      end
+    end
+
     extend Observable::ArtistBrowse
 
     # @return [Array<Symbol>] artist browsing types for use in {#initialize}
@@ -63,48 +113,29 @@ module Hallon
       Rational(duration, 1000) if duration > 0
     end
 
-    # Retrieve artist portraits as an {Image} or a {Link}.
-    #
-    # @param [Boolean] as_image true if you want an enumerator of Images (false for Links)
-    # @return [Enumerator<Image>, Enumerator<Link>] artist portraits.
-    def portraits(as_image = true)
-      size = Spotify.artistbrowse_num_portraits(pointer)
-      Enumerator.new(size) do |i|
-        if as_image
-          id = Spotify.artistbrowse_portrait(pointer, i)
-          Image.new(id)
-        else
-          link = Spotify.link_create_from_artistbrowse_portrait!(pointer, i)
-          Link.new(link)
-        end
-      end
+    # @return [Portraits] artist portraits as {Image}s.
+    def portraits
+      Portraits.new(self)
+    end
+
+    # @return [PortraitImages] artist portraits as {Link}s.
+    def portrait_links
+      PortraitLinks.new(self)
     end
 
-    # @return [Enumerator<Track>] artist authored tracks.
+    # @return [Tracks] artist authored tracks.
     def tracks
-      size = Spotify.artistbrowse_num_tracks(pointer)
-      Enumerator.new(size) do |i|
-        track = Spotify.artistbrowse_track!(pointer, i)
-        Track.new(track)
-      end
+      Tracks.new(self)
     end
 
-    # @return [Enumerator<Album>] artist authored albums.
+    # @return [Albums] artist authored albums.
     def albums
-      size = Spotify.artistbrowse_num_albums(pointer)
-      Enumerator.new(size) do |i|
-        album = Spotify.artistbrowse_album!(pointer, i)
-        Album.new(album)
-      end
+      Albums.new(self)
     end
 
-    # @return [Enumartor<Artist>] similar artists to this artist.
+    # @return [SimilarArtists] similar artists to this artist.
     def similar_artists
-      size = Spotify.artistbrowse_num_similar_artists(pointer)
-      Enumerator.new(size) do |i|
-        artist = Spotify.artistbrowse_similar_artist!(pointer, i)
-        Artist.new(artist)
-      end
+      SimilarArtists.new(self)
     end
   end
 end