win32-sound 0.4.0

data/CHANGES

@@ -0,0 +1,33 @@
+== 0.4.0 - 26-Feb-2006
+* Now pure Ruby only.
+* Documentation updates and reorganization.
+* Added a gemspec.
+* Minor test suite changes.
+
+== 0.3.0 - 29-May-2005
+* Changed the Sound.volume= method (which didn't work) to
+  Sound.set_wave_volume because it takes up to two values and only affects
+  the wave volume, not the master volume.
+* Renamed the Sound.volume method to Sound.wave_volume.
+* Fixed a bug in the Sound.wave_volume method.
+* Created the Sound.get_wave_volume alias for Sound.wave_volume.
+* Fixed the Sound.set_wave_volume method.
+* Test adjustments and additions to reflect API changes.
+* Now Unicode friendly.
+* Removed the sound.rd file.  The sound.txt file is now rdoc friendly.
+
+== 0.2.1 - 1-Mar-2005
+* Moved the 'examples' directory to the toplevel directory
+* Made the CHANGES and README files rdoc friendly
+* Some cleanup in sound.h.
+
+== 0.2.0 - 13-Jul-2004
+* Moved the SoundError class under the Win32 module namespace
+* Replaced the deprecated STR2CSTR() function with the StringValuePtr()
+  function.  This means that as of version 0.2.0, this package requires
+  Ruby 1.8.0 or later.
+* Moved the test.rb script to doc/examples
+* Added the README file (oops).
+
+== 0.1.0 - 14-Feb-2004
+* Initial release

data/MANIFEST

@@ -0,0 +1,11 @@
+MANIFEST
+CHANGES
+README
+install.rb
+win32-sound.gempsec
+
+examples/sound_test.rb
+
+lib/win32/sound.rb
+
+test/tc_sound.rb

data/README

@@ -0,0 +1,69 @@
+== Description
+   A package for playing with sound on Windows.
+
+== Prerequisites
+   This package requires Ruby 1.8.0 or later.
+
+== Installation instructions
+=== Gem installation
+   ruby win32-sound.gemspect
+   gem install win32-sound-X.X.X.gem
+
+=== Manual installation
+   ruby install.rb
+   ri lib\win32\sound.rb (to generate documentation)
+
+== Synopsis
+   require "win32/sound"
+   include Win32
+	
+   # Get the current volume of the waveform-audio output device.
+   p Sound.volume.join(", ") # left channel, right channel
+	
+   # Play a system sound
+   Sound.play("SystemAsterisk",Sound::ALIAS)
+	
+   # Play a wav file
+   Sound.play("somefile.wav")
+
+== Acknowledgements
+   API ideas derived (or not) from Perl's Win32::Sound module and Python's
+   winsound package.
+	
+== Known Bugs
+   None that I'm aware of.  Please report any bugs on the Win32 Utils home
+   page at http://rubyforge.org/projects/win32utils.
+   
+== Questions and Comments
+   Please post questions and/or comments on one of the forums on the project
+   page at http://rubyforge.org/projects/win32utils.  Click the 'Forums' tab.
+	
+== Future Plans
+   Add ability to retrieve information about WAV files.
+   Add MIDI support?
+	
+== Developer's Notes
+   The MessageBeep() function, which the Python "winsound" module contains,
+   is intentionally omitted here.  I felt it was redundant, because you can
+   achieve the same effect with something like
+   Sound.play("SystemAsterisk", Sound::ALIAS).
+	
+== License
+   Ruby's
+	
+== Copyright
+   (C) 2004-2006, Daniel J. Berger, All Rights Reserved
+	
+== Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+	
+== Author(s)
+   Daniel Berger
+   djberg96 at gmail dot com
+   imperator/mok on IRC (irc.freenode.net)
+	
+   Park Heesob
+   phasis at nownuri dot net
+   phasis68 on IRC (irc.freenode.net)

data/examples/sound_test.rb

@@ -0,0 +1,50 @@
+##############################################################
+# sound_test.rb (win32-sound)
+#
+# A test script for general futzing.  Modify as you see fit.
+##############################################################
+if File.basename(Dir.pwd) == "examples"
+	Dir.chdir ".."
+	$LOAD_PATH.unshift Dir.pwd + '/lib'
+end
+
+require "win32/sound"
+include Win32
+
+wav = "c:\\windows\\media\\chimes.wav"
+
+puts "VERSION: " + Sound::VERSION
+#puts "Devices: " + Sound.devices.join(", ")
+
+#Sound.volume = [77,128] # my personal settings
+
+orig_left, orig_right = Sound.wave_volume
+puts "Volume was: #{orig_left}, #{orig_right}"
+
+#Sound.volume = 140
+#puts "Volume is now: " + Sound.volume.join(", ")
+
+#Sound.volume = [orig_left,orig_right]
+#puts "Volume is now: " + Sound.volume.join(", ")
+
+puts "Playing 'SystemAsterisk' sound"
+sleep 1
+Sound.play("SystemAsterisk",Sound::ALIAS)
+
+puts "Playing 'chimes' sound once"
+sleep 1
+Sound.play(wav)
+
+puts "Playing 'chimes' sound in a loop for 3 seconds"
+sleep 1
+Sound.play(wav,Sound::ASYNC|Sound::LOOP)
+sleep 3
+Sound.stop
+
+puts "Playing default sound"
+sleep 1
+Sound.play("Foofoo",Sound::ALIAS)
+
+puts "Playing a beep"
+sleep 1
+Sound.beep(500,10000)

data/lib/win32/sound.rb

@@ -0,0 +1,202 @@
+require 'Win32API'
+module Win32
+   class SoundError < StandardError; end
+   class Sound
+      VERSION        = '0.4.0'
+      LOW_FREQUENCY  = 37
+      HIGH_FREQUENCY = 32767
+      MAX_VOLUME     = 0xFFFF
+      
+      SYNC           = 0x0000  # play synchronously (default)
+      ASYNC          = 0x0001  # play asynchronously
+      NODEFAULT      = 0x0002  # silence (!default) if sound not found
+      MEMORY         = 0x0004  # pszSound points to a memory file
+      LOOP           = 0x0008  # loop the sound until next sndPlaySound
+      NOSTOP         = 0x0010  # don't stop any currently playing sound 
+      NOWAIT         = 8192    # don't wait if the driver is busy
+      ALIAS          = 65536   # name is a registry alias
+      ALIAS_ID       = 1114112 # alias is a predefined ID
+      FILENAME       = 131072  # name is file name
+      RESOURCE       = 262148  # name is resource name or atom
+      PURGE          = 0x0040  # purge non-static events for task
+      APPLICATION    = 0x0080  # look for application specific association
+      
+      @@Beep              = Win32API.new('kernel32', 'Beep', 'LL', 'I')
+      @@PlaySound         = Win32API.new('winmm', 'PlaySound', 'PPL', 'I')
+      @@waveOutSetVolume  = Win32API.new('winmm', 'waveOutSetVolume', 'PL', 'I')
+      @@waveOutGetVolume  = Win32API.new('winmm', 'waveOutGetVolume', 'IP', 'I')
+      @@waveOutGetNumDevs = Win32API.new('winmm', 'waveOutGetNumDevs', 'V', 'I')
+      @@waveInGetNumDevs  = Win32API.new('winmm', 'waveInGetNumDevs', 'V', 'I')
+      @@midiOutGetNumDevs = Win32API.new('winmm', 'midiOutGetNumDevs', 'V', 'I')
+      @@midiInGetNumDevs  = Win32API.new('winmm', 'midiInGetNumDevs', 'V', 'I')
+      @@auxGetNumDevs     = Win32API.new('winmm', 'auxGetNumDevs', 'V', 'I')
+      @@mixerGetNumDevs   = Win32API.new('winmm', 'mixerGetNumDevs', 'V', 'I')
+           
+      @@GetLastError  = Win32API.new('kernel32', 'GetLastError', '', 'L')
+      @@FormatMessage = Win32API.new('kernel32', 'FormatMessage', 'LPLLPLP', 'L')
+      
+      # Returns an array of all the available sound devices; their names contain
+      # the type of the device and a zero-based ID number.  Possible return values
+      # are WAVEOUT, WAVEIN, MIDIOUT, MIDIIN, AUX or MIXER.
+      def self.devices
+         devs = []
+         
+         begin
+            0.upto(@@waveOutGetNumDevs.call){ |i| devs << "WAVEOUT#{i}" }
+            0.upto(@@waveInGetNumDevs.call){ |i| devs << "WAVEIN#{i}" }
+            0.upto(@@midiOutGetNumDevs.call){ |i| devs << "MIDIOUT#{i}" }
+            0.upto(@@midiInGetNumDevs.call){ |i| devs << "MIDIIN#{i}" }
+            0.upto(@@auxGetNumDevs.call){ |i| devs << "AUX#{i}" }
+            0.upto(@@mixerGetNumDevs.call){ |i| devs << "MIXER#{i}" }
+         rescue Exception => err
+            raise SoundError, get_last_error
+         end
+         
+         devs
+      end
+
+      # Generates simple tones on the speaker. The function is synchronous; it
+      # does not return control to its caller until the sound finishes.
+	  #
+	  # The frequency (in Hertz) must be between 37 and 32767.
+      # The duration is in milliseconds.
+      def self.beep(frequency, duration)
+         if frequency > HIGH_FREQUENCY || frequency < LOW_FREQUENCY
+            raise SoundError, 'invalid frequency'
+         end
+         
+         if 0 == @@Beep.call(frequency, duration)
+            raise SoundError, get_last_error
+         end        
+         self
+      end
+      
+      # Stops any currently playing waveform sound.  If +purge+ is set to
+      # true, then *all* sounds are stopped.  The default is false.
+      def self.stop(purge = false)
+         if purge && purge != 0
+            flags = PURGE
+         else
+            flags = 0
+         end
+         
+         if 0 == @@PlaySound.call(0, 0, flags)
+            raise SoundError, get_last_error
+         end
+         self
+      end
+      
+      # Plays the specified sound.  The sound can be a wave file or a system
+      # sound, when used in conjunction with the ALIAS flag.
+      #
+      # Valid flags:
+      #
+      # Sound::ALIAS
+	  #   The sound parameter is a system-event alias in the registry or the
+	  #   WIN.INI file. If the registry contains no such name, it plays the
+	  #   system default sound unless the NODEFAULT value is also specified.
+	  #   Do not use with FILENAME.
+	  #
+      # Sound::APPLICATION
+	  #   The sound is played using an application-specific association.
+	  #
+	  # Sound::ASYNC
+	  #   The sound is played asynchronously and the function returns
+	  #   immediately after beginning the sound.
+	  #
+	  # Sound::FILENAME
+	  #   The sound parameter is the name of a WAV file.  Do not use with 
+	  #   ALIAS.
+	  #
+	  # Sound::LOOP
+	  #   The sound plays repeatedly until Sound.stop() is called. You must
+	  #   also specify the ASYNC flag to loop sounds.
+ 	  #
+ 	  # Sound::MEMORY
+	  #   The sound points to an image of a waveform sound in memory.
+      #	
+      # Sound::NODEFAULT
+	  #   If the sound cannot be found, the function returns silently without
+	  #   playing the default sound.
+	  #
+	  # Sound::NOSTOP
+	  #   If a sound is currently playing, the function immediately returns
+	  #   false without playing the requested sound.
+	  #
+      # Sound::NOWAIT
+	  #   If the driver is busy, return immediately without playing the sound.
+	  #
+      # Sound::PURGE
+	  #   Stop playing all instances of the specified sound.
+      #	
+      # Sound::SYNC
+	  #   The sound is played synchronously and the function does not return
+	  #   until the sound ends.
+      def self.play(sound, flags = 0)
+         if 0 == @@PlaySound.call(sound, 0, flags)
+            raise SoundError, get_last_error
+         end
+         self
+      end
+      
+      # Sets the volume for the left and right channel.  If the +right_channel+
+      # is omitted, the volume is set for *both* channels.
+	  #
+      # You may optionally pass a single Integer rather than an Array, in which
+      # case it is assumed you are setting both channels to the same value.
+      def self.set_wave_volume(left_channel, right_channel = nil)
+         right_channel ||= left_channel
+         
+         lvolume = left_channel > MAX_VOLUME ? MAX_VOLUME : left_channel
+         rvolume = right_channel > MAX_VOLUME ? MAX_VOLUME : right_channel
+         
+         volume = lvolume | rvolume << 16
+         
+         if @@waveOutSetVolume.call(-1, volume) != 0
+            raise SoundError, get_last_error
+         end
+         self
+      end
+      
+      # Returns a 2-element array that contains the volume for the left channel
+      # and right channel, respectively.
+      def self.wave_volume
+         volume = [0].pack('L')
+         if @@waveOutGetVolume.call(-1, volume) != 0
+            raise SoundError, get_last_error
+         end
+         volume = volume.unpack('L').first
+         [low_word(volume), high_word(volume)]
+      end
+      
+      # Alias for Sound.wave_volume
+      def self.get_wave_volume
+         self.wave_volume
+      end
+      
+      private
+      
+      def self.low_word(num)
+         num & 0xFFFF
+      end
+      
+      def self.high_word(num)
+         num >> 16
+      end
+      
+      # Convenience method that wraps FormatMessage with some sane defaults.
+      def self.get_last_error(err_num = @@GetLastError.call)
+         buf = 0.chr * 260
+         @@FormatMessage.call(
+            12288,
+            0,
+            err_num,
+            0,
+            buf,
+            buf.length,
+            0
+         )
+         buf.split(0.chr).first.chomp
+      end
+   end
+end

data/test/tc_sound.rb

@@ -0,0 +1,95 @@
+###########################################
+# tc_sound.rb
+#
+# Test suite for the win32-sound package.
+############################################
+base = File.basename(Dir.pwd)
+
+if base == "test" || base =~ /win32-sound/
+	Dir.chdir("..") if base == "test"
+	$LOAD_PATH.unshift Dir.pwd + '/lib'
+	Dir.chdir("test") if base =~ /win32-sound/
+end
+
+puts "You may hear some funny noises - don't panic"
+sleep 1
+
+require "test/unit"
+require "win32/sound"
+include Win32
+
+class TC_Sound < Test::Unit::TestCase
+   def setup
+      @wav = "c:\\windows\\media\\chimes.wav"
+   end
+   
+   def test_version
+      assert_equal("0.4.0", Sound::VERSION)
+   end
+   
+   def test_beep
+      assert_respond_to(Sound, :beep)
+      assert_nothing_raised{ Sound.beep(55,100) }
+      
+      assert_raises(SoundError){ Sound.beep(0,100) }
+      assert_raises(ArgumentError){ Sound.beep }
+      assert_raises(ArgumentError){ Sound.beep(500) }
+      assert_raises(ArgumentError){ Sound.beep(500,500,5) }
+   end
+   
+   def test_devices
+      assert_respond_to(Sound, :devices)
+      assert_nothing_raised{ Sound.devices }
+      
+      assert_kind_of(Array,Sound.devices)
+   end
+   
+   def test_stop
+      assert_respond_to(Sound, :stop)
+      assert_nothing_raised{ Sound.stop }
+      assert_nothing_raised{ Sound.stop(true) }
+   end
+   
+   def test_get_volume
+      assert_respond_to(Sound, :wave_volume)
+      assert_respond_to(Sound, :get_wave_volume)
+      assert_nothing_raised{ Sound.get_wave_volume }
+      
+      assert_kind_of(Array, Sound.get_wave_volume)
+      assert_equal(2, Sound.get_wave_volume.length)
+   end
+
+   def test_set_volume
+      assert_respond_to(Sound, :set_wave_volume)
+      assert_nothing_raised{ Sound.set_wave_volume(30000) } # About half
+      assert_nothing_raised{ Sound.set_wave_volume(30000, 30000) }
+   end
+   
+   def test_play
+      assert_respond_to(Sound, :play)
+      assert_nothing_raised{ Sound.play(@wav) }
+      assert_nothing_raised{ Sound.play("SystemAsterisk", Sound::ALIAS) }
+   end
+   
+   def test_expected_errors
+      assert_raises(SoundError){ Sound.beep(-1, 1) }
+   end
+   
+   def test_constants
+      assert_not_nil(Sound::ALIAS)
+      assert_not_nil(Sound::APPLICATION)
+      assert_not_nil(Sound::ASYNC)
+      assert_not_nil(Sound::FILENAME)
+      assert_not_nil(Sound::LOOP)
+      assert_not_nil(Sound::MEMORY)
+      assert_not_nil(Sound::NODEFAULT)
+      assert_not_nil(Sound::NOSTOP)
+      assert_not_nil(Sound::NOWAIT)
+      assert_not_nil(Sound::PURGE)
+      assert_not_nil(Sound::SYNC)
+   end
+   
+   def teardown
+      @wav = nil
+   end
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: win32-sound
+version: !ruby/object:Gem::Version 
+  version: 0.4.0
+date: 2006-02-26 00:00:00 -07:00
+summary: A package for playing with sound on Windows.
+require_paths: 
+- lib
+email: djberg96@gmail.com
+homepage: http://www.rubyforge.org/projects/win32utils
+rubyforge_project: win32utils
+description: A package for playing with sound on Windows.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Daniel J. Berger
+files: 
+- examples/sound_test.rb
+- lib/win32/sound.rb
+- test/tc_sound.rb
+- CHANGES
+- MANIFEST
+- README
+test_files: 
+- test/tc_sound.rb
+rdoc_options: []
+
+extra_rdoc_files: 
+- CHANGES
+- README
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+