Skip to content
Browse files

Added documentation

  • Loading branch information...
1 parent 2a93aea commit 81d5fcd52d0c57d7a9533a2a464e63f115bde39b @wedesoft committed Nov 17, 2010
Showing with 106 additions and 15 deletions.
  1. +1 −1 Rakefile
  2. +47 −0 lib/hornetseye-alsa/alsainput.rb
  3. +25 −11 lib/hornetseye-alsa/alsaoutput.rb
  4. +33 −3 lib/hornetseye-alsa/docs.rb
View
2 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' ]
View
47 lib/hornetseye-alsa/alsainput.rb
@@ -17,21 +17,68 @@
# 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
end
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
View
36 lib/hornetseye-alsa/alsaoutput.rb
@@ -24,23 +24,30 @@ class AlsaOutput
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 @@ def new( pcm_name = 'default:0', rate = 48000, channels = 2, periods = 16,
end
+ # Alias for native method
+ #
+ # @private
alias_method :orig_write, :write
# Write an audio frame to the sound device
@@ -62,14 +72,17 @@ def new( pcm_name = 'default:0', rate = 48000, channels = 2, periods = 16,
# 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 @@ def write( frame )
"#{frame.shape.first}"
end
orig_write Hornetseye::Sequence( UBYTE, 2 * frame.size ).new( frame.memory )
+ frame
end
end
View
36 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 @@ class AlsaOutput
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 @@ def avail
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

0 comments on commit 81d5fcd

Please sign in to comment.
Something went wrong with that request. Please try again.