Fix T49657: Audio backend "Jack" should be named "JACK".
[blender.git] / intern / audaspace / intern / AUD_C-API.h
1 /*
2  * ***** BEGIN GPL LICENSE BLOCK *****
3  *
4  * Copyright 2009-2011 Jörg Hermann Müller
5  *
6  * This file is part of AudaSpace.
7  *
8  * Audaspace is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation; either version 2 of the License, or
11  * (at your option) any later version.
12  *
13  * AudaSpace is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with Audaspace; if not, write to the Free Software Foundation,
20  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
21  *
22  * ***** END GPL LICENSE BLOCK *****
23  */
24
25 /** \file AUD_C-API.h
26  *  \ingroup audaspace
27  */
28  
29 #ifndef __AUD_C_API_H__
30 #define __AUD_C_API_H__
31
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35
36 #include "AUD_Space.h"
37
38 /// Supported output devices.
39 typedef enum
40 {
41         AUD_NULL_DEVICE = 0,
42         AUD_SDL_DEVICE,
43         AUD_OPENAL_DEVICE,
44         AUD_JACK_DEVICE
45 } AUD_DeviceType;
46
47 /// Sound information structure.
48 typedef struct
49 {
50         AUD_Specs specs;
51         float length;
52 } AUD_SoundInfo;
53
54 #ifndef AUD_CAPI_IMPLEMENTATION
55         typedef void AUD_Sound;
56         typedef void AUD_Handle;
57         typedef void AUD_Device;
58         typedef void AUD_SEntry;
59         typedef float (*AUD_volumeFunction)(void *, void *, float);
60         typedef void (*AUD_syncFunction)(void *, int, float);
61 #endif
62
63 /**
64  * Initializes audio routines (FFMPEG/JACK if it is enabled).
65  */
66 extern void AUD_initOnce(void);
67
68 /**
69  * Unitinitializes an audio routines.
70  */
71 extern void AUD_exitOnce(void);
72
73 /**
74  * Initializes an audio device.
75  * \param device The device type that should be used.
76  * \param specs The audio specification to be used.
77  * \param buffersize The buffersize for the device.
78  * \return Whether the device has been initialized.
79  */
80 extern AUD_Device* AUD_init(const char* device, AUD_DeviceSpecs specs, int buffersize, const char* name);
81
82 /**
83  * Unitinitializes an audio device.
84  */
85 extern void AUD_exit(AUD_Device* device);
86
87 /**
88  * Locks the playback device.
89  */
90 extern void AUD_Device_lock(AUD_Device* device);
91
92 /**
93  * Unlocks the device.
94  */
95 extern void AUD_Device_unlock(AUD_Device* device);
96
97 extern AUD_Channels AUD_Device_getChannels(AUD_Device* device);
98
99 extern AUD_SampleRate AUD_Device_getRate(AUD_Device* device);
100
101 /**
102  * Returns information about a sound.
103  * \param sound The sound to get the info about.
104  * \return The AUD_SoundInfo structure with filled in data.
105  */
106 extern AUD_SoundInfo AUD_getInfo(AUD_Sound *sound);
107
108 /**
109  * Loads a sound file.
110  * \param filename The filename of the sound file.
111  * \return A handle of the sound file.
112  */
113 extern AUD_Sound *AUD_Sound_file(const char *filename);
114
115 /**
116  * Loads a sound file.
117  * \param buffer The buffer which contains the sound file.
118  * \param size The size of the buffer.
119  * \return A handle of the sound file.
120  */
121 extern AUD_Sound *AUD_Sound_bufferFile(unsigned char *buffer, int size);
122
123 /**
124  * Buffers a sound.
125  * \param sound The sound to buffer.
126  * \return A handle of the sound buffer.
127  */
128 extern AUD_Sound *AUD_Sound_cache(AUD_Sound *sound);
129
130 /**
131  * Rechannels the sound to be mono.
132  * \param sound The sound to rechannel.
133  * \return The mono sound.
134  */
135 extern AUD_Sound *AUD_Sound_rechannel(AUD_Sound *sound, AUD_Channels channels);
136
137 /**
138  * Delays a sound.
139  * \param sound The sound to dealy.
140  * \param delay The delay in seconds.
141  * \return A handle of the delayed sound.
142  */
143 extern AUD_Sound *AUD_Sound_delay(AUD_Sound *sound, float delay);
144
145 /**
146  * Limits a sound.
147  * \param sound The sound to limit.
148  * \param start The start time in seconds.
149  * \param end The stop time in seconds.
150  * \return A handle of the limited sound.
151  */
152 extern AUD_Sound *AUD_Sound_limit(AUD_Sound *sound, float start, float end);
153
154 /**
155  * Ping pongs a sound.
156  * \param sound The sound to ping pong.
157  * \return A handle of the ping pong sound.
158  */
159 extern AUD_Sound *AUD_Sound_pingpong(AUD_Sound *sound);
160
161 /**
162  * Loops a sound.
163  * \param sound The sound to loop.
164  * \return A handle of the looped sound.
165  */
166 extern AUD_Sound *AUD_Sound_loop(AUD_Sound *sound);
167
168 /**
169  * Sets a remaining loop count of a looping sound that currently plays.
170  * \param handle The playback handle.
171  * \param loops The count of remaining loops, -1 for infinity.
172  * \return Whether the handle is valid.
173  */
174 extern int AUD_Handle_setLoopCount(AUD_Handle *handle, int loops);
175
176 /**
177  * Rectifies a sound.
178  * \param sound The sound to rectify.
179  * \return A handle of the rectified sound.
180  */
181 extern AUD_Sound *AUD_rectifySound(AUD_Sound *sound);
182
183 /**
184  * Unloads a sound of any type.
185  * \param sound The handle of the sound.
186  */
187 extern void AUD_Sound_free(AUD_Sound *sound);
188
189 /**
190  * Plays back a sound file.
191  * \param sound The handle of the sound file.
192  * \param keep When keep is true the sound source will not be deleted but set to
193  *             paused when its end has been reached.
194  * \return A handle to the played back sound.
195  */
196 extern AUD_Handle *AUD_Device_play(AUD_Device* device, AUD_Sound *sound, int keep);
197
198 /**
199  * Pauses a played back sound.
200  * \param handle The handle to the sound.
201  * \return Whether the handle has been playing or not.
202  */
203 extern int AUD_Handle_pause(AUD_Handle *handle);
204
205 /**
206  * Resumes a paused sound.
207  * \param handle The handle to the sound.
208  * \return Whether the handle has been paused or not.
209  */
210 extern int AUD_Handle_resume(AUD_Handle *handle);
211
212 /**
213  * Stops a playing or paused sound.
214  * \param handle The handle to the sound.
215  * \return Whether the handle has been valid or not.
216  */
217 extern int AUD_Handle_stop(AUD_Handle *handle);
218
219 extern void AUD_Device_stopAll(void* device);
220
221 /**
222  * Sets the end behaviour of a playing or paused sound.
223  * \param handle The handle to the sound.
224  * \param keep When keep is true the sound source will not be deleted but set to
225  *             paused when its end has been reached.
226  * \return Whether the handle has been valid or not.
227  */
228 extern int AUD_Handle_setKeep(AUD_Handle *handle, int keep);
229
230 /**
231  * Seeks a playing or paused sound.
232  * \param handle The handle to the sound.
233  * \param seekTo From where the sound file should be played back in seconds.
234  * \return Whether the handle has been valid or not.
235  */
236 extern int AUD_Handle_setPosition(AUD_Handle *handle, float seekTo);
237
238 /**
239  * Retrieves the playback position of a handle.
240  * \param handle The handle to the sound.
241  * \return The current playback position in seconds or 0.0 if the handle is
242  *         invalid.
243  */
244 extern float AUD_Handle_getPosition(AUD_Handle *handle);
245
246 /**
247  * Returns the status of a playing, paused or stopped sound.
248  * \param handle The handle to the sound.
249  * \return The status of the sound behind the handle.
250  */
251 extern AUD_Status AUD_Handle_getStatus(AUD_Handle *handle);
252
253 /**
254  * Sets the listener location.
255  * \param location The new location.
256  */
257 extern int AUD_Device_setListenerLocation(const float location[3]);
258
259 /**
260  * Sets the listener velocity.
261  * \param velocity The new velocity.
262  */
263 extern int AUD_Device_setListenerVelocity(const float velocity[3]);
264
265 /**
266  * Sets the listener orientation.
267  * \param orientation The new orientation as quaternion.
268  */
269 extern int AUD_Device_setListenerOrientation(const float orientation[4]);
270
271 /**
272  * Sets the speed of sound.
273  * This value is needed for doppler effect calculation.
274  * \param speed The new speed of sound.
275  */
276 extern int AUD_Device_setSpeedOfSound(void* device, float speed);
277
278 /**
279  * Sets the doppler factor.
280  * This value is a scaling factor for the velocity vectors of sources and
281  * listener which is used while calculating the doppler effect.
282  * \param factor The new doppler factor.
283  */
284 extern int AUD_Device_setDopplerFactor(void* device, float factor);
285
286 /**
287  * Sets the distance model.
288  * \param model distance model.
289  */
290 extern int AUD_Device_setDistanceModel(void* device, AUD_DistanceModel model);
291
292 /**
293  * Sets the location of a source.
294  * \param handle The handle of the source.
295  * \param location The new location.
296  * \return Whether the action succeeded.
297  */
298 extern int AUD_Handle_setLocation(AUD_Handle *handle, const float location[3]);
299
300 /**
301  * Sets the velocity of a source.
302  * \param handle The handle of the source.
303  * \param velocity The new velocity.
304  * \return Whether the action succeeded.
305  */
306 extern int AUD_Handle_setVelocity(AUD_Handle *handle, const float velocity[3]);
307
308 /**
309  * Sets the orientation of a source.
310  * \param handle The handle of the source.
311  * \param orientation The new orientation as quaternion.
312  * \return Whether the action succeeded.
313  */
314 extern int AUD_Handle_setOrientation(AUD_Handle *handle, const float orientation[4]);
315
316 /**
317  * Sets whether the source location, velocity and orientation are relative
318  * to the listener.
319  * \param handle The handle of the source.
320  * \param relative Whether the source is relative.
321  * \return Whether the action succeeded.
322  */
323 extern int AUD_Handle_setRelative(AUD_Handle *handle, int relative);
324
325 /**
326  * Sets the maximum volume of a source.
327  * \param handle The handle of the source.
328  * \param volume The new maximum volume.
329  * \return Whether the action succeeded.
330  */
331 extern int AUD_Handle_setVolumeMaximum(AUD_Handle *handle, float volume);
332
333 /**
334  * Sets the minimum volume of a source.
335  * \param handle The handle of the source.
336  * \param volume The new minimum volume.
337  * \return Whether the action succeeded.
338  */
339 extern int AUD_Handle_setVolumeMinimum(AUD_Handle *handle, float volume);
340
341 /**
342  * Sets the maximum distance of a source.
343  * If a source is further away from the reader than this distance, the
344  * volume will automatically be set to 0.
345  * \param handle The handle of the source.
346  * \param distance The new maximum distance.
347  * \return Whether the action succeeded.
348  */
349 extern int AUD_Handle_setDistanceMaximum(AUD_Handle *handle, float distance);
350
351 /**
352  * Sets the reference distance of a source.
353  * \param handle The handle of the source.
354  * \param distance The new reference distance.
355  * \return Whether the action succeeded.
356  */
357 extern int AUD_Handle_setDistanceReference(AUD_Handle *handle, float distance);
358
359 /**
360  * Sets the attenuation of a source.
361  * This value is used for distance calculation.
362  * \param handle The handle of the source.
363  * \param factor The new attenuation.
364  * \return Whether the action succeeded.
365  */
366 extern int AUD_Handle_setAttenuation(AUD_Handle *handle, float factor);
367
368 /**
369  * Sets the outer angle of the cone of a source.
370  * \param handle The handle of the source.
371  * \param angle The new outer angle of the cone.
372  * \return Whether the action succeeded.
373  */
374 extern int AUD_Handle_setConeAngleOuter(AUD_Handle *handle, float angle);
375
376 /**
377  * Sets the inner angle of the cone of a source.
378  * \param handle The handle of the source.
379  * \param angle The new inner angle of the cone.
380  * \return Whether the action succeeded.
381  */
382 extern int AUD_Handle_setConeAngleInner(AUD_Handle *handle, float angle);
383
384 /**
385  * Sets the outer volume of the cone of a source.
386  * The volume between inner and outer angle is interpolated between inner
387  * volume and this value.
388  * \param handle The handle of the source.
389  * \param volume The new outer volume of the cone.
390  * \return Whether the action succeeded.
391  */
392 extern int AUD_Handle_setConeVolumeOuter(AUD_Handle *handle, float volume);
393
394 /**
395  * Sets the volume of a played back sound.
396  * \param handle The handle to the sound.
397  * \param volume The new volume, must be between 0.0 and 1.0.
398  * \return Whether the action succeeded.
399  */
400 extern int AUD_Handle_setVolume(AUD_Handle *handle, float volume);
401
402 /**
403  * Sets the pitch of a played back sound.
404  * \param handle The handle to the sound.
405  * \param pitch The new pitch.
406  * \return Whether the action succeeded.
407  */
408 extern int AUD_Handle_setPitch(AUD_Handle *handle, float pitch);
409
410 /**
411  * Opens a read device, with which audio data can be read.
412  * \param specs The specification of the audio data.
413  * \return A device handle.
414  */
415 extern AUD_Device *AUD_openReadDevice(AUD_DeviceSpecs specs);
416
417 /**
418  * Sets the main volume of a device.
419  * \param device The device.
420  * \param volume The new volume, must be between 0.0 and 1.0.
421  * \return Whether the action succeeded.
422  */
423 extern int AUD_setDeviceVolume(AUD_Device *device, float volume);
424
425 /**
426  * Plays back a sound file through a read device.
427  * \param device The read device.
428  * \param sound The handle of the sound file.
429  * \param seek The position where the sound should be seeked to.
430  * \return A handle to the played back sound.
431  */
432 extern AUD_Handle *AUD_playDevice(AUD_Device *device, AUD_Sound *sound, float seek);
433
434 /**
435  * Reads the next samples into the supplied buffer.
436  * \param device The read device.
437  * \param buffer The target buffer.
438  * \param length The length in samples to be filled.
439  * \return True if the reading succeeded, false if there are no sounds
440  *         played back currently, in that case the buffer is filled with
441  *         silence.
442  */
443 extern int AUD_Device_read(AUD_Device *device, data_t *buffer, int length);
444
445 /**
446  * Closes a read device.
447  * \param device The read device.
448  */
449 extern void AUD_Device_free(AUD_Device *device);
450
451 /**
452  * Reads a sound file into a newly created float buffer.
453  * The sound is therefore bandpassed, rectified and resampled.
454  */
455 extern float *AUD_readSoundBuffer(const char *filename, float low, float high,
456                                   float attack, float release, float threshold,
457                                   int accumulate, int additive, int square,
458                                   float sthreshold, double samplerate,
459                                   int *length);
460
461 /**
462  * Pauses a playing sound after a specific amount of time.
463  * \param handle The handle to the sound.
464  * \param seconds The time in seconds.
465  * \return The silence handle.
466  */
467 extern AUD_Handle *AUD_pauseAfter(AUD_Handle *handle, float seconds);
468
469 /**
470  * Creates a new sequenced sound scene.
471  * \param fps The FPS of the scene.
472  * \param muted Whether the scene is muted.
473  * \return The new sound scene.
474  */
475 extern AUD_Sound *AUD_Sequence_create(float fps, int muted);
476
477 /**
478  * Deletes a sound scene.
479  * \param sequencer The sound scene.
480  */
481 extern void AUD_Sequence_free(AUD_Sound *sequencer);
482
483 /**
484  * Sets the muting state of the scene.
485  * \param sequencer The sound scene.
486  * \param muted Whether the scene is muted.
487  */
488 extern void AUD_Sequence_setMuted(AUD_Sound *sequencer, int muted);
489
490 /**
491  * Sets the scene's FPS.
492  * \param sequencer The sound scene.
493  * \param fps The new FPS.
494  */
495 extern void AUD_Sequence_setFPS(AUD_Sound *sequencer, float fps);
496
497 /**
498  * Adds a new entry to the scene.
499  * \param sequencer The sound scene.
500  * \param sound The sound this entry should play.
501  * \param begin The start time.
502  * \param end The end time or a negative value if determined by the sound.
503  * \param skip How much seconds should be skipped at the beginning.
504  * \return The entry added.
505  */
506 extern AUD_SEntry *AUD_Sequence_add(AUD_Sound *sequencer, AUD_Sound *sound,
507                                    float begin, float end, float skip);
508
509 /**
510  * Removes an entry from the scene.
511  * \param sequencer The sound scene.
512  * \param entry The entry to remove.
513  */
514 extern void AUD_Sequence_remove(AUD_Sound *sequencer, AUD_SEntry *entry);
515
516 /**
517  * Moves the entry.
518  * \param entry The sequenced entry.
519  * \param begin The new start time.
520  * \param end The new end time or a negative value if unknown.
521  * \param skip How many seconds to skip at the beginning.
522  */
523 extern void AUD_SequenceEntry_move(AUD_SEntry *entry, float begin, float end, float skip);
524
525 /**
526  * Sets the muting state of the entry.
527  * \param entry The sequenced entry.
528  * \param mute Whether the entry should be muted or not.
529  */
530 extern void AUD_SequenceEntry_setMuted(AUD_SEntry *entry, char mute);
531
532 /**
533  * Sets the sound of the entry.
534  * \param entry The sequenced entry.
535  * \param sound The new sound.
536  */
537 extern void AUD_SequenceEntry_setSound(AUD_SEntry *entry, AUD_Sound *sound);
538
539 /**
540  * Writes animation data to a sequenced entry.
541  * \param entry The sequenced entry.
542  * \param type The type of animation data.
543  * \param frame The frame this data is for.
544  * \param data The data to write.
545  * \param animated Whether the attribute is animated.
546  */
547 extern void AUD_SequenceEntry_setAnimationData(AUD_SEntry *entry, AUD_AnimateablePropertyType type, int frame, float *data, char animated);
548
549 /**
550  * Writes animation data to a sequenced entry.
551  * \param sequencer The sound scene.
552  * \param type The type of animation data.
553  * \param frame The frame this data is for.
554  * \param data The data to write.
555  * \param animated Whether the attribute is animated.
556  */
557 extern void AUD_Sequence_setAnimationData(AUD_Sound *sequencer, AUD_AnimateablePropertyType type, int frame, float *data, char animated);
558
559 /**
560  * Sets the distance model of a sequence.
561  * param sequence The sequence to set the distance model from.
562  * param value The new distance model to set.
563  */
564 extern void AUD_Sequence_setDistanceModel(AUD_Sound* sequence, AUD_DistanceModel value);
565
566 /**
567  * Sets the doppler factor of a sequence.
568  * param sequence The sequence to set the doppler factor from.
569  * param value The new doppler factor to set.
570  */
571 extern void AUD_Sequence_setDopplerFactor(AUD_Sound* sequence, float value);
572
573 /**
574  * Sets the speed of sound of a sequence.
575  * param sequence The sequence to set the speed of sound from.
576  * param value The new speed of sound to set.
577  */
578 extern void AUD_Sequence_setSpeedOfSound(AUD_Sound* sequence, float value);
579 /**
580  * Sets the attenuation of a sequence_entry.
581  * param sequence_entry The sequence_entry to set the attenuation from.
582  * param value The new attenuation to set.
583  */
584 extern void AUD_SequenceEntry_setAttenuation(AUD_SEntry* sequence_entry, float value);
585
586 /**
587  * Sets the cone angle inner of a sequence_entry.
588  * param sequence_entry The sequence_entry to set the cone angle inner from.
589  * param value The new cone angle inner to set.
590  */
591 extern void AUD_SequenceEntry_setConeAngleInner(AUD_SEntry* sequence_entry, float value);
592
593 /**
594  * Sets the cone angle outer of a sequence_entry.
595  * param sequence_entry The sequence_entry to set the cone angle outer from.
596  * param value The new cone angle outer to set.
597  */
598 extern void AUD_SequenceEntry_setConeAngleOuter(AUD_SEntry* sequence_entry, float value);
599
600 /**
601  * Sets the cone volume outer of a sequence_entry.
602  * param sequence_entry The sequence_entry to set the cone volume outer from.
603  * param value The new cone volume outer to set.
604  */
605 extern void AUD_SequenceEntry_setConeVolumeOuter(AUD_SEntry* sequence_entry, float value);
606
607 /**
608  * Sets the distance maximum of a sequence_entry.
609  * param sequence_entry The sequence_entry to set the distance maximum from.
610  * param value The new distance maximum to set.
611  */
612 extern void AUD_SequenceEntry_setDistanceMaximum(AUD_SEntry* sequence_entry, float value);
613
614 /**
615  * Sets the distance reference of a sequence_entry.
616  * param sequence_entry The sequence_entry to set the distance reference from.
617  * param value The new distance reference to set.
618  */
619 extern void AUD_SequenceEntry_setDistanceReference(AUD_SEntry* sequence_entry, float value);
620
621 /**
622  * Sets the relative of a sequence_entry.
623  * param sequence_entry The sequence_entry to set the relative from.
624  * param value The new relative to set.
625  */
626 extern void AUD_SequenceEntry_setRelative(AUD_SEntry* sequence_entry, int value);
627
628 /**
629  * Sets the volume maximum of a sequence_entry.
630  * param sequence_entry The sequence_entry to set the volume maximum from.
631  * param value The new volume maximum to set.
632  */
633 extern void AUD_SequenceEntry_setVolumeMaximum(AUD_SEntry* sequence_entry, float value);
634
635 /**
636  * Sets the volume minimum of a sequence_entry.
637  * param sequence_entry The sequence_entry to set the volume minimum from.
638  * param value The new volume minimum to set.
639  */
640 extern void AUD_SequenceEntry_setVolumeMinimum(AUD_SEntry* sequence_entry, float value);
641
642 /**
643  * Sets the audio output specification of the sound scene to the specs of the
644  * current playback device.
645  * \param sequencer The sound scene.
646  */
647 extern void AUD_setSequencerDeviceSpecs(AUD_Sound *sequencer);
648
649 /**
650  * Sets the audio output specification of the sound scene.
651  * \param sequencer The sound scene.
652  * \param specs The new specification.
653  */
654 extern void AUD_Sequence_setSpecs(AUD_Sound *sequencer, AUD_Specs specs);
655
656 /**
657  * Seeks sequenced sound scene playback.
658  * \param handle Playback handle.
659  * \param time Time in seconds to seek to.
660  */
661 extern void AUD_seekSynchronizer(AUD_Handle *handle, float time);
662
663 /**
664  * Returns the current sound scene playback time.
665  * \param handle Playback handle.
666  * \return The playback time in seconds.
667  */
668 extern float AUD_getSynchronizerPosition(AUD_Handle *handle);
669
670 /**
671  * Starts the playback of jack transport if possible.
672  */
673 extern void AUD_playSynchronizer(void);
674
675 /**
676  * Stops the playback of jack transport if possible.
677  */
678 extern void AUD_stopSynchronizer(void);
679
680 #ifdef WITH_JACK
681 /**
682  * Sets the sync callback for jack transport.
683  * \param function The callback function.
684  * \param data The data parameter for the callback.
685  */
686 extern void AUD_setSynchronizerCallback(AUD_syncFunction function, void *data);
687 #endif
688
689 /**
690  * Returns whether jack transport is currently playing.
691  * \return Whether jack transport is currently playing.
692  */
693 extern int AUD_isSynchronizerPlaying(void);
694
695 /**
696  * Reads a sound into a buffer for drawing at a specific sampling rate.
697  * \param sound The sound to read.
698  * \param buffer The buffer to write to. Must have a size of 3*4*length.
699  * \param length How many samples to read from the sound.
700  * \param samples_per_second How many samples to read per second of the sound.
701  * \return How many samples really have been read. Always <= length.
702  */
703 extern int AUD_readSound(AUD_Sound *sound, sample_t *buffer, int length, int samples_per_second, short *interrupt);
704
705 /**
706  * Copies a sound.
707  * \param sound Sound to copy.
708  * \return Copied sound.
709  */
710 extern AUD_Sound *AUD_Sound_copy(AUD_Sound *sound);
711
712 /**
713  * Frees a handle.
714  * \param channel Handle to free.
715  */
716 extern void AUD_Handle_free(AUD_Handle *channel);
717
718 /**
719  * Creates a new set.
720  * \return The new set.
721  */
722 extern void *AUD_createSet(void);
723
724 /**
725  * Deletes a set.
726  * \param set The set to delete.
727  */
728 extern void AUD_destroySet(void *set);
729
730 /**
731  * Removes an entry from a set.
732  * \param set The set work on.
733  * \param entry The entry to remove.
734  * \return Whether the entry was in the set or not.
735  */
736 extern char AUD_removeSet(void *set, void *entry);
737
738 /**
739  * Adds a new entry to a set.
740  * \param set The set work on.
741  * \param entry The entry to add.
742  */
743 extern void AUD_addSet(void *set, void *entry);
744
745 /**
746  * Removes one entry from a set and returns it.
747  * \param set The set work on.
748  * \return The entry or NULL if the set is empty.
749  */
750 extern void *AUD_getSet(void *set);
751
752 /**
753  * Mixes a sound down into a file.
754  * \param sound The sound scene to mix down.
755  * \param start The start frame.
756  * \param length The count of frames to write.
757  * \param buffersize How many samples should be written at once.
758  * \param filename The file to write to.
759  * \param specs The file's audio specification.
760  * \param format The file's container format.
761  * \param codec The codec used for encoding the audio data.
762  * \param bitrate The bitrate for encoding.
763  * \return An error message or NULL in case of success.
764  */
765 extern const char *AUD_mixdown(AUD_Sound *sound, unsigned int start, unsigned int length,
766                                unsigned int buffersize, const char *filename,
767                                AUD_DeviceSpecs specs, AUD_Container format,
768                                AUD_Codec codec, unsigned int bitrate);
769
770 /**
771  * Mixes a sound down into multiple files.
772  * \param sound The sound scene to mix down.
773  * \param start The start frame.
774  * \param length The count of frames to write.
775  * \param buffersize How many samples should be written at once.
776  * \param filename The file to write to, the channel number and an underscore are added at the beginning.
777  * \param specs The file's audio specification.
778  * \param format The file's container format.
779  * \param codec The codec used for encoding the audio data.
780  * \param bitrate The bitrate for encoding.
781  * \return An error message or NULL in case of success.
782  */
783 extern const char *AUD_mixdown_per_channel(AUD_Sound *sound, unsigned int start, unsigned int length,
784                                            unsigned int buffersize, const char *filename,
785                                            AUD_DeviceSpecs specs, AUD_Container format,
786                                            AUD_Codec codec, unsigned int bitrate);
787
788 /**
789  * Opens a read device and prepares it for mixdown of the sound scene.
790  * \param specs Output audio specifications.
791  * \param sequencer The sound scene to mix down.
792  * \param volume The overall mixdown volume.
793  * \param start The start time of the mixdown in the sound scene.
794  * \return The read device for the mixdown.
795  */
796 extern AUD_Device *AUD_openMixdownDevice(AUD_DeviceSpecs specs, AUD_Sound *sequencer, float volume, float start);
797
798 #ifdef WITH_PYTHON
799 /**
800  * Retrieves the python factory of a sound.
801  * \param sound The sound factory.
802  * \return The python factory.
803  */
804 extern void *AUD_getPythonSound(AUD_Sound *sound);
805
806 /**
807  * Retrieves the sound factory of a python factory.
808  * \param sound The python factory.
809  * \return The sound factory.
810  */
811 extern AUD_Sound *AUD_getSoundFromPython(void *sound);
812 #endif
813
814 extern AUD_Device *AUD_Device_getCurrent(void);
815
816 extern int AUD_isJackSupported(void);
817
818 #ifdef __cplusplus
819 }
820 #endif
821
822 #endif //__AUD_C_API_H__