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 * \param rate The sample rate of the silence sound. 117 * \return A handle of the sound. 118 */ 119 extern AUD_API AUD_Sound* AUD_Sound_silence(AUD_SampleRate rate); 120 121 /** 122 * Creates a sine sound. 123 * \param frequency The frequency of the generated sine sound. 124 * \param rate The sample rate of the sine sound. 125 * \return A handle of the sound. 126 */ 127 extern AUD_API AUD_Sound* AUD_Sound_sine(float frequency, AUD_SampleRate rate); 128 129 /** 130 * Creates a square sound. 131 * \param frequency The frequency of the generated square sound. 132 * \param rate The sample rate of the square sound. 133 * \return A handle of the sound. 134 */ 135 extern AUD_API AUD_Sound* AUD_Sound_square(float frequency, AUD_SampleRate rate); 136 137 /** 138 * Creates a triangle sound. 139 * \param frequency The frequency of the generated triangle sound. 140 * \param rate The sample rate of the triangle sound. 141 * \return A handle of the sound. 142 */ 143 extern AUD_API AUD_Sound* AUD_Sound_triangle(float frequency, AUD_SampleRate rate); 144 145 /** 146 * Accumulates a sound by summing over positive input differences thus generating a monotonic sigal. 147 * If additivity is set to true negative input differences get added too, but positive ones with a factor of two. 148 * Note that with additivity the signal is not monotonic anymore. 149 * \param sound The sound to accumulate. 150 * \param additive Whether the accumulation should be additive or not. 151 * \return A handle of the accumulated sound. 152 */ 153 extern AUD_API AUD_Sound* AUD_Sound_accumulate(AUD_Sound* sound, int additive); 154 155 /** 156 * Attack-Decay-Sustain-Release envelopes the volume of a sound. 157 * Note: there is currently no way to trigger the release with this API. 158 * \param sound The sound to filter. 159 * \param attack The attack time in seconds. 160 * \param decay The decay time in seconds. 161 * \param sustain The sustain level. 162 * \param release The release time in seconds. 163 * \return A handle of the filtered sound. 164 */ 165 extern AUD_API AUD_Sound* AUD_Sound_ADSR(AUD_Sound* sound, float attack, float decay, float sustain, float release); 166 167 /** 168 * Delays a sound. 169 * \param sound The sound to dealy. 170 * \param delay The delay in seconds. 171 * \return A handle of the delayed sound. 172 */ 173 extern AUD_API AUD_Sound* AUD_Sound_delay(AUD_Sound* sound, float delay); 174 175 /** 176 * Envelopes a sound. 177 * \param sound The sound to envelope. 178 * \param attack The attack factor. 179 * \param release The release factor. 180 * \param threshold The general threshold value. 181 * \param arthreshold The attack/release threshold value. 182 * \return A handle of the enveloped sound. 183 */ 184 extern AUD_API AUD_Sound* AUD_Sound_envelope(AUD_Sound* sound, float attack, float release, float threshold, float arthreshold); 185 186 /** 187 * Fade in a sound. 188 * \param sound The sound to be fade in. 189 * \param start The time when the fading should start in seconds. 190 * \param length The duration of the fade in seconds. 191 * \return A handle of the faded sound. 192 */ 193 extern AUD_API AUD_Sound* AUD_Sound_fadein(AUD_Sound* sound, float start, float length); 194 195 /** 196 * Fade out a sound. 197 * \param sound The sound to be fade out. 198 * \param start The time when the fading should start in seconds. 199 * \param length The duration of the fade in seconds. 200 * \return A handle of the faded sound. 201 */ 202 extern AUD_API AUD_Sound* AUD_Sound_fadeout(AUD_Sound* sound, float start, float length); 203 204 /** 205 * Filter a sound. 206 * \param sound The sound to be filtered. 207 * \param b The nominator filter coefficients, may be NULL. 208 * \param b_length The length of the b array. 209 * \param a The denominator filter coefficients, may be NULL. 210 * \param a_length The length of the a array. 211 * \return A handle of the filtered sound. 212 */ 213 extern AUD_API AUD_Sound* AUD_Sound_filter(AUD_Sound* sound, float* b, int b_length, float* a, int a_length); 214 215 /** 216 * Highpass filters a sound. 217 * \param sound The sound to filter. 218 * \param frequency The filter cut-off frequency. 219 * \param Q The filter quality. If usunsure which value to use, pass 1.0f. 220 * \return A handle of the filtered sound. 221 */ 222 extern AUD_API AUD_Sound* AUD_Sound_highpass(AUD_Sound* sound, float frequency, float Q); 223 224 /** 225 * Limits a sound. 226 * \param sound The sound to limit. 227 * \param start The start time in seconds. 228 * \param end The stop time in seconds. 229 * \return A handle of the limited sound. 230 */ 231 extern AUD_API AUD_Sound* AUD_Sound_limit(AUD_Sound* sound, float start, float end); 232 233 /** 234 * Loops a sound. 235 * \param sound The sound to loop. 236 * \param count How often the sound should be looped. Negative values mean endlessly. 237 * \return A handle of the looped sound. 238 */ 239 extern AUD_API AUD_Sound* AUD_Sound_loop(AUD_Sound* sound, int count); 240 241 /** 242 * Lowpass filters a sound. 243 * \param sound The sound to filter. 244 * \param frequency The filter cut-off frequency. 245 * \param Q The filter quality. If usunsure which value to use, pass 1.0f. 246 * \return A handle of the filtered sound. 247 */ 248 extern AUD_API AUD_Sound* AUD_Sound_lowpass(AUD_Sound* sound, float frequency, float Q); 249 250 /** 251 * Modulates two sound, which means multiplying the sound samples. 252 * \param first The first sound. 253 * \param second The second sound. 254 * \return A handle of the modulated sound. 255 */ 256 extern AUD_API AUD_Sound* AUD_Sound_modulate(AUD_Sound* first, AUD_Sound* second); 257 258 /** 259 * Changes the pitch of a sound. 260 * \param sound The sound to change. 261 * \param factor The factor to change the pitch with. 262 * \return A handle of the pitched sound. 263 */ 264 extern AUD_API AUD_Sound* AUD_Sound_pitch(AUD_Sound* sound, float factor); 265 266 /** 267 * Rechannels the sound. 268 * \param sound The sound to rechannel. 269 * \param channels The new channel configuration. 270 * \return The rechanneled sound. 271 */ 272 extern AUD_API AUD_Sound* AUD_Sound_rechannel(AUD_Sound* sound, AUD_Channels channels); 273 274 /** 275 * Resamples the sound. 276 * \param sound The sound to resample. 277 * \param rate The new sample rate. 278 * \param high_quality When true use a higher quality but slower resampler. 279 * \return The resampled sound. 280 */ 281 extern AUD_API AUD_Sound* AUD_Sound_resample(AUD_Sound* sound, AUD_SampleRate rate, bool high_quality); 282 283 /** 284 * Reverses a sound. Make sure the sound source can be reversed. 285 * \param sound The sound to reverse. 286 * \return A handle of the reversed sound. 287 */ 288 extern AUD_API AUD_Sound* AUD_Sound_reverse(AUD_Sound* sound); 289 290 /** 291 * Sums the samples of a sound. 292 * \param sound The sound to sum. 293 * \return A handle of the summed sound. 294 */ 295 extern AUD_API AUD_Sound* AUD_Sound_sum(AUD_Sound* sound); 296 297 /** 298 * Turns a sound into a square wave by thresholding. 299 * \param sound The sound to threshold. 300 * \param threshold Threshold value over which an amplitude counts non-zero. 301 * \return A handle of the thresholded sound. 302 */ 303 extern AUD_API AUD_Sound* AUD_Sound_threshold(AUD_Sound* sound, float threshold); 304 305 /** 306 * Changes the volume of a sound. 307 * \param sound The sound to change. 308 * \param volume The new volume of the sound. Should be in the range 0 to 1. Use higher values with caution. 309 * \return A handle of the amplified sound. 310 */ 311 extern AUD_API AUD_Sound* AUD_Sound_volume(AUD_Sound* sound, float volume); 312 313 /** 314 * Joins two sound, which means playing them one after the other. 315 * \param first The first sound. 316 * \param second The second sound. 317 * \return A handle of the joined sound. 318 */ 319 extern AUD_API AUD_Sound* AUD_Sound_join(AUD_Sound* first, AUD_Sound* second); 320 321 /** 322 * Mixes two sound, which means superposing the sound samples. 323 * \param first The first sound. 324 * \param second The second sound. 325 * \return A handle of the mixed sound. 326 */ 327 extern AUD_API AUD_Sound* AUD_Sound_mix(AUD_Sound* first, AUD_Sound* second); 328 329 /** 330 * Ping pongs a sound. 331 * \param sound The sound to ping pong. 332 * \return A handle of the ping pong sound. 333 */ 334 extern AUD_API AUD_Sound* AUD_Sound_pingpong(AUD_Sound* sound); 335 336 /** 337 * Unloads a sound of any type. 338 * \param sound The handle of the sound. 339 */ 340 extern AUD_API void AUD_Sound_free(AUD_Sound* sound); 341 342 /** 343 * Copies a sound. 344 * \param sound Sound to copy. 345 * \return Copied sound. 346 */ 347 extern AUD_API AUD_Sound* AUD_Sound_copy(AUD_Sound* sound); 348 349 /** 350 * Creates an empty sound list that can contain several sounds. 351 * \param random A flag that indicates how the list will be played: Randomly or sequentially. 352 * if 0 the playback will be sequential, if not 0 the playback will be random. 353 * \return A handle of the sound list. 354 */ 355 extern AUD_API AUD_Sound* AUD_Sound_list(int random); 356 357 /** 358 * Adds a new sound to a sound list. 359 * \param list The sound list in which the sound will be added. 360 * \param sound The sound that will be added to the list. 361 * \return 0 if the sound couldn't be added (the list parameter isn't a sound list). 362 */ 363 extern AUD_API int AUD_SoundList_addSound(AUD_Sound* list, AUD_Sound* sound); 364 365 /** 366 * Creates a sound that will be restarted when sought backwards. If the original sound is a sound list, the playing sound can change. 367 * \param sound The handle of the sound. 368 * \return A handle of the mutable sound. 369 */ 370 extern AUD_API AUD_Sound* AUD_Sound_mutable(AUD_Sound* sound); 371 372 #ifdef WITH_CONVOLUTION 373 extern AUD_API AUD_Sound* AUD_Sound_Convolver(AUD_Sound* sound, AUD_ImpulseResponse* filter, AUD_ThreadPool* threadPool); 374 extern AUD_API AUD_Sound* AUD_Sound_Binaural(AUD_Sound* sound, AUD_HRTF* hrtfs, AUD_Source* source, AUD_ThreadPool* threadPool); 375 #endif 376 377 #ifdef __cplusplus 378 } 379 #endif 380