tmp
[blender.git] / extern / audaspace / bindings / C / AUD_Special.h
1 /*******************************************************************************
2  * Copyright 2009-2016 Jörg Müller
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *   http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  ******************************************************************************/
16
17 #pragma once
18
19 #include "AUD_Types.h"
20
21 #ifdef __cplusplus
22 extern "C" {
23 #endif
24
25 /**
26  * Returns information about a sound.
27  * \param sound The sound to get the info about.
28  * \return The AUD_SoundInfo structure with filled in data.
29  */
30 extern AUD_API AUD_SoundInfo AUD_getInfo(AUD_Sound* sound);
31
32 /**
33  * Reads a sound file into a newly created float buffer.
34  * The sound is therefore bandpassed, rectified and resampled.
35  */
36 extern AUD_API float* AUD_readSoundBuffer(const char* filename, float low, float high,
37                                                                   float attack, float release, float threshold,
38                                                                   int accumulate, int additive, int square,
39                                                                   float sthreshold, double samplerate,
40                                                                   int* length);
41
42 /**
43  * Pauses a playing sound after a specific amount of time.
44  * \param handle The handle to the sound.
45  * \param seconds The time in seconds.
46  * \return The silence handle.
47  */
48 extern AUD_API AUD_Handle* AUD_pauseAfter(AUD_Handle* handle, float seconds);
49
50 /**
51  * Reads a sound into a buffer for drawing at a specific sampling rate.
52  * \param sound The sound to read.
53  * \param buffer The buffer to write to. Must have a size of 3*4*length.
54  * \param length How many samples to read from the sound.
55  * \param samples_per_second How many samples to read per second of the sound.
56  * \return How many samples really have been read. Always <= length.
57  */
58 extern AUD_API int AUD_readSound(AUD_Sound* sound, float* buffer, int length, int samples_per_second, short* interrupt);
59
60 /**
61  * Mixes a sound down into a file.
62  * \param sound The sound scene to mix down.
63  * \param start The start frame.
64  * \param length The count of frames to write.
65  * \param buffersize How many samples should be written at once.
66  * \param filename The file to write to.
67  * \param specs The file's audio specification.
68  * \param format The file's container format.
69  * \param codec The codec used for encoding the audio data.
70  * \param bitrate The bitrate for encoding.
71  * \return An error message or NULL in case of success.
72  */
73 extern AUD_API const char* AUD_mixdown(AUD_Sound* sound, unsigned int start, unsigned int length,
74                                                            unsigned int buffersize, const char* filename,
75                                                            AUD_DeviceSpecs specs, AUD_Container format,
76                                                            AUD_Codec codec, unsigned int bitrate);
77
78 /**
79  * Mixes a sound down into multiple files.
80  * \param sound The sound scene to mix down.
81  * \param start The start frame.
82  * \param length The count of frames to write.
83  * \param buffersize How many samples should be written at once.
84  * \param filename The file to write to, the channel number and an underscore are added at the beginning.
85  * \param specs The file's audio specification.
86  * \param format The file's container format.
87  * \param codec The codec used for encoding the audio data.
88  * \param bitrate The bitrate for encoding.
89  * \return An error message or NULL in case of success.
90  */
91 extern AUD_API const char* AUD_mixdown_per_channel(AUD_Sound* sound, unsigned int start, unsigned int length,
92                                                                                    unsigned int buffersize, const char* filename,
93                                                                                    AUD_DeviceSpecs specs, AUD_Container format,
94                                                                                    AUD_Codec codec, unsigned int bitrate);
95
96 /**
97  * Opens a read device and prepares it for mixdown of the sound scene.
98  * \param specs Output audio specifications.
99  * \param sequencer The sound scene to mix down.
100  * \param volume The overall mixdown volume.
101  * \param start The start time of the mixdown in the sound scene.
102  * \return The read device for the mixdown.
103  */
104 extern AUD_API AUD_Device* AUD_openMixdownDevice(AUD_DeviceSpecs specs, AUD_Sound* sequencer, float volume, float start);
105
106 /**
107  * Initializes audio routines (FFMPEG/JACK if it is enabled).
108  */
109 extern AUD_API void AUD_initOnce();
110
111 /**
112  * Unitinitializes an audio routines.
113  */
114 extern AUD_API void AUD_exitOnce();
115
116 /**
117  * Initializes an audio device.
118  * \param device The device type that should be used.
119  * \param specs The audio specification to be used.
120  * \param buffersize The buffersize for the device.
121  * \return Whether the device has been initialized.
122  */
123 extern AUD_API AUD_Device* AUD_init(const char* device, AUD_DeviceSpecs specs, int buffersize, const char* name);
124
125 /**
126  * Unitinitializes an audio device.
127  * \param device The device to free.
128  */
129 extern AUD_API void AUD_exit(AUD_Device* device);
130
131 /**
132  * Retrieves available devices. Note that all memory returned has to be freed!
133  */
134 extern AUD_API char** AUD_getDeviceNames();
135
136 #ifdef __cplusplus
137 }
138 #endif