NAME

       SDL::Mixer::Music - functions for music

CATEGORY

       Mixer

METHODS

   load_MUS
        my $music = SDL::Mixer::Music::load_MUS( $file );

       "load_MUS" loads a music file into a "SDL::Mixer::MixMusic" structure. This can be passed
       to play_music.

   load_MUS_RW
        my $music = SDL::Mixer::Music::load_MUS_RW( $rwops );

       "load_MUS_RW" does the same like "load_MUS" except that it accepts an SDL::RWOps-object
       rather than a filename.

       Example for loading music from a variable:

        use SDL;
        use SDL::Mixer;
        use SDL::Mixer::Music;
        use SDL::RWOps;

        [...]

        my $rwops = SDL::RWOps->new_const_mem( $scalar_holding_music );
        my $music = SDL::Mixer::Music::load_MUS_RW( $rwops );

       Note: You need at least libSDL_mixer 1.2.7 for this feature.

   hook_music
        SDL::Mixer::Music::hook_music( $callback, $position );

       This sets up a custom music player function, so you can pass your own audio stream data
       into the SDL::Mixer.  The function will be called with "position" passed into the first
       parameter when the "callback" is called.  The audio stream buffer has to be filled with
       length bytes of music (2nd parameter).  The music player will then be called automatically
       when the mixer needs it. Music playing will start as soon as this is called.  All the
       music playing and stopping functions have no effect on music after this. Pause and resume
       will work.  Using a custom music player and the internal music player is not possible, the
       custom music player takes priority.

       To stop the custom music player call "hook_music()" without arguments.

       Note: NEVER call "SDL::Mixer" functions, nor SDL::Audio::lock, from a callback function.

       Note: At program termination also call "SDL::Mixer::Music::hook_music()" to stop this
       callback.

       Example:

        sub callback
        {
            my $position = shift; # position (first time its 0, on each call $length is added)
            my $length   = shift; # length of bytes we have to put in stream
            my @stream   = '';

            printf("position=%8d, stream length=%6d\n", $position, $length);

            for(my $i = 0; $i < $length; $i++)
            {
                push(@stream, (($i + $position) & 0xFF));
            }

            return @stream;
        }

        SDL::Mixer::Music::hook_music( 'main::callback', 0 );

   hook_music_finished
        SDL::Mixer::Music::hook_music_finished( 'main::callback' );

       This callback is called when music called by e.g. SDL::Mixer::Music::play_music or
       SDL::Mixer::Music::fade_in_music stops naturally.  This happens when the music is over or
       is fading out.

       Note: If you play music via SDL::Mixer::Music::hook_music, this callback will never be
       called.

       Example:

        my $music_is_playing = 0;
        my @music            = qw(first.mp3 next.mp3 other.mp3 last.mp3);
        sub callback
        {
            $music_is_playing = 0;
        }

        SDL::Mixer::Music::hook_music_finished( 'main::callback' );

        foreach my $this_song ( @music )
        {
            SDL::Mixer::Music::play_music( $this_song, 0 );
            $music_is_playing = 1;

            SDL::delay( 100 ) while( $music_is_playing );
        }

        SDL::Mixer::Music::hook_music_finished(); # cleanup

   get_music_hook_data
        my $position = SDL::Mixer::Music::get_music_hook_data();

       Returns the "position" (first) parameter that will be passed to
       SDL::Mixer::Music::hook_music's callback.

   play_music
        my $play_music = SDL::Mixer::Music::play_music( $mix_music, $loops );

       "play_music" plays a given "SDL::Mixer::MixMusic".  Passing -1 to $loops will loop the
       music infinitely.

       Example:

        my $music = SDL::Mixer::Music::load_MUS( 'music.mp3' );

        unless(SDL::Mixer::Music::play_music($sample_music, -1))
        {
            print("Something went wrong!\n");
        }

   fade_in_music
        my $music = SDL::Mixer::Music::fade_in_music( $mix_music, $loops, $ms );

       Same as SDL::Mixer::Music::play_music but you can specify the fade-in time by $ms.

   fade_out_music
        my $fading_music = SDL::Mixer::Music::fade_out_music( $ms );

       "fade_out_music" fades out the music with a duration specified in "ms" in milliseconds.

       Returns the the number of channels that will be faded out.

   fading_music
        my $fading_music = SDL::Mixer::Music::fading_music();

       Returns one of the following:

       •   MIX_NO_FADING

       •   MIX_FADING_OUT

       •   MIX_FADING_IN

   volume_music
        my $volume_before = SDL::Mixer::Music::volume_music( $new_volume );

       "volume_music" set the volume in $new_volume and returns the volume that was set before.
       Passing "-1" as argument causes only to return the current volume.

       Volume is between 0 (silence) and "MIX_MAX_VOLUME = 128".

       Example:

        # set the music volume to 1/2 maximum, and then check it
        printf( "volume was    : %d\n", SDL::Mixer::Music::volume_music( MIX_MAX_VOLUME / 2 ) );
        printf( "volume is now : %d\n", SDL::Mixer::Music::volume_music( -1 ) );

   halt_music
        SDL::Mixer::Music::halt_music();

       Halts the music.

   pause_music
        SDL::Mixer::Music::pause_music();

       Pauses the music.

   resume_music
        SDL::Mixer::Music::resume_music();

       Resumes the music.

   rewind_music
        SDL::Mixer::Music::rewind_music();

       Rewinds the music.

   set_music_position
        SDL::Mixer::Music::set_music_position( $position );

       Set the position of the currently playing music. The position takes different meanings for
       different music sources. It only works on the music sources listed below.

       MOD The double is cast to Uint16 and used for a pattern number in the module.  Passing
           zero is similar to rewinding the song.

       OGG Jumps to position seconds from the beginning of the song.

       MP3 Jumps to position seconds from the current position in the stream.  So you may want to
           call SDL::Mixer::Music::rewind_music before this.  Does not go in reverse... negative
           values do nothing.

       Returns: 0 on success, or "-1" if the codec doesn't support this function.

   paused_music
        my $paused = SDL::Mixer::Music::paused_music();

       Returns 1 if the music is paused, otherwise 0.

   playing_music
        my $playing_music = SDL::Mixer::Music::playing_music();

       Returns 1 if the music is playing sound, otherwise 0. It doesn't check if the music is
       paused.

AUTHORS

       See "AUTHORS" in SDL.