plaything 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,3 @@
+-Ilib
+--color
+--require ./spec/spec_helper

data/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "pry"

data/README.md

@@ -0,0 +1,28 @@
+# Plaything
+
+Blast raw PCM audio through your speakers using OpenAL.
+
+## License
+
+Copyright (c) 2013 Kim Burgestrand
+
+MIT License
+
+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.

data/Rakefile

@@ -0,0 +1,14 @@
+begin
+  require "bundler/gem_tasks"
+
+  task :console do
+    exec "pry", "-rbundler/setup", "-rplaything"
+  end
+rescue LoadError
+  # don't need bundler for dev
+end
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:default) do |spec|
+  spec.ruby_opts = %w[-W]
+end

data/lib/plaything.rb

@@ -0,0 +1,147 @@
+require "ffi"
+require "plaything/version"
+require "plaything/monkey_patches/ffi"
+require "plaything/support"
+require "plaything/objects"
+require "plaything/openal"
+
+class Plaything
+  Error = Class.new(StandardError)
+
+  # 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 })
+    @device  = OpenAL.open_device(nil)
+    raise Error, "Failed to open device" if @device.null?
+
+    @context = OpenAL.create_context(@device, nil)
+    OpenAL.make_context_current(@context)
+    OpenAL.distance_model(:none)
+    OpenAL.listenerf(:gain, 1.0)
+
+    FFI::MemoryPointer.new(OpenAL::Source, 1) do |ptr|
+      OpenAL.gen_sources(ptr.count, ptr)
+      @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)
+    end
+
+    @free_buffers = @buffers.clone
+    @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
+
+    @total_buffers_processed = 0
+  end
+
+  # Start playback of queued audio.
+  #
+  # @note You must continue to supply audio, or playback will cease.
+  def play
+    OpenAL.source_play(@source)
+  end
+
+  # Pause playback of queued audio. Playback will resume from current position when {#play} is called.
+  def pause
+    OpenAL.source_pause(@source)
+  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
+  end
+
+  # @return [Rational] how many seconds of audio that has been played.
+  def position
+    Rational(@total_buffers_processed * @buffer_length + sample_offset, @sample_rate)
+  end
+
+  # @return [Integer] total size of current play queue.
+  def queue_size
+    @source.get(:buffers_queued, Integer) * @buffer_length - sample_offset
+  end
+
+  # @return [Integer] how many audio drops since last call to drops.
+  def drops
+    0
+  end
+
+  # Queue audio frames for playback.
+  #
+  # @param [Array<[ Channels… ]>] frames array of N-sized arrays of integers.
+  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) }
+      end
+    end
+
+    wanted_size = (@buffer_size - @queued_frames.length).div(@channels) * @channels
+    consumed_frames = frames.take(wanted_size)
+    @queued_frames.concat(consumed_frames)
+
+    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
+
+      @queued_buffers.push(current_buffer)
+    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
+  end
+end

data/lib/plaything/monkey_patches/ffi.rb

@@ -0,0 +1,7 @@
+require "ffi"
+
+class FFI::AbstractMemory
+  def count
+    size.div(type_size)
+  end
+end

data/lib/plaything/objects.rb

@@ -0,0 +1,4 @@
+require "plaything/objects/device"
+require "plaything/objects/context"
+require "plaything/objects/source"
+require "plaything/objects/buffer"

data/lib/plaything/objects/buffer.rb

@@ -0,0 +1,7 @@
+class Plaything
+  module OpenAL
+    class Buffer < TypeClass(FFI::Type::UINT)
+      include OpenAL::Paramable(:buffer)
+    end
+  end
+end

data/lib/plaything/objects/context.rb

@@ -0,0 +1,12 @@
+class Plaything
+  module OpenAL
+    class Context < ManagedPointer
+      def self.release(context)
+        super do |pointer|
+          OpenAL.make_context_current(nil)
+          OpenAL.destroy_context(context)
+        end
+      end
+    end
+  end
+end

data/lib/plaything/objects/device.rb

@@ -0,0 +1,9 @@
+class Plaything
+  module OpenAL
+    class Device < ManagedPointer
+      def self.release(device)
+        super { |pointer| OpenAL.close_device(device) }
+      end
+    end
+  end
+end

data/lib/plaything/objects/source.rb

@@ -0,0 +1,30 @@
+class Plaything
+  module OpenAL
+    class Source < TypeClass(FFI::Type::UINT)
+      include OpenAL::Paramable(:source)
+
+      # Detach all queued or attached buffers.
+      #
+      # @note all buffers must be processed for this operation to succeed.
+      # @note all buffers are considered processed when {#stopped?}.
+      def detach_buffers
+        set(:buffer, 0)
+      end
+
+      # @return [Symbol] :initial, :paused, :playing, :stopped
+      def state
+        get(:source_state)
+      end
+
+      # @return [Boolean] true if source is in stopped state.
+      def stopped?
+        state == :stopped
+      end
+
+      # @return [Boolean] true if source is in stopped state.
+      def playing?
+        state == :playing
+      end
+    end
+  end
+end

data/lib/plaything/openal.rb

@@ -0,0 +1,164 @@
+class Plaything
+  module OpenAL
+    extend FFI::Library
+
+    ffi_lib ["openal", "/System/Library/Frameworks/OpenAL.framework/Versions/Current/OpenAL"]
+
+    typedef :pointer, :attributes
+    typedef :int, :sizei
+
+    # Errors
+    Error = Class.new(StandardError)
+
+    enum :error, [
+      :no_error, 0,
+      :invalid_name, 0xA001,
+      :invalid_enum, 0xA002,
+      :invalid_value, 0xA003,
+      :invalid_operation, 0xA004,
+      :out_of_memory, 0xA005,
+    ]
+    attach_function :get_error, :alGetError, [ ], :error
+
+    # Overridden for three purposes.
+    #
+    # 1. Allows us to only supply OpenAL name, and converts it to snake_case
+    #    for attaching the function.
+    # 2. Wraps the call in an error-raise checker.
+    # 3. Creates a bang method that does not do automatic error checking.
+    def self.attach_function(c_name, params, returns, options = {})
+      ruby_name = c_name
+        .to_s
+        .sub(/\Aalc?/, "")
+        .gsub(/(?<!\A)\p{Lu}/u, '_\0')
+        .downcase
+      bang_name = "#{ruby_name}!"
+
+      super(ruby_name, c_name, params, returns, options)
+      alias_method(bang_name, ruby_name)
+
+      define_method(ruby_name) do |*args, &block|
+        get_error # clear error
+        public_send(bang_name, *args, &block).tap do
+          error = get_error
+          unless error == :no_error
+            raise Error, "#{ruby_name} failed with #{error}"
+          end
+        end
+      end
+
+      module_function ruby_name
+      module_function bang_name
+    end
+
+    # Devices
+    attach_function :alcOpenDevice, [ :string ], Device
+    attach_function :alcCloseDevice, [ Device ], :bool
+
+    # Context
+    attach_function :alcCreateContext, [ Device, :attributes ], Context
+    attach_function :alcDestroyContext, [ Context ], :void
+    attach_function :alcMakeContextCurrent, [ Context ], :bool
+
+    # Sources
+    attach_function :alGenSources, [ :sizei, :pointer ], :void
+    attach_function :alDeleteSources, [ :sizei, :pointer ], :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
+
+    # Buffers
+    enum :format, [
+      :mono8, 0x1100,
+      :mono16, 0x1101,
+      :stereo8, 0x1102,
+      :stereo16, 0x1103,
+    ]
+    attach_function :alGenBuffers, [ :sizei, :pointer ], :void
+    attach_function :alDeleteBuffers, [ :sizei, :pointer ], :void
+
+    attach_function :alBufferData, [ Buffer, :format, :pointer, :sizei, :sizei ], :void
+
+    # Parameters
+    enum :parameter, [
+      :none, 0x0000,
+
+      :source_relative, 0x0202,
+
+      :cone_inner_angle, 0x1001,
+      :cone_outer_angle, 0x1002,
+      :pitch, 0x1003,
+      :position, 0x1004,
+      :direction, 0x1005,
+      :velocity, 0x1006,
+      :looping, 0x1007,
+      :buffer, 0x1009,
+      :gain, 0x100A,
+      :min_gain, 0x100D,
+      :max_gain, 0x100E,
+      :orientation, 0x100F,
+
+      :source_state, 0x1010,
+      :initial, 0x1011,
+      :playing, 0x1012,
+      :paused, 0x1013,
+      :stopped, 0x1014,
+      :buffers_queued, 0x1015,
+      :buffers_processed, 0x1016,
+
+      :reference_distance, 0x1020,
+      :rolloff_factor, 0x1021,
+      :cone_outer_gain, 0x1022,
+      :max_distance, 0x1023,
+      :sec_offset, 0x1024,
+      :sample_offset, 0x1025,
+      :byte_offset, 0x1026,
+      :source_type, 0x1027,
+
+      :frequency, 0x2001,
+      :bits, 0x2002,
+      :channels, 0x2003,
+      :size, 0x2004,
+      :unused, 0x2010,
+      :pending, 0x2011,
+      :processed, 0x2012,
+
+      :distance_model, 0xD000,
+      :inverse_distance, 0xD001,
+      :inverse_distance_clamped, 0xD002,
+      :linear_distance, 0xD003,
+      :linear_distance_clamped, 0xD004,
+      :exponent_distance, 0xD005,
+      :exponent_distance_clamped, 0xD006,
+    ]
+
+    ## Utility
+    attach_function :alGetEnumValue, [ :string ], :int
+
+    enum_type(:parameter).to_h.each do |name, value|
+      real_name  = "AL_#{name.to_s.upcase}"
+      real_value = get_enum_value(real_name)
+      if real_value != -1 && value != real_value
+        raise NameError, "#{name} has value #{value}, should be #{real_value}"
+      end
+    end
+
+    ## Listeners
+    attach_function :alListenerf, [ :parameter, :float ], :void
+
+    ## Sources
+    attach_function :alSourcei, [ Source, :parameter, :int ], :void
+    attach_function :alGetSourcei, [ Source, :parameter, :pointer ], :void
+
+    ## Sources
+    attach_function :alBufferi, [ Buffer, :parameter, :int ], :void
+    attach_function :alGetBufferi, [ Buffer, :parameter, :pointer ], :void
+
+    # Global params
+    attach_function :alDistanceModel, [ :parameter ], :void
+  end
+end

data/lib/plaything/support.rb

@@ -0,0 +1,3 @@
+require "plaything/support/managed_pointer"
+require "plaything/support/type_class"
+require "plaything/support/paramable"

data/lib/plaything/support/managed_pointer.rb

@@ -0,0 +1,26 @@
+class Plaything
+  module OpenAL
+    class ManagedPointer < FFI::AutoPointer
+      class << self
+        def release(pointer)
+          if pointer.null?
+            warn "Trying to release NULL #{name}."
+          elsif block_given?
+            yield pointer
+          else
+            warn "No releaser for #{name}."
+          end
+        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
+end

data/lib/plaything/support/paramable.rb

@@ -0,0 +1,42 @@
+class Plaything
+  module OpenAL
+    def self.Paramable(type)
+      Module.new do
+        define_method(:al_type) do
+          type
+        end
+
+        def set(parameter, value)
+          type = if value.is_a?(Integer)
+            OpenAL.public_send(:"#{al_type}i", self, parameter, value)
+          elsif value.is_a?(Float)
+            OpenAL.public_send(:"#{al_type}f", self, parameter, value)
+          else
+            raise TypeError, "invalid type of #{value}, must be int or float"
+          end
+        end
+
+        def get(parameter, type = :enum)
+          name = if type == Integer
+            :i
+          elsif type == Float
+            :f
+          elsif type == :enum
+            :i
+          else
+            raise TypeError, "unknown type #{type}"
+          end
+
+          reader = { f: :float, i: :int }.fetch(name)
+
+          FFI::MemoryPointer.new(reader) do |ptr|
+            OpenAL.public_send(:"get_#{al_type}#{name}", self, parameter, ptr)
+            value = ptr.public_send(:"read_#{reader}")
+            value = OpenAL.enum_type(:parameter)[value] if type == :enum
+            return value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plaything/support/type_class.rb

@@ -0,0 +1,53 @@
+class Plaything
+  module OpenAL
+    def self.TypeClass(type)
+      Class.new do
+        extend FFI::DataConverter
+        @@type = type
+
+        class << self
+          def inherited(other)
+            other.native_type(type)
+          end
+
+          def type
+            @@type
+          end
+
+          def to_native(source, ctx)
+            source.value
+          end
+
+          def from_native(value, ctx)
+            new(value)
+          end
+
+          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)
+          @value = value
+        end
+
+        def ==(other)
+          other.is_a?(self.class) and other.value == value
+        end
+
+        def to_native
+          self.class.to_native(self, nil)
+        end
+
+        attr_reader :value
+      end
+    end
+  end
+end
+

data/lib/plaything/version.rb

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

data/plaything.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+require File.expand_path("./lib/plaything/version", File.dirname(__FILE__))
+
+Gem::Specification.new do |spec|
+  spec.name          = "plaything"
+  spec.summary       = "Blast raw PCM audio through your speakers using OpenAL."
+
+  spec.homepage      = "https://github.com/Burgestrand/plaything"
+  spec.authors       = ["Kim Burgestrand"]
+  spec.email         = ["kim@burgestrand.se"]
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.version       = Plaything::VERSION
+  spec.required_ruby_version = ">= 1.9"
+
+  spec.add_dependency "ffi", "~> 1.1"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rake"
+end

data/spec/plaything_spec.rb

@@ -0,0 +1,5 @@
+describe "Plaything" do
+  specify "VERSION is defined" do
+    defined?(Plaything::VERSION).should eq "constant"
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require "plaything"

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: plaything
+version: !ruby/object:Gem::Version
+  prerelease: 
+  version: 1.0.0
+platform: ruby
+authors:
+- Kim Burgestrand
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-26 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
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  prerelease: false
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  type: :development
+- !ruby/object:Gem::Dependency
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  prerelease: false
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+    none: false
+  type: :development
+description: 
+email:
+- kim@burgestrand.se
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- README.md
+- Rakefile
+- lib/plaything.rb
+- lib/plaything/monkey_patches/ffi.rb
+- lib/plaything/objects.rb
+- lib/plaything/objects/buffer.rb
+- lib/plaything/objects/context.rb
+- lib/plaything/objects/device.rb
+- lib/plaything/objects/source.rb
+- lib/plaything/openal.rb
+- lib/plaything/support.rb
+- lib/plaything/support/managed_pointer.rb
+- lib/plaything/support/paramable.rb
+- lib/plaything/support/type_class.rb
+- lib/plaything/version.rb
+- plaything.gemspec
+- spec/plaything_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/Burgestrand/plaything
+licenses:
+- MIT
+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
+signing_key: 
+specification_version: 3
+summary: Blast raw PCM audio through your speakers using OpenAL.
+test_files:
+- spec/plaything_spec.rb
+- spec/spec_helper.rb