### Home Classes Methods

### In Files

- lib/rubygame/music.rb

### Parent

Object

### Methods

- ::autoload
- ::current_music
- ::load
- ::new
- #fade_out
- #fading?
- #initialize_copy
- #jump_to
- #pause
- #paused?
- #play
- #playing?
- #rewind
- #stop
- #stopped?
- #unpause
- #volume
- #volume=

### Included Modules

- Rubygame::NamedResource

### Files

- CREDITS
- LICENSE
- NEWS
- README
- ROADMAP
- custom_sdl_load_paths.rdoc
- getting_started.rdoc
- keyboard_symbols.rdoc
- macosx_install.rdoc
- managing_framerate.rdoc
- surface_palettes.rdoc
- windows_install.rdoc

### Class/Module Index

Quicksearch

- Rubygame
- Rubygame::ActiveEvent
- Rubygame::Clock
- Rubygame::Color
- Rubygame::Color::ColorBase
- Rubygame::Color::ColorHSL
- Rubygame::Color::ColorHSV
- Rubygame::Color::ColorRGB
- Rubygame::Color::Palette
- Rubygame::Event
- Rubygame::EventActions
- Rubygame::EventActions::BlockAction
- Rubygame::EventActions::MethodAction
- Rubygame::EventActions::MultiAction
- Rubygame::EventHandler
- Rubygame::EventHandler::HasEventHandler
- Rubygame::EventHook
- Rubygame::EventQueue
- Rubygame::EventTriggers
- Rubygame::EventTriggers::AndTrigger
- Rubygame::EventTriggers::AttrTrigger
- Rubygame::EventTriggers::BlockTrigger
- Rubygame::EventTriggers::InstanceOfTrigger
- Rubygame::EventTriggers::KeyPressTrigger
- Rubygame::EventTriggers::KeyReleaseTrigger
- Rubygame::EventTriggers::KindOfTrigger
- Rubygame::EventTriggers::MouseMoveTrigger
- Rubygame::EventTriggers::MousePressTrigger
- Rubygame::EventTriggers::MouseReleaseTrigger
- Rubygame::EventTriggers::OrTrigger
- Rubygame::EventTriggers::TickTrigger
- Rubygame::EventTriggers::YesTrigger
- Rubygame::Events
- Rubygame::Events::ClockTicked
- Rubygame::Events::InputFocusGained
- Rubygame::Events::InputFocusLost
- Rubygame::Events::JoystickAxisMoved
- Rubygame::Events::JoystickBallMoved
- Rubygame::Events::JoystickButtonEvent
- Rubygame::Events::JoystickButtonPressed
- Rubygame::Events::JoystickButtonReleased
- Rubygame::Events::JoystickHatMoved
- Rubygame::Events::KeyPressed
- Rubygame::Events::KeyReleased
- Rubygame::Events::KeyboardEvent
- Rubygame::Events::MouseButtonEvent
- Rubygame::Events::MouseFocusGained
- Rubygame::Events::MouseFocusLost
- Rubygame::Events::MouseMoved
- Rubygame::Events::MousePressed
- Rubygame::Events::MouseReleased
- Rubygame::Events::QuitRequested
- Rubygame::Events::WindowExposed
- Rubygame::Events::WindowMinimized
- Rubygame::Events::WindowResized
- Rubygame::Events::WindowUnminimized
- Rubygame::ExposeEvent
- Rubygame::Ftor
- Rubygame::GL
- Rubygame::Hotspot
- Rubygame::JoyAxisEvent
- Rubygame::JoyBallEvent
- Rubygame::JoyDownEvent
- Rubygame::JoyHatEvent
- Rubygame::JoyUpEvent
- Rubygame::Joystick
- Rubygame::Key
- Rubygame::KeyDownEvent
- Rubygame::KeyUpEvent
- Rubygame::MailQueue
- Rubygame::MediaBag
- Rubygame::Mixer
- Rubygame::Mixer::Music
- Rubygame::Mixer::Sample
- Rubygame::Mouse
- Rubygame::MouseDownEvent
- Rubygame::MouseMotionEvent
- Rubygame::MouseUpEvent
- Rubygame::Music
- Rubygame::NamedResource
- Rubygame::NamedResource::NamedResourceClassMethods
- Rubygame::QuitEvent
- Rubygame::Rect
- Rubygame::ResizeEvent
- Rubygame::SDLError
- Rubygame::SFont
- Rubygame::Screen
- Rubygame::Sound
- Rubygame::Sprites
- Rubygame::Sprites::DepthSortGroup
- Rubygame::Sprites::Group
- Rubygame::Sprites::LimitGroup
- Rubygame::Sprites::Sprite
- Rubygame::Sprites::UpdateGroup
- Rubygame::Surface
- Rubygame::TTF

No matching classes.

# Rubygame::Music

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:

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 music files 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.

### Public Class Methods

autoload( filename ) click to toggle source

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.

    # File lib/rubygame/music.rb, line 57
    def autoload( filename )
      path = find_file( filename )

      if( path )
        return load( path )
      else
        return nil
      end
    end

current_music() click to toggle source

    # File lib/rubygame/music.rb, line 90
    def current_music
      @current_music
    end

load( filename ) click to toggle source

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.

    # File lib/rubygame/music.rb, line 76
    def load( filename )
      Rubygame.open_audio

      music = SDL::Mixer.LoadMUS( filename )

      if( music.pointer.null? )
        raise( Rubygame::SDLError, "Could not load Music file '%s': %s"%
               [filename, SDL.GetError()] )
      end

      return new( music )
    end

new click to toggle source

*NOTE*: Don't use this method. Use Music.load.

Raises NotImplementedError.

    # File lib/rubygame/music.rb, line 108
    def initialize( music=nil )
      if( music.instance_of? SDL::Mixer::Music )
        @struct  = music
        @volume  = 1
        @repeats = 0
      else
        raise( NotImplementedError, "Music.new is not implemented. "+
               "Use Music.load to load a music file." )
      end
    end

### Public Instance Methods

fade_out( fade_time ) click to toggle source

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.

    # File lib/rubygame/music.rb, line 340
    def fade_out( fade_time )
      if( fade_time < 0 )
        raise ArgumentError, "fade time cannot be negative (got %.2f)"%fade_time
      end

      if current?
        result = SDL::Mixer.FadeOutMusic( (fade_time * 1000).to_i )
        if( result < 0 )
          raise Rubygame::SDLError, "Error fading out music: #{SDL.GetError()}"
        end
      end

      return self
    end

fading?( direction=:either ) click to toggle source

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)

    # File lib/rubygame/music.rb, line 362
    def fading?( direction=:either )
      return false unless current?

      case direction
      when :in
        SDL::Mixer.FadingMusic() == SDL::Mixer::FADING_IN
      when :out
        SDL::Mixer.FadingMusic() == SDL::Mixer::FADING_OUT
      else
        SDL::Mixer.FadingMusic() != SDL::Mixer::NO_FADING
      end
    end

clone( other ) → music click to toggle source
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.

    # File lib/rubygame/music.rb, line 139
    def initialize_copy( other )
      @struct  = other.struct
      @volume  = other.volume
      @repeats = other.repeats
    end

jump_to( time ) click to toggle source

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!

    # File lib/rubygame/music.rb, line 464
    def jump_to( time )
      if current? and not stopped?
        was_paused = paused?

        if( time < 0 )
          raise Rubygame::SDLError, "cannot jump to negative time (got #{time})"
        end

        result = SDL::Mixer.SetMusicPosition( time.to_f )

        if( result == -1)
          raise Rubygame::SDLError, "could not jump music: #{SDL.GetError()}"
        end

        SDL::Mixer.PauseMusic() if was_paused
      end

      return self
    end

pause() click to toggle source

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.

    # File lib/rubygame/music.rb, line 268
    def pause
      if current?
        SDL::Mixer.PauseMusic()
      end

      return self
    end

paused?() click to toggle source

True if the Music is currently paused (not playing and not stopped). See also playing? and stopped?.

    # File lib/rubygame/music.rb, line 296
    def paused?
      current? and
        SDL::Mixer.PlayingMusic() == 1 and
        SDL::Mixer.PausedMusic() == 1
    end

play( options={:fade_in => 0, :repeats => 0, :start_at => 0} ) click to toggle source

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

    # File lib/rubygame/music.rb, line 184
    def play( options={} )

      fade_in  = (options[:fade_in]  or 0)
      repeats  = (options[:repeats]  or 0)
      start_at = (options[:start_at] or 0)

      fade_in =
        if( fade_in < 0 )
          raise ArgumentError, ":fade_in cannot be negative (got %.2f)"%fade_in
        elsif( fade_in < 0.05 )
          # Work-around for a bug with SDL_mixer not working with small
          # non-zero fade-ins
          0
        else
          (fade_in * 1000).to_i
        end

      repeats =
        if( repeats < -1 )
          raise( ArgumentError,
                 ":repeats cannot be negative, except -1 (got #{repeats})" )
        elsif( repeats > -1 )
          # Adjust so repeats means the same as it does for Sound
          (repeats + 1).to_i
        else
          -1
        end

      start_at =
        if( start_at < 0 )
          raise( ArgumentError,
                 ":start_at cannot be negative, (got %.2f)"%start_at )
        else
          start_at.to_f
        end

      Rubygame.open_audio

      # Doing a little restart dance to please the SDL_mixer gods.
      SDL::Mixer.PlayMusic( @struct, 0 )
      SDL::Mixer.HaltMusic()

      # Set music channel volume before we play
      SDL::Mixer.VolumeMusic( (SDL::Mixer::MAX_VOLUME * @volume).to_i )

      @repeats = repeats

      result = SDL::Mixer.FadeInMusicPos( @struct, repeats, fade_in, start_at )

      if( result == -1 )
        raise Rubygame::SDLError, "Could not play Music: #{SDL.GetError()}"
      end

      self.class.__current_music = self

      return self

    end

playing?() click to toggle source

True if the Music is currently playing (not paused and not stopped). See also paused? and stopped?.

    # File lib/rubygame/music.rb, line 253
    def playing?
      current? and
        SDL::Mixer.PlayingMusic() == 1 and
        SDL::Mixer.PausedMusic() == 0
    end

rewind() click to toggle source

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.

    # File lib/rubygame/music.rb, line 428
    def rewind
      if current? and not stopped?
        was_paused = paused?

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

        if( result == -1 )
          raise Rubygame::SDLError, "Could not rewind music: #{SDL.GetError()}"
        end

        SDL::Mixer.PauseMusic() if was_paused
      end

      return self
    end

stop() click to toggle source

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.

    # File lib/rubygame/music.rb, line 311
    def stop
      if current?
        SDL::Mixer.HaltMusic()
      end

      return self
    end

stopped?() click to toggle source

True if the Music is currently stopped (not playing and not paused). See also playing? and paused?.

    # File lib/rubygame/music.rb, line 323
    def stopped?
      (not current?) or (SDL::Mixer.PlayingMusic() == 0)
    end

unpause() click to toggle source

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.

    # File lib/rubygame/music.rb, line 284
    def unpause
      if current?
        SDL::Mixer.ResumeMusic()
      end

      return self
    end

volume() click to toggle source

Return the volume level of the music. 0.0 is totally silent, 1.0 is full volume.

*NOTE*: Ignores fading in or out.

    # File lib/rubygame/music.rb, line 382
    def volume
      @volume
    end

volume=( new_vol ) click to toggle source

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.

    # File lib/rubygame/music.rb, line 398
    def volume=( new_vol )
      # Clamp it to valid range
      new_vol = if new_vol < 0.0;      0.0
                elsif new_vol > 1.0;   1.0
                else;                  new_vol
                end

      if current?
        if fading?
          raise Rubygame::SDLError, "cannot set Music volume while fading"
        else
          SDL::Mixer.VolumeMusic( (SDL::Mixer::MAX_VOLUME * new_vol).to_i )
        end
      end

      @volume = new_vol
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.