1SDLx::Music(3)        User Contributed Perl Documentation       SDLx::Music(3)
2
3
4

NAME

6       SDLx::Music - A powerful, convenient interface to "SDL::Mixer::Music"
7

CATEGORY

9       Extension
10

SYNOPSIS

12               use SDL;
13               use SDLx::Music;
14
15               my $music = SDLx::Music->new;
16
17               #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
24               #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
38               #instead, do it the short way with the help of defaults
39
40               #clobber everything
41               $music->clear;
42
43               #specify the class-wide default for file extension
44               SDLx::Music->default->ext('.ogg');
45
46               #specify the object-wide default for file directory
47               $music->default->dir('music/');
48
49               #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
63               #and we can redefine the others like this
64               $music->data_for(
65                       'fast',
66                       'slow',
67               )->data(
68                       magical => 'magic/cake',
69               );
70
71               #get to that named data
72               my $splurge = $music->data('splurge');
73
74               #and add to/modify it without clobbering existing data
75               $splurge
76                       ->volume(55)
77                       ->file('data/' . $splurge->file)
78               ;
79
80               #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
84               sleep 5;
85
86               #pause it
87               $music->pause if $music->playing;
88
89               #load everything else
90               $music->load;
91
92               #resume playing it at a lower volume
93               $music->volume(44);
94               $music->play;
95
96               #get the names for all music
97               my @names = keys %{ $music->data };
98
99               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
106               #fade out the last song
107               $music->fade_out(5);
108
109               sleep 4;
110
111               die "CAKE!" if $music->fading->name eq "magical";
112
113               sleep 1;
114

DESCRIPTION

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
122       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
126       Please note: do not mix use of this class with SDL::Mixer::Music if you
127       want everything to work right.
128

METHODS

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
135       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
142   data
143               $music->data;
144               $music->data( $name );
145               $music->data( $data );
146               $music->data( %args );
147
148       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
151       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
156       With a hash of arguments: for each pair, and returns a
157       SDLx::Music::Data. Returns $music.
158
159   data_for
160               $music->data_for( @names_or_data_objects );
161
162       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
166   has_data
167               $music->has_data;
168               $music->has_data( $name );
169               $music->has_data( $data );
170
171       Without arguments: returns how many data objects the class has.
172
173       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
176       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
179   default
180               $music->default;
181               SDLx::Music->default;
182
183       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
187   load
188               $music->load;
189               $music->load( @names_or_data_objects );
190               SDLx::Music->load( @data_objects );
191
192       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
200       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
204   unload
205               $music->unload;
206               $music->unload( @names_or_data_objects );
207               SDLx::Music->unload( @data_objects );
208
209       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
213       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
217   clear
218               $music->clear;
219               $music->clear( @names );
220
221       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
226       With arguments: does the same, but only deletes the values of the data
227       hash for the names in the list.
228
229   real_clear
230               $music->real_clear;
231               $music->real_clear( @names_or_data_objects );
232               SDLx::Music->real_clear( @data_objects );
233
234       The full, brute force version of "clear".
235
236       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
242       With arguments: does the same, but only clears out the names or data
243       objects in the list.
244
245   play
246               $music_or_class->play;
247               $music->play( $name, $params );
248               $music_or_class->play( $data, %params );
249
250       Without arguments: resumes any paused music. Returns the object or
251       class.
252
253       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
260       loops
261           Plays the music file "loops" times. If "loops" is 0, loops it
262           infinitely.
263
264       fade_in
265           Fades the music in for its first "fade_in" milliseconds, if
266           "fade_in" is defined.
267
268       vol Sets the music volume to "vol".
269
270       vol_portion
271           Multiplies the "vol" by "vol_portion" (values from 0 to 1 are
272           encouraged) before setting the volume.
273
274       pos Sets the music position to "pos" if "pos" is defined.
275
276       Returns the object or class.
277
278   pause
279               $music_or_class->pause;
280
281       Pauses any playing music. Returns the object or class.
282
283   stop
284               $music_or_class->stop;
285
286       Stops any playing music. Returns the object or class.
287
288   last_played
289               my $last_played = $music_or_class->last_played;
290
291       Returns the data object that was "play"ed last.
292
293   playing
294               my $playing = $music->playing;
295
296       If there is something playing, returns the data object that was
297       "play"ed last. Otherwise, returns undef.
298
299   paused
300       If there is something paused, returns the data object that was "play"ed
301       last. Otherwise, returns undef.
302
303   fading
304       If there is something fading, returns the data object that was "play"ed
305       last. Otherwise, returns undef.
306
307   volume
308               my $volume = $music_or_class->volume;
309               $music_or_class->volume( $volume );
310
311       Without arguments: returns the current music volume
312
313       With arguments: Sets the music volume to $volume. Returns the object or
314       class.
315
316   fade_out
317               $music_or_class->fade_out( $fade_out );
318
319       Fades the music out for its next "fade_in" milliseconds. Returns the
320       object or class.
321
322   rewind
323               $music_or_class->rewind;
324
325       Rewinds the music to its start. Returns the object or class.
326
327   pos
328               $music_or_class->pos( $pos );
329
330       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

SEE ALSO

336       SDLx::Music::Data SDLx::Mixer SDL::Mixer::Music SDL::Mixer
337

AUTHORS

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.
344
345
346
347perl v5.36.0                      2022-07-22                    SDLx::Music(3)
Impressum