Class Rubygame::Mixer::Music
In: ext/rubygame/rubygame_mixer.c
Parent: Object

**NOTE:** This class is DEPRECATED and will be removed in Rubygame 3.0. Please use the Rubygame::Music class instead.

The Music class is used for playing music from a file. It supports WAVE, MOD, MIDI, OGG, and MP3 files. There are two important differences between Music and Sample:

  1. Music streams the music from disk, which means it can start faster and uses less memory than Sample, which loads the entire file into memory. This is especially important for music files, which are often several minutes long.
  2. There can only be one Music instance playing at once, while there can be many Samples playing at once. If you play a second Music while one is already playing, the first one will be stopped. See play.

Methods

fade_in   fade_out   fading?   jump   load_audio   pause   paused?   play   playing?   resume   rewind   stop   volume   volume=  

Public Class methods

**NOTE:** Rubygame::Mixer::Music is DEPRECATED and will be removed in Rubygame 3.0. Please use the Rubygame::Music class instead.

Load music from a file. Supports WAVE, MOD, MIDI, OGG, and MP3 formats.

Raises SDLError if the music could not be loaded.

[Source]

/* call-seq:
 *  load_audio( filename )  ->  Music
 *
 *  **NOTE:** Rubygame::Mixer::Music is DEPRECATED and will be removed
 *  in Rubygame 3.0. Please use the Rubygame::Music class instead.
 *
 *  Load music from a file. Supports WAVE, MOD, MIDI, OGG, and MP3 formats.
 *
 *  Raises SDLError if the music could not be loaded.
 */
VALUE rbgm_mixmusic_new(VALUE class, VALUE filev)
{

  /* This feature will be removed in Rubygame 3.0. */
  rg_deprecated("Rubygame::Mixer::Music", "3.0");

  VALUE self;
  Mix_Music* music;

  music = Mix_LoadMUS( StringValuePtr(filev) );

  if( music == NULL )
  { 
    rb_raise(eSDLError, "Error loading audio music from file `%s': %s",
             StringValuePtr(filev), Mix_GetError());
  }
        self = Data_Wrap_Struct( cOldMusic, 0, Mix_FreeMusic, music );

        //rb_obj_call_init(self,argc,argv);

  return self;
}

Public Instance methods

Play the music, fading in and repeating a certain number of times. See also play.

Raises SDLError if something goes wrong.

fade_time:Time in seconds for the fade-in effect to complete.
repeats:Number of extra times to play through the music. -1 plays the music forever until it is stopped. Defaults to 0, play only once (no repeats).
start:Time to start from, in seconds since the beginning. Defaults to 0, the beginning of the song. Non-zero values only work for OGG and MP3; other music types will raise SDLError.

[Source]

/*  call-seq:
 *     fade_in( fade_time, repeats=0, start=0 )  ->  self
 *
 *  Play the music, fading in and repeating a certain number of times.
 *  See also #play.
 *
 *  Raises SDLError if something goes wrong.
 *  
 *  fade_time::  Time in seconds for the fade-in effect to complete.
 *  repeats::    Number of extra times to play through the music.
 *               -1 plays the music forever until it is stopped.
 *               Defaults to 0, play only once (no repeats).
 *  start::      Time to start from, in seconds since the beginning.
 *               Defaults to 0, the beginning of the song.
 *               Non-zero values only work for OGG and MP3; other
 *               music types will raise SDLError.
 */
VALUE rbgm_mixmusic_fadein(int argc, VALUE *argv, VALUE self)
{
  VALUE fadev, repsv, startv;
  rb_scan_args(argc, argv, "12", &fadev, &repsv, &startv);

  Mix_Music* music;
  Data_Get_Struct( self, Mix_Music, music );

  int fade, reps, result;
  fade = (int)(NUM2DBL(fadev) * 1000); /* convert to milliseconds */

  if( RTEST(repsv) )
  {
    reps = NUM2INT(repsv);
  }
  else
  {
    reps = 0;
  }

  if( reps > -1 )
  {
    /* Adjust so repeats means the same as it does for Samples */
    reps += 1;
  }
  
  if( !RTEST(startv) || NUM2DBL(startv) == 0.0 )
  {
                result = Mix_FadeInMusic(music, reps, fade);
  }
  else
        {
    result = Mix_FadeInMusicPos(music, reps, fade, NUM2DBL(startv));
  }

  if( result < 0 )
  {
    rb_raise(eSDLError, "Error fading in music: %s", Mix_GetError());
  }

  return self;
}

Gradually fade the music to silence over fade_length seconds. After the fade is complete, the music will be automatically stopped.

Raises SDLError if something goes wrong.

fade_time:Time until the music is totally silent, in seconds.

[Source]

/*  call-seq:
 *     fade_out( fade_time )  ->  self
 *
 *  Gradually fade the music to silence over +fade_length+ seconds.
 *  After the fade is complete, the music will be automatically stopped.
 *
 *  Raises SDLError if something goes wrong.
 *
 *  fade_time::    Time until the music is totally silent, in seconds.
 */
VALUE rbgm_mixmusic_fadeout(VALUE self, VALUE fadev)
{
  int fade = (int)(NUM2DBL(fadev) * 1000);
  int result = Mix_FadeOutMusic(fade);

  if ( result < 0 )
  {
    rb_raise(eSDLError, "Error fading out music: %s", Mix_GetError());
  }
  return self;
}

True if the music is fading in or out (or either). You can specify direction as :in/:out to check only fading in/out; otherwise, it will return true if it‘s fading either way.

direction::in, :out, or nil if you don‘t care which.
Returns:true if the music is fading in the given direction.

[Source]

/*  call-seq:
 *     fading?( direction = nil )  ->  true or false
 *
 *  True if the music is fading in or out (or either). You can
 *  specify +direction+ as :in/:out to check only fading in/out;
 *  otherwise, it will return true if it's fading either way.
 *
 *  direction::  :in, :out, or nil if you don't care which.
 *  Returns::    true if the music is fading in the given direction.
 */
VALUE rbgm_mixmusic_fading(int argc, VALUE *argv, VALUE self)
{
  VALUE dirv;
  rb_scan_args(argc, argv, "01", &dirv);

  if( dirv == make_symbol("in") )
  {
    return ( (Mix_FadingMusic() == MIX_FADING_IN)  ? Qtrue : Qfalse );
  }
  else if( dirv == make_symbol("out") )
  {
    return ( (Mix_FadingMusic() == MIX_FADING_OUT) ? Qtrue : Qfalse );
  }
  else
  {
    return ( (Mix_FadingMusic() != MIX_NO_FADING)  ? Qtrue : Qfalse );
  }
}

Jump to a certain time in the music. Only works when music is playing or paused (but not stopped). Only works for OGG and MP3 files.

Raises SDLError if something goes wrong, or if the music type does not support setting the position.

time:Time to jump to, in seconds from the beginning.

[Source]

/*  call-seq:
 *     jump( time )  ->  self
 *
 *  Jump to a certain time in the music.
 *  Only works when music is playing or paused (but not stopped).
 *  Only works for OGG and MP3 files.
 *
 *  Raises SDLError if something goes wrong, or if the music type does not
 *  support setting the position.
 *
 *  time::  Time to jump to, in seconds from the beginning.
 *
 */
VALUE rbgm_mixmusic_jump(VALUE self, VALUE vtime)
{
  double time = NUM2DBL(vtime);

  switch( Mix_GetMusicType(NULL) )
        {
    case MUS_OGG:
    case MUS_MP3:
      Mix_RewindMusic(); // Needed for MP3, and OK with OGG

      int result = Mix_SetMusicPosition(time);
      if( result < 0 )
      {
        rb_raise(eSDLError, "Error jumping to time in music: %s", Mix_GetError());
      }

      return self;

    case MUS_NONE:
      rb_raise(eSDLError, "Cannot jump when no music is playing.");

    default:
      rb_raise(eSDLError, "Music type does not support jumping.");
  }
}

Pause playback of the playing music. You can later resume playback from the point where you paused. Safe to use on already-paused music. See also play_music.

[Source]

/*  call-seq:
 *     pause()  -> self
 *
 *  Pause playback of the playing music. You can later #resume
 *  playback from the point where you paused.
 *  Safe to use on already-paused music.
 *  See also #play_music.
 */
VALUE rbgm_mixmusic_pause(VALUE self)
{
  Mix_PauseMusic();
  return self;
}

Returns true if the music is currently paused.

[Source]

/*  call-seq:
 *     paused?  ->  true or false
 *
 *  Returns true if the music is currently paused.
 *
 */
VALUE rbgm_mixmusic_paused(VALUE self)
{
  return Mix_PausedMusic() ? Qtrue : Qfalse;
}

Play music, repeating a certain number of extra times. If any music was already playing, that music will be stopped first, and this music will start.

Raises SDLError if something goes wrong.

This method takes these arguments:

repeats:how many extra times to play the music. Can be -1 to repeat forever until it is stopped.

[Source]

/*  call-seq:
 *     play( repeats = 0 )  ->  self
 *
 *  Play music, repeating a certain number of extra times. If
 *  any music was already playing, that music will be stopped
 *  first, and this music will start.
 *
 *  Raises SDLError if something goes wrong.
 *  
 *  This method takes these arguments:
 *  repeats::     how many extra times to play the music.
 *                Can be -1 to repeat forever until it is stopped.
 */
VALUE rbgm_mixmusic_play(int argc, VALUE *argv, VALUE self)
{
  Mix_Music* music;
  int reps, result;
  VALUE repsv;

  Data_Get_Struct( self, Mix_Music, music );

  rb_scan_args(argc, argv, "01", &repsv);

  if( RTEST(repsv) )
  {
    reps = NUM2INT(repsv);
  }
  else
  {
    reps = 0;
  }
  
  if( reps > -1 )
  {
    /* Adjust so repeats means the same as it does for Samples */
    reps += 1;
  }
  
  result = Mix_PlayMusic(music, reps);

  if ( result < 0 )
  {
    rb_raise(eSDLError, "Error playing music: %s", 
             Mix_GetError());
  }

  return self;
}

Returns true if the music is currently playing.

[Source]

/*  call-seq:
 *     playing?  ->  true or false
 *
 *  Returns true if the music is currently playing.
 *
 */
VALUE rbgm_mixmusic_playing(VALUE self)
{
  return Mix_PlayingMusic() ? Qtrue : Qfalse;
}

Resume playback of paused music from the point it was paused. Safe to use on already-playing music. See also play.

[Source]

/*  call-seq:
 *     resume()  ->  self
 *
 *  Resume playback of paused music from the point it was paused.
 *  Safe to use on already-playing music.
 *  See also #play.
 */
VALUE rbgm_mixmusic_resume(VALUE self)
{
  Mix_ResumeMusic();
  return self;
}

Rewind the music to the start. This is safe to use on stopped, paused, and playing music. Only works for MOD, OGG, MP3, and MIDI (but not WAV).

[Source]

/*  call-seq:
 *     rewind()  ->  self
 *
 *  Rewind the music to the start. This is safe to use on stopped, paused, and playing music. 
 *  Only works for MOD, OGG, MP3, and MIDI (but not WAV).
 * 
 */
VALUE rbgm_mixmusic_rewind(VALUE self)
{
  Mix_RewindMusic();
  return self;
}

Stop playback of music. See also play

[Source]

/*  call-seq:
 *     stop()  -> self
 *
 *  Stop playback of music. 
 *  See also #play
 */
VALUE rbgm_mixmusic_stop(VALUE self)
{
  Mix_HaltMusic();
  return self;
}

Returns the current volume level of the music. 0.0 is total silence, 1.0 is maximum volume.

[Source]

/*  call-seq:
 *     volume
 *
 *  Returns the current volume level of the music.
 *  0.0 is total silence, 1.0 is maximum volume.
 */
VALUE rbgm_mixmusic_getvolume(VALUE self)
{
  return rb_float_new( (double)(Mix_VolumeMusic(-1)) / MIX_MAX_VOLUME );
}

Sets the volume level of the music. 0.0 is total silence, 1.0 is maximum volume.

[Source]

/*  call-seq:
 *     volume = new_volume
 *
 *  Sets the volume level of the music.
 *  0.0 is total silence, 1.0 is maximum volume.
 */
VALUE rbgm_mixmusic_setvolume(VALUE self, VALUE volumev)
{
  double volume = NUM2DBL(volumev);
  Mix_VolumeMusic( (int)(volume * MIX_MAX_VOLUME) );
  return volumev;
}

[Validate]