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

NAME

6       SDL::Audio - SDL Bindings for Audio
7

CATEGORY

9       Core, Audio
10

CONSTANTS

12       The constants are exported by default. You can avoid this by doing:
13
14        use SDL::Audio ();
15
16       and access them directly:
17
18        SDL::Audio::AUDIO_S16SYS;
19
20       or by choosing the export tags below:
21
22       Export tag: ':format'
23
24        AUDIO_U8
25        AUDIO_S8
26        AUDIO_U16LSB
27        AUDIO_S16LSB
28        AUDIO_U16MSB
29        AUDIO_S16MSB
30        AUDIO_U16
31        AUDIO_S16
32        AUDIO_U16SYS
33        AUDIO_S16SYS
34
35       Export tag: ':status'
36
37        SDL_AUDIO_STOPPED
38        SDL_AUDIO_PLAYING
39        SDL_AUDIO_PAUSED
40

METHODS

42   open
43         use SDL;
44         use SDL::Audio;
45
46         SDL::init(SDL_INIT_AUDIO);
47
48         my $desired = SDL::AudioSpec->new();
49
50         my $obtained;
51
52         SDL::Audio::open( $desired, $obtained );
53
54         # $obtained->... (A new SDL::AudioSpec now);
55
56       This function opens the audio device with the desired parameters, and
57       returns 0 if successful, placing the actual hardware parameters in the
58       structure pointed to by obtained. If obtained is NULL, the audio data
59       passed to the callback function will be guaranteed to be in the
60       requested format, and will be automatically converted to the hardware
61       audio format if necessary. This function returns -1 if it failed to
62       open the audio device, or couldn't set up the audio thread.
63
64       To open the audio device a desired SDL::AudioSpec must be created.
65
66         my $desired = SDL::AudioSpec->new();
67
68       You must then fill this structure with your desired audio
69       specifications.
70
71       The desired audio frequency in samples-per-second.
72               $desired->freq
73
74       The desired audio format. See SDL::AudioSpec
75               $desired->format
76
77       The desired channels (1 for mono, 2 for stereo, 4 for surround, 6 for
78       surround with center and lfe).
79               $desired->channels
80
81       The desired size of the audio buffer in samples. This number should be
82       a power of two, and may be adjusted by the audio driver to a value more
83       suitable for the hardware. Good values seem to range between 512 and
84       8192 inclusive, depending on the application and CPU speed. Smaller
85       values yield faster response time, but can lead to underflow if the
86       application is doing heavy processing and cannot fill the audio buffer
87       in time. A stereo sample consists of both right and left channels in LR
88       ordering. Note that the number of samples is directly related to time
89       by the following formula: ms = (samples*1000)/freq
90               $desired->samples
91
92       This should be set to a function that will be called when the audio
93       device is ready for more data. It is passed a pointer to the audio
94       buffer, and the length in bytes of the audio buffer. This function
95       usually runs in a separate thread, and so you should protect data
96       structures that it accesses by calling SDL::Audio::lock and
97       SDL::Audio::unlock in your code.
98           THIS IS NOT READY YET
99
100               $desired->callback
101
102               my $callback = sub{ my ($userdata, $stream, $len) = @_;  };
103
104               $userdata is a reference stored in the userdata field of the SDL::AudioSpec.
105               $stream is a pointer to the audio buffer you want to fill with information and $len is the length of the audio buffer in bytes.
106
107               $desired->userdata
108
109               This pointer is passed as the first parameter to the callback function.
110
111       SDL::Audio::open reads these fields from the desired SDL::AudioSpec
112       structure passed to the function and attempts to find an audio
113       configuration matching your desired. As mentioned above, if the
114       obtained parameter is NULL then SDL with convert from your desired
115       audio settings to the hardware settings as it plays.
116
117       If obtained is NULL then the desired SDL::AudioSpec is your working
118       specification, otherwise the obtained SDL::AudioSpec becomes the
119       working specification and the desired specification can be deleted. The
120       data in the working specification is used when building SDL::AudioCVT's
121       for converting loaded data to the hardware format.
122
123       SDL::Audio::open calculates the size and silence fields for both the
124       $desired and $obtained specifications. The size field stores the total
125       size of the audio buffer in bytes, while the silence stores the value
126       used to represent silence in the audio buffer
127
128       The audio device starts out playing silence when it's opened, and
129       should be enabled for playing by calling SDL::Audio::pause(0) when you
130       are ready for your audio callback function to be called. Since the
131       audio driver may modify the requested size of the audio buffer, you
132       should allocate any local mixing buffers after you open the audio
133       device.
134
135   pause
136        pause( $bool )
137
138       This function pauses and unpauses the audio callback processing. It
139       should be called with "$bool = 0" after opening the audio device to
140       start playing sound. This is so you can safely initialize data for your
141       callback function after opening the audio device. Silence will be
142       written to the audio device during the pause.
143
144   get_status
145        int get_status();
146
147       Returns either "SDL_AUDIO_STOPPED", "SDL_AUDIO_PLAYING" or
148       "SDL_AUDIO_PAUSED" depending on the current audio state.
149
150   load_wav
151        SDL::AudioSpec load_wav( $filename, $spec );
152
153       This function loads a WAVE file into memory.
154
155       If this function succeeds, it returns the given "SDL::AudioSpec",
156       filled with the audio data format of the wave data, and sets "buf" to a
157       buffer containing the audio data, and sets "len" to the length of that
158       audio buffer, in bytes. You need to free the audio buffer with
159       "SDL::Audio::free_wav" when you are done with it.
160
161       This function returns NULL and sets the SDL error message if the wave
162       file cannot be opened, uses an unknown data format, or is corrupt.
163       Currently raw, MS-ADPCM and IMA-ADPCM WAVE files are supported.
164
165       Example:
166
167        use SDL;
168        use SDL::Audio;
169        use SDL::AudioSpec;
170
171        SDL::init(SDL_INIT_AUDIO);
172
173        # Converting some WAV data to hardware format
174
175        my $desired  = SDL::AudioSpec->new();
176        my $obtained = SDL::AudioSpec->new();
177
178        # Set desired format
179        $desired->freq(22050);
180        $desired->channels(1);
181        $desired->format(AUDIO_S16);
182        $desired->samples(8192);
183
184        # Open the audio device
185        if( SDL::Audio::open($desired, $obtained) < 0 )
186        {
187            printf( STDERR "Couldn't open audio: %s\n", SDL::get_error() );
188            exit(-1);
189        }
190
191        # Load the test.wav
192        my $wav_ref = SDL::Audio::load_wav('../../test/data/sample.wav', $obtained);
193
194        unless( $wav_ref )
195        {
196            warn( "Could not open sample.wav: %s\n", SDL::get_error() );
197            SDL::Audio::close_audio();
198            SDL::quit;
199            exit(-1);
200        }
201
202        my ( $wav_spec, $wav_buf, $wav_len ) = @{$wav_ref};
203
204   free_wav
205        free_wav( $buffer )
206
207       After a WAVE file has been opened with "load_wav" its data can
208       eventually be freed with "free_wav". "buffer" is the buffer created by
209       "load_wav".
210
211   convert
212        SDL::Audio->convert( cvt, data, len )
213
214       Converts audio data to a desired audio format.
215
216       "convert" takes as first parameter "cvt", which was previously
217       initialized. Initializing a "SDL::AudioCVT" is a two step process.
218       First of all, the structure must be created via "SDL::AudioCVT->build"
219       along with source and destination format parameters. Secondly, the
220       "data" and "len" fields must be setup. "data" should point to the audio
221       data buffer being source and destination at once and "len" should be
222       set to the buffer length in bytes. Remember, the length of the buffer
223       pointed to by buf should be "len*len_mult" bytes in length.
224
225       Once the "SDL::AudioCVT" structure is initialized, we can pass it to
226       "convert", which will convert the audio data pointed to by "data". If
227       "convert" fails "undef" is returned, otherwise the converted
228       "SDL::AudioCVT" structure.
229
230       If the conversion completed successfully then the converted audio data
231       can be read from "cvt->buf". The amount of valid, converted, audio data
232       in the buffer is equal to "cvt->len*cvt->len_ratio".
233
234       Example:
235
236        use SDL;
237        use SDL::Audio;
238        use SDL::AudioSpec;
239        use SDL::AudioCVT;
240
241        SDL::init(SDL_INIT_AUDIO);
242
243        # Converting some WAV data to hardware format
244
245        my $desired  = SDL::AudioSpec->new();
246        my $obtained = SDL::AudioSpec->new();
247
248        # Set desired format
249        $desired->freq(22050);
250        $desired->channels(1);
251        $desired->format(AUDIO_S16);
252        $desired->samples(8192);
253
254        # Open the audio device
255        if( SDL::Audio::open($desired, $obtained) < 0 )
256        {
257            printf( STDERR "Couldn't open audio: %s\n", SDL::get_error() );
258            exit(-1);
259        }
260
261        # Load the test.wav
262        my $wav_ref = SDL::Audio::load_wav('../../test/data/sample.wav', $obtained);
263
264        unless( $wav_ref )
265        {
266            warn( "Could not open sample.wav: %s\n", SDL::get_error() );
267            SDL::Audio::close_audio();
268            SDL::quit;
269            exit(-1);
270        }
271
272        my ( $wav_spec, $wav_buf, $wav_len ) = @{$wav_ref};
273
274        # Build AudioCVT
275        my $wav_cvt = SDL::AudioCVT->build( $wav_spec->format, $wav_spec->channels, $wav_spec->freq,
276                                            $obtained->format, $obtained->channels, $obtained->freq);
277
278        # Check that the convert was built
279        if( $wav_cvt == -1 )
280        {
281            warn( "Couldn't build converter!\n" );
282            SDL::Audio::close();
283            SDL::Audio::free_wav($wav_buf);
284            SDL::quit();
285            exit(-1);
286        }
287
288        # And now we're ready to convert
289        SDL::Audio::convert($wav_cvt, $wav_buf, $wav_len);
290
291        # We can free original WAV data now
292        SDL::Audio::free_wav($wav_buf);
293
294       TODO: What to do with it? How to use callback? See
295       http://www.libsdl.org/cgi/docwiki.cgi/SDL_ConvertAudio
296
297   mix
298       Mixes audio data
299
300       Not implemented yet. See:
301       <http://www.libsdl.org/cgi/docwiki.cgi/SDL_MixAudio>
302
303   lock
304        lock();
305
306       The lock manipulated by these functions protects the callback function.
307       During a "lock" period, you can be guaranteed that the callback
308       function is not running. Do not call this from the callback function or
309       you will cause deadlock.
310
311   unlock
312        unlock();
313
314       Unlocks a previous "lock" call.
315
316   close
317        close();
318
319       Shuts down audio processing and closes the audio device.
320

AUTHORS

322       See "AUTHORS" in SDL.
323
324
325
326perl v5.36.0                      2023-03-10                     SDL::Audio(3)