win32-sound 0.4.3-universal-mswin32

data/CHANGES

@@ -0,0 +1,56 @@
+== 0.4.3 - 21-May-2011
+* Refactored Rakefile, removing an old gem install task and adding a
+  default task and a clean task.
+* Altered the gemspec, including a platform change to 'universal-win32', and
+  removed a deprecated specification method.
+
+== 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.
+* Removed the install.rb file. Installation is now handled via a rake task.
+* Documentation updates.
+
+== 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,8 @@
+* MANIFEST
+* CHANGES
+* README
+* Rakefile
+* win32-sound.gempsec
+* examples/sound_test.rb
+* lib/win32/sound.rb
+* test/tc_sound.rb

data/README

@@ -0,0 +1,63 @@
+== Description
+   A library for playing and controlling sounds on MS Windows.
+
+== Prerequisites
+   * 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)
+
+== Synopsis
+   require 'win32/sound'
+   include Win32
+
+   # Play a wav file
+   Sound.play("somefile.wav")
+
+   # Play a system sound
+   Sound.play("SystemAsterisk",Sound::ALIAS)
+
+   # 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
+   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 this:
+   Sound.play("SystemAsterisk", Sound::ALIAS).
+	
+== License
+   Artistic 2.0
+
+== Copyright
+   (C) 2004-2009, 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
+   Park Heesob

data/Rakefile

@@ -0,0 +1,31 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/clean'
+
+CLEAN.include("**/*.gem", "**/*.rbc")
+
+namespace :gem do
+  desc "Create the win32-sound gem"
+  task :create => [:clean] do
+    spec = eval(IO.read("win32-sound.gemspec"))
+    Gem::Builder.new(spec).build
+  end
+
+  desc "Install the win32-sound library"
+  task :install => [:create] do
+    file = Dir["*.gem"].first
+    sh "gem install #{file}"
+  end
+end
+
+desc 'Run the example program'
+task :example do
+  ruby '-Ilib examples\example_win32_sound.rb'
+end
+
+Rake::TestTask.new do |t|
+  t.warning = true
+  t.verbose = true
+end
+
+task :default => :test

data/examples/example_win32_sound.rb

@@ -0,0 +1,48 @@
+#######################################################################
+# example_win32_sound.rb (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"
+
+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,211 @@
+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
+
+    include Windows::Sound
+    include Windows::Error
+    extend Windows::Sound
+    extend Windows::Error
+
+    # The version of the win32-sound library
+    VERSION = '0.4.3'
+
+    LOW_FREQUENCY  = 37
+    HIGH_FREQUENCY = 32767
+    MAX_VOLUME     = 0xFFFF
+
+    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
+    # are WAVEOUT, WAVEIN, MIDIOUT, MIDIIN, AUX or MIXER.
+    #
+    def self.devices
+      devs = []
+
+      begin
+        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
+
+      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 Error, 'invalid frequency'
+      end
+
+      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.
+    #
+    def self.stop(purge = false)
+      if purge && purge != 0
+        flags = PURGE
+      else
+        flags = 0
+      end
+
+      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
+    # 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.
+    #
+    # 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)
+      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+
+    # 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(-1, volume) != 0
+        raise Error, 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(-1, volume) != 0
+        raise Error, get_last_error
+      end
+      volume = volume.unpack('L').first
+      [low_word(volume), high_word(volume)]
+    end
+
+    class << self
+      alias get_wave_volume wave_volume
+    end
+
+    private
+
+    def self.low_word(num)
+      num & 0xFFFF
+    end
+
+    def self.high_word(num)
+      num >> 16
+    end
+  end
+end

data/test/test_win32_sound.rb

@@ -0,0 +1,91 @@
+##########################################################################
+# test_win32_sound.rb
+#
+# Test suite for the win32-sound library. You should run this test case
+# via the 'rake test' task.
+##########################################################################
+require 'test/unit'
+require 'win32/sound'
+include Win32
+
+class TC_Win32_Sound < Test::Unit::TestCase
+  def setup
+    @wav = "c:\\windows\\media\\chimes.wav"
+  end
+
+  def test_version
+    assert_equal('0.4.3', Sound::VERSION)
+  end
+
+  def test_beep
+    assert_respond_to(Sound, :beep)
+    assert_nothing_raised{ Sound.beep(55, 100) }
+  end
+
+  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) }
+  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_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
+
+  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) }
+  end
+
+  def test_play_alias
+    assert_nothing_raised{ Sound.play('SystemAsterisk', Sound::ALIAS) }
+  end
+
+  def test_expected_errors
+    assert_raises(Sound::Error){ 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

data/win32-sound.gemspec

@@ -0,0 +1,25 @@
+require 'rubygems'
+
+Gem::Specification.new do |spec|
+  spec.name      = 'win32-sound'
+  spec.version   = '0.4.3'
+  spec.author    = 'Daniel J. Berger'
+  spec.license   = 'Artistic 2.0'
+  spec.email     = 'djberg96@gmail.com'
+  spec.homepage  = 'http://www.rubyforge.org/projects/win32utils'
+  spec.platform  = Gem::Platform.new('universal-mswin32')
+  spec.summary   = 'A library for playing with sound on MS Windows.'
+  spec.test_file = 'test/test_win32_sound.rb'
+  spec.files     = Dir['**/*'] << ".gemtest"
+
+  spec.extra_rdoc_files  = ['CHANGES', 'README', 'MANIFEST']
+  spec.rubyforge_project = 'win32utils'
+
+  spec.add_dependency('windows-pr', '>= 1.0.6')
+
+  spec.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

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification 
+name: win32-sound
+version: !ruby/object:Gem::Version 
+  hash: 9
+  prerelease: 
+  segments: 
+  - 0
+  - 4
+  - 3
+  version: 0.4.3
+platform: universal-mswin32
+authors: 
+- Daniel J. Berger
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-05-21 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: windows-pr
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 0
+        - 6
+        version: 1.0.6
+  type: :runtime
+  version_requirements: *id001
+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: 
+- CHANGES
+- examples/example_win32_sound.rb
+- lib/win32/sound.rb
+- MANIFEST
+- Rakefile
+- README
+- test/test_win32_sound.rb
+- win32-sound.gemspec
+- .gemtest
+homepage: http://www.rubyforge.org/projects/win32utils
+licenses: 
+- Artistic 2.0
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: win32utils
+rubygems_version: 1.8.2
+signing_key: 
+specification_version: 3
+summary: A library for playing with sound on MS Windows.
+test_files: 
+- test/test_win32_sound.rb