Permalink
Browse files

Added documentation for AlsaOutput

  • Loading branch information...
1 parent bbc517e commit 2a93aea694f155d10ea7f604562f103680a09e6e @wedesoft committed Nov 17, 2010
Showing with 66 additions and 2 deletions.
  1. +1 −1 Rakefile
  2. +39 −1 lib/hornetseye-alsa/alsaoutput.rb
  3. +26 −0 lib/hornetseye-alsa/{native.rb → docs.rb}
View
@@ -7,7 +7,7 @@ require 'rake/loaders/makefile'
require 'rbconfig'
PKG_NAME = 'hornetseye-alsa'
-PKG_VERSION = '0.3.1'
+PKG_VERSION = '0.3.2'
CFG = RbConfig::CONFIG
CXX = ENV[ 'CXX' ] || 'g++'
RB_FILES = FileList[ 'lib/**/*.rb' ]
@@ -17,12 +17,32 @@
# Namespace of Hornetseye computer vision library
module Hornetseye
+ # Class for playing sounds using the ALSA library
+ #
+ # @see http://www.alsa-project.org/
class AlsaOutput
class << self
alias_method :orig_new, :new
-
+
+ # Open a sound device
+ #
+ # 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
+ # rate near the desired one.
+ #
+ # @example Open a sound device
+ # speaker = AlsaOutput.new 'default:0', 44_100, 2, 16, 1024
+ #
+ # @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.
+ #
+ # @see #rate
def new( pcm_name = 'default:0', rate = 48000, channels = 2, periods = 16,
frames = 1024 )
orig_new pcm_name, rate, channels, periods, frames
@@ -32,6 +52,24 @@ def new( pcm_name = 'default:0', rate = 48000, channels = 2, periods = 16,
alias_method :orig_write, :write
+ # Write an audio frame to the sound device
+ #
+ # The audio data is written to the output buffer of the sound device. Playback is
+ # resumed if a buffer underflow occurred earlier. The first dimension of the array
+ # with the audio data must match the number of channels of the audio device. The
+ # second dimension is the number of audio samples.
+ #
+ # 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
+ #
+ # @param [Node] frame A two-dimensional array of short-integer audio samples.
def write( frame )
if frame.typecode != SINT
raise "Audio data must be of type SINT (but was #{frame.typecode})"
@@ -39,25 +39,51 @@ def prepare
class AlsaOutput
+ # 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
def close
end
+ # Drop content of audio output buffer
def drop
end
+ # Wait until audio buffer underflows
def drain
end
+ # Space available for writing in the audio buffer
+ #
+ # @return [Integer] Number of audio samples which can be written to the audio
+ # buffer.
def avail
end
+ # Number of audio samples in the audio buffer
+ #
+ # Returns the number of audio samples left in the audio buffer. This can be used
+ # to properly synchronise video display with audio output.
+ #
+ # @return [Integer] Number of audio samples left to play.
def delay
end
+ # Reset the sound device.
+ #
+ # One needs to call this method if one wants to resume playing audio samples after
+ # calling #drop or #drain.
def prepare
end

0 comments on commit 2a93aea

Please sign in to comment.