Class: Rubygame::Mixer::Music

Inherits:
Object
  • Object
show all
Defined in:
lib/rubygame/deprecated_mixer.rb

Overview

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.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(struct = nil) ⇒ Music

call-seq: new



351
352
353
 
# File 'lib/rubygame/deprecated_mixer.rb', line 351

def initialize( struct=nil )
  @struct = struct
end

Class Method Details

.load_audio ⇒ Object

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 WAV, MOD, MIDI, OGG, and MP3 formats.

Raises SDLError if the music could not be loaded.



331
332
333
334
335
336
337
338
339
340
341
342
343
 
# File 'lib/rubygame/deprecated_mixer.rb', line 331

def self.load_audio
  Rubygame.deprecated( "Rubygame::Mixer::Music", "3.0" )

  music = SDL::Mixer.LoadMUS( filename )

  if( music.pointer.null? )
    raise( Rubygame::SDLError,
           "Error loading audio music from file `%s': %s"%
           [filename, SDL.GetError()] )
  end

  return new( music )
end

Instance Method Details

#fade_in(fade_time, repeats = 0, start = 0) ⇒ Object

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.



495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
 
# File 'lib/rubygame/deprecated_mixer.rb', line 495

def fade_in( fade_time, repeats=0, start=0 )
  fade_time *= 1000 # convert to milliseconds
  repeats = (repeats or 0)
  start   = (start   or 0)

  # Adjust so repeats means the same as it does for Samples
  repeats += 1 if repeats > -1

  result =
    if( start == 0 )
      SDL::Mixer.FadeInMusic( @struct, repeats, fade_time )
    else
      SDL::Mixer.FadeInMusicPos( @struct, repeats, fade_time, start )
    end

  if( result < 0 )
    raise Rubygame::SDLError, "Error fading in music: #{SDL.GetError()}"
  end

  return self
end

#fade_out(fade_time) ⇒ Object

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.



525
526
527
528
529
530
531
532
533
 
# File 'lib/rubygame/deprecated_mixer.rb', line 525

def fade_out( fade_time )
  fade_time *= 1000 # convert to milliseconds

  result = SDL::Mixer.FadeOutMusic( fade_time )

  if( result < 0 )
    raise Rubygame::SDLError, "Error fading out music: #{SDL.GetError()}"
  end
end

#fading?(direction = nil) ⇒ Boolean

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.

Returns:

  • (Boolean) 


543
544
545
546
547
548
549
550
551
552
 
# File 'lib/rubygame/deprecated_mixer.rb', line 543

def fading?( direction=nil )
  case direction
  when :in
    return (SDL::Mixer.FadingMusic() == SDL::Mixer::FADING_IN)
  when :out
    return (SDL::Mixer.FadingMusic() == SDL::Mixer::FADING_OUT)
  else
    return (SDL::Mixer.FadingMusic() != SDL::Mixer::NO_FADING)
  end
end

#jump(time) ⇒ Object

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.



429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
 
# File 'lib/rubygame/deprecated_mixer.rb', line 429

def jump( time )
  case SDL::Mixer.GetMusicType(nil)
  when SDL::Mixer::MUS_OGG, SDL::Mixer::MUS_MP3

    SDL::Mixer::RewindMusic() # Needed for MP3, and OK with OGG

    result = SDL::Mixer.SetmusicPosition( time )
    
    if( result < 0 )
      raise( Rubygame::SDLError,
             "Error jumping to time in music: #{SDL.GetError()}" )
    end

  when SDL::Mixer::MUS_NONE
    raise Rubygame::SDLError, "Cannot jump when no music is playing."
  else
    raise Rubygame::SDLError, "Music type does not support jumping."
  end
end

#pause ⇒ Object

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.



394
395
396
397
 
# File 'lib/rubygame/deprecated_mixer.rb', line 394

def pause
  SDL::Mixer::PauseMusic()
  return self
end

#paused? ⇒ Boolean

Returns true if the music is currently paused.

Returns:

  • (Boolean) 


459
460
461
 
# File 'lib/rubygame/deprecated_mixer.rb', line 459

def paused?
  return SDL::Mixer::PausedMusic()
end

#play(repeats = 0) ⇒ Object

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.



366
367
368
369
370
371
372
373
374
375
376
377
 
# File 'lib/rubygame/deprecated_mixer.rb', line 366

def play( repeats=0 )
  # Adjust so repeats means the same as it does for Samples
  repeats += 1 if repeats > -1

  result = SDL::Mixer.PlayMusic( @struct, repeats )

  if( result < 0 )
    raise Rubygame::SDLError, "Error playing music: #{SDL.GetError()}"
  end

  return self
end

#playing? ⇒ Boolean

Returns true if the music is currently playing.

Returns:

  • (Boolean) 


452
453
454
 
# File 'lib/rubygame/deprecated_mixer.rb', line 452

def playing?
  return SDL::Mixer::PlayingMusic()
end

#resume ⇒ Object

Resume playback of paused music from the point it was paused.

Safe to use on already-playing music.
See also #play.



404
405
406
407
 
# File 'lib/rubygame/deprecated_mixer.rb', line 404

def resume
  SDL::Mixer::ResumeMusic()
  return self
end

#rewind ⇒ Object

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).



414
415
416
417
 
# File 'lib/rubygame/deprecated_mixer.rb', line 414

def rewind
  SDL::Mixer::RewindMusic()
  return self
end

#stop ⇒ Object

Stop playback of music.

See also #play



383
384
385
386
 
# File 'lib/rubygame/deprecated_mixer.rb', line 383

def stop
  SDL::Mixer::HaltMusic()
  return self
end

#volume ⇒ Object

Returns the current volume level of the music.

0.0 is total silence, 1.0 is maximum volume.



467
468
469
 
# File 'lib/rubygame/deprecated_mixer.rb', line 467

def volume
  return (SDL::Mixer::VolumeMusic(-1).to_f / SDL::Mixer::MAX_VOLUME)
end

#volume=(new_volume) ⇒ Object

Sets the volume level of the music.

0.0 is total silence, 1.0 is maximum volume.



475
476
477
478
 
# File 'lib/rubygame/deprecated_mixer.rb', line 475

def volume=( new_volume )
  SDL::Mixer.VolumeMusic( (volume * SDL::Mixer::MAX_VOLUME).to_i )
  return new_volume
end