audio 0 → 0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e3138318ed37af8b4a5921015231c48d82a86fc6
-  data.tar.gz: 02d940091ca420f1f33d9e0bd308b438187e1575
+  metadata.gz: 3f7750670a7a9f4d0554765012808dbe2f6477c9
+  data.tar.gz: a9e49107f1c2d316f416ecacc9a0f4ede1df1e66
 SHA512:
-  metadata.gz: 5caac54e7891da34d0641eb8fa953cc3b151a7fab0fd044e0f4b82abbc55c2edd21a066829f86384899cc6570a73ce4925585fb15b1f7b823deb253218aa5936
-  data.tar.gz: 4a3356fa7fdf3b7633d990b54274a43010078c6bed9aaed84d2e799ab4d45e7b2dbd5b402a34fdd8c1d45297e7154bacebc70572a06abd072b893f33b6303cc6
+  metadata.gz: 8a813230ad12d52963266b54ab57dfef88728af3fc6b6883bc19a1c71b783e9fcae205b2f06dfcecb2f06869e91185dfb2c47c2defbdec07d286b61c2a8ab414
+  data.tar.gz: a6dbf92c29fbce40913e41e099f549b9f314e1c7bed5f50eeaf73f2d79a73a41cf847b94e870c609cc0bc71bb2029d7cddbf21d081d43e9e100a7e148902c6bb

data/README.md

@@ -1,6 +1,62 @@
 # Audio
 
-TODO: Write a gem description
+'Audio' is a cross-platform audio device interface that allows you to read and
+write audio streams from the comfort and safety of Ruby.
+
+## Cross-Platform Status
+
+Currently, only support for OS X has been implemented. Support for Windows and
+Linux will be added in the future. If you feel like working on either of those,
+I'm more than happy to take Pull Requests!
+
+## Usage
+
+### Listing Available Audio Devices
+
+The Audio module provides a method that retrieves a list of all of the audio
+devices available on your system.
+
+```ruby
+require 'audio'
+
+devices = Audio.devices	    # => An Array of Device objects
+```
+
+Each Device object has attributes that wrap the various properties provided by
+the host operating system. For example, to get a list of device names...
+
+```ruby
+Audio.devices.each do |device|
+    puts "Device Name: #{device.device_name}"
+end
+```
+
+Running that on a MacBook Pro (late 2013), with a single external microphone 
+connected, produces...
+
+```
+Device Name: Built-in Microphone
+Device Name: Built-in Output
+Device Name: Blue Snowball
+```
+
+### Recording Audio
+
+You can record audio from a particular device by calling its `start` method.
+Once started, the device will continue recording until its `stop` method is
+called. If you provide a block parameter to `start`, it will be called whenever
+the host OS provides a new buffer of audio samples.
+
+```ruby
+device = Audio.devices.last     # Hopefully that's an input device
+device.start do |*args|
+    # Do something fancy
+end
+
+sleep 5	    # Record 5 seconds of audio
+
+device.stop
+```
 
 ## Installation
 
@@ -18,14 +74,7 @@ Or install it yourself as:
 
     $ gem install audio
 
-## Usage
-
-TODO: Write usage instructions here
-
-## Contributing
+License
+-------
 
-1. Fork it ( https://github.com/[my-github-username]/audio/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+Copyright 2015 Brandon Fosdick <bfoz@bfoz.net> and released under the BSD license.

data/audio.gemspec

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
     spec.name          = "audio"
-    spec.version       = '0'
+    spec.version       = '0.1'
     spec.authors       = ["Brandon Fosdick"]
     spec.email         = ["bfoz@bfoz.net"]
     spec.summary       = %q{Cross-platform Audio Device Input and Output}

data/lib/audio.rb

@@ -1,3 +1,8 @@
+require_relative 'core_audio'
+
 module Audio
-  # Your code goes here...
+    # @return [Array<Device>]  the list of available audio devices
+    def self.devices
+	CoreAudio.devices
+    end
 end

data/lib/core_audio.rb

@@ -0,0 +1,54 @@
+require 'ffi'
+
+module CoreAudio
+    extend FFI::Library
+    ffi_lib '/System/Library/Frameworks/CoreAudio.framework/CoreAudio'
+
+    typedef :uint32, :OSStatus
+
+    # @group CoreAudioTypes.h
+    class AudioBuffer < FFI::Struct
+	layout :mNumberChannels, :uint32,
+	       :mDataByteSize, :uint32,
+	       :mData, :pointer
+
+	# @return [String]  the raw bytes
+	def bytes
+	    self[:mData].get_bytes(0, self[:mDataByteSize])
+	end
+    end
+
+    class AudioBufferList < FFI::Struct
+	layout :mNumberBuffers, :uint32,
+	       :mBuffers, AudioBuffer
+    end
+    # @endgroup
+end
+
+require_relative 'core_audio/audio_device'
+
+module CoreAudio
+    # AudioHardware.h
+    # OSStatus AudioObjectGetPropertyDataSize(AudioObjectID			inObjectID,
+    #					      const AudioObjectPropertyAddress* inAddress,
+    #					      UInt32                            inQualifierDataSize,
+    #					      const void*                       inQualifierData,
+    #					      UInt32*                           outDataSize)
+    attach_function :AudioObjectGetPropertyDataSize, [AudioObject::ObjectID, AudioObject::PropertyAddress.by_ref, :uint32, :pointer, :pointer], :OSStatus
+
+    # OSStatus AudioObjectGetPropertyData(AudioObjectID                     inObjectID,
+    #					  const AudioObjectPropertyAddress* inAddress,
+    #					  UInt32                            inQualifierDataSize,
+    #					  const void*                       inQualifierData,
+    #					  UInt32*                           ioDataSize,
+    #					  void*                             outData)
+    attach_function :AudioObjectGetPropertyData, [AudioObject::ObjectID, AudioObject::PropertyAddress.by_ref, :uint32, :pointer, :pointer, :pointer], :OSStatus
+
+    # @return [Array<AudioObject>]  the list of available audio devices
+    def self.devices
+	address = AudioObject::PropertyAddress.global_master(AudioHardware::PropertyDevices)
+	buffer = AudioObject.system.get_property(address)
+	device_IDs = buffer.get_array_of_int32(0, buffer.size/4)
+	device_IDs.map {|id| AudioDevice.new(id)}
+    end
+end

data/lib/core_audio/audio_device.rb

@@ -0,0 +1,97 @@
+require_relative 'audio_object'
+
+module CoreAudio
+    AudioDeviceIOProcID = FFI::Pointer
+    typedef :pointer, :AudioDeviceIOProcID
+
+    # @group AudioHardware.h
+
+    # typedef OSStatus (*AudioDeviceIOProc)(AudioObjectID           inDevice,
+    #					    const AudioTimeStamp*   inNow,
+    #					    const AudioBufferList*  inInputData,
+    #					    const AudioTimeStamp*   inInputTime,
+    #					    AudioBufferList*        outOutputData,
+    #					    const AudioTimeStamp*   inOutputTime,
+    #					    void*                   inClientData);
+    callback :AudioDeviceIOProc, [AudioObject::ObjectID, :pointer, AudioBufferList.by_ref, :pointer, AudioBufferList.by_ref, :pointer, :pointer], :OSStatus
+
+    # OSStatus AudioDeviceCreateIOProcID(AudioObjectID           inDevice,
+    #					 AudioDeviceIOProc       inProc,
+    #					 void*                   inClientData,
+    #					 AudioDeviceIOProcID*    outIOProcID)
+    attach_function :AudioDeviceCreateIOProcID, [AudioObject::ObjectID, :AudioDeviceIOProc, :pointer, :pointer], :OSStatus
+
+    # OSStatus AudioDeviceDestroyIOProcID(AudioObjectID           inDevice,
+    #					  AudioDeviceIOProcID     inIOProcID
+    attach_function :AudioDeviceDestroyIOProcID, [AudioObject::ObjectID, :AudioDeviceIOProc], :OSStatus
+
+    # OSStatus AudioDeviceStart(AudioObjectID       inDevice,
+    #				AudioDeviceIOProcID inProcID)
+    attach_function :AudioDeviceStart, [AudioObject::ObjectID, :AudioDeviceIOProcID], :OSStatus
+
+    # OSStatus AudioDeviceStop(AudioObjectID       inDevice,
+    #			       AudioDeviceIOProcID inProcID)
+    attach_function :AudioDeviceStop, [AudioObject::ObjectID, :AudioDeviceIOProcID], :OSStatus
+
+    # @endgroup
+
+    class AudioDevice < AudioObject
+
+	# @group AudioHardware.h: AudioDevice Properties
+	PropertyPlugIn                          = 'plug'
+	PropertyDeviceHasChanged                = 'diff'
+	PropertyDeviceIsRunningSomewhere        = 'gone'
+	ProcessorOverload                       = 'over'
+	PropertyIOStoppedAbnormally             = 'stpd'
+	PropertyHogMode                         = 'oink'
+	PropertyBufferFrameSize                 = 'fsiz'
+	PropertyBufferFrameSizeRange            = 'fsz#'
+	PropertyUsesVariableBufferFrameSizes    = 'vfsz'
+	PropertyIOCycleUsage                    = 'ncyc'
+	PropertyStreamConfiguration             = 'slay'
+	PropertyIOProcStreamUsage               = 'suse'
+	PropertyActualSampleRate                = 'asrt'
+	# @endgroup
+
+	# @group Properties
+	def actual_sample_rate
+	    address = PropertyAddress.global_master(PropertyActualSampleRate)
+	    get_property(address).get_float64(0)
+	end
+
+	def buffer_frame_size
+	    address = PropertyAddress.global_master(PropertyBufferFrameSize)
+	    get_property(address).get_uint32(0)
+	end
+
+	def running_somewhere?
+	    address = PropertyAddress.global_master(PropertyDeviceIsRunningSomewhere)
+	    0 != get_property(address).get_uint32(0)
+	end
+	# @endgroup
+
+	# Start the AudioDevice
+	#  If a block is provided, register it as a callback before starting the device
+	#  @note The device will continue to run until `stop` is called
+	def start(&block)
+	    if block_given?
+		io_proc_id = FFI::MemoryPointer.new(:pointer)
+		status = CoreAudio.AudioDeviceCreateIOProcID(id, block, nil, io_proc_id)
+
+		raise "Couldn't create an IO Proc #{status} => '#{[status].pack('L').reverse}'" unless status.zero? # && !@proc_id.nil?
+
+		@proc_id = io_proc_id.get_pointer(0)
+	    end
+
+	    Thread.start do
+		CoreAudio.AudioDeviceStart(id, @proc_id)
+	    end
+	end
+
+	# Stop the AudioDevice and delete any registered callbacks
+	def stop
+	    CoreAudio.AudioDeviceStop(id, @proc_id)
+	    CoreAudio.AudioDeviceDestroyIOProcID(id, @proc_id)
+	end
+    end
+end

data/lib/core_audio/audio_object.rb

@@ -0,0 +1,188 @@
+require_relative '../core_foundation'
+
+module CoreAudio
+    extend FFI::Library
+
+    module AudioHardwareBase
+	# AudioHardwareBase.h: AudioDevice Properties
+	AudioDevicePropertyConfigurationApplication        = 'capp'
+	AudioDevicePropertyDeviceUID                       = 'uid '
+	AudioDevicePropertyModelUID                        = 'muid'
+	AudioDevicePropertyTransportType                   = 'tran'
+	AudioDevicePropertyRelatedDevices                  = 'akin'
+	AudioDevicePropertyClockDomain                     = 'clkd'
+	AudioDevicePropertyDeviceIsAlive                   = 'livn'
+	AudioDevicePropertyDeviceIsRunning                 = 'goin'
+	AudioDevicePropertyDeviceCanBeDefaultDevice        = 'dflt'
+	AudioDevicePropertyDeviceCanBeDefaultSystemDevice  = 'sflt'
+	AudioDevicePropertyLatency                         = 'ltnc'
+	AudioDevicePropertyStreams                         = 'stm#'
+	AudioObjectPropertyControlList                     = 'ctrl'
+	AudioDevicePropertySafetyOffset                    = 'saft'
+	AudioDevicePropertyNominalSampleRate               = 'nsrt'
+	AudioDevicePropertyAvailableNominalSampleRates     = 'nsr#'
+	AudioDevicePropertyIcon                            = 'icon'
+	AudioDevicePropertyIsHidden                        = 'hidn'
+	AudioDevicePropertyPreferredChannelsForStereo      = 'dch2'
+	AudioDevicePropertyPreferredChannelLayout          = 'srnd'
+    end
+
+    module AudioHardware
+	# AudioHardware.h: AudioSystemObject Properties
+	PropertyDevices				    = 'dev#'
+	PropertyDefaultInputDevice		    = 'dIn '
+	PropertyDefaultOutputDevice		    = 'dOut'
+	PropertyDefaultSystemOutputDevice	    = 'sOut'
+	PropertyTranslateUIDToDevice		    = 'uidd'
+	PropertyMixStereoToMono			    = 'stmo'
+	PropertyPlugInList			    = 'plg#'
+	PropertyTranslateBundleIDToPlugIn	    = 'bidp'
+	PropertyTransportManagerList                = 'tmg#'
+	PropertyTranslateBundleIDToTransportManager = 'tmbi'
+	PropertyBoxList				    = 'box#'
+	PropertyTranslateUIDToBox		    = 'uidb'
+	PropertyProcessIsMaster                     = 'mast'
+	PropertyIsInitingOrExiting                  = 'inot'
+	PropertyUserIDChanged                       = 'euid'
+	PropertyProcessIsAudible                    = 'pmut'
+	PropertySleepingIsAllowed                   = 'slep'
+	PropertyUnloadingIsAllowed                  = 'unld'
+	PropertyHogModeIsAllowed                    = 'hogr'
+	PropertyUserSessionIsActiveOrHeadless       = 'user'
+	PropertyServiceRestarted                    = 'srst'
+	PropertyPowerHint                           = 'powh'
+
+	# AudioHardware.h: AudioDevice Properties
+	AudioDevicePropertyPlugIn                          = 'plug'
+	AudioDevicePropertyDeviceHasChanged                = 'diff'
+	AudioDevicePropertyDeviceIsRunningSomewhere        = 'gone'
+	AudioDeviceProcessorOverload                       = 'over'
+	AudioDevicePropertyIOStoppedAbnormally             = 'stpd'
+	AudioDevicePropertyHogMode                         = 'oink'
+	AudioDevicePropertyBufferFrameSize                 = 'fsiz'
+	AudioDevicePropertyBufferFrameSizeRange            = 'fsz#'
+	AudioDevicePropertyUsesVariableBufferFrameSizes    = 'vfsz'
+	AudioDevicePropertyIOCycleUsage                    = 'ncyc'
+	AudioDevicePropertyStreamConfiguration             = 'slay'
+	AudioDevicePropertyIOProcStreamUsage               = 'suse'
+	AudioDevicePropertyActualSampleRate                = 'asrt'
+    end
+
+    class AudioObject
+	attr_reader :id
+
+	ObjectID = FFI::Type::UINT32
+	PropertyElement = FFI::Type::UINT32
+	PropertyScope = FFI::Type::UINT32
+	PropertySelector = FFI::Type::UINT32
+
+	# AudioHardwareBase.h: Basic Constants
+	PropertyScopeGlobal         = 'glob'
+	PropertyScopeInput          = 'inpt'
+	PropertyScopeOutput         = 'outp'
+	PropertyScopePlayThrough    = 'ptru'
+	PropertyElementMaster       = 0
+
+	# AudioHardwareBase.h: AudioObject Properties
+	PropertyBaseClass           = 'bcls'
+	PropertyClass               = 'clas'
+	PropertyOwner               = 'stdv'
+	PropertyName                = 'lnam'
+	PropertyModelName           = 'lmod'
+	PropertyManufacturer        = 'lmak'
+	PropertyElementName         = 'lchn'
+	PropertyElementCategoryName = 'lccn'
+	PropertyElementNumberName   = 'lcnn'
+	PropertyOwnedObjects        = 'ownd'
+	PropertyIdentify            = 'iden'
+	PropertySerialNumber        = 'snum'
+	PropertyFirmwareVersion     = 'fwvn'
+
+	# AudioHardware.h: Basic Constants
+	SystemObject = 1
+
+	def self.system
+	    new(SystemObject)
+	end
+
+	def initialize(id)
+	    @id = id
+	end
+
+	# @return [FFI::MemoryPointer]
+	def get_property(address)
+	    buffer_size = FFI::MemoryPointer.new(:uint32)
+	    status = CoreAudio.AudioObjectGetPropertyDataSize(id, address, 0, nil, buffer_size)
+	    raise('Could not get audio property size') unless 0 == status
+
+	    # buffer_size is now the size of the buffer to be passed to AudioObjectGetPropertyData()
+	    buffer = FFI::MemoryPointer.new(1, buffer_size.get_int32(0))
+	    status = CoreAudio.AudioObjectGetPropertyData(id, address, 0, nil, buffer_size, buffer)
+	    raise('Could not get the audio property data') unless 0 == status
+
+	    buffer
+	end
+
+	# @group Convenience Attributes
+	def external?
+	    not internal?
+	end
+
+	def internal?
+	    transport_type == 'bltn'
+	end
+	# @endgroup
+
+	# @return [String]  the name of the device
+	def device_name
+	    address = PropertyAddress.global_master(PropertyName)
+	    get_string(address)
+	end
+
+	def device_uid
+	    address = PropertyAddress.global_master(AudioHardwareBase::AudioDevicePropertyDeviceUID)
+	    get_string(address)
+	end
+
+	# @return [String] a persistent identifier for the model of an AudioDevice
+	def model_uid
+	    address = PropertyAddress.global_master(AudioHardwareBase::AudioDevicePropertyModelUID)
+	    get_string(address)
+	end
+
+	# @return [String]  the 4-character transport type identifier
+	def transport_type
+	    address = PropertyAddress.global_master(AudioHardwareBase::AudioDevicePropertyTransportType)
+	    buffer = get_property(address)
+	    buffer.get_bytes(0, buffer.size).reverse
+	end
+
+	class PropertyAddress < FFI::Struct
+	    layout  :mSelector, AudioObject::PropertySelector,
+		    :mScope, AudioObject::PropertyScope,
+		    :mElement, AudioObject::PropertyElement
+
+	    def self.make(selector, scope, element)
+		element, scope, selector = [element, scope, selector].map {|a| a.is_a?(String) ? a.reverse.unpack('L').first : a }
+		new.tap do |address|
+		    address[:mSelector] = selector
+		    address[:mScope] = scope
+		    address[:mElement] = element
+		end
+	    end
+
+	    def self.global_master(selector)
+		make(selector, PropertyScopeGlobal, PropertyElementMaster)
+	    end
+	end
+
+	private
+
+	# @return [String]  the String for the addressed property
+	def get_string(address)
+	    buffer = get_property(address)
+	    cf_string_ref = buffer.get_pointer(0)
+	    CoreFoundation::CFStringRef.new(cf_string_ref).to_s
+	end
+    end
+end

data/lib/core_foundation.rb

@@ -0,0 +1,87 @@
+require 'ffi'
+
+module CoreFoundation
+    extend FFI::Library
+    ffi_lib '/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation'
+
+    typedef :pointer, :CFStringRef
+
+    if FFI::Platform::ARCH == 'x86_64'
+	CFIndex = FFI::Type::LONG_LONG
+    else
+	CFIndex = FFI::Type::LONG
+    end
+
+    # CFString.h
+    CFStringEncoding = enum :uint32,
+			:MacRoman, 0,
+			:WindowsLatin1, 0x0500,	    # ANSI codepage 1252
+			:ISOLatin1, 0x0201,	    # ISO 8859-1
+			:NextStepLatin, 0x0B01,	    # NextStep encoding
+			:ASCII, 0x0600,		    # 0..127 (in creating CFString, values greater than 0x7F are treated as corresponding Unicode value)
+			:Unicode, 0x0100,	    # kTextEncodingUnicodeDefault  + kTextEncodingDefaultFormat (aka kUnicode16BitFormat)
+			:UTF8, 0x08000100,	    # kTextEncodingUnicodeDefault + kUnicodeUTF8Format
+			:NonLossyASCII, 0x0BFF,	    # 7bit Unicode variants used by Cocoa & Java
+			:UTF16, 0x0100,		    # kTextEncodingUnicodeDefault + kUnicodeUTF16Format (alias of kCFStringEncodingUnicode)
+			:UTF16BE, 0x10000100,	    # kTextEncodingUnicodeDefault + kUnicodeUTF16BEFormat
+			:UTF16LE, 0x14000100,	    # kTextEncodingUnicodeDefault + kUnicodeUTF16LEFormat
+			:UTF32, 0x0c000100,	    # kTextEncodingUnicodeDefault + kUnicodeUTF32Format
+			:UTF32BE, 0x18000100,	    # kTextEncodingUnicodeDefault + kUnicodeUTF32BEFormat
+			:UTF32LE, 0x1c000100,	    # kTextEncodingUnicodeDefault + kUnicodeUTF32LEFormat
+			:Invalid, 0xffffffff	    # Invalid Encoding
+
+    class CFRange < FFI::Struct
+	layout :location, CFIndex,
+	       :length, CFIndex
+
+	def self.make(location:0, length:0)
+	    new.tap do |range|
+		range[:location] = location
+		range[:length] = length
+	    end
+	end
+    end
+
+    class CFStringRef < FFI::Pointer
+	# @return [CFIndex] the length of the referenced CFString
+	def length
+	    CoreFoundation.CFStringGetLength(self)
+	end
+
+	# @return [CFIndex] the maximum size of the buffer that will hold the string
+	def max_size
+	    CoreFoundation.CFStringGetMaximumSizeForEncoding(length, CFStringEncoding[:UTF8])
+	end
+
+	# @return [String]  the CFString, converted to a UTF-8 string
+	def to_s
+	    buffer = FFI::MemoryPointer.new(:char, max_size)
+	    used_bytes = FFI::MemoryPointer.new(CFIndex)
+	    CoreFoundation.CFStringGetBytes(self,
+					    CFRange.make(location:0, length:length),
+					    CFStringEncoding[:UTF8],
+					    0,
+					    false,
+					    buffer,
+					    buffer.size,
+					    used_bytes)
+
+	    used_bytes = if CFIndex == CoreFoundation.find_type(:long_long)
+		used_bytes.read_long_long
+	    else
+		used_bytes.read_long
+	    end
+
+	    buffer.read_string(used_bytes).force_encoding(Encoding::UTF_8)
+	end
+    end
+
+    # CFIndex CFStringGetBytes(CFStringRef theString, CFRange range, CFStringEncoding encoding, UInt8 lossByte, Boolean isExternalRepresentation, UInt8 *buffer, CFIndex maxBufLen, CFIndex *usedBufLen)
+    attach_function :CFStringGetBytes, [:CFStringRef, CFRange.by_value, CFStringEncoding, :uint8, :bool, :buffer_out, CFIndex, :buffer_out], CFIndex
+
+    # CFIndex CFStringGetLength(CFStringRef theString)
+    attach_function :CFStringGetLength, [:CFStringRef], CFIndex
+
+    # CFIndex CFStringGetMaximumSizeForEncoding(CFIndex length, CFStringEncoding encoding)
+    attach_function :CFStringGetMaximumSizeForEncoding, [CFIndex, CFStringEncoding], CFIndex
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: audio
 version: !ruby/object:Gem::Version
-  version: '0'
+  version: '0.1'
 platform: ruby
 authors:
 - Brandon Fosdick
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-13 00:00:00.000000000 Z
+date: 2015-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -51,6 +51,10 @@ files:
 - Rakefile
 - audio.gemspec
 - lib/audio.rb
+- lib/core_audio.rb
+- lib/core_audio/audio_device.rb
+- lib/core_audio/audio_object.rb
+- lib/core_foundation.rb
 homepage: http://github.com/bfoz/audio-ruby
 licenses:
 - BSD