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

💖 NAME 💖

SDLx::Music — a powerful, convenient interface to SDL::Mixer::Music ✨

(this is the pods::...::Music(3pm) page btw, straight out of the User Contributed Perl Documentation, and it's a whole vibe 🎀)

🦋 CATEGORY 🦋

Extension 💅

🌸 SYNOPSIS 🌸

okay so first you gotta summon it:

use SDL;
use SDLx::Music;

my $music = SDLx::Music->new;

#define music data with just a name and file path
$music->data(
        fast => 'music/fast.ogg',
        slow => 'music/slow.ogg',
        magical => 'music/magic/cake.ogg',
);

#define more the long way with a parameter hash
$music->data(
        squelch => {
                file    => 'music/squelch.ogg',
                loops   => 3,
                fade_in => 0.5,
                volume  => 72,
        }
        splurge => {
                file     => 'music/splurge.ogg',
                finished => sub { print 'Splurged!' },
        },
);

#instead, do it the short way with the help of defaults

#clobber everything
$music->clear;

#specify the class-wide default for file extension
SDLx::Music->default->ext('.ogg');

#specify the object-wide default for file directory
$music->default->dir('music/');

#redefine squelch and splurge
$music->data(
        squelch => {
                #file defaults to the data name, so the path becomes
                #'music/squelch.ogg', which is what we wanted
                loops   => 3,
                fade_in => 0.5,
                volume  => 72,
        }
        splurge => {
                finished => sub { print 'Splurged!' },
        },
);

#and we can redefine the others like this
$music->data_for(
        'fast',
        'slow',
)->data(
        magical => 'magic/cake',
);

#get to that named data
my $splurge = $music->data('splurge');

#and add to/modify it without clobbering existing data
$splurge
        ->volume(55)
        ->file('data/' . $splurge->file)
;

#play it once, fading in for 2 seconds
$music->play($splurge, loops => 1, fade_in => 2);
#(it will be loaded automatically and played with its specified params)

sleep 5;

#pause it
$music->pause if $music->playing;

#load everything else
$music->load;

#resume playing it at a lower volume
$music->volume(44);
$music->play;

#get the names for all music
my @names = keys %{ $music->data };

for my $name (@names) {
        #play it in an infinite loop
        $music->play($name, loops => 0);
        warn "Cake!" if $music->playing eq "magical";
        sleep 10;
}

#fade out the last song
$music->fade_out(5);

sleep 4;

die "CAKE!" if $music->fading->name eq "magical";

sleep 1;

like, that's the whole tour, no cap 🫶

✨ DESCRIPTION ✨

so this class is literally a powerful and convenient interface to SDL::Mixer::Music 💖 the whole goal was making music code neater and clearer, because nobody wants to read spaghetti at 3am. and the things that make that happen? this class gives you class-wide AND object-wide defaults, and it automatically shares duplicate use of the same files (iconic behaviour honestly, it ate).

the doc you're reading rn is meant to be reference material. if you want the beginner-friendly version of this class, see chapter X of the SDL Perl Manual (when it is written 👀 — yeah, "when", we're all waiting together bestie).

⚠️ please note: do not mix use of this class with SDL::Mixer::Music if you want everything to work right. like, just don't. it's giving chaos 💀

---

👑 METHODS 👑

🎀 new

SDLx::Music->new;
#Option arguments showing the default parameters
SDLx::Music->new( freq => 44100, format => SDL::Audio::AUDIO_S16SYS, channels => 2, chunksize => 4096);

creates the new music object ✨ it inits audio with a call to SDLx::Mixer::init, if it isn't already init'd (tho if you want more precise control over what gets initialized, make sure you call SDLx::Mixer::init yourself before you call this method — main character energy, you take the wheel 💅). it also creates an empty default data object for object-wide defaults. and if you pass in arguments, it calls data with them to set up any initial data objects. returns the new music object 🫶

🎀 data

$music->data;
$music->data( $name );
$music->data( $data );
$music->data( %args );

• no arguments — returns a reference to the data hash. that hash has data names as keys and the associated data objects as values 💖
• with a name — creates the data name if it doesn't already exist. does this with a call to SDLx::Music::Data-new|SDLx::Music::Data/new> with name = $name> (yes that's literally how it's written in the pod, don't @ me 😭) and puts that new object in the data hash under the key of $name. returns the data object for that name ✨
• with a hash of arguments — for each pair, and returns a SDLx::Music::Data. returns $music 🌸

🎀 data_for

$music->data_for( @names_or_data_objects );

calls data repeatedly, passing it one element of the list at a time, to initialise multiple empty names and/or add data objects. returns $music 💜

🎀 has_data

$music->has_data;
$music->has_data( $name );
$music->has_data( $data );

• no arguments — returns how many data objects the class has 🔢
• with a name — returns the data object for $name. and if there's no data object for $name, it is not created and undef gets returned instead 🙈
• with a data object — does a (slowish 🐌) reverse of the data hash to see if the data object belongs to $music. returns it or undef.

🎀 default

$music->default;
SDLx::Music->default;

returns the default data object belonging to $music (created back in new), or to the class ✨ see SDLx::Music::Data for the whole lore on how defaults work 🧚

🎀 load

$music->load;
$music->load( @names_or_data_objects );
SDLx::Music->load( @data_objects );

• no arguments — for every data object belonging to $music, if the data object doesn't already have a loaded file, loads the file named by dir, file and ext if it hasn't been loaded already. sets the data object's loaded parameter to this. two or more objects that use the same file will use the same loaded file 🔁 reference counting is respected, so if two data objects use the same loaded file it'll be removed from memory only after both are destroyed. returns <$music>.
• with arguments — does the same, but only for the names or data objects in the list. and if there isn't a data object for any name, it will be created 👀

🎀 unload

$music->unload;
$music->unload( @names_or_data_objects );
SDLx::Music->unload( @data_objects );

• no arguments — clears the loaded parameter for all of the data objects in $music. the loaded file is removed from memory if it loses its last reference to it. returns <$music> 💖
• with arguments — does the same, but only for the names or data objects in the list. doesn't create a data object for a name that doesn't exist (respectful, honestly 🫶)

🎀 clear

$music->clear;
$music->clear( @names );

• no arguments — empties $music's data hash of all of its objects. the objects will be destroyed only if the last reference to them is removed, and no parameters will be cleared if this is not the case. returns $music.
• with arguments — does the same, but only deletes the values of the data hash for the names in the list ✨

🎀 real_clear

$music->real_clear;
$music->real_clear( @names_or_data_objects );
SDLx::Music->real_clear( @data_objects );

the full, brute force version of clear 💀 like it's not playing around.

• no arguments — empties out the parameters of every data object in $music (including unload-ing them) and then removes them from the data hash. this may not remove the objects from memory if there are still remaining references to them, but it is the closest thing to it. returns $music 🔥
• with arguments — does the same, but only clears out the names or data objects in the list.

🎀 play

$music_or_class->play;
$music->play( $name, $params );
$music_or_class->play( $data, %params );

• no arguments — resumes any paused music 🎶 returns the object or class.
• with arguments — plays the sound found in $music's $name, or in $data (depending on which is specified). it loads it if it needs to be loaded (which in turn creates the name if it needs to be created 👑). the %params are all optional and, if defined, are used instead of the values returned by the data object's parameter methods. the accepted parameters here are:

🌈 loops

plays the music file loops times. if loops is 0, loops it infinitely ♾️

🌈 fade_in

fades the music in for its first fade_in milliseconds, if fade_in is defined ✨

🌈 vol

sets the music volume to vol 🔊

🌈 vol_portion

multiplies the vol by vol_portion (values from 0 to 1 are encouraged 🥺) before setting the volume.

🌈 pos

sets the music position to pos if pos is defined.

returns the object or class 💅

🎀 pause

$music_or_class->pause;

pauses any playing music ⏸️ returns the object or class.

🎀 stop

$music_or_class->stop;

stops any playing music ⏹️ returns the object or class.

🎀 last_played

my $last_played = $music_or_class->last_played;

returns the data object that was played last 🕐

🎀 playing

my $playing = $music->playing;

if there is something playing, returns the data object that was played last. otherwise, returns undef 💀

🎀 paused

if there is something paused, returns the data object that was played last. otherwise, returns undef 🙈

🎀 fading

if there is something fading, returns the data object that was played last. otherwise, returns undef 🌫️

🎀 volume

my $volume = $music_or_class->volume;
$music_or_class->volume( $volume );

• no arguments — returns the current music volume 🔊
• with arguments — sets the music volume to $volume. returns the object or class 💖

🎀 fade_out

$music_or_class->fade_out( $fade_out );

fades the music out for its next fade_in milliseconds (yes bestie, the pod literally says fade_in here — I'm not making the rules 😭). returns the object or class ✨

🎀 rewind

$music_or_class->rewind;

rewinds the music to its start ⏪ returns the object or class.

🎀 pos

$music_or_class->pos( $pos );

sets the music position to $pos milliseconds. it does different things for different file types, so see SDL::Mixer::Music::set_music_position for the details 👀 note that this method divides $pos by 1000 to pass it to that function, which uses seconds (math, but make it fashion 💅). returns the object or class 🌸

---

...and there's more where that came from, bestie — don't go anywhere 🦋✨

🌈 SEE ALSO ✨

okay so like, if you wanna go deeper down this rabbit hole (and honestly? you should, it's giving main character energy), here's the whole squad:

• SDLx::Music::Data — the data bestie 🎀
• SDLx::Mixer — the mixer wrapper that keeps the vibes immaculate 💅
• SDL::Mixer::Music — the low-level music layer, iykyk 🔥
• SDL::Mixer — the OG mixer itself, no cap 👑

---

💖 AUTHORS 🌸

head over to "AUTHORS" in SDL if you wanna see who actually built all this — they're the real ones fr fr 🫶

---

🦋 COPYRIGHT & LICENSE ⭐

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

like, literally free. go wild bestie, just keep the same Perl terms and we're golden 💜

---

and that's a wrap on the whole page!! 🎀 This lil beauty comes from perl v5.42.3 and was dated 2026-08-19 — so yeah, it's fresh, it's iconic, and it ate 💅✨ bye bestie, go make some music 🎵🦋