hornetseye-alsa 0.3.1 → 0.3.2

data/Rakefile

@@ -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' ]

data/lib/hornetseye-alsa/alsaoutput.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 @@ module Hornetseye
 
     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})"

data/lib/hornetseye-alsa/docs.rb

@@ -0,0 +1,93 @@
+# hornetseye-alsa - Play audio data using libalsa
+# Copyright (C) 2010 Jan Wedekind
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# Namespace of Hornetseye computer vision library
+module Hornetseye
+
+  class AlsaInput
+
+    attr_reader :rate
+
+    attr_reader :channels
+
+    def close
+    end
+
+    def avail
+    end
+
+    def delay
+    end
+
+    def prepare
+    end
+
+  end
+  
+  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
+
+  end
+
+end
+

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 3
-  - 1
-  version: 0.3.1
+  - 2
+  version: 0.3.2
 platform: ruby
 authors: 
 - Jan Wedekind
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-15 00:00:00 +00:00
+date: 2010-11-17 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -72,6 +72,7 @@ files:
 - COPYING
 - .document
 - lib/hornetseye-alsa/alsainput.rb
+- lib/hornetseye-alsa/docs.rb
 - lib/hornetseye-alsa/alsaoutput.rb
 - lib/hornetseye_alsa_ext.rb
 - ext/alsainput.cc