Class | Rubygame::Music |
In: |
lib/rubygame/music.rb
lib/rubygame/music.rb |
Parent: | Object |
IMPORTANT: this class only exists if SDL_mixer is available! Your code should check "defined?(Rubygame::Music) != nil" to see if you can use this class, or be prepared to rescue from NameError.
Music holds a song, streamed from an audio file (see load for supported formats). There are two important differences between the Music and Sound classes:
Music can play, pause/unpause, stop, rewind, jump_to another time, adjust volume, and fade_out (fade in by passing an option to play).
Music includes the Rubygame::NamedResource mixin module, which can perform autoloading of music on demand, among other things.
Searches each directory in Music.autoload_dirs for a file with the given filename. If it finds that file, loads it and returns a Music instance. If it doesn‘t find the file, returns nil.
See Rubygame::NamedResource for more information about this functionality.
Searches each directory in Music.autoload_dirs for a file with the given filename. If it finds that file, loads it and returns a Music 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 music is silent, it is automatically stopped.
Returns: | The receiver (self). |
*NOTE*: If the music 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 music is currently stopped.
Fade out to silence over the given number of seconds. Once the music is silent, it is automatically stopped.
Returns: | The receiver (self). |
*NOTE*: If the music 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 music is currently stopped.
Create a copy of the given Music instance. More efficient than using load to load the music file again.
other: | An existing Music instance. (Music, required) |
Returns: | The new Music instance. (Music) |
*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 Music instance. More efficient than using load to load the music file again.
other: | An existing Music instance. (Music, required) |
Returns: | The new Music instance. (Music) |
*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.
Jump to any time in the Music, in seconds since the beginning. If the Music was paused, it will still be paused again after the jump. Does nothing if the Music was stopped.
*NOTE*: Only works for OGG and MP3 formats! Other formats (e.g. WAV) will usually raise SDLError.
time: | the time to jump to, in seconds since the beginning of the song. (Numeric, required) |
May raise: | SDLError if something goes wrong, or if the music type does not support jumping. |
*CAUTION*: This method may be unreliable (and could even crash!) if you jump to a time after the end of the song. Unfortunately, SDL_Mixer does not provide a way to find the song‘s length, so Rubygame cannot warn you if you go off the end. Be careful!
Jump to any time in the Music, in seconds since the beginning. If the Music was paused, it will still be paused again after the jump. Does nothing if the Music was stopped.
*NOTE*: Only works for OGG and MP3 formats! Other formats (e.g. WAV) will usually raise SDLError.
time: | the time to jump to, in seconds since the beginning of the song. (Numeric, required) |
May raise: | SDLError if something goes wrong, or if the music type does not support jumping. |
*CAUTION*: This method may be unreliable (and could even crash!) if you jump to a time after the end of the song. Unfortunately, SDL_Mixer does not provide a way to find the song‘s length, so Rubygame cannot warn you if you go off the end. Be careful!
True if the Music is currently paused (not playing and not stopped). See also playing? and stopped?.
True if the Music is currently paused (not playing and not stopped). See also playing? and stopped?.
Play the Music, optionally fading in, repeating a certain number of times (or forever), and/or starting at a certain position in the song.
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 music the given number of times, or forever (or until stopped) if -1. Default: 0. (Integer, optional) :start_at:: Start playing the music at the given time in the song, in seconds. Default: 0. (Numeric, optional) **NOTE**: Non-zero start times only work for OGG and MP3 formats! Please refer to #jump.
Returns: | The receiver (self). |
May raise: | SDLError, if the audio device could not be opened, or if the music file could not be played, or if you used :start_at with an unsupported format. |
*NOTE*: Only one music can be playing at once. If any music is already playing (or paused), it will be stopped before playing the new music.
Example:
# Fade in over 2 seconds, play 4 times (1 + 3 repeats), # starting at 60 seconds since the beginning of the song. music.play( :fade_in => 2, :repeats => 3, :start_at => 60 );
Play the Music, optionally fading in, repeating a certain number of times (or forever), and/or starting at a certain position in the song.
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 music the given number of times, or forever (or until stopped) if -1. Default: 0. (Integer, optional) :start_at:: Start playing the music at the given time in the song, in seconds. Default: 0. (Numeric, optional) **NOTE**: Non-zero start times only work for OGG and MP3 formats! Please refer to #jump.
Returns: | The receiver (self). |
May raise: | SDLError, if the audio device could not be opened, or if the music file could not be played, or if you used :start_at with an unsupported format. |
*NOTE*: Only one music can be playing at once. If any music is already playing (or paused), it will be stopped before playing the new music.
Example:
# Fade in over 2 seconds, play 4 times (1 + 3 repeats), # starting at 60 seconds since the beginning of the song. music.play( :fade_in => 2, :repeats => 3, :start_at => 60 );
True if the Music is currently playing (not paused and not stopped). See also paused? and stopped?.
True if the Music is currently playing (not paused and not stopped). See also paused? and stopped?.
True if the Music is currently stopped (not playing and not paused). See also playing? and paused?.
True if the Music is currently stopped (not playing and not paused). See also playing? and paused?.
Set the new volume level of the music. 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 music is fading in or out. Be sure to check fading? or rescue from SDLError when using this method.
May raise: | SDLError if the music is fading in or out. |
Set the new volume level of the music. 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 music is fading in or out. Be sure to check fading? or rescue from SDLError when using this method.
May raise: | SDLError if the music is fading in or out. |