1SDLx::Music(3) User Contributed Perl Documentation SDLx::Music(3)
2
6 SDLx::Music - A powerful, convenient interface to "SDL::Mixer::Music"
7
9 Extension
10
12 use SDL;
13 use SDLx::Music;
14 my $music = SDLx::Music->new;
16 #define music data with just a name and file path
18 $music->data(
19 fast => 'music/fast.ogg',
20 slow => 'music/slow.ogg',
21 magical => 'music/magic/cake.ogg',
22 );
23 #define more the long way with a parameter hash
25 $music->data(
26 squelch => {
27 file => 'music/squelch.ogg',
28 loops => 3,
29 fade_in => 0.5,
30 volume => 72,
31 }
32 splurge => {
33 file => 'music/splurge.ogg',
34 finished => sub { print 'Splurged!' },
35 },
36 );
37 #instead, do it the short way with the help of defaults
39 #clobber everything
41 $music->clear;
42 #specify the class-wide default for file extension
44 SDLx::Music->default->ext('.ogg');
45 #specify the object-wide default for file directory
47 $music->default->dir('music/');
48 #redefine squelch and splurge
50 $music->data(
51 squelch => {
52 #file defaults to the data name, so the path becomes
53 #'music/squelch.ogg', which is what we wanted
54 loops => 3,
55 fade_in => 0.5,
56 volume => 72,
57 }
58 splurge => {
59 finished => sub { print 'Splurged!' },
60 },
61 );
62 #and we can redefine the others like this
64 $music->data_for(
65 'fast',
66 'slow',
67 )->data(
68 magical => 'magic/cake',
69 );
70 #get to that named data
72 my $splurge = $music->data('splurge');
73 #and add to/modify it without clobbering existing data
75 $splurge
76 ->volume(55)
77 ->file('data/' . $splurge->file)
78 ;
79 #play it once, fading in for 2 seconds
81 $music->play($splurge, loops => 1, fade_in => 2);
82 #(it will be loaded automatically and played with its specified params)
83 sleep 5;
85 #pause it
87 $music->pause if $music->playing;
88 #load everything else
90 $music->load;
91 #resume playing it at a lower volume
93 $music->volume(44);
94 $music->play;
95 #get the names for all music
97 my @names = keys %{ $music->data };
98 for my $name (@names) {
100 #play it in an infinite loop
101 $music->play($name, loops => 0);
102 warn "Cake!" if $music->playing eq "magical";
103 sleep 10;
104 }
105 #fade out the last song
107 $music->fade_out(5);
108 sleep 4;
110 die "CAKE!" if $music->fading->name eq "magical";
112 sleep 1;
114
116 This class provides a powerful and convenient interface to
117 SDL::Mixer::Music. The main goal was to make music code neater and
118 clearer. Among the things that help this, this class provides class-
119 wide and object-wide defaults and it automatically shares duplicate use
120 of the same files.
121 The following document is intended for reference. For a more beginner-
123 friendly description of this class, see chapter X of the SDL Perl
124 Manual (when it is written).
125 Please note: do not mix use of this class with SDL::Mixer::Music if you
127 want everything to work right.
128
130 new
131 SDLx::Music->new;
132 #Option arguments showing the default parameters
133 SDLx::Music->new( freq => 44100, format => SDL::Audio::AUDIO_S16SYS, channels => 2, chunksize => 4096);
134 Creates the new music object. Inits audio with a call to
136 SDLx::Mixer::init, if it isn't already (if you want more precise
137 control over what is initialized, make sure you call SDLx::Mixer::init
138 before you call this method). Creates an empty default data object for
139 object-wide defaults. If arguments are supplied, calls "data" with them
140 to set up any initial data objects. Returns the new music object.
141 data
143 $music->data;
144 $music->data( $name );
145 $music->data( $data );
146 $music->data( %args );
147 With no arguments: returns a reference to the data hash. This hash has
149 data names as keys and the associated data objects as values.
150 With a name: creates the data name if it doesn't already exist. Does
152 this with a call to SDLx::Music::Data-new|SDLx::Music::Data/new> with
153 "name =" $name> and puts that new object in the data hash under the key
154 of $name. Returns the data object for that name.
155 With a hash of arguments: for each pair, and returns a
157 SDLx::Music::Data. Returns $music.
158 data_for
160 $music->data_for( @names_or_data_objects );
161 Calls "data" repeatedly, passing it one element of the list at a time,
163 to initialise multiple empty names and/or add data objects. Returns
164 $music.
165 has_data
167 $music->has_data;
168 $music->has_data( $name );
169 $music->has_data( $data );
170 Without arguments: returns how many data objects the class has.
172 With a name: returns the data object for $name. If there is no data
174 object for $name it is not created and undef is returned instead.
175 With a data object: does a (slowish) reverse of the data hash to see if
177 the data object belongs to $music. Returns it or undef.
178 default
180 $music->default;
181 SDLx::Music->default;
182 Returns the default data object belonging to $music (created in "new"),
184 or to the class. See SDLx::Music::Data for information on how defaults
185 work.
186 load
188 $music->load;
189 $music->load( @names_or_data_objects );
190 SDLx::Music->load( @data_objects );
191 Without arguments: for every data object belonging to $music, if the
193 data object doesn't already have a loaded file, loads the file named by
194 dir, file and ext if it hasn't been loaded already. Sets the data
195 object's loaded parameter to this. Two or more objects that use the
196 same file will use the same loaded file. Reference counting is
197 respected, so if two data objects use the same loaded file it will be
198 removed from memory only after both are destroyed. Returns <$music>.
199 With arguments: does the same, but only for the names or data objects
201 in the list. If there isn't a data object for any name, it will be
202 created.
203 unload
205 $music->unload;
206 $music->unload( @names_or_data_objects );
207 SDLx::Music->unload( @data_objects );
208 Without arguments: clears the loaded parameter for all of the data
210 objects in $music. The loaded file is removed from memory if it loses
211 its last reference to it. Returns <$music>.
212 With arguments: does the same, but only for the names or data objects
214 in the list. Doesn't create a data object for a name that doesn't
215 exist.
216 clear
218 $music->clear;
219 $music->clear( @names );
220 Without arguments: empties $music's data hash of all of its objects.
222 The objects will be destroyed only if the last reference to them is
223 removed, and no parameters will be cleared if this is not the case.
224 Returns $music.
225 With arguments: does the same, but only deletes the values of the data
227 hash for the names in the list.
228 real_clear
230 $music->real_clear;
231 $music->real_clear( @names_or_data_objects );
232 SDLx::Music->real_clear( @data_objects );
233 The full, brute force version of "clear".
235 Without arguments: empties out the parameters of every data object in
237 $music (including "unload"ing them) and then removes them from the data
238 hash. This may not remove the objects from memory if there are still
239 remaining references to them, but it is the closest thing to it.
240 Returns $music.
241 With arguments: does the same, but only clears out the names or data
243 objects in the list.
244 play
246 $music_or_class->play;
247 $music->play( $name, $params );
248 $music_or_class->play( $data, %params );
249 Without arguments: resumes any paused music. Returns the object or
251 class.
252 With arguments: plays the sound found in $music's $name, or in $data
254 (depending on which is specified). "load"s it if it needs to be loaded
255 (which in turn creates the name if it needs to be created). The %params
256 are all optional and, if defined, are used instead of the values
257 returned by the data object's parameter methods. The accepted
258 parameters here are:
259 loops
261 Plays the music file "loops" times. If "loops" is 0, loops it
262 infinitely.
263 fade_in
265 Fades the music in for its first "fade_in" milliseconds, if
266 "fade_in" is defined.
267 vol Sets the music volume to "vol".
269 vol_portion
271 Multiplies the "vol" by "vol_portion" (values from 0 to 1 are
272 encouraged) before setting the volume.
273 pos Sets the music position to "pos" if "pos" is defined.
275 Returns the object or class.
277 pause
279 $music_or_class->pause;
280 Pauses any playing music. Returns the object or class.
282 stop
284 $music_or_class->stop;
285 Stops any playing music. Returns the object or class.
287 last_played
289 my $last_played = $music_or_class->last_played;
290 Returns the data object that was "play"ed last.
292 playing
294 my $playing = $music->playing;
295 If there is something playing, returns the data object that was
297 "play"ed last. Otherwise, returns undef.
298 paused
300 If there is something paused, returns the data object that was "play"ed
301 last. Otherwise, returns undef.
302 fading
304 If there is something fading, returns the data object that was "play"ed
305 last. Otherwise, returns undef.
306 volume
308 my $volume = $music_or_class->volume;
309 $music_or_class->volume( $volume );
310 Without arguments: returns the current music volume
312 With arguments: Sets the music volume to $volume. Returns the object or
314 class.
315 fade_out
317 $music_or_class->fade_out( $fade_out );
318 Fades the music out for its next "fade_in" milliseconds. Returns the
320 object or class.
321 rewind
323 $music_or_class->rewind;
324 Rewinds the music to its start. Returns the object or class.
326 pos
328 $music_or_class->pos( $pos );
329 Sets the music position to $pos milliseconds. It does different things
331 for different file types, so see SDL::Mixer::Music::set_music_position
332 for details. Note that this method divides $pos by 1000 to pass it to
333 that function, which uses seconds. Returns the object or class.
334
336 SDLx::Music::Data SDLx::Mixer SDL::Mixer::Music SDL::Mixer
337
339 See "AUTHORS" in SDL.
340
342 This program is free software; you can redistribute it and/or modify it
343 under the same terms as Perl itself.
344perl v5.36.0 2022-07-22 SDLx::Music(3)