hornetseye-alsa 0.3.2 → 0.3.3

data/Rakefile

@@ -7,7 +7,7 @@ require 'rake/loaders/makefile'
 require 'rbconfig'
 
 PKG_NAME = 'hornetseye-alsa'
-PKG_VERSION = '0.3.2'
+PKG_VERSION = '0.3.3'
 CFG = RbConfig::CONFIG
 CXX = ENV[ 'CXX' ] || 'g++'
 RB_FILES = FileList[ 'lib/**/*.rb' ]

data/lib/hornetseye-alsa/alsainput.rb

@@ -17,12 +17,39 @@
 # Namespace of Hornetseye computer vision library
 module Hornetseye
 
+  # Class for capturing audio samples from an ALSA device
+  #
+  # @see http://www.alsa-project.org/
   class AlsaInput
 
     class << self
 
+      # Alias for native constructor
+      #
+      # @return [AlsaInput] An object for accessing a microphone.
+      #
+      # @private
       alias_method :orig_new, :new
 
+      # Open a sound device for input
+      #
+      # Open the specified sound device for reading. Note that the desired sample rate
+      # may not be supported. In that case the sound library will choose a sampling
+      # rate near the desired one.
+      #
+      # @example Open standard microphone device
+      #   require 'hornetseye_alsa'
+      #   include Hornetseye
+      #   microphone = AlsaInput.new 'default:0', 44_100, 2
+      #
+      # @param [String] pcm_name Name of the PCM device
+      # @param [Integer] rate Desired sampling rate.
+      # @param [Integer] channels Number of channels (1=mono, 2=stereo).
+      # @param [Integer] periods Number of audio frames of the output buffer.
+      # @param [Integer] frames Size of the audio frames of the output buffer.
+      # @return [AlsaInput] An object for accessing the microphone.
+      #
+      # @see #rate
       def new( pcm_name = 'default:0', rate = 48000, channels = 2, periods = 16,
                frames = 1024 )
         orig_new pcm_name, rate, channels, periods, frames
@@ -30,8 +57,28 @@ module Hornetseye
 
     end
 
+    # Alias for native method
+    #
+    # @return [Node] A two-dimensional array with short-integer audio samples.
+    #
+    # @private
     alias_method :orig_read, :read
 
+    # Read specified number of samples from the sound device
+    #
+    # Audio data is read from the input buffer.
+    #
+    # A blocking read operation is used. I.e. the program is blocked until there is
+    # sufficient data available in the audio output buffer.
+    #
+    # @example Read 3 seconds of audio samples
+    #   require 'hornetseye_alsa'
+    #   include Hornetseye
+    #   microphone = AlsaInput.new 'default:0', 44_100, 2
+    #   data = microphone.read 3 * 44_100
+    #
+    # @param [Integer] samples Number of samples to read.
+    # @return [Node] A two-dimensional array with short-integer audio samples.
     def read( samples )
       Hornetseye::MultiArray( SINT, channels, samples ).
         new orig_read( samples ).memory

data/lib/hornetseye-alsa/alsaoutput.rb

@@ -24,23 +24,30 @@ module Hornetseye
 
     class << self
 
+      # Alias for native constructor
+      #
+      # @return [AlsaOutput] An object for accessing the speakers.
+      #
+      # @private
       alias_method :orig_new, :new
      
-      # Open a sound device
+      # Open a sound device for output
       #
       # Open the specified sound device for writing. Note that the desired sample rate
-      # may not be supported. In that case the sound library will provide a sampling
+      # may not be supported. In that case the sound library will select a sampling
       # rate near the desired one.
       #
-      # @example Open a sound device
-      #   speaker = AlsaOutput.new 'default:0', 44_100, 2, 16, 1024
+      # @example Open default speakers
+      #   require 'hornetseye_alsa'
+      #   include Hornetseye
+      #   speaker = AlsaOutput.new 'default:0', 44_100, 2
       #
       # @param [String] pcm_name Name of the PCM device
       # @param [Integer] rate Desired sampling rate.
       # @param [Integer] channels Number of channels (1=mono, 2=stereo).
       # @param [Integer] periods Number of audio frames of the output buffer.
       # @param [Integer] frames Size of the audio frames of the output buffer.
-      # @return [AlsaOutput] An object for accessing the sound device.
+      # @return [AlsaOutput] An object for accessing the speakers.
       #
       # @see #rate
       def new( pcm_name = 'default:0', rate = 48000, channels = 2, periods = 16,
@@ -50,6 +57,9 @@ module Hornetseye
 
     end
 
+    # Alias for native method
+    #
+    # @private
     alias_method :orig_write, :write
 
     # Write an audio frame to the sound device
@@ -62,14 +72,17 @@ module Hornetseye
     # A blocking write operation is used. I.e. the program is blocked until there is
     # sufficient space in the audio output buffer.
     #
-    # @example Writing audio samples
-    #   speaker = AlsaOutput.new 'default:0', 44_100, 2, 16, 1024
-    #   wave = lazy( 2, 110 ) { |j,i| Math.sin( i * 2 * Math::PI / 110 ) * 0x7FFF }.to_sint
-    #   while true
-    #     speaker.write wave
-    #   end
+    # @example Play a 400Hz tune for 3 seconds
+    #   require 'hornetseye_alsa'
+    #   include Hornetseye
+    #   speaker = AlsaOutput.new 'default:0', 44_100, 2
+    #   L = 44_100 / 400
+    #   wave = lazy( 2, L ) { |j,i| Math.sin( i * 2 * Math::PI / L ) * 0x7FFF }.to_sint
+    #   ( 3 * 400 ).times { speaker.write wave }
     #
     # @param [Node] frame A two-dimensional array of short-integer audio samples.
+    #
+    # @return [Node] Returns the parameter +frame+.
     def write( frame )
       if frame.typecode != SINT
         raise "Audio data must be of type SINT (but was #{frame.typecode})"
@@ -82,6 +95,7 @@ module Hornetseye
               "#{frame.shape.first}"
       end
       orig_write Hornetseye::Sequence( UBYTE, 2 * frame.size ).new( frame.memory )
+      frame
     end
 
   end

data/lib/hornetseye-alsa/docs.rb

@@ -19,19 +19,41 @@ module Hornetseye
 
   class AlsaInput
 
+    # Get the sampling rate of the sound device
+    #
+    # The sampling rate may be different to the desired sampling rate specified in
+    # the constructor.
+    #
+    # @return [Integer] The sampling rate of the sound device.
     attr_reader :rate
 
+    # Number of audio channels
+    #
+    # @return [Integer] Number of audio channels (1=mono, 2=stereo).
     attr_reader :channels
 
+    # Close the audio device
+    #
+    # @return [AlsaInput] Returns +self+.
     def close
     end
 
+    # Space available for recording to the audio buffer
+    #
+    # @return [Integer] Number of audio samples left for recording before the buffer
+    #         overflows.
     def avail
     end
 
+    # Number of samples available for retrieval
+    #
+    # @return [Integer] Number of audio samples available for retrieval.
     def delay
     end
 
+    # Reset the sound device
+    #
+    # @return [AlsaInput] Returns +self+.
     def prepare
     end
 
@@ -53,18 +75,24 @@ module Hornetseye
     attr_reader :channels
 
     # Close the audio device
+    #
+    # @return [AlsaOutput] Returns +self+.
     def close
     end
 
     # Drop content of audio output buffer
+    #
+    # @return [AlsaOutput] Returns +self+.
     def drop
     end
 
     # Wait until audio buffer underflows
+    #
+    # @return [AlsaOutput] Returns +self+.
     def drain
     end
 
-    # Space available for writing in the audio buffer
+    # Space available for writing to the audio buffer
     #
     # @return [Integer] Number of audio samples which can be written to the audio
     #         buffer.
@@ -80,10 +108,12 @@ module Hornetseye
     def delay
     end
 
-    # Reset the sound device.
+    # Reset the sound device
     #
     # One needs to call this method if one wants to resume playing audio samples after
-    # calling #drop or #drain.
+    # calling #drop.
+    #
+    # @return [AlsaOutput] Returns +self+.
     def prepare
     end
 

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 3
-  - 2
-  version: 0.3.2
+  - 3
+  version: 0.3.3
 platform: ruby
 authors: 
 - Jan Wedekind