Class | Rubygame::Music |
In: |
ext/rubygame/rubygame_mixer.c
|
Parent: | Object |
*IMPORTANT*: Music is only available if Rubygame was compiled with SDL_mixer support!
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:
1. Only one Music can be playing. If you try to play a second song, the first one will be stopped. 2. Music doesn't load the entire audio file, so it can begin quickly and doesn't use much memory. This is good, because songs are usually much longer than sound effects!
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.
/* * call-seq: * Music.autoload( filename ) -> Surface or nil * * 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. * */ VALUE rg_music_autoload( VALUE klass, VALUE namev ) { VALUE pathv = rb_funcall( klass, rb_intern("find_file"), 1, namev ); if( RTEST(pathv) ) { return rg_music_load( klass, pathv ); } else { return Qnil; } }
Return the Music which is currently set on the music channel (i.e. was played most recently) or nil if no Music has ever been played.
NOTE: The current Music could be playing, paused, or stopped. Use playing? or stopped? if you want to know whether the current music is still playing.
/* * Return the Music which is currently set on the music channel (i.e. * was played most recently) or nil if no Music has ever been played. * * NOTE: The current Music could be playing, paused, or stopped. Use * #playing? or #stopped? if you want to know whether the current * music is still playing. */ static VALUE rg_music_current( VALUE klass ) { return rb_iv_get( cMusic, "@current_music" ); }
Load the given audio file. Supported file formats are WAVE, MOD, MIDI, OGG, and MP3.
filename: | Full or relative path to the file. (String, required) |
Returns: | The new Music instance. (Music) |
May raise: | SDLError, if the music file could not be loaded. |
/* * call-seq: * load( filename ) -> music * * Load the given audio file. * Supported file formats are WAVE, MOD, MIDI, OGG, and MP3. * * filename:: Full or relative path to the file. (String, required) * * Returns:: The new Music instance. (Music) * May raise:: SDLError, if the music file could not be loaded. * */ static VALUE rg_music_load( VALUE klass, VALUE filename ) { RG_Music *music; VALUE s = rg_music_alloc( cMusic ); Data_Get_Struct( s, RG_Music, music ); char *file = StringValuePtr( filename ); int result = _rg_music_load( music, file ); if( result == -1 ) { rb_raise(eSDLError, "Could not load Music file '%s': %s", file, Mix_GetError()); } return s; }
*NOTE*: Don‘t use this method. Use Music.load.
Raises NotImplementedError.
/* * call-seq: * new * * **NOTE**: Don't use this method. Use Music.load. * * Raises NotImplementedError. * */ static VALUE rg_music_new( int argc, VALUE *ARGV, VALUE self ) { rb_raise(rb_eNotImpError, "Music.new is not implemented. Use Music.load to load a music file."); }
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.
/* * call-seq: * fade_out( fade_time ) -> self * * 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. * */ static VALUE rg_music_fadeout( VALUE self, VALUE fade_time ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); int fade_ms = (int)(1000 * NUM2DBL(fade_time)); if( fade_ms < 0 ) { rb_raise(rb_eArgError, "fade_time cannot be negative (got %.2f)", fade_ms / 1000); } /* Check that the music is current */ if( _rg_music_current_check(self) ) { int result = Mix_FadeOutMusic( fade_ms ); if ( result < 0 ) { rb_raise(eSDLError, "Error fading out music: %s", Mix_GetError()); } } return self; }
True if the Music is currently fading in or out. See also play and fade_out.
direction: | Check if it is fading :in, :out, or :either. (Symbol, required) |
/* * call-seq: * fading?( direction=:either ) -> true or false * * True if the Music is currently fading in or out. * See also #play and #fade_out. * * direction:: Check if it is fading :in, :out, or :either. * (Symbol, required) * */ static VALUE rg_music_fadingp( int argc, VALUE *argv, VALUE self ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); VALUE vdirection; rb_scan_args(argc, argv, "01", &vdirection); /* If the music is not current, return false right away. */ if( !(_rg_music_current_check(self)) ) { return Qfalse; } if( RTEST(vdirection) ) { if( make_symbol("in") == vdirection ) { return ( (Mix_FadingMusic() == MIX_FADING_IN) ? Qtrue : Qfalse ); } else if( make_symbol("out") == vdirection ) { return ( (Mix_FadingMusic() == MIX_FADING_OUT) ? Qtrue : Qfalse ); } else if( make_symbol("either") == vdirection ) { return ( (Mix_FadingMusic() != MIX_NO_FADING) ? Qtrue : Qfalse ); } } /* default */ return ( (Mix_FadingMusic() != MIX_NO_FADING) ? Qtrue : Qfalse ); }
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.
/* * call-seq: * clone( other ) -> music * dup( other ) -> music * * 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. * */ static VALUE rg_music_initialize_copy( VALUE self, VALUE other ) { RG_Music *musicA, *musicB; Data_Get_Struct(self, RG_Music, musicA); Data_Get_Struct(other, RG_Music, musicB); _rg_music_copy( musicA, musicB ); return self; }
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!
/* * call-seq: * jump_to( time ) -> self * * 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! */ static VALUE rg_music_jumpto( VALUE self, VALUE vtime ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); /* Check that the music is current. */ if( _rg_music_current_check(self) ) { /* Only do anything if it's not stopped */ if( !rg_music_stoppedp(self) ) { /* Remember whether it was paused. */ int was_paused = Mix_PausedMusic(); double time = NUM2DBL(vtime); /* in seconds */ if( time < 0 ) { rb_raise(rb_eArgError, "jump_to time cannot be negative (got %d)", time); } int result = Mix_SetMusicPosition( time ); if( result == -1 ) { rb_raise(eSDLError, "Could not jump Music: %s", Mix_GetError()); } /* Pause it again if it was paused before. */ if( was_paused ) { Mix_PauseMusic(); } } } return self; }
Pause the Music. Unlike stop, it can be unpaused later to resume from where it was paused. See also unpause and paused?.
Returns: | The receiver (self). |
*NOTE*: Does nothing if the music is not currently playing.
/* * call-seq: * pause -> self * * Pause the Music. Unlike #stop, it can be unpaused later to resume * from where it was paused. See also #unpause and #paused?. * * Returns:: The receiver (self). * * **NOTE**: Does nothing if the music is not currently playing. * */ static VALUE rg_music_pause( VALUE self ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); /* Check that the music is current. */ if( _rg_music_current_check(self) ) { Mix_PauseMusic(); } return self; }
True if the Music is currently paused (not playing or stopped). See also playing? and stopped?.
/* * call-seq: * paused? -> true or false * * True if the Music is currently paused (not playing or stopped). * See also #playing? and #stopped?. * */ static VALUE rg_music_pausedp( VALUE self ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); /* Check that the music is current. */ if( _rg_music_current_check(self) ) { /* Return true if it's "playing" (not stopped), as well as paused. */ if( Mix_PlayingMusic() && Mix_PausedMusic() ) { return Qtrue; } else { return Qfalse; } } else { return Qfalse; } }
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 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 );
/* * call-seq: * play( options={:fade_in => 0, :repeats => 0, :start_at => 0} ) -> self * * Play the Music, optionally fading in, repeating a certain number * of times (or forever), and/or starting at a certain position in * the song. * * See also #pause and #stop. * * 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 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 ); * */ static VALUE rg_music_play( int argc, VALUE *argv, VALUE self ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); VALUE options; rb_scan_args(argc, argv, "01", &options); int fade_in = 0; int repeats = 1; double start_at = 0; /* If we got some options */ if( RTEST(options) ) { /* Make sure options is a Hash table */ if( TYPE(options) != T_HASH ) { rb_raise(rb_eTypeError, "wrong argument type %s (expected Hash)", rb_obj_classname(options)); } VALUE temp; temp = rb_hash_aref(options, make_symbol("fade_in")); if( RTEST(temp) ) { fade_in = (int)(1000 * NUM2DBL( temp )); if( fade_in < 0 ) { rb_raise(rb_eArgError, ":fade_in cannot be negative (got %.2f)", fade_in / 1000); } else if( fade_in < 50 ) { /* Work-around for a bug with SDL_mixer not working with small non-zero fade-ins */ fade_in = 0; } } temp = rb_hash_aref(options, make_symbol("repeats")); if( RTEST(temp) ) { repeats = NUM2INT(temp); if( repeats > -1 ) { /* Adjust so repeats means the same as it does for Sound */ repeats += 1; } if( repeats < -1 ) { rb_raise(rb_eArgError, ":repeats cannot be negative, except -1 (got %d)", repeats); } } temp = rb_hash_aref(options, make_symbol("start_at")); if( RTEST(temp) ) { start_at = (double)(NUM2DBL( temp )); if( start_at < 0 ) { rb_raise(rb_eArgError, ":start_at cannot be negative (got %.2f)", start_at); } } } int result = _rg_music_play( music, fade_in, repeats, start_at ); if( result == -1 ) { rb_raise(eSDLError, "Could not play Music: %s", Mix_GetError()); } /* This music is now current. */ _rg_music_set_current( self ); return self; }
True if the Music is currently playing (not paused or stopped). See also paused? and stopped?.
/* * call-seq: * playing? -> true or false * * True if the Music is currently playing (not paused or stopped). * See also #paused? and #stopped?. * */ static VALUE rg_music_playingp( VALUE self ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); /* Check that the music is current. */ if( _rg_music_current_check(self) ) { /* Return true if music is playing, but not paused. */ if( Mix_PlayingMusic() && !Mix_PausedMusic() ) { return Qtrue; } else { return Qfalse; } } else { return Qfalse; } }
Rewind the Music to the beginning. If the Music was paused, it will still be paused after the rewind. Does nothing if the Music is stopped.
/* * call-seq: * rewind -> self * * Rewind the Music to the beginning. If the Music was paused, it * will still be paused after the rewind. Does nothing if the Music * is stopped. */ static VALUE rg_music_rewind( VALUE self ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); /* Check that the music is current. */ if( _rg_music_current_check(self) ) { /* Only do anything if it's not stopped */ if( !rg_music_stoppedp(self) ) { /* Remember whether it was paused. */ int was_paused = Mix_PausedMusic(); /* * Rather than using SDL_mixer's crippled Mix_RewindMusic, * which only works for a few file types, we'll just stop and * start the music again from the beginning. */ Mix_HaltMusic(); int result = Mix_PlayMusic(music->wrap->music, music->repeats); if( result == -1 ) { rb_raise(eSDLError, "Could not rewind Music: %s", Mix_GetError()); } /* Pause it again if it was paused before. */ if( was_paused ) { Mix_PauseMusic(); } } } return self; }
Stop the Music. Unlike pause, the music must be played again from the beginning, it cannot be resumed from it was stopped.
Returns: | The receiver (self). |
*NOTE*: Does nothing if the music is not currently playing or paused.
/* * call-seq: * stop -> self * * Stop the Music. Unlike #pause, the music must be played again from * the beginning, it cannot be resumed from it was stopped. * * Returns:: The receiver (self). * * **NOTE**: Does nothing if the music is not currently playing or paused. * */ static VALUE rg_music_stop( VALUE self ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); /* Check that the music is current. */ if( _rg_music_current_check(self) ) { Mix_HaltMusic(); } return self; }
True if the Music is currently stopped (not playing or paused). See also playing? and paused?.
/* * call-seq: * stopped? -> true or false * * True if the Music is currently stopped (not playing or paused). * See also #playing? and #paused?. * */ static VALUE rg_music_stoppedp( VALUE self ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); /* Check that the music is current. */ if( _rg_music_current_check(self) ) { /* Return true if it's not playing. */ if( !Mix_PlayingMusic() ) { return Qtrue; } else { return Qfalse; } } else { return Qtrue; } }
Unpause the Music, if it is currently paused. Resumes from where it was paused. See also pause and paused?.
Returns: | The receiver (self). |
*NOTE*: Does nothing if the music is not currently paused.
/* * call-seq: * unpause -> self * * Unpause the Music, if it is currently paused. Resumes from * where it was paused. See also #pause and #paused?. * * Returns:: The receiver (self). * * **NOTE**: Does nothing if the music is not currently paused. * */ static VALUE rg_music_unpause( VALUE self ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); /* Check that the music is current. */ if( _rg_music_current_check(self) ) { Mix_ResumeMusic(); } return self; }
Return the volume level of the music. 0.0 is totally silent, 1.0 is full volume.
*NOTE*: Ignores fading in or out.
/* * call-seq: * volume -> vol * * Return the volume level of the music. * 0.0 is totally silent, 1.0 is full volume. * * **NOTE**: Ignores fading in or out. * */ static VALUE rg_music_getvolume( VALUE self ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); return rb_float_new(music->volume); }
Set the new volume level of the music. 0.0 is totally silent, 1.0 is full volume.
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. |
/* * call-seq: * volume = new_vol * * Set the new #volume level of the music. * 0.0 is totally silent, 1.0 is full volume. * * 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. * */ static VALUE rg_music_setvolume( VALUE self, VALUE volume ) { RG_Music *music; Data_Get_Struct(self, RG_Music, music); /* If the music is current, we'll change the current volume. */ if( _rg_music_current_check(self) ) { /* But only if it's not fading right now. */ if( Mix_FadingMusic() == MIX_NO_FADING ) { music->volume = NUM2DBL(volume); Mix_VolumeMusic( (int)(MIX_MAX_VOLUME * music->volume) ); } else { rb_raise(eSDLError, "cannot set Music volume while fading"); } } else { /* Save it for later. */ music->volume = NUM2DBL(volume); } return volume; }