tmp
[blender.git] / extern / audaspace / bindings / C / AUD_Sound.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  * Retrieves the sample specification of the sound.
27  * \param sound The sound to retrieve from.
28  * \return The sample specification of the sound.
29  * \note This function creates a reader from the sound and deletes it again.
30  */
31 extern AUD_API AUD_Specs AUD_Sound_getSpecs(AUD_Sound* sound);
32
33 /**
34  * Retrieves the approximate length of the sound.
35  * \param sound The sound to retrieve from.
36  * \return The length of the sound in samples.
37  * \note This function creates a reader from the sound and deletes it again.
38  */
39 extern AUD_API int AUD_getLength(AUD_Sound* sound);
40
41 /**
42  * Reads a sound's samples into memory.
43  * \param sound The sound to read.
44  * \param length Pointer to store the length of memory read.
45  * \param specs Pointer to store the data's sample specification.
46  * \return A pointer to the sample data.
47  * \warning The data has to be freed with AUD_Sound_freeData.
48  */
49 extern AUD_API sample_t* AUD_Sound_data(AUD_Sound* sound, int* length, AUD_Specs* specs);
50
51 /**
52  * Frees a buffer previously allocated with AUD_Sound_data.
53  * \param data The buffer to be freed.
54  */
55 extern AUD_API void AUD_Sound_freeData(sample_t* data);
56
57 /**
58  * Writes the sound to a file.
59  * \param sound The sound to write.
60  * \param filename The path to write to..
61  * \param rate The sample rate to write with.
62  * \param channels The number of channels to write with.
63  * \param format The sample format to write with.
64  * \param container The container format for the file.
65  * \param codec The codec to use in the file.
66  * \param bitrate The bitrate to write with.
67  * \param buffersize The size of the writing buffer.
68  * \return A nullptr or an error message in case of error.
69  * \note Most parameters can be set to zero for default values.
70  */
71 extern AUD_API const char* AUD_Sound_write(AUD_Sound* sound, const char* filename, AUD_SampleRate rate, AUD_Channels channels, AUD_SampleFormat format, AUD_Container container, AUD_Codec codec, int bitrate, int buffersize);
72
73 /**
74  * Creates a sound from a data buffer.
75  * \param data The data as interleaved samples.
76  * \param length The data's length in samples.
77  * \param specs The data's sample specification.
78  * \return A handle of the sound.
79  * \note The data gets copied to an internal memory buffer.
80  *       The pointer does not need to stay valid for the lifetime of the object.
81  */
82 extern AUD_API AUD_Sound* AUD_Sound_buffer(sample_t* data, int length, AUD_Specs specs);
83
84 /**
85  * Loads a sound file from a memory buffer.
86  * \param buffer The buffer which contains the sound file.
87  * \param size The size of the buffer.
88  * \return A handle of the sound file.
89  */
90 extern AUD_API AUD_Sound* AUD_Sound_bufferFile(unsigned char* buffer, int size);
91
92 /**
93  * Caches a sound into a memory buffer.
94  * \param sound The sound to cache.
95  * \return A handle of the cached sound.
96  */
97 extern AUD_API AUD_Sound* AUD_Sound_cache(AUD_Sound* sound);
98
99 /**
100  * Loads a sound file.
101  * \param filename The filename of the sound file.
102  * \return A handle of the sound file.
103  */
104 extern AUD_API AUD_Sound* AUD_Sound_file(const char* filename);
105
106 /**
107  * Creates a sawtooth sound.
108  * \param frequency The frequency of the generated sawtooth sound.
109  * \param rate The sample rate of the sawtooth sound.
110  * \return A handle of the sound.
111  */
112 extern AUD_API AUD_Sound* AUD_Sound_sawtooth(float frequency, AUD_SampleRate rate);
113
114 /**
115  * Creates a quiet sound.
116  * \return A handle of the sound.
117  */
118 extern AUD_API AUD_Sound* AUD_Sound_silence();
119
120 /**
121  * Creates a sine sound.
122  * \param frequency The frequency of the generated sine sound.
123  * \param rate The sample rate of the sine sound.
124  * \return A handle of the sound.
125  */
126 extern AUD_API AUD_Sound* AUD_Sound_sine(float frequency, AUD_SampleRate rate);
127
128 /**
129  * Creates a square sound.
130  * \param frequency The frequency of the generated square sound.
131  * \param rate The sample rate of the square sound.
132  * \return A handle of the sound.
133  */
134 extern AUD_API AUD_Sound* AUD_Sound_square(float frequency, AUD_SampleRate rate);
135
136 /**
137  * Creates a triangle sound.
138  * \param frequency The frequency of the generated triangle sound.
139  * \param rate The sample rate of the triangle sound.
140  * \return A handle of the sound.
141  */
142 extern AUD_API AUD_Sound* AUD_Sound_triangle(float frequency, AUD_SampleRate rate);
143
144 /**
145  * Accumulates a sound by summing over positive input differences thus generating a monotonic sigal.
146  * If additivity is set to true negative input differences get added too, but positive ones with a factor of two.
147  * Note that with additivity the signal is not monotonic anymore.
148  * \param sound The sound to accumulate.
149  * \param additive Whether the accumulation should be additive or not.
150  * \return A handle of the accumulated sound.
151  */
152 extern AUD_API AUD_Sound* AUD_Sound_accumulate(AUD_Sound* sound, int additive);
153
154 /**
155  * Attack-Decay-Sustain-Release envelopes the volume of a sound.
156  * Note: there is currently no way to trigger the release with this API.
157  * \param sound The sound to filter.
158  * \param attack The attack time in seconds.
159  * \param decay The decay time in seconds.
160  * \param sustain The sustain level.
161  * \param release The release time in seconds.
162  * \return A handle of the filtered sound.
163  */
164 extern AUD_API AUD_Sound* AUD_Sound_ADSR(AUD_Sound* sound, float attack, float decay, float sustain, float release);
165
166 /**
167  * Delays a sound.
168  * \param sound The sound to dealy.
169  * \param delay The delay in seconds.
170  * \return A handle of the delayed sound.
171  */
172 extern AUD_API AUD_Sound* AUD_Sound_delay(AUD_Sound* sound, float delay);
173
174 /**
175  * Envelopes a sound.
176  * \param sound The sound to envelope.
177  * \param attack The attack factor.
178  * \param release The release factor.
179  * \param threshold The general threshold value.
180  * \param arthreshold The attack/release threshold value.
181  * \return A handle of the enveloped sound.
182  */
183 extern AUD_API AUD_Sound* AUD_Sound_envelope(AUD_Sound* sound, float attack, float release, float threshold, float arthreshold);
184
185 /**
186  * Fade in a sound.
187  * \param sound The sound to be fade in.
188  * \param start The time when the fading should start in seconds.
189  * \param length The duration of the fade in seconds.
190  * \return A handle of the faded sound.
191  */
192 extern AUD_API AUD_Sound* AUD_Sound_fadein(AUD_Sound* sound, float start, float length);
193
194 /**
195  * Fade out a sound.
196  * \param sound The sound to be fade out.
197  * \param start The time when the fading should start in seconds.
198  * \param length The duration of the fade in seconds.
199  * \return A handle of the faded sound.
200  */
201 extern AUD_API AUD_Sound* AUD_Sound_fadeout(AUD_Sound* sound, float start, float length);
202
203 /**
204  * Filter a sound.
205  * \param sound The sound to be filtered.
206  * \param b The nominator filter coefficients, may be NULL.
207  * \param b_length The length of the b array.
208  * \param a The denominator filter coefficients, may be NULL.
209  * \param a_length The length of the a array.
210  * \return A handle of the filtered sound.
211  */
212 extern AUD_API AUD_Sound* AUD_Sound_filter(AUD_Sound* sound, float* b, int b_length, float* a, int a_length);
213
214 /**
215  * Highpass filters a sound.
216  * \param sound The sound to filter.
217  * \param frequency The filter cut-off frequency.
218  * \param Q The filter quality. If usunsure which value to use, pass 1.0f.
219  * \return A handle of the filtered sound.
220  */
221 extern AUD_API AUD_Sound* AUD_Sound_highpass(AUD_Sound* sound, float frequency, float Q);
222
223 /**
224  * Limits a sound.
225  * \param sound The sound to limit.
226  * \param start The start time in seconds.
227  * \param end The stop time in seconds.
228  * \return A handle of the limited sound.
229  */
230 extern AUD_API AUD_Sound* AUD_Sound_limit(AUD_Sound* sound, float start, float end);
231
232 /**
233  * Loops a sound.
234  * \param sound The sound to loop.
235  * \param count How often the sound should be looped. Negative values mean endlessly.
236  * \return A handle of the looped sound.
237  */
238 extern AUD_API AUD_Sound* AUD_Sound_loop(AUD_Sound* sound, int count);
239
240 /**
241  * Lowpass filters a sound.
242  * \param sound The sound to filter.
243  * \param frequency The filter cut-off frequency.
244  * \param Q The filter quality. If usunsure which value to use, pass 1.0f.
245  * \return A handle of the filtered sound.
246  */
247 extern AUD_API AUD_Sound* AUD_Sound_lowpass(AUD_Sound* sound, float frequency, float Q);
248
249 /**
250  * Changes the pitch of a sound.
251  * \param sound The sound to change.
252  * \param factor The factor to change the pitch with.
253  * \return A handle of the pitched sound.
254  */
255 extern AUD_API AUD_Sound* AUD_Sound_pitch(AUD_Sound* sound, float factor);
256
257 /**
258  * Rechannels the sound.
259  * \param sound The sound to rechannel.
260  * \param channels The new channel configuration.
261  * \return The rechanneled sound.
262  */
263 extern AUD_API AUD_Sound* AUD_Sound_rechannel(AUD_Sound* sound, AUD_Channels channels);
264
265 /**
266  * Resamples the sound.
267  * \param sound The sound to resample.
268  * \param rate The new sample rate.
269  * \param high_quality When true use a higher quality but slower resampler.
270  * \return The resampled sound.
271  */
272 extern AUD_API AUD_Sound* AUD_Sound_resample(AUD_Sound* sound, AUD_SampleRate rate, bool high_quality);
273
274 /**
275  * Reverses a sound. Make sure the sound source can be reversed.
276  * \param sound The sound to reverse.
277  * \return A handle of the reversed sound.
278  */
279 extern AUD_API AUD_Sound* AUD_Sound_reverse(AUD_Sound* sound);
280
281 /**
282  * Sums the samples of a sound.
283  * \param sound The sound to sum.
284  * \return A handle of the summed sound.
285  */
286 extern AUD_API AUD_Sound* AUD_Sound_sum(AUD_Sound* sound);
287
288 /**
289  * Turns a sound into a square wave by thresholding.
290  * \param sound The sound to threshold.
291  * \param threshold Threshold value over which an amplitude counts non-zero.
292  * \return A handle of the thresholded sound.
293  */
294 extern AUD_API AUD_Sound* AUD_Sound_threshold(AUD_Sound* sound, float threshold);
295
296 /**
297  * Changes the volume of a sound.
298  * \param sound The sound to change.
299  * \param volume The new volume of the sound. Should be in the range 0 to 1. Use higher values with caution.
300  * \return A handle of the amplified sound.
301  */
302 extern AUD_API AUD_Sound* AUD_Sound_volume(AUD_Sound* sound, float volume);
303
304 /**
305  * Joins two sound, which means playing them one after the other.
306  * \param first The first sound.
307  * \param second The second sound.
308  * \return A handle of the joined sound.
309  */
310 extern AUD_API AUD_Sound* AUD_Sound_join(AUD_Sound* first, AUD_Sound* second);
311
312 /**
313  * Mixes two sound, which means superposing the sound samples.
314  * \param first The first sound.
315  * \param second The second sound.
316  * \return A handle of the mixed sound.
317  */
318 extern AUD_API AUD_Sound* AUD_Sound_mix(AUD_Sound* first, AUD_Sound* second);
319
320 /**
321  * Ping pongs a sound.
322  * \param sound The sound to ping pong.
323  * \return A handle of the ping pong sound.
324  */
325 extern AUD_API AUD_Sound* AUD_Sound_pingpong(AUD_Sound* sound);
326
327 /**
328  * Unloads a sound of any type.
329  * \param sound The handle of the sound.
330  */
331 extern AUD_API void AUD_Sound_free(AUD_Sound* sound);
332
333 /**
334  * Copies a sound.
335  * \param sound Sound to copy.
336  * \return Copied sound.
337  */
338 extern AUD_API AUD_Sound* AUD_Sound_copy(AUD_Sound* sound);
339
340 /**
341  * Creates an empty sound list that can contain several sounds.
342  * \param random A flag that indicates how the list will be played: Randomly or sequentially.
343  *                              if 0 the playback will be sequential, if not 0 the playback will be random.
344  * \return A handle of the sound list.
345  */
346 extern AUD_API AUD_Sound* AUD_Sound_list(int random);
347
348 /**
349 * Adds a new sound to a sound list.
350  * \param list The sound list in which the sound will be added.
351  * \param sound The sound that will be added to the list.
352  * \return 0 if the sound couldn't be added (the list parameter isn't a sound list).
353 */
354 extern AUD_API int AUD_SoundList_addSound(AUD_Sound* list, AUD_Sound* sound);
355
356 /**
357  * Creates a sound that will be restarted when sought backwards. If the original sound is a sound list, the playing sound can change.
358  * \param sound The handle of the sound.
359  * \return A handle of the mutable sound.
360 */
361 extern AUD_API AUD_Sound* AUD_Sound_mutable(AUD_Sound* sound);
362
363 #ifdef WITH_CONVOLUTION
364         extern AUD_API AUD_Sound* AUD_Sound_Convolver(AUD_Sound* sound, AUD_ImpulseResponse* filter, AUD_ThreadPool* threadPool);
365         extern AUD_API AUD_Sound* AUD_Sound_Binaural(AUD_Sound* sound, AUD_HRTF* hrtfs, AUD_Source* source, AUD_ThreadPool* threadPool);
366 #endif
367
368 #ifdef __cplusplus
369 }
370 #endif