pods::...::Music(3pm)

💖 SDL::Mixer::Music 💖

okay so bestie, this is the pods::...::Music(3pm) page from the User Contributed Perl Documentation — and it's literally your whole guide to the music functions in SDL::Mixer. Vibe check: loading, playing, fading, pausing, hooking, the works. Let's go 🎶💅

---

✨ NAME ✨

SDL::Mixer::Music — functions for music. That's the name, and it ate. 🫶

🎀 CATEGORY 🎀

Mixer — category said, periodt.

💅 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. Cute, right? 💖

🎧 load_MUS_RW

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

load_MUS_RW does the same thing as load_MUS, except that it accepts an SDL::RWOps-object rather than a filename. Iconic.

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.

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. Lowkey handy. ✨

🎧 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. We love an endless bop. 🔥

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. Gentle entrance, main character energy. 🦋

🎧 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 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 sets 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. Literally stops it. 🛑

🎧 pause_music

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

Pauses the music. A little break, bestie. ⏸️

🎧 resume_music

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

Resumes the music. Back to the vibes. ▶️

🎧 rewind_music

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

Rewinds the music. Rewind era. ⏪

🎧 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. Bestie check. 💅

🎧 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. No cap.

💖 AUTHORS 💖

See "AUTHORS" in SDL.

---

okay bestie, that's the whole pods::...::Music(3pm) page from User Contributed Perl Documentation, source/version perl v5.42.0, dated 2024-05-01 — now go make something iconic. 🎶💖🫶