spotify 12.3.0 → 12.4.0

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+[HEAD][]
+-----------
+This release breaks backwards-compatibility, as functions will no
+longer accept pointers of any other type of what they expect. This
+means that you must wrap any pointers in a Spotify::ManagedPointer
+of the appropriate type before using them to call API functions.
+
+Callbacks now receive actual structs (by reference) in their params,
+instead of a pointer which needed to be manually casted.
+
+- [1fe1abed6] refactor retaining class for all managed pointer
+- [af54c02e1] **naive type-checking for all spotify objects**
+- [1d6939cd8] monkeypatch-add FFI::AbstractMemory#read_size_t
+- [b9ce8941c] unlock mutex for Spotify::Error.explain (considered thread-safe)
+- [fd2490728] add Spotify::Struct#to_s/to_h
+- [1cbaf4a64] **callbacks now receive structs by reference instead of raw pointer**
+
 [v12.3.0][]
 -----------
 Lots of internal and external changes. You could almost say it’s a rewrite.
@@ -147,6 +164,8 @@ v0.0.0
 ------
 - release to register rubygems.org name
 
+[HEAD]: https://github.com/Burgestrand/spotify/compare/v12.3.0...HEAD
+
 [v12.3.0]: https://github.com/Burgestrand/spotify/compare/v12.2.0...v12.3.0
 [v12.2.0]: https://github.com/Burgestrand/spotify/compare/v12.0.3...v12.2.0
 [v12.0.3]: https://github.com/Burgestrand/spotify/compare/v12.0.2...v12.0.3

data/Gemfile

@@ -4,3 +4,4 @@ gemspec
 gem 'pry'
 gem 'yard'
 gem 'redcarpet'
+gem "plaything", "~> 1.0"

data/README.markdown

@@ -17,12 +17,12 @@ The Spotify gem has:
 - [100% API coverage][], including callback support. You’ll be able to use any function from the libspotify library.
 - [Automatic garbage collection][]. Piggybacking on Ruby’s GC to manage pointer lifecycle.
 - [Parallell function call protection][]. libspotify is not thread-safe, but Spotify protects you.
-- [Type conversion][]. Special pointers for every Spotify type.
+- [Type conversion and type safety][]. Special pointers for every Spotify type, protecting you from accidental mix-ups.
 
 [100% API coverage]: http://rdoc.info/github/Burgestrand/spotify/master/Spotify/API
 [Automatic garbage collection]: http://rdoc.info/github/Burgestrand/spotify/master/Spotify/ManagedPointer
 [Parallell function call protection]: http://rdoc.info/github/Burgestrand/spotify/master/Spotify#method_missing-class_method
-[Type conversion]: http://rdoc.info/github/Burgestrand/spotify/master/Spotify/ManagedPointer
+[Type conversion and type safety]: http://rdoc.info/github/Burgestrand/spotify/master/Spotify/ManagedPointer
 
 The Spotify gem is aimed at experienced developers
 --------------------------------------------------
@@ -32,14 +32,15 @@ you can write using it. The Spotify gem itself, however, has very few opinions.
 
 Known supporting libraries:
 
-- [Hallon](https://github.com/Burgestrand/Hallon), the original. Currently Hallon is simply
-  a more convenient Spotify gem, written on top of the Spotify gem. It is diverging from its
-  previous path, now towards a more focused and opinionated framework. If you’re unsure of
-  what to use, start with the Hallon gem!
+- [Hallon](https://github.com/Burgestrand/Hallon). Hallon attempted to be a one-gem-does-all,
+  at a higher abstraction level than the Spotify gem. It features a slightly more convenient
+  API for certain things, and requires no ruby FFI knowledge, but it is not really an expert
+  on any use case.
 
-Do not let this stop you! Despite my harsh words the Spotify API is well suited for experimentation,
-and it can be awfully fun to play with. If you need any assitance feel free to post a message
-on the mailing list: [ruby-hallon@googlegroups.com][] (<https://groups.google.com/d/forum/ruby-hallon>).
+The Spotify API is well suited for experimentation, and it can be awfully fun to play with.
+The examples/ directory contains example code for achieving certain tasks with the Spotify gem.
+
+If you need any assitance feel free to post a message on the mailing list: [ruby-hallon@googlegroups.com][].
 
 Manually installing libspotify
 ------------------------------
@@ -63,7 +64,25 @@ Given a version `X.Y.Z`, each segment corresponds to:
 
 License
 -------
-X11 license, see the LICENSE document for details.
+Copyright (c) 2012 Kim Burgestrand <kim@burgestrand.se>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
 
 [semantic versioning (semver.org)]: http://semver.org/
 [ruby-hallon@googlegroups.com]: mailto:ruby-hallon@googlegroups.com

data/Rakefile

@@ -20,9 +20,16 @@ rescue LoadError
   puts "WARN: YARD not available. You may install documentation dependencies via bundler."
 end
 
+desc "Run code benchmarks"
+task :bench do
+  sh "ruby", "spec/bench_helper.rb"
+end
+
 desc "re-generate spec/api.h.xml"
 task :gen do
-  sh 'gccxml spec/api.h -fxml=spec/api.h.xml'
+  Dir["spec/support/api-*.h"].each do |header|
+    sh "gccxml", header, "-fxml=#{header.sub('.h', '.xml')}"
+  end
 end
 
 task :console do
@@ -31,11 +38,11 @@ end
 
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:test_mac) do |spec|
-  spec.ruby_opts = ['-r ./spec/mac-platform']
+  spec.ruby_opts = ['-r ./spec/support/mac-platform', '-W']
 end
 
 RSpec::Core::RakeTask.new(:test_linux) do |spec|
-  spec.ruby_opts = ['-r ./spec/linux-platform']
+  spec.ruby_opts = ['-r ./spec/support/linux-platform', '-W']
 end
 
 desc "Run the tests for both Linux and Mac OS"

data/examples/.gitignore

@@ -0,0 +1,4 @@
+spotify_appkey.key
+.spotify
+spotify_tracefile.txt
+Gemfile.lock

data/examples/README.md

@@ -0,0 +1,15 @@
+# How to run the examples:
+
+1. Install the dependencies. Preferrably via bundler with `bundle install`.
+2. Configure your environment variables SPOTIFY\_USERNAME, SPOTIFY\_PASSWORD.
+3. Download your binary application key from <https://developer.spotify.com/technologies/libspotify/keys/>.
+4. Put your `spotify_appkey.key` application key in the example directory.
+5. Run your specific example, e.g. `bundle exec ruby logging-in.rb`.
+
+## Available examples and what they do
+
+- **logging-in.rb**
+
+  a fairly small example on how you could login with the spotify API. It
+  has some callbacks to provide more information on what happens during
+  the process.

data/examples/audio-stream.rb

@@ -0,0 +1,170 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler/setup"
+require "spotify"
+require "logger"
+require "json"
+require "pry"
+require "plaything"
+
+Thread.abort_on_exception = true
+
+# We use a logger to print some information on when things are happening.
+$logger = Logger.new($stderr)
+$logger.level = Logger::INFO
+
+# libspotify supports callbacks, but they are not useful for waiting on
+# operations (how they fire can be strange at times, and sometimes they
+# might not fire at all). As a result, polling is the way to go.
+def poll(session)
+  until yield
+    FFI::MemoryPointer.new(:int) do |ptr|
+      Spotify.session_process_events(session, ptr)
+    end
+    sleep(0.1)
+  end
+end
+
+# For making sure fetching configuration options fail with a useful error
+# message when running the examples.
+def env(name)
+  ENV.fetch(name) do
+    raise "Missing ENV[#{name}]. Please: export #{name}=\"your value\""
+  end
+end
+
+def play_track(uri)
+  link = Spotify.link_create_from_string(uri)
+  track = Spotify.link_as_track(link)
+  poll($session) { Spotify.track_is_loaded(track) }
+  Spotify.try(:session_player_play, $session, false)
+  Spotify.try(:session_player_load, $session, track)
+  Spotify.try(:session_player_play, $session, true)
+end
+
+class FrameReader
+  include Enumerable
+
+  def initialize(channels, sample_type, frames_count, frames_ptr)
+    @channels = channels
+    @sample_type = sample_type
+    @size = frames_count * @channels
+    # strip type information, we work with bytes
+    @pointer = FFI::Pointer.new(frames_ptr)
+  end
+
+  attr_reader :size
+
+  def each
+    return enum_for(__method__) unless block_given?
+
+    ffi_read = :"get_#{@sample_type}"
+    ffi_size = FFI.type_size(@sample_type)
+
+    (0...size).each do |index|
+      yield @pointer.public_send(ffi_read, index * ffi_size)
+    end
+  end
+end
+
+plaything = Plaything.new
+
+#
+# Global callback procs.
+#
+# They are global variables to protect from ever being garbage collected.
+#
+# You must not allow the callbacks to ever be garbage collected, or libspotify
+# will hold information about callbacks that no longer exist, and crash upon
+# calling the first missing callback. This is *very* important!
+
+$session_callbacks = {
+  log_message: proc do |session, message|
+    $logger.info("session (log message)") { message }
+  end,
+
+  logged_in: proc do |session, error|
+    $logger.debug("session (logged in)") { Spotify::Error.explain(error) }
+  end,
+
+  logged_out: proc do |session|
+    $logger.debug("session (logged out)") { "logged out!" }
+  end,
+
+  streaming_error: proc do |session, error|
+    $logger.error("session (player)") { "streaming error %s" % Spotify::Error.explain(error) }
+  end,
+
+  start_playback: proc do |session|
+    $logger.debug("session (player)") { "start playback" }
+    plaything.play
+  end,
+
+  stop_playback: proc do |session|
+    $logger.debug("session (player)") { "stop playback" }
+    plaything.stop
+  end,
+
+  get_audio_buffer_stats: proc do |session, stats|
+    stats[:samples] = plaything.queue_size
+    stats[:stutter] = plaything.drops
+    $logger.debug("session (player)") { "queue size [#{stats[:samples]}, #{stats[:stutter]}]" }
+  end,
+
+  music_delivery: proc do |session, format, frames, num_frames|
+    if num_frames == 0
+      plaything.stop
+      $logger.debug("session (player)") { "music delivery audio discontuity" }
+    else
+      frames = FrameReader.new(format[:channels], format[:sample_type], num_frames, frames)
+      consumed_samples = plaything << frames
+      consumed_frames = consumed_samples / format[:channels]
+      $logger.debug("session (player)") { "music delivery #{consumed_frames} of #{num_frames}" }
+      consumed_frames
+    end
+  end,
+
+  end_of_track: proc do |session|
+    $end_of_track = true
+    $logger.debug("session (player)") { "end of track" }
+    plaything.stop
+  end,
+}
+
+#
+# Main work code.
+#
+
+# You can read about what these session configuration options do in the
+# libspotify documentation:
+# https://developer.spotify.com/technologies/libspotify/docs/12.1.45/structsp__session__config.html
+config = Spotify::SessionConfig.new({
+  api_version: Spotify::API_VERSION.to_i,
+  application_key: IO.read("./spotify_appkey.key"),
+  cache_location: ".spotify/",
+  settings_location: ".spotify/",
+  tracefile: "spotify_tracefile.txt",
+  user_agent: "spotify for ruby",
+  callbacks: Spotify::SessionCallbacks.new($session_callbacks),
+})
+
+$logger.info "Creating session."
+FFI::MemoryPointer.new(Spotify::Session) do |ptr|
+  Spotify.try(:session_create, config, ptr)
+  $session = Spotify::Session.new(ptr.read_pointer)
+end
+
+$logger.info "Created! Logging in."
+Spotify.session_login($session, env("SPOTIFY_USERNAME"), env("SPOTIFY_PASSWORD"), false, nil)
+
+$logger.info "Log in requested. Waiting forever until logged in."
+poll($session) { Spotify.session_connectionstate($session) == :logged_in }
+
+$logger.info "Logged in as #{Spotify.session_user_name($session)}."
+
+print "Spotify track URI: "
+play_track gets.chomp
+
+$logger.info "Playing track until end. Use ^C to exit."
+poll($session) { $end_of_track }

data/examples/logging-in.rb

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require 'spotify'
+require 'logger'
+
+# We use a logger to print some information on when things are happening.
+$logger = Logger.new($stderr)
+
+#
+# Some utility.
+#
+
+# This method is just for convenience. Calling the process_events function
+# is slightly cumbersome.
+def process_events(session)
+  FFI::MemoryPointer.new(:int) do |ptr|
+    Spotify.session_process_events(session, ptr)
+    return Rational(ptr.read_int, 1000)
+  end
+end
+
+# libspotify supports callbacks, but they are not useful for waiting on
+# operations (how they fire can be strange at times, and sometimes they
+# might not fire at all). As a result, polling is the way to go.
+def poll(session)
+  until yield
+    process_events(session)
+    sleep(0.01)
+  end
+end
+
+# For making sure fetching configuration options fail with a useful error
+# message when running the examples.
+def env(name)
+  ENV.fetch(name) do
+    raise "Missing ENV['#{name}']. Please: export #{name}='your value'"
+  end
+end
+
+#
+# Global callback procs.
+#
+# They are global variables to protect from ever being garbage collected.
+#
+# You must not allow the callbacks to ever be garbage collected, or libspotify
+# will hold information about callbacks that no longer exist, and crash upon
+# calling the first missing callback. This is *very* important!
+
+$session_callbacks = {
+  log_message: lambda do |session, message|
+    $logger.info('session (log message)') { message }
+  end,
+
+  logged_in: lambda do |session, error|
+    $logger.info('session (logged in)') { Spotify::Error.explain(error) }
+  end,
+
+  logged_out: lambda do |session|
+    $logger.info('session (logged out)') { 'logged out!' }
+  end,
+}
+
+#
+# Main work code.
+#
+
+# You can read about what these session configuration options do in the
+# libspotify documentation:
+# https://developer.spotify.com/technologies/libspotify/docs/12.1.45/structsp__session__config.html
+config = Spotify::SessionConfig.new({
+  api_version: Spotify::API_VERSION.to_i,
+  application_key: IO.read('./spotify_appkey.key'),
+  cache_location: ".spotify/",
+  settings_location: ".spotify/",
+  tracefile: "spotify_tracefile.txt",
+  user_agent: "spotify for ruby",
+  callbacks: Spotify::SessionCallbacks.new($session_callbacks),
+})
+
+$logger.info "Creating session."
+FFI::MemoryPointer.new(Spotify::Session) do |ptr|
+  # Spotify.try is a special method. It raises a ruby exception if the returned spotify
+  # error code is an error.
+  Spotify.try(:session_create, config, ptr)
+  $session = Spotify::Session.new(ptr.read_pointer)
+end
+
+$logger.info "Created! Logging in."
+Spotify.session_login($session, env('SPOTIFY_USERNAME'), env('SPOTIFY_PASSWORD'), false, nil)
+
+$logger.info "Log in requested. Waiting forever until logged in."
+poll($session) { Spotify.session_connectionstate($session) == :logged_in }
+
+$logger.info "Logged in as #{Spotify.session_user_name($session)}."

data/lib/spotify.rb

@@ -1,5 +1,6 @@
 # encoding: utf-8
 require 'ffi'
+require 'spotify/monkey_patches/ffi_pointer'
 require 'libspotify'
 require 'monitor'
 
@@ -28,7 +29,7 @@ module Spotify
     extend FFI::Library
 
     begin
-      ffi_lib [LIBSPOTIFY_BIN, 'libspotify', '/Library/Frameworks/libspotify.framework/libspotify']
+      ffi_lib [LIBSPOTIFY_BIN, 'spotify', 'libspotify', '/Library/Frameworks/libspotify.framework/libspotify']
     rescue LoadError
       puts <<-ERROR.gsub(/^ */, '')
         Failed to load the `libspotify` library. It is possible that the libspotify gem

data/lib/spotify/error.rb

@@ -4,6 +4,9 @@ module Spotify
     class << self
       # Explain a Spotify error with a descriptive message.
       #
+      # @note this method calls the API directly, since the
+      #       underlying API call is considered thread-safe.
+      #
       # @param [Symbol, Integer] error
       # @return [String] a decriptive string of the error
       def explain(error)
@@ -11,7 +14,7 @@ module Spotify
 
         message = []
         message << "[#{symbol.to_s.upcase}]"
-        message << Spotify.error_message(error)
+        message << Spotify::API.error_message(error)
         message << "(#{error})"
 
         message.join(' ')