win32-sound 0.4.1 → 0.4.2

data/CHANGES

@@ -1,3 +1,14 @@
+== 0.4.2 - 6-Aug-2009
+* Changed the license to Artistic 2.0.
+* Updated to use the Windows::Sound module from the windows-pr library.
+* Fixed the Sound::ALIAS value. It was wrongly set to SND_ALIAS_ID.
+* Several gemspec updates, including the license and description.
+* The Sound.get_wave_volume method is now a true alias.
+* Renamed the test file to test_win32_sound.rb.
+* Renamed the example file to example_win32_sound.rb to avoid any possible
+  confusion with actual test files.
+* Added the 'example' rake task.
+
 == 0.4.1 - 27-Jul-2007
 * Changed SoundError to Sound::Error.
 * Added a Rakefile with tasks for installation and testing.
@@ -36,4 +47,4 @@
 * Added the README file (oops).
 
 == 0.1.0 - 14-Feb-2004
-* Initial release
+* Initial release

data/README

@@ -1,11 +1,14 @@
 == Description
-   A package for playing with sound on Windows.
+   A library for playing and controlling sounds on MS Windows.
 
 == Prerequisites
-   This package requires Ruby 1.8.0 or later. Ruby 1.8.2 or later is
-   recommended.
+   * windows-pr 1.0.6 or later
 
 == Installation instructions
+=== Gem installation
+   gem install win32-sound
+
+=== Local installation
    rake test (optional)
    rake install (non-gem) or rake install_gem (gem)
 
@@ -13,14 +16,14 @@
    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 wav file
+   Sound.play("somefile.wav")
 
    # Play a system sound
    Sound.play("SystemAsterisk",Sound::ALIAS)
 
-   # Play a wav file
-   Sound.play("somefile.wav")
+   # Get the current volume of the waveform-audio output device.
+   p Sound.volume.join(", ") # left channel, right channel
 
 == Acknowledgements
    API ideas derived (or not) from Perl's Win32::Sound module and Python's
@@ -41,14 +44,14 @@
 == 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
+   achieve the same effect with something like this:
    Sound.play("SystemAsterisk", Sound::ALIAS).
 	
 == License
-   Ruby's
+   Artistic 2.0
 
 == Copyright
-   (C) 2004-2007, Daniel J. Berger, All Rights Reserved
+   (C) 2004-2009, Daniel J. Berger, All Rights Reserved
 
 == Warranty
    This package is provided "as is" and without any express or
@@ -57,9 +60,4 @@
 
 == Author(s)
    Daniel Berger
-   djberg96 at nospam at gmail dot com
-   imperator on IRC (irc.freenode.net)
-
    Park Heesob
-   phasis at nospam at nownuri dot net
-   phasis68 on IRC (irc.freenode.net)

data/Rakefile

@@ -15,8 +15,12 @@ task :install_gem do
    sh "gem install #{file}"
 end
 
+desc 'Run the example program'
+task :example do
+   ruby '-Ilib examples\example_win32_sound.rb'
+end
+
 Rake::TestTask.new do |t|
-   t.libs << 'lib'
    t.warning = true
-   t.test_files = FileList['test/tc*']
+   t.verbose = true
 end

data/examples/{sound_test.rb → example_win32_sound.rb}

@@ -1,14 +1,12 @@
-##############################################################
-# sound_test.rb (win32-sound)
+#######################################################################
+# example_win32_sound.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"
+# A example script to demonstrate the win32-sound library and for
+# general futzing. You can run this via the 'rake example' task.
+#
+# Modify as you see fit.
+#######################################################################
+require 'win32/sound'
 include Win32
 
 wav = "c:\\windows\\media\\chimes.wav"
@@ -43,8 +41,8 @@ Sound.stop
 
 puts "Playing default sound"
 sleep 1
-Sound.play("Foofoo",Sound::ALIAS)
+Sound.play("Foofoo", Sound::ALIAS)
 
 puts "Playing a beep"
 sleep 1
-Sound.beep(500,10000)
+Sound.beep(500, 10000)

data/lib/win32/sound.rb

@@ -1,55 +1,58 @@
-require 'Win32API'
+require 'windows/sound'
+require 'windows/error'
+
+# The Win32 module serves as a namespace only.
 module Win32
+
+   # The Sound class encapsulates various methods for playing sound as well
+   # as querying or configuring sound related properties.
    class Sound
+
+      # The Win32::Sound::Error class is typically raised if any of the
+      # Win32::Sound methods fail.
       class Error < StandardError; end
 
-      VERSION        = '0.4.1'
+      include Windows::Sound
+      include Windows::Error
+      extend Windows::Sound
+      extend Windows::Error
+
+      # The version of the win32-sound library
+      VERSION = '0.4.2'
+
       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')
+      SYNC           = SND_SYNC        # play synchronously (default)
+      ASYNC          = SND_ASYNC       # play asynchronously
+      NODEFAULT      = SND_NODEFAULT   # silence (!default) if sound not found
+      MEMORY         = SND_MEMORY      # pszSound points to a memory file
+      LOOP           = SND_LOOP        # loop the sound until next sndPlaySound
+      NOSTOP         = SND_NOSTOP      # don't stop any currently playing sound
+      NOWAIT         = SND_NOWAIT      # don't wait if the driver is busy
+      ALIAS          = SND_ALIAS       # name is a registry alias
+      ALIAS_ID       = SND_ALIAS_ID    # alias is a predefined ID
+      FILENAME       = SND_FILENAME    # name is file name
+      RESOURCE       = SND_RESOURCE    # name is resource name or atom
+      PURGE          = SND_PURGE       # purge non-static events for task
+      APPLICATION    = SND_APPLICATION # look for app specific association
       
       # 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
+      # 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
+            0.upto(waveOutGetNumDevs()){ |i| devs << "WAVEOUT#{i}" }
+            0.upto(waveInGetNumDevs()){ |i| devs << "WAVEIN#{i}" }
+            0.upto(midiOutGetNumDevs()){ |i| devs << "MIDIOUT#{i}" }
+            0.upto(midiInGetNumDevs()){ |i| devs << "MIDIIN#{i}" }
+            0.upto(auxGetNumDevs()){ |i| devs << "AUX#{i}" }
+            0.upto(mixerGetNumDevs()){ |i| devs << "MIXER#{i}" }
+         rescue Exception
             raise Error, get_last_error
          end
          
@@ -58,22 +61,25 @@ module Win32
 
       # 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 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 Error, 'invalid frequency'
          end
          
-         if 0 == @@Beep.call(frequency, duration)
+         if 0 == Beep(frequency, duration)
             raise Error, 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.
+      # 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
@@ -81,70 +87,87 @@ module Win32
             flags = 0
          end
          
-         if 0 == @@PlaySound.call(0, 0, flags)
+         unless PlaySound(0, 0, flags)
             raise Error, get_last_error
          end
+
          self
       end
       
-      # Plays the specified sound.  The sound can be a wave file or a system
+      # 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.
-	  #
+      #   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.
+      #   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.
-	  #
+      #   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.
-	  #
+      #   If the driver is busy, return immediately without playing the sound.
+      #
       # Sound::PURGE
-	  #   Stop playing all instances of the specified sound.
+      #   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.
+      #   The sound is played synchronously and the function does not return
+      #   until the sound ends.
+      #
+      # Examples:
+      #
+      #    require 'win32/sound'
+      #    include Win32
+      #
+      #    # Play a wave file once
+      #    Sound.play('some_file.wav')
+      #
+      #    # Play a wave file in an asynchronous loop for 2 seconds
+      #    Sound.play('some_file.wav', Sound::ASYNC | Sound::LOOP)
+      #    sleep 2
+      #    Sound.stop
+      #
       def self.play(sound, flags = 0)
-         if 0 == @@PlaySound.call(sound, 0, flags)
+         unless PlaySound(sound, 0, flags)
             raise Error, get_last_error
          end
+
          self
       end
       
-      # Sets the volume for the left and right channel.  If the +right_channel+
+      # 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
          
@@ -153,9 +176,10 @@ module Win32
          
          volume = lvolume | rvolume << 16
          
-         if @@waveOutSetVolume.call(-1, volume) != 0
+         if waveOutSetVolume(-1, volume) != 0
             raise Error, get_last_error
          end
+
          self
       end
       
@@ -163,16 +187,15 @@ module Win32
       # and right channel, respectively.
       def self.wave_volume
          volume = [0].pack('L')
-         if @@waveOutGetVolume.call(-1, volume) != 0
+         if waveOutGetVolume(-1, volume) != 0
             raise Error, 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
+
+      class << self
+         alias get_wave_volume wave_volume
       end
       
       private
@@ -184,20 +207,5 @@ module Win32
       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 → test_win32_sound.rb}

@@ -1,39 +1,37 @@
 ##########################################################################
-# tc_sound.rb
+# test_win32_sound.rb
 #
-# Test suite for the win32-sound package. You should run this test case
+# Test suite for the win32-sound library. You should run this test case
 # via the 'rake test' task.
 ##########################################################################
-puts "You may hear some funny noises - don't panic"
-sleep 1
-
-require "test/unit"
-require "win32/sound"
+require 'test/unit'
+require 'win32/sound'
 include Win32
 
-class TC_Sound < Test::Unit::TestCase
+class TC_Win32_Sound < Test::Unit::TestCase
    def setup
       @wav = "c:\\windows\\media\\chimes.wav"
    end
    
    def test_version
-      assert_equal("0.4.1", Sound::VERSION)
+      assert_equal('0.4.2', Sound::VERSION)
    end
    
    def test_beep
       assert_respond_to(Sound, :beep)
-      assert_nothing_raised{ Sound.beep(55,100) }
+      assert_nothing_raised{ Sound.beep(55, 100) }
+   end
       
-      assert_raises(Sound::Error){ Sound.beep(0,100) }
+   def test_beep_expected_errors
+      assert_raises(Sound::Error){ Sound.beep(0, 100) }
       assert_raises(ArgumentError){ Sound.beep }
       assert_raises(ArgumentError){ Sound.beep(500) }
-      assert_raises(ArgumentError){ Sound.beep(500,500,5) }
+      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
    
@@ -43,11 +41,13 @@ class TC_Sound < Test::Unit::TestCase
       assert_nothing_raised{ Sound.stop(true) }
    end
    
-   def test_get_volume
+   def test_get_volume_basic
       assert_respond_to(Sound, :wave_volume)
       assert_respond_to(Sound, :get_wave_volume)
       assert_nothing_raised{ Sound.get_wave_volume }
+   end
       
+   def test_get_volume
       assert_kind_of(Array, Sound.get_wave_volume)
       assert_equal(2, Sound.get_wave_volume.length)
    end
@@ -61,7 +61,10 @@ class TC_Sound < Test::Unit::TestCase
    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_play_alias
+      assert_nothing_raised{ Sound.play('SystemAsterisk', Sound::ALIAS) }
    end
    
    def test_expected_errors

data/win32-sound.gemspec

@@ -1,27 +1,28 @@
-require "rubygems"
+require 'rubygems'
 
 spec = Gem::Specification.new do |gem|
-	gem.name         = "win32-sound"
-	gem.version      = "0.4.1"
-	gem.author       = "Daniel J. Berger"
-	gem.email        = "djberg96@gmail.com"
-	gem.homepage     = "http://www.rubyforge.org/projects/win32utils"
-	gem.platform     = Gem::Platform::RUBY
-	gem.summary      = "A library for playing with sound on MS Windows."
-	gem.description  = "A library for playing with sound on MS Windows."
-	gem.test_file    = "test/tc_sound.rb"
-	gem.has_rdoc     = true
-	gem.require_path = "lib"
+	gem.name      = 'win32-sound'
+	gem.version   = '0.4.2'
+	gem.author    = 'Daniel J. Berger'
+   gem.license   = 'Artistic 2.0'
+	gem.email     = 'djberg96@gmail.com'
+	gem.homepage  = 'http://www.rubyforge.org/projects/win32utils'
+	gem.platform  = Gem::Platform::RUBY
+	gem.summary   = 'A library for playing with sound on MS Windows.'
+	gem.test_file = 'test/test_win32_sound.rb'
+	gem.has_rdoc  = true
+   gem.files     = Dir['**/*'].reject{ |f| f.include?('CVS') }
+
 	gem.extra_rdoc_files  = ['CHANGES', 'README', 'MANIFEST']
-	gem.rubyforge_project = "win32utils"
+	gem.rubyforge_project = 'win32utils'
+
+   gem.add_dependency('windows-pr', '>= 1.0.6')
 	
-	files = Dir["doc/*"] + Dir["examples/*"] + Dir["lib/win32/*"]
-	files += Dir["test/*"] + Dir["[A-Z]*"]
-	files.delete_if{ |item| item.include?("CVS") }
-	gem.files = files
+	gem.description = <<-EOF
+      The win32-sound library provides an interface for playing various
+      sounds on MS Windows operating systems, including system sounds and
+      wave files, as well as querying and configuring sound related properties.
+   EOF
 end
 
-if $0 == __FILE__
-   Gem.manage_gems
-   Gem::Builder.new(spec).build
-end
+Gem::Builder.new(spec).build

metadata

@@ -1,58 +1,73 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.2
-specification_version: 1
 name: win32-sound
 version: !ruby/object:Gem::Version 
-  version: 0.4.1
-date: 2007-07-27 00:00:00 -06:00
-summary: A library for playing with sound on MS Windows.
-require_paths: 
-- lib
-email: djberg96@gmail.com
-homepage: http://www.rubyforge.org/projects/win32utils
-rubyforge_project: win32utils
-description: A library for playing with sound on MS 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: 
+  version: 0.4.2
 platform: ruby
-signing_key: 
-cert_chain: 
-post_install_message: 
 authors: 
 - Daniel J. Berger
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-06 00:00:00 -06:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: windows-pr
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.0.6
+    version: 
+description: "      The win32-sound library provides an interface for playing various\n      sounds on MS Windows operating systems, including system sounds and\n      wave files, as well as querying and configuring sound related properties.\n"
+email: djberg96@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- CHANGES
+- README
+- MANIFEST
 files: 
-- examples/sound_test.rb
-- lib/win32/sound.rb
-- test/tc_sound.rb
 - CHANGES
-- examples
-- lib
+- examples/example_win32_sound.rb
+- lib/win32/sound.rb
 - MANIFEST
 - Rakefile
 - README
-- test
+- test/test_win32_sound.rb
 - win32-sound.gemspec
-test_files: 
-- test/tc_sound.rb
+has_rdoc: true
+homepage: http://www.rubyforge.org/projects/win32utils
+licenses: 
+- Artistic 2.0
+post_install_message: 
 rdoc_options: []
 
-extra_rdoc_files: 
-- CHANGES
-- README
-- MANIFEST
-executables: []
-
-extensions: []
-
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
 requirements: []
 
-dependencies: []
-
+rubyforge_project: win32utils
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: A library for playing with sound on MS Windows.
+test_files: 
+- test/test_win32_sound.rb