Class: Win32::Sound

Inherits:
Object
  • Object
show all
Extended by:
FFI::Library
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.

Constant Summary collapse

VERSION =

The version of the win32-sound library

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

play synchronously (default)

0x00000000
ASYNC =

play asynchronously

0x00000001
NODEFAULT =

silence (!default) if sound not found

0x00000002
MEMORY =

pszSound points to a memory file

0x00000004
LOOP =

loop the sound until next sndPlaySound

0x00000008
NOSTOP =

don’t stop any currently playing sound

0x00000010
NOWAIT =

don’t wait if the driver is busy

8192
ALIAS =

name is a registry alias

65536
ALIAS_ID =

alias is a predefined ID

1114112
FILENAME =

name is file name

131072
RESOURCE =

name is resource name or atom

262148
PURGE =

purge non-static events for task

0x00000040
APPLICATION =

look for app specific association

0x00000080

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.



87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/win32/sound.rb', line 87

def self.beep(frequency, duration)
  if frequency > HIGH_FREQUENCY || frequency < LOW_FREQUENCY
    raise ArgumentError, 'invalid frequency'
  end

  if 0 == Beep(frequency, duration)
    raise SystemCallError, FFI.errno, "Beep"
  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.



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

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 SystemCallError, FFI.errno, "GetNumDevs"
  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



176
177
178
179
180
181
182
 
# File 'lib/win32/sound.rb', line 176

def self.play(sound, flags = 0)
  unless PlaySound(sound, 0, flags)
    raise SystemCallError, FFI.errno, "PlaySound"
  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.



190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/win32/sound.rb', line 190

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 SystemCallError, FFI.errno, "waveOutSetVolume"
  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.



102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/win32/sound.rb', line 102

def self.stop(purge = false)
  if purge && purge != 0
    flags = PURGE
  else
    flags = 0
  end

  unless PlaySound(nil, 0, flags)
    raise SystemCallError, FFI.errno, "PlaySound"
  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.



207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/win32/sound.rb', line 207

def self.wave_volume
  ptr = FFI::MemoryPointer.new(:ulong)

  if waveOutGetVolume(-1, ptr) != 0
    raise SystemCallError, FFI.errno, "waveOutGetVolume"
  end

  volume = ptr.read_long

  [low_word(volume), high_word(volume)]
end