Class: Win32::Sound

Inherits:
Object
  • Object
show all
Extended by:
Windows::Error, Windows::Sound
Includes:
Windows::Error, Windows::Sound
Defined in:
lib/win32/sound.rb

Overview

The Sound class encapsulates various methods for playing sound as well as querying or configuring sound related properties.

Defined Under Namespace

Classes: Error

Constant Summary collapse

VERSION =

The version of the win32-sound library

'0.4.2'
LOW_FREQUENCY = 
37
HIGH_FREQUENCY = 
32767
MAX_VOLUME = 
0xFFFF
SYNC =

play synchronously (default)

SND_SYNC
ASYNC =

play asynchronously

SND_ASYNC
NODEFAULT =

silence (!default) if sound not found

SND_NODEFAULT
MEMORY =

pszSound points to a memory file

SND_MEMORY
LOOP =

loop the sound until next sndPlaySound

SND_LOOP
NOSTOP =

don’t stop any currently playing sound

SND_NOSTOP
NOWAIT =

don’t wait if the driver is busy

SND_NOWAIT
ALIAS =

name is a registry alias

SND_ALIAS
ALIAS_ID =

alias is a predefined ID

SND_ALIAS_ID
FILENAME =

name is file name

SND_FILENAME
RESOURCE =

name is resource name or atom

SND_RESOURCE
PURGE =

purge non-static events for task

SND_PURGE
APPLICATION =

look for app specific association

SND_APPLICATION

Class Method Summary collapse

Class Method Details

.beep(frequency, duration) ⇒ Object

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.



68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/win32/sound.rb', line 68

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

.devices ⇒ Object

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.



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/win32/sound.rb', line 45

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

.play(sound, flags = 0) ⇒ Object

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



157
158
159
160
161
162
163
 
# File 'lib/win32/sound.rb', line 157

def self.play(sound, flags = 0)
   unless PlaySound(sound, 0, flags)
      raise Error, get_last_error
   end

   self
end

.set_wave_volume(left_channel, right_channel = nil) ⇒ Object

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.



171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/win32/sound.rb', line 171

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

.stop(purge = false) ⇒ Object

Stops any currently playing waveform sound. If purge is set to true, then all sounds are stopped. The default is false.



83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/win32/sound.rb', line 83

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

.wave_volume ⇒ Object Also known as: get_wave_volume

Returns a 2-element array that contains the volume for the left channel and right channel, respectively.



188
189
190
191
192
193
194
195
 
# File 'lib/win32/sound.rb', line 188

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