Class | Rubygame::Sound |
In: |
lib/rubygame/sound.rb
lib/rubygame/sound.rb |
Parent: | Object |
IMPORTANT: this class only exists if SDL_mixer is available! Your code should check "defined?(Rubygame::Sound) != nil" to see if you can use this class, or be prepared to rescue from NameError.
Sound holds a sound effect, loaded from an audio file (see load for supported formats).
Sound can play, pause/unpause, stop, adjust volume, and fade_out (you can fade in by passing an option to play).
Sound can create duplicates (with dup or clone) in a memory-efficient way — the new Sound instance refers back to the same audio data, so having 100 duplicates of a sound uses only slightly more memory than having the first sound. Duplicates can different volume levels, too!
Sound includes the Rubygame::NamedResource mixin module, which can perform autoloading of sounds on demand, among other things.
Searches each directory in Sound.autoload_dirs for a file with the given filename. If it finds that file, loads it and returns a Sound instance. If it doesn‘t find the file, returns nil.
See Rubygame::NamedResource for more information about this functionality.
Searches each directory in Sound.autoload_dirs for a file with the given filename. If it finds that file, loads it and returns a Sound instance. If it doesn‘t find the file, returns nil.
See Rubygame::NamedResource for more information about this functionality.
Fade out to silence over the given number of seconds. Once the sound is silent, it is automatically stopped.
Returns: | The receiver (self). |
*NOTE*: If the sound is currently paused, the fade will start, but you won‘t be able to hear it happening unless you unpause during the fade.
Does nothing if the sound is currently stopped.
Fade out to silence over the given number of seconds. Once the sound is silent, it is automatically stopped.
Returns: | The receiver (self). |
*NOTE*: If the sound is currently paused, the fade will start, but you won‘t be able to hear it happening unless you unpause during the fade.
Does nothing if the sound is currently stopped.
Create a copy of the given Sound instance. More efficient than using load to load the sound file again.
other: | An existing Sound instance. (Sound, required) |
Returns: | The new Sound instance. (Sound) |
*NOTE*: clone and dup do slightly different things; clone will copy the ‘frozen’ state of the object, while dup will create a fresh, un-frozen object.
Create a copy of the given Sound instance. More efficient than using load to load the sound file again.
other: | An existing Sound instance. (Sound, required) |
Returns: | The new Sound instance. (Sound) |
*NOTE*: clone and dup do slightly different things; clone will copy the ‘frozen’ state of the object, while dup will create a fresh, un-frozen object.
True if the Sound is currently paused (not playing and not stopped). See also playing? and stopped?.
True if the Sound is currently paused (not playing and not stopped). See also playing? and stopped?.
Play the Sound, optionally fading in, repeating a certain number of times (or forever), and/or stopping automatically after a certain time.
options: | Hash of options, listed below. (Hash, required) |
:fade_in:: Fade in from silence over the given number of seconds. Default: 0. (Numeric, optional) :repeats:: Repeat the sound the given number of times, or forever (or until stopped) if -1. Default: 0. (Integer, optional) :stop_after:: Automatically stop playing after playing for the given number of seconds. Use nil to disable this behavior. (Numeric or nil, optional)
Returns: | The receiver (self). |
May raise: | SDLError, if the audio device could not be opened, or if the sound file could not be played. |
*NOTE*: If the sound is already playing (or paused), it will be stopped and played again from the beginning.
Example:
# Fade in over 2 seconds, play 4 times (1 + 3 repeats), # but stop playing after 5 seconds. sound.play( :fade_in => 2, :repeats => 3, :stop_after => 5 );
Play the Sound, optionally fading in, repeating a certain number of times (or forever), and/or stopping automatically after a certain time.
options: | Hash of options, listed below. (Hash, required) |
:fade_in:: Fade in from silence over the given number of seconds. Default: 0. (Numeric, optional) :repeats:: Repeat the sound the given number of times, or forever (or until stopped) if -1. Default: 0. (Integer, optional) :stop_after:: Automatically stop playing after playing for the given number of seconds. Use nil to disable this behavior. (Numeric or nil, optional)
Returns: | The receiver (self). |
May raise: | SDLError, if the audio device could not be opened, or if the sound file could not be played. |
*NOTE*: If the sound is already playing (or paused), it will be stopped and played again from the beginning.
Example:
# Fade in over 2 seconds, play 4 times (1 + 3 repeats), # but stop playing after 5 seconds. sound.play( :fade_in => 2, :repeats => 3, :stop_after => 5 );
True if the Sound is currently playing (not paused and not stopped). See also paused? and stopped?.
True if the Sound is currently playing (not paused and not stopped). See also paused? and stopped?.
True if the Sound is currently stopped (not playing and not paused). See also playing? and paused?.
True if the Sound is currently stopped (not playing and not paused). See also playing? and paused?.
Set the new volume level of the sound. 0.0 is totally silent, 1.0 is full volume. The new volume will be clamped to this range if it is too small or too large.
Volume cannot be set while the sound is fading in or out. Be sure to check fading? or rescue from SDLError when using this method.
May raise: | SDLError if the sound is fading in or out. |
Set the new volume level of the sound. 0.0 is totally silent, 1.0 is full volume. The new volume will be clamped to this range if it is too small or too large.
Volume cannot be set while the sound is fading in or out. Be sure to check fading? or rescue from SDLError when using this method.
May raise: | SDLError if the sound is fading in or out. |