.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "pods::SDL::Mixer::Music 3pm"
.TH pods::SDL::Mixer::Music 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
SDL::Mixer::Music \- functions for music
.SH CATEGORY
.IX Header "CATEGORY"
Mixer
.SH METHODS
.IX Header "METHODS"
.SS load_MUS
.IX Subsection "load_MUS"
.Vb 1
\& my $music = SDL::Mixer::Music::load_MUS( $file );
.Ve
.PP
\&\f(CW\*(C`load_MUS\*(C'\fR loads a music file into a \f(CW\*(C`SDL::Mixer::MixMusic\*(C'\fR structure. This can be passed to play_music.
.SS load_MUS_RW
.IX Subsection "load_MUS_RW"
.Vb 1
\& my $music = SDL::Mixer::Music::load_MUS_RW( $rwops );
.Ve
.PP
\&\f(CW\*(C`load_MUS_RW\*(C'\fR does the same like \f(CW\*(C`load_MUS\*(C'\fR except that it accepts an SDL::RWOps\-object rather than a filename.
.PP
Example for loading music from a variable:
.PP
.Vb 4
\& 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 );
.Ve
.PP
\&\fBNote:\fR You need at least libSDL_mixer 1.2.7 for this feature.
.SS hook_music
.IX Subsection "hook_music"
.Vb 1
\& SDL::Mixer::Music::hook_music( $callback, $position );
.Ve
.PP
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 \f(CW\*(C`position\*(C'\fR passed into the first parameter when the \f(CW\*(C`callback\*(C'\fR 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.
.PP
To stop the custom music player call \f(CWhook_music()\fR without arguments.
.PP
\&\fBNote\fR: NEVER call \f(CW\*(C`SDL::Mixer\*(C'\fR functions, nor SDL::Audio::lock, from a callback function.
.PP
\&\fBNote\fR: At program termination also call \f(CWSDL::Mixer::Music::hook_music()\fR to stop this callback.
.PP
Example:
.PP
.Vb 5
\& 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   = \*(Aq\*(Aq;
\& 
\&     printf("position=%8d, stream length=%6d\en", $position, $length);
\& 
\&     for(my $i = 0; $i < $length; $i++)
\&     {
\&         push(@stream, (($i + $position) & 0xFF));
\&     }
\& 
\&     return @stream;
\& }
\& 
\& SDL::Mixer::Music::hook_music( \*(Aqmain::callback\*(Aq, 0 );
.Ve
.SS hook_music_finished
.IX Subsection "hook_music_finished"
.Vb 1
\& SDL::Mixer::Music::hook_music_finished( \*(Aqmain::callback\*(Aq );
.Ve
.PP
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.
.PP
\&\fBNote\fR: If you play music via SDL::Mixer::Music::hook_music, this callback will never be called.
.PP
Example:
.PP
.Vb 6
\& 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( \*(Aqmain::callback\*(Aq );
\& 
\& 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
.Ve
.SS get_music_hook_data
.IX Subsection "get_music_hook_data"
.Vb 1
\& my $position = SDL::Mixer::Music::get_music_hook_data();
.Ve
.PP
Returns the \f(CW\*(C`position\*(C'\fR (first) parameter that will be passed to SDL::Mixer::Music::hook_music's callback.
.SS play_music
.IX Subsection "play_music"
.Vb 1
\& my $play_music = SDL::Mixer::Music::play_music( $mix_music, $loops );
.Ve
.PP
\&\f(CW\*(C`play_music\*(C'\fR plays a given \f(CW\*(C`SDL::Mixer::MixMusic\*(C'\fR.
Passing \-1 to \f(CW$loops\fR will loop the music infinitely.
.PP
Example:
.PP
.Vb 1
\& my $music = SDL::Mixer::Music::load_MUS( \*(Aqmusic.mp3\*(Aq );
\& 
\& unless(SDL::Mixer::Music::play_music($sample_music, \-1))
\& {
\&     print("Something went wrong!\en");
\& }
.Ve
.SS fade_in_music
.IX Subsection "fade_in_music"
.Vb 1
\& my $music = SDL::Mixer::Music::fade_in_music( $mix_music, $loops, $ms );
.Ve
.PP
Same as SDL::Mixer::Music::play_music but you can specify the fade-in time by \f(CW$ms\fR.
.SS fade_out_music
.IX Subsection "fade_out_music"
.Vb 1
\& my $fading_music = SDL::Mixer::Music::fade_out_music( $ms );
.Ve
.PP
\&\f(CW\*(C`fade_out_music\*(C'\fR fades out the music with a duration specified in \f(CW\*(C`ms\*(C'\fR in milliseconds.
.PP
Returns the the number of channels that will be faded out.
.SS fading_music
.IX Subsection "fading_music"
.Vb 1
\& my $fading_music = SDL::Mixer::Music::fading_music();
.Ve
.PP
Returns one of the following:
.IP \(bu 4
MIX_NO_FADING
.IP \(bu 4
MIX_FADING_OUT
.IP \(bu 4
MIX_FADING_IN
.SS volume_music
.IX Subsection "volume_music"
.Vb 1
\& my $volume_before = SDL::Mixer::Music::volume_music( $new_volume );
.Ve
.PP
\&\f(CW\*(C`volume_music\*(C'\fR set the volume in \f(CW$new_volume\fR and returns the volume that was set before.
Passing \f(CW\-1\fR as argument causes only to return the current volume.
.PP
Volume is between \f(CW0\fR (silence) and \f(CW\*(C`MIX_MAX_VOLUME = 128\*(C'\fR.
.PP
Example:
.PP
.Vb 3
\& # set the music volume to 1/2 maximum, and then check it
\& printf( "volume was    : %d\en", SDL::Mixer::Music::volume_music( MIX_MAX_VOLUME / 2 ) );
\& printf( "volume is now : %d\en", SDL::Mixer::Music::volume_music( \-1 ) );
.Ve
.SS halt_music
.IX Subsection "halt_music"
.Vb 1
\& SDL::Mixer::Music::halt_music();
.Ve
.PP
Halts the music.
.SS pause_music
.IX Subsection "pause_music"
.Vb 1
\& SDL::Mixer::Music::pause_music();
.Ve
.PP
Pauses the music.
.SS resume_music
.IX Subsection "resume_music"
.Vb 1
\& SDL::Mixer::Music::resume_music();
.Ve
.PP
Resumes the music.
.SS rewind_music
.IX Subsection "rewind_music"
.Vb 1
\& SDL::Mixer::Music::rewind_music();
.Ve
.PP
Rewinds the music.
.SS set_music_position
.IX Subsection "set_music_position"
.Vb 1
\& SDL::Mixer::Music::set_music_position( $position );
.Ve
.PP
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.
.IP MOD 4
.IX Item "MOD"
The double is cast to Uint16 and used for a pattern number in the module.
Passing zero is similar to rewinding the song.
.IP OGG 4
.IX Item "OGG"
Jumps to position seconds from the beginning of the song.
.IP MP3 4
.IX Item "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.
.PP
Returns: \f(CW0\fR on success, or \f(CW\-1\fR if the codec doesn't support this function.
.SS paused_music
.IX Subsection "paused_music"
.Vb 1
\& my $paused = SDL::Mixer::Music::paused_music();
.Ve
.PP
Returns \f(CW1\fR if the music is paused, otherwise \f(CW0\fR.
.SS playing_music
.IX Subsection "playing_music"
.Vb 1
\& my $playing_music = SDL::Mixer::Music::playing_music();
.Ve
.PP
Returns \f(CW1\fR if the music is playing sound, otherwise \f(CW0\fR. It doesn't check if the music is paused.
.SH AUTHORS
.IX Header "AUTHORS"
See "AUTHORS" in SDL.