SDL::Mixer::Music(3pm)

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

NAME

6       SDL::Mixer::Music - functions for music
7

METHODS

12   load_MUS
13        my $music = SDL::Mixer::Music::load_MUS( $file );
14
15       "load_MUS" loads a music file into a "SDL::Mixer::MixMusic" structure.
16       This can be passed to play_music.
17
18   load_MUS_RW
19        my $music = SDL::Mixer::Music::load_MUS_RW( $rwops );
20
21       "load_MUS_RW" does the same like "load_MUS" except that it accepts an
22       SDL::RWOps-object rather than a filename.
23
24       Example for loading music from a variable:
25
26        use SDL;
27        use SDL::Mixer;
28        use SDL::Mixer::Music;
29        use SDL::RWOps;
30
31        [...]
32
33        my $rwops = SDL::RWOps->new_const_mem( $scalar_holding_music );
34        my $music = SDL::Mixer::Music::load_MUS_RW( $rwops );
35
36       Note: You need at least libSDL_mixer 1.2.7 for this feature.
37
38   hook_music
39        SDL::Mixer::Music::hook_music( $callback, $position );
40
41       This sets up a custom music player function, so you can pass your own
42       audio stream data into the SDL::Mixer.  The function will be called
43       with "position" passed into the first parameter when the "callback" is
44       called.  The audio stream buffer has to be filled with length bytes of
45       music (2nd parameter).  The music player will then be called
46       automatically when the mixer needs it. Music playing will start as soon
47       as this is called.  All the music playing and stopping functions have
48       no effect on music after this. Pause and resume will work.  Using a
49       custom music player and the internal music player is not possible, the
50       custom music player takes priority.
51
52       To stop the custom music player call "hook_music()" without arguments.
53
54       Note: NEVER call "SDL::Mixer" functions, nor SDL::Audio::lock, from a
55       callback function.
56
57       Note: At program termination also call
58       "SDL::Mixer::Music::hook_music()" to stop this callback.
59
60       Example:
61
62        sub callback
63        {
64            my $position = shift; # position (first time its 0, on each call $length is added)
65            my $length   = shift; # length of bytes we have to put in stream
66            my @stream   = '';
67
68            printf("position=%8d, stream length=%6d\n", $position, $length);
69
70            for(my $i = 0; $i < $length; $i++)
71            {
72                push(@stream, (($i + $position) & 0xFF));
73            }
74
75            return @stream;
76        }
77
78        SDL::Mixer::Music::hook_music( 'main::callback', 0 );
79
80   hook_music_finished
81        SDL::Mixer::Music::hook_music_finished( 'main::callback' );
82
83       This callback is called when music called by e.g.
84       SDL::Mixer::Music::play_music or SDL::Mixer::Music::fade_in_music stops
85       naturally.  This happens when the music is over or is fading out.
86
87       Note: If you play music via SDL::Mixer::Music::hook_music, this
88       callback will never be called.
89
90       Example:
91
92        my $music_is_playing = 0;
93        my @music            = qw(first.mp3 next.mp3 other.mp3 last.mp3);
94        sub callback
95        {
96            $music_is_playing = 0;
97        }
98
99        SDL::Mixer::Music::hook_music_finished( 'main::callback' );
100
101        foreach my $this_song ( @music )
102        {
103            SDL::Mixer::Music::play_music( $this_song, 0 );
104            $music_is_playing = 1;
105
106            SDL::delay( 100 ) while( $music_is_playing );
107        }
108
109        SDL::Mixer::Music::hook_music_finished(); # cleanup
110
111   get_music_hook_data
112        my $position = SDL::Mixer::Music::get_music_hook_data();
113
114       Returns the "position" (first) parameter that will be passed to
115       SDL::Mixer::Music::hook_music's callback.
116
117   play_music
118        my $play_music = SDL::Mixer::Music::play_music( $mix_music, $loops );
119
120       "play_music" plays a given "SDL::Mixer::MixMusic".  Passing -1 to
121       $loops will loop the music infinitely.
122
123       Example:
124
125        my $music = SDL::Mixer::Music::load_MUS( 'music.mp3' );
126
127        unless(SDL::Mixer::Music::play_music($sample_music, -1))
128        {
129            print("Something went wrong!\n");
130        }
131
132   fade_in_music
133        my $music = SDL::Mixer::Music::fade_in_music( $mix_music, $loops, $ms );
134
135       Same as SDL::Mixer::Music::play_music but you can specify the fade-in
136       time by $ms.
137
138   fade_out_music
139        my $fading_music = SDL::Mixer::Music::fade_out_music( $ms );
140
141       "fade_out_music" fades out the music with a duration specified in "ms"
142       in milliseconds.
143
144       Returns the the number of channels that will be faded out.
145
146   fading_music
147        my $fading_music = SDL::Mixer::Music::fading_music();
148
149       Returns one of the following:
150
151       •   MIX_NO_FADING
152
153       •   MIX_FADING_OUT
154
155       •   MIX_FADING_IN
156
157   volume_music
158        my $volume_before = SDL::Mixer::Music::volume_music( $new_volume );
159
160       "volume_music" set the volume in $new_volume and returns the volume
161       that was set before.  Passing "-1" as argument causes only to return
162       the current volume.
163
164       Volume is between 0 (silence) and "MIX_MAX_VOLUME = 128".
165
166       Example:
167
168        # set the music volume to 1/2 maximum, and then check it
169        printf( "volume was    : %d\n", SDL::Mixer::Music::volume_music( MIX_MAX_VOLUME / 2 ) );
170        printf( "volume is now : %d\n", SDL::Mixer::Music::volume_music( -1 ) );
171
172   halt_music
173        SDL::Mixer::Music::halt_music();
174
175       Halts the music.
176
177   pause_music
178        SDL::Mixer::Music::pause_music();
179
180       Pauses the music.
181
182   resume_music
183        SDL::Mixer::Music::resume_music();
184
185       Resumes the music.
186
187   rewind_music
188        SDL::Mixer::Music::rewind_music();
189
190       Rewinds the music.
191
192   set_music_position
193        SDL::Mixer::Music::set_music_position( $position );
194
195       Set the position of the currently playing music. The position takes
196       different meanings for different music sources. It only works on the
197       music sources listed below.
198
199       MOD The double is cast to Uint16 and used for a pattern number in the
200           module.  Passing zero is similar to rewinding the song.
201
202       OGG Jumps to position seconds from the beginning of the song.
203
204       MP3 Jumps to position seconds from the current position in the stream.
205           So you may want to call SDL::Mixer::Music::rewind_music before
206           this.  Does not go in reverse... negative values do nothing.
207
208       Returns: 0 on success, or "-1" if the codec doesn't support this
209       function.
210
211   paused_music
212        my $paused = SDL::Mixer::Music::paused_music();
213
214       Returns 1 if the music is paused, otherwise 0.
215
216   playing_music
217        my $playing_music = SDL::Mixer::Music::playing_music();
218
219       Returns 1 if the music is playing sound, otherwise 0. It doesn't check
220       if the music is paused.
221

AUTHORS

223       See "AUTHORS" in SDL.
224
225
226
227perl v5.34.0                      2022-01-21              SDL::Mixer::Music(3)

NAME

CATEGORY

METHODS

AUTHORS