plaything 1.0.0 → 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3b370e69436137efbd0bb9964231b74bae9863a7
+  data.tar.gz: e8d93ef8632e8191f2be628a58618f04723e5cf6
+SHA512:
+  metadata.gz: 5026505b6b2650bbac2e3a644b10bdbbb78ff675a8c8b9d3c86ec9d33ab81ac5176b5596da5d117837546a99b6aadf4b455ff2630cdd53682c8a2e60cb4fb1bc
+  data.tar.gz: d5590baa1b903ea691266b1c38d9834ead39c9d669b01113f929055e730918afefbb4847ebbd73fd973b6e82016c4824662d9bd869dd4001107de3f11be488e0

data/README.md

@@ -1,6 +1,18 @@
 # Plaything
 
-Blast raw PCM audio through your speakers using OpenAL.
+> OpenAL is a cross-platform 3D audio API appropriate for use with gaming applications and many other types of audio applications.
+
+Plaything is tiny API wrapper around OpenAL, and makes it easy to play raw (PCM) streaming audio through your speakers.
+
+Plaything was initially written to support audio playback from the [spotify gem](http://rubygems.org/gems/spotify).
+
+
+
+## Note about the OpenAL bindings
+
+Plaything contains bindings to a subset of the OpenAL API, just enough to cover the necessary streaming functionality. With little further work, the OpenAL bindings could be extracted and further developed indepdendently of Plaything.
+
+Additionally, the OpenAL streaming source is retrievable from Plaything, and allows you to modify parameters on the playback source, such as pitch, gain, and anything else OpenAL allows you to change.
 
 ## License
 

data/lib/plaything.rb

@@ -1,3 +1,4 @@
+require "monitor"
 require "ffi"
 require "plaything/version"
 require "plaything/monkey_patches/ffi"
@@ -5,16 +6,33 @@ require "plaything/support"
 require "plaything/objects"
 require "plaything/openal"
 
+# Plaything is tiny API wrapper around OpenAL, and makes it easy to play raw
+# (PCM) streaming audio through your speakers.
+#
+# API consist of a few key methods available on the Plaything instance.
+#
+# - {#play}, {#pause}, {#stop} — controls source playback state. If the source
+#   runs out of audio to play, it will forcefully stop playback.
+# - {#position}, can be used to retrieve playback position.
+# - {#queue_size}, {#drops} — status information; should be used by the streaming
+#   source to improve playback experience.
+# - {#format=} — allows you to change format, even during playback.
+# - {#stream}, {#<<} — fills the audio buffers with PCM audio.
+#
+# Internally, Plaything will queue and unqueue buffers as they are played during
+# streaming. When a sufficient amount of audio has been fed into plaything, the
+# audio will be queued on the source and plaything can accept additional audio.
+#
+# Plaything is considered thread-safe.
 class Plaything
   Error = Class.new(StandardError)
+  Formats = {
+    [ :int16, 1 ] => :mono16,
+    [ :int16, 2 ] => :stereo16,
+  }
 
   # Open the default output device and prepare it for playback.
-  #
-  # @param [Hash] options
-  # @option options [Symbol] sample_type (:int16)
-  # @option options [Integer] sample_rate (44100)
-  # @option options [Integer] channels (2)
-  def initialize(options = { sample_type: :int16, sample_rate: 44100, channels: 2 })
+  def initialize(format = { sample_rate: 44100, sample_type: :int16, channels: 2 })
     @device  = OpenAL.open_device(nil)
     raise Error, "Failed to open device" if @device.null?
 
@@ -28,14 +46,6 @@ class Plaything
       @source = OpenAL::Source.new(ptr.read_uint)
     end
 
-    @sample_type = options.fetch(:sample_type)
-    @sample_rate = Integer(options.fetch(:sample_rate))
-    @channels    = Integer(options.fetch(:channels))
-
-    @sample_format = { [ :int16, 2 ] => :stereo16, }.fetch([@sample_type, @channels]) do
-      raise TypeError, "unknown sample format for type [#{@sample_type}, #{@channels}]"
-    end
-
     FFI::MemoryPointer.new(OpenAL::Buffer, 3) do |ptr|
       OpenAL.gen_buffers(ptr.count, ptr)
       @buffers = OpenAL::Buffer.extract(ptr, ptr.count)
@@ -45,103 +55,170 @@ class Plaything
     @queued_buffers = []
     @queued_frames = []
 
-    # 44100 int16s = 22050 frames = 0.5s (1 frame * 2 channels = 2 int16 = 1 sample = 1/44100 s)
-    @buffer_size  = @sample_rate * @channels * 1.0
-    # how many samples there are in each buffer, irrespective of channels
-    @buffer_length = @buffer_size / @channels
-    # buffer_duration = buffer_length / sample_rate
-
+    @drops = 0
     @total_buffers_processed = 0
+
+    @monitor = Monitor.new
+
+    self.format = format
   end
 
+  # @return [Plaything::OpenAL::Source] the back-end audio source.
+  attr_reader :source
+
   # Start playback of queued audio.
   #
   # @note You must continue to supply audio, or playback will cease.
   def play
-    OpenAL.source_play(@source)
+    synchronize { @source.play }
   end
 
   # Pause playback of queued audio. Playback will resume from current position when {#play} is called.
   def pause
-    OpenAL.source_pause(@source)
+    synchronize { @source.pause }
   end
 
   # Stop playback and clear any queued audio.
   #
   # @note All audio queues are completely cleared, and {#position} is reset.
   def stop
-    OpenAL.source_stop(@source)
-    @source.detach_buffers
-    @free_buffers.concat(@queued_buffers)
-    @queued_buffers.clear
-    @queued_frames.clear
-    @total_buffers_processed = 0
+    synchronize do
+      @source.stop
+      @source.detach_buffers
+      @free_buffers.concat(@queued_buffers)
+      @queued_buffers.clear
+      @queued_frames.clear
+      @total_buffers_processed = 0
+    end
   end
 
   # @return [Rational] how many seconds of audio that has been played.
   def position
-    Rational(@total_buffers_processed * @buffer_length + sample_offset, @sample_rate)
+    synchronize do
+      total_samples_processed = @total_buffers_processed * @buffer_length
+      Rational(total_samples_processed + @source.sample_offset, @sample_rate)
+    end
   end
 
   # @return [Integer] total size of current play queue.
   def queue_size
-    @source.get(:buffers_queued, Integer) * @buffer_length - sample_offset
+    synchronize do
+      @source.buffers_queued * @buffer_length - @source.sample_offset
+    end
   end
 
   # @return [Integer] how many audio drops since last call to drops.
   def drops
-    0
+    synchronize do
+      @drops.tap { @drops = 0 }
+    end
+  end
+
+  # @return [Hash] current audio format in the queues
+  def format
+    synchronize do
+      {
+        sample_rate: @sample_rate,
+        sample_type: @sample_type,
+        channels: @channels,
+      }
+    end
+  end
+
+  # Change the format.
+  #
+  # @note if there is any queued audio it will be cleared,
+  #       and the playback will be stopped.
+  #
+  # @param [Hash] format
+  # @option format [Symbol] sample_type only :int16 available
+  # @option format [Integer] sample_rate
+  # @option format [Integer] channels 1 or 2
+  def format=(format)
+    synchronize do
+      if @source.playing?
+        stop
+        @drops += 1
+      end
+
+      @sample_type = format.fetch(:sample_type)
+      @sample_rate = Integer(format.fetch(:sample_rate))
+      @channels    = Integer(format.fetch(:channels))
+
+      @sample_format = Formats.fetch([@sample_type, @channels]) do
+        raise TypeError, "unknown sample format for type [#{@sample_type}, #{@channels}]"
+      end
+
+      # 44100 int16s = 22050 frames = 0.5s (1 frame * 2 channels = 2 int16 = 1 sample = 1/44100 s)
+      @buffer_size  = @sample_rate * @channels * 1.0
+      # how many samples there are in each buffer, irrespective of channels
+      @buffer_length = @buffer_size / @channels
+      # buffer_duration = buffer_length / sample_rate
+    end
   end
 
   # Queue audio frames for playback.
   #
-  # @param [Array<[ Channels… ]>] frames array of N-sized arrays of integers.
+  # @note this method is here for backwards-compatibility,
+  #       and does not support changing format automatically.
+  #       You should use {#stream} instead.
+  #
+  # @param [Array<Integer>] array of interleaved audio samples.
+  # @return (see #stream)
   def <<(frames)
-    if buffers_processed > 0
-      FFI::MemoryPointer.new(OpenAL::Buffer, buffers_processed) do |ptr|
-        OpenAL.source_unqueue_buffers(@source, ptr.count, ptr)
-        @total_buffers_processed += ptr.count
-        @free_buffers.concat OpenAL::Buffer.extract(ptr, ptr.count)
-        @queued_buffers.delete_if { |buffer| @free_buffers.include?(buffer) }
+    stream(frames, format)
+  end
+
+  # Queue audio frames for playback.
+  #
+  # @param [Array<Integer>] array of interleaved audio samples.
+  # @param [Hash] format
+  # @option format [Symbol] :sample_type should be :int16
+  # @option format [Integer] :sample_rate
+  # @option format [Integer] :channels
+  # @return [Integer] number of frames consumed (consumed_samples / channels), a multiple of channels
+  def stream(frames, frame_format)
+    synchronize do
+      if @source.playing? and @source.buffers_processed > 0
+        FFI::MemoryPointer.new(OpenAL::Buffer, @source.buffers_processed) do |ptr|
+          OpenAL.source_unqueue_buffers(@source, ptr.count, ptr)
+          @total_buffers_processed += ptr.count
+          @free_buffers.concat OpenAL::Buffer.extract(ptr, ptr.count)
+          @queued_buffers.delete_if { |buffer| @free_buffers.include?(buffer) }
+        end
       end
-    end
 
-    wanted_size = (@buffer_size - @queued_frames.length).div(@channels) * @channels
-    consumed_frames = frames.take(wanted_size)
-    @queued_frames.concat(consumed_frames)
+      self.format = frame_format if frame_format != format
 
-    if @queued_frames.length >= @buffer_size and @free_buffers.any?
-      current_buffer = @free_buffers.shift
+      wanted_size = (@buffer_size - @queued_frames.length).div(@channels) * @channels
+      consumed_frames = frames.take(wanted_size)
+      @queued_frames.concat(consumed_frames)
 
-      FFI::MemoryPointer.new(@sample_type, @queued_frames.length) do |frames|
-        frames.public_send(:"write_array_of_#{@sample_type}", @queued_frames)
-        # stereo16 = 2 int16s (1 frame) = 1 sample
-        OpenAL.buffer_data(current_buffer, @sample_format, frames, frames.size, @sample_rate)
-        @queued_frames.clear
-      end
+      if @queued_frames.length >= @buffer_size and @free_buffers.any?
+        current_buffer = @free_buffers.shift
+
+        FFI::MemoryPointer.new(@sample_type, @queued_frames.length) do |frames|
+          frames.public_send(:"write_array_of_#{@sample_type}", @queued_frames)
+          # stereo16 = 2 int16s (1 frame) = 1 sample
+          OpenAL.buffer_data(current_buffer, @sample_format, frames, frames.size, @sample_rate)
+          @queued_frames.clear
+        end
+
+        FFI::MemoryPointer.new(OpenAL::Buffer, 1) do |buffers|
+          buffers.write_uint(current_buffer.to_native)
+          OpenAL.source_queue_buffers(@source, buffers.count, buffers)
+        end
 
-      FFI::MemoryPointer.new(OpenAL::Buffer, 1) do |buffers|
-        buffers.write_uint(current_buffer.to_native)
-        OpenAL.source_queue_buffers(@source, buffers.count, buffers)
+        @queued_buffers.push(current_buffer)
       end
 
-      @queued_buffers.push(current_buffer)
+      consumed_frames.length / @channels
     end
-
-    consumed_frames.length
   end
 
   protected
 
-  def sample_offset
-    @source.get(:sample_offset, Integer)
-  end
-
-  def buffers_processed
-    if not @source.stopped?
-      @source.get(:buffers_processed, Integer)
-    else
-      0
-    end
+  def synchronize
+    @monitor.synchronize { return yield }
   end
 end

data/lib/plaything/objects/buffer.rb

@@ -2,6 +2,10 @@ class Plaything
   module OpenAL
     class Buffer < TypeClass(FFI::Type::UINT)
       include OpenAL::Paramable(:buffer)
+
+      def self.extract(pointer, count)
+        count.times.map { |index| new pointer.get_uint(type.size * index) }
+      end
     end
   end
 end

data/lib/plaything/objects/source.rb

@@ -3,6 +3,37 @@ class Plaything
     class Source < TypeClass(FFI::Type::UINT)
       include OpenAL::Paramable(:source)
 
+      # Start playback.
+      def play
+        OpenAL.source_play(self)
+      end
+
+      # Pause playback.
+      def pause
+        OpenAL.source_pause(self)
+      end
+
+      # Stop playback and rewind the source.
+      def stop
+        OpenAL.source_stop(self)
+      end
+
+      # @return [Integer] how many samples (/ channels) that have been played from the queued buffers
+      def sample_offset
+        get(:sample_offset, Integer)
+      end
+
+      # @return [Integer] number of queued buffers.
+      def buffers_queued
+        get(:buffers_queued, Integer)
+      end
+
+      # @note returns {#buffers_queued} if source is not playing!
+      # @return [Integer] number of processed buffers.
+      def buffers_processed
+        get(:buffers_processed, Integer)
+      end
+
       # Detach all queued or attached buffers.
       #
       # @note all buffers must be processed for this operation to succeed.

data/lib/plaything/openal.rb

@@ -5,6 +5,8 @@ class Plaything
     ffi_lib ["openal", "/System/Library/Frameworks/OpenAL.framework/Versions/Current/OpenAL"]
 
     typedef :pointer, :attributes
+    typedef :pointer, :source_array
+    typedef :pointer, :buffer_array
     typedef :int, :sizei
 
     # Errors
@@ -61,15 +63,15 @@ class Plaything
     attach_function :alcMakeContextCurrent, [ Context ], :bool
 
     # Sources
-    attach_function :alGenSources, [ :sizei, :pointer ], :void
-    attach_function :alDeleteSources, [ :sizei, :pointer ], :void
+    attach_function :alGenSources, [ :sizei, :source_array ], :void
+    attach_function :alDeleteSources, [ :sizei, :source_array ], :void
 
     attach_function :alSourcePlay, [ Source ], :void
     attach_function :alSourcePause, [ Source ], :void
     attach_function :alSourceStop, [ Source ], :void
 
-    attach_function :alSourceQueueBuffers, [ Source, :sizei, :pointer ], :void
-    attach_function :alSourceUnqueueBuffers, [ Source, :sizei, :pointer ], :void
+    attach_function :alSourceQueueBuffers, [ Source, :sizei, :buffer_array ], :void
+    attach_function :alSourceUnqueueBuffers, [ Source, :sizei, :buffer_array ], :void
 
     # Buffers
     enum :format, [
@@ -78,8 +80,8 @@ class Plaything
       :stereo8, 0x1102,
       :stereo16, 0x1103,
     ]
-    attach_function :alGenBuffers, [ :sizei, :pointer ], :void
-    attach_function :alDeleteBuffers, [ :sizei, :pointer ], :void
+    attach_function :alGenBuffers, [ :sizei, :buffer_array ], :void
+    attach_function :alDeleteBuffers, [ :sizei, :buffer_array ], :void
 
     attach_function :alBufferData, [ Buffer, :format, :pointer, :sizei, :sizei ], :void
 

data/lib/plaything/support/managed_pointer.rb

@@ -13,13 +13,6 @@ class Plaything
         rescue => e
           warn "release for #{name} failed: #{e.message}."
         end
-
-        def allocate(*args, &block)
-          pointer = FFI::MemoryPointer.new(*args)
-          yield pointer
-          pointer.autorelease = false
-          new(FFI::Pointer.new(pointer))
-        end
       end
     end
   end

data/lib/plaything/support/type_class.rb

@@ -3,17 +3,16 @@ class Plaything
     def self.TypeClass(type)
       Class.new do
         extend FFI::DataConverter
-        @@type = type
+
+        define_singleton_method(:type) do
+          type
+        end
 
         class << self
           def inherited(other)
             other.native_type(type)
           end
 
-          def type
-            @@type
-          end
-
           def to_native(source, ctx)
             source.value
           end
@@ -25,12 +24,6 @@ class Plaything
           def size
             type.size
           end
-
-          def extract(pointer, count)
-            pointer.read_array_of_type(self, :read_uint, count).map do |uint|
-              new(uint)
-            end
-          end
         end
 
         def initialize(value)

data/lib/plaything/version.rb

@@ -1,3 +1,3 @@
 class Plaything
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,64 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: plaything
 version: !ruby/object:Gem::Version
-  prerelease: 
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Kim Burgestrand
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-26 00:00:00.000000000 Z
+date: 2013-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '1.1'
-    none: false
-  prerelease: false
   name: ffi
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.1'
-    none: false
   type: :runtime
-- !ruby/object:Gem::Dependency
+  prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
-    none: false
-  prerelease: false
+        version: '1.1'
+- !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-    none: false
   type: :development
-- !ruby/object:Gem::Dependency
+  prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-    none: false
-  prerelease: false
+- !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-    none: false
   type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - kim@burgestrand.se
@@ -90,30 +83,26 @@ files:
 homepage: https://github.com/Burgestrand/plaything
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '1.9'
-  none: false
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 2964046639458012733
-  none: false
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 2.0.3
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Blast raw PCM audio through your speakers using OpenAL.
 test_files:
 - spec/plaything_spec.rb