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_CAPI
  30 #define AUD_CAPI
  31
  32 #ifdef WITH_PYTHON
  33 #include "Python.h"
  34 #endif
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 #include "AUD_Space.h"
  41
  42 /// Supported output devices.
  43 typedef enum
  44 {
  45         AUD_NULL_DEVICE = 0,
  46         AUD_SDL_DEVICE,
  47         AUD_OPENAL_DEVICE,
  48         AUD_JACK_DEVICE
  49 } AUD_DeviceType;
  50
  51 /// Sound information structure.
  52 typedef struct
  53 {
  54         AUD_Specs specs;
  55         float length;
  56 } AUD_SoundInfo;
  57
  58 #ifndef AUD_CAPI_IMPLEMENTATION
  59         typedef void AUD_Sound;
  60         typedef void AUD_Handle;
  61         typedef void AUD_Device;
  62         typedef void AUD_SEntry;
  63         typedef float (*AUD_volumeFunction)(void*, void*, float);
  64         typedef void (*AUD_syncFunction)(void*, int, float);
  65 #endif
  66
  67 /**
  68  * Initializes FFMPEG if it is enabled.
  69  */
  70 extern void AUD_initOnce(void);
  71
  72 /**
  73  * Initializes an audio device.
  74  * \param device The device type that should be used.
  75  * \param specs The audio specification to be used.
  76  * \param buffersize The buffersize for the device.
  77  * \return Whether the device has been initialized.
  78  */
  79 extern int AUD_init(AUD_DeviceType device, AUD_DeviceSpecs specs, int buffersize);
  80
  81 /**
  82  * Unitinitializes an audio device.
  83  */
  84 extern void AUD_exit(void);
  85
  86 /**
  87  * Locks the playback device.
  88  */
  89 extern void AUD_lock(void);
  90
  91 /**
  92  * Unlocks the device.
  93  */
  94 extern void AUD_unlock(void);
  95
  96 /**
  97  * Returns information about a sound.
  98  * \param sound The sound to get the info about.
  99  * \return The AUD_SoundInfo structure with filled in data.
 100  */
 101 extern AUD_SoundInfo AUD_getInfo(AUD_Sound* sound);
 102
 103 /**
 104  * Loads a sound file.
 105  * \param filename The filename of the sound file.
 106  * \return A handle of the sound file.
 107  */
 108 extern AUD_Sound* AUD_load(const char* filename);
 109
 110 /**
 111  * Loads a sound file.
 112  * \param buffer The buffer which contains the sound file.
 113  * \param size The size of the buffer.
 114  * \return A handle of the sound file.
 115  */
 116 extern AUD_Sound* AUD_loadBuffer(unsigned char* buffer, int size);
 117
 118 /**
 119  * Buffers a sound.
 120  * \param sound The sound to buffer.
 121  * \return A handle of the sound buffer.
 122  */
 123 extern AUD_Sound* AUD_bufferSound(AUD_Sound* sound);
 124
 125 /**
 126  * Rechannels the sound to be mono.
 127  * \param sound The sound to rechannel.
 128  * \return The mono sound.
 129  */
 130 extern AUD_Sound* AUD_monoSound(AUD_Sound* sound);
 131
 132 /**
 133  * Delays a sound.
 134  * \param sound The sound to dealy.
 135  * \param delay The delay in seconds.
 136  * \return A handle of the delayed sound.
 137  */
 138 extern AUD_Sound* AUD_delaySound(AUD_Sound* sound, float delay);
 139
 140 /**
 141  * Limits a sound.
 142  * \param sound The sound to limit.
 143  * \param start The start time in seconds.
 144  * \param end The stop time in seconds.
 145  * \return A handle of the limited sound.
 146  */
 147 extern AUD_Sound* AUD_limitSound(AUD_Sound* sound, float start, float end);
 148
 149 /**
 150  * Ping pongs a sound.
 151  * \param sound The sound to ping pong.
 152  * \return A handle of the ping pong sound.
 153  */
 154 extern AUD_Sound* AUD_pingpongSound(AUD_Sound* sound);
 155
 156 /**
 157  * Loops a sound.
 158  * \param sound The sound to loop.
 159  * \return A handle of the looped sound.
 160  */
 161 extern AUD_Sound* AUD_loopSound(AUD_Sound* sound);
 162
 163 /**
 164  * Sets a remaining loop count of a looping sound that currently plays.
 165  * \param handle The playback handle.
 166  * \param loops The count of remaining loops, -1 for infinity.
 167  * \return Whether the handle is valid.
 168  */
 169 extern int AUD_setLoop(AUD_Handle* handle, int loops);
 170
 171 /**
 172  * Rectifies a sound.
 173  * \param sound The sound to rectify.
 174  * \return A handle of the rectified sound.
 175  */
 176 extern AUD_Sound* AUD_rectifySound(AUD_Sound* sound);
 177
 178 /**
 179  * Unloads a sound of any type.
 180  * \param sound The handle of the sound.
 181  */
 182 extern void AUD_unload(AUD_Sound* sound);
 183
 184 /**
 185  * Plays back a sound file.
 186  * \param sound The handle of the sound file.
 187  * \param keep When keep is true the sound source will not be deleted but set to
 188  *             paused when its end has been reached.
 189  * \return A handle to the played back sound.
 190  */
 191 extern AUD_Handle* AUD_play(AUD_Sound* sound, int keep);
 192
 193 /**
 194  * Pauses a played back sound.
 195  * \param handle The handle to the sound.
 196  * \return Whether the handle has been playing or not.
 197  */
 198 extern int AUD_pause(AUD_Handle* handle);
 199
 200 /**
 201  * Resumes a paused sound.
 202  * \param handle The handle to the sound.
 203  * \return Whether the handle has been paused or not.
 204  */
 205 extern int AUD_resume(AUD_Handle* handle);
 206
 207 /**
 208  * Stops a playing or paused sound.
 209  * \param handle The handle to the sound.
 210  * \return Whether the handle has been valid or not.
 211  */
 212 extern int AUD_stop(AUD_Handle* handle);
 213
 214 /**
 215  * Sets the end behaviour of a playing or paused sound.
 216  * \param handle The handle to the sound.
 217  * \param keep When keep is true the sound source will not be deleted but set to
 218  *             paused when its end has been reached.
 219  * \return Whether the handle has been valid or not.
 220  */
 221 extern int AUD_setKeep(AUD_Handle* handle, int keep);
 222
 223 /**
 224  * Seeks a playing or paused sound.
 225  * \param handle The handle to the sound.
 226  * \param seekTo From where the sound file should be played back in seconds.
 227  * \return Whether the handle has been valid or not.
 228  */
 229 extern int AUD_seek(AUD_Handle* handle, float seekTo);
 230
 231 /**
 232  * Retrieves the playback position of a handle.
 233  * \param handle The handle to the sound.
 234  * \return The current playback position in seconds or 0.0 if the handle is
 235  *         invalid.
 236  */
 237 extern float AUD_getPosition(AUD_Handle* handle);
 238
 239 /**
 240  * Returns the status of a playing, paused or stopped sound.
 241  * \param handle The handle to the sound.
 242  * \return The status of the sound behind the handle.
 243  */
 244 extern AUD_Status AUD_getStatus(AUD_Handle* handle);
 245
 246 /**
 247  * Sets the listener location.
 248  * \param location The new location.
 249  */
 250 extern int AUD_setListenerLocation(const float* location);
 251
 252 /**
 253  * Sets the listener velocity.
 254  * \param velocity The new velocity.
 255  */
 256 extern int AUD_setListenerVelocity(const float* velocity);
 257
 258 /**
 259  * Sets the listener orientation.
 260  * \param orientation The new orientation as quaternion.
 261  */
 262 extern int AUD_setListenerOrientation(const float* orientation);
 263
 264 /**
 265  * Sets the speed of sound.
 266  * This value is needed for doppler effect calculation.
 267  * \param speed The new speed of sound.
 268  */
 269 extern int AUD_setSpeedOfSound(float speed);
 270
 271 /**
 272  * Sets the doppler factor.
 273  * This value is a scaling factor for the velocity vectors of sources and
 274  * listener which is used while calculating the doppler effect.
 275  * \param factor The new doppler factor.
 276  */
 277 extern int AUD_setDopplerFactor(float factor);
 278
 279 /**
 280  * Sets the distance model.
 281  * \param model distance model.
 282  */
 283 extern int AUD_setDistanceModel(AUD_DistanceModel model);
 284
 285 /**
 286  * Sets the location of a source.
 287  * \param handle The handle of the source.
 288  * \param location The new location.
 289  * \return Whether the action succeeded.
 290  */
 291 extern int AUD_setSourceLocation(AUD_Handle* handle, const float* location);
 292
 293 /**
 294  * Sets the velocity of a source.
 295  * \param handle The handle of the source.
 296  * \param velocity The new velocity.
 297  * \return Whether the action succeeded.
 298  */
 299 extern int AUD_setSourceVelocity(AUD_Handle* handle, const float* velocity);
 300
 301 /**
 302  * Sets the orientation of a source.
 303  * \param handle The handle of the source.
 304  * \param orientation The new orientation as quaternion.
 305  * \return Whether the action succeeded.
 306  */
 307 extern int AUD_setSourceOrientation(AUD_Handle* handle, const float* orientation);
 308
 309 /**
 310  * Sets whether the source location, velocity and orientation are relative
 311  * to the listener.
 312  * \param handle The handle of the source.
 313  * \param relative Whether the source is relative.
 314  * \return Whether the action succeeded.
 315  */
 316 extern int AUD_setRelative(AUD_Handle* handle, int relative);
 317
 318 /**
 319  * Sets the maximum volume of a source.
 320  * \param handle The handle of the source.
 321  * \param volume The new maximum volume.
 322  * \return Whether the action succeeded.
 323  */
 324 extern int AUD_setVolumeMaximum(AUD_Handle* handle, float volume);
 325
 326 /**
 327  * Sets the minimum volume of a source.
 328  * \param handle The handle of the source.
 329  * \param volume The new minimum volume.
 330  * \return Whether the action succeeded.
 331  */
 332 extern int AUD_setVolumeMinimum(AUD_Handle* handle, float volume);
 333
 334 /**
 335  * Sets the maximum distance of a source.
 336  * If a source is further away from the reader than this distance, the
 337  * volume will automatically be set to 0.
 338  * \param handle The handle of the source.
 339  * \param distance The new maximum distance.
 340  * \return Whether the action succeeded.
 341  */
 342 extern int AUD_setDistanceMaximum(AUD_Handle* handle, float distance);
 343
 344 /**
 345  * Sets the reference distance of a source.
 346  * \param handle The handle of the source.
 347  * \param distance The new reference distance.
 348  * \return Whether the action succeeded.
 349  */
 350 extern int AUD_setDistanceReference(AUD_Handle* handle, float distance);
 351
 352 /**
 353  * Sets the attenuation of a source.
 354  * This value is used for distance calculation.
 355  * \param handle The handle of the source.
 356  * \param factor The new attenuation.
 357  * \return Whether the action succeeded.
 358  */
 359 extern int AUD_setAttenuation(AUD_Handle* handle, float factor);
 360
 361 /**
 362  * Sets the outer angle of the cone of a source.
 363  * \param handle The handle of the source.
 364  * \param angle The new outer angle of the cone.
 365  * \return Whether the action succeeded.
 366  */
 367 extern int AUD_setConeAngleOuter(AUD_Handle* handle, float angle);
 368
 369 /**
 370  * Sets the inner angle of the cone of a source.
 371  * \param handle The handle of the source.
 372  * \param angle The new inner angle of the cone.
 373  * \return Whether the action succeeded.
 374  */
 375 extern int AUD_setConeAngleInner(AUD_Handle* handle, float angle);
 376
 377 /**
 378  * Sets the outer volume of the cone of a source.
 379  * The volume between inner and outer angle is interpolated between inner
 380  * volume and this value.
 381  * \param handle The handle of the source.
 382  * \param volume The new outer volume of the cone.
 383  * \return Whether the action succeeded.
 384  */
 385 extern int AUD_setConeVolumeOuter(AUD_Handle* handle, float volume);
 386
 387 /**
 388  * Sets the volume of a played back sound.
 389  * \param handle The handle to the sound.
 390  * \param volume The new volume, must be between 0.0 and 1.0.
 391  * \return Whether the action succeeded.
 392  */
 393 extern int AUD_setSoundVolume(AUD_Handle* handle, float volume);
 394
 395 /**
 396  * Sets the pitch of a played back sound.
 397  * \param handle The handle to the sound.
 398  * \param pitch The new pitch.
 399  * \return Whether the action succeeded.
 400  */
 401 extern int AUD_setSoundPitch(AUD_Handle* handle, float pitch);
 402
 403 /**
 404  * Opens a read device, with which audio data can be read.
 405  * \param specs The specification of the audio data.
 406  * \return A device handle.
 407  */
 408 extern AUD_Device* AUD_openReadDevice(AUD_DeviceSpecs specs);
 409
 410 /**
 411  * Sets the main volume of a device.
 412  * \param device The device.
 413  * \param volume The new volume, must be between 0.0 and 1.0.
 414  * \return Whether the action succeeded.
 415  */
 416 extern int AUD_setDeviceVolume(AUD_Device* device, float volume);
 417
 418 /**
 419  * Plays back a sound file through a read device.
 420  * \param device The read device.
 421  * \param sound The handle of the sound file.
 422  * \param seek The position where the sound should be seeked to.
 423  * \return A handle to the played back sound.
 424  */
 425 extern AUD_Handle* AUD_playDevice(AUD_Device* device, AUD_Sound* sound, float seek);
 426
 427 /**
 428  * Reads the next samples into the supplied buffer.
 429  * \param device The read device.
 430  * \param buffer The target buffer.
 431  * \param length The length in samples to be filled.
 432  * \return True if the reading succeeded, false if there are no sounds
 433  *         played back currently, in that case the buffer is filled with
 434  *         silence.
 435  */
 436 extern int AUD_readDevice(AUD_Device* device, data_t* buffer, int length);
 437
 438 /**
 439  * Closes a read device.
 440  * \param device The read device.
 441  */
 442 extern void AUD_closeReadDevice(AUD_Device* device);
 443
 444 /**
 445  * Reads a sound file into a newly created float buffer.
 446  * The sound is therefore bandpassed, rectified and resampled.
 447  */
 448 extern float* AUD_readSoundBuffer(const char* filename, float low, float high,
 449                                                                   float attack, float release, float threshold,
 450                                                                   int accumulate, int additive, int square,
 451                                                                   float sthreshold, double samplerate,
 452                                                                   int* length);
 453
 454 /**
 455  * Pauses a playing sound after a specific amount of time.
 456  * \param handle The handle to the sound.
 457  * \param time The time in seconds.
 458  * \return The silence handle.
 459  */
 460 extern AUD_Handle* AUD_pauseAfter(AUD_Handle* handle, float seconds);
 461
 462 /**
 463  * Creates a new sequenced sound scene.
 464  * \param fps The FPS of the scene.
 465  * \param muted Whether the scene is muted.
 466  * \return The new sound scene.
 467  */
 468 extern AUD_Sound* AUD_createSequencer(float fps, int muted);
 469
 470 /**
 471  * Deletes a sound scene.
 472  * \param sequencer The sound scene.
 473  */
 474 extern void AUD_destroySequencer(AUD_Sound* sequencer);
 475
 476 /**
 477  * Sets the muting state of the scene.
 478  * \param sequencer The sound scene.
 479  * \param muted Whether the scene is muted.
 480  */
 481 extern void AUD_setSequencerMuted(AUD_Sound* sequencer, int muted);
 482
 483 /**
 484  * Sets the scene's FPS.
 485  * \param sequencer The sound scene.
 486  * \param fps The new FPS.
 487  */
 488 extern void AUD_setSequencerFPS(AUD_Sound* sequencer, float fps);
 489
 490 /**
 491  * Adds a new entry to the scene.
 492  * \param sequencer The sound scene.
 493  * \param sound The sound this entry should play.
 494  * \param begin The start time.
 495  * \param end The end time or a negative value if determined by the sound.
 496  * \param skip How much seconds should be skipped at the beginning.
 497  * \return The entry added.
 498  */
 499 extern AUD_SEntry* AUD_addSequence(AUD_Sound* sequencer, AUD_Sound* sound,
 500                                                                    float begin, float end, float skip);
 501
 502 /**
 503  * Removes an entry from the scene.
 504  * \param sequencer The sound scene.
 505  * \param entry The entry to remove.
 506  */
 507 extern void AUD_removeSequence(AUD_Sound* sequencer, AUD_SEntry* entry);
 508
 509 /**
 510  * Moves the entry.
 511  * \param entry The sequenced entry.
 512  * \param begin The new start time.
 513  * \param end The new end time or a negative value if unknown.
 514  * \param skip How many seconds to skip at the beginning.
 515  */
 516 extern void AUD_moveSequence(AUD_SEntry* entry, float begin, float end, float skip);
 517
 518 /**
 519  * Sets the muting state of the entry.
 520  * \param entry The sequenced entry.
 521  * \param mute Whether the entry should be muted or not.
 522  */
 523 extern void AUD_muteSequence(AUD_SEntry* entry, char mute);
 524
 525 /**
 526  * Sets whether the entrie's location, velocity and orientation are relative
 527  * to the listener.
 528  * \param entry The sequenced entry.
 529  * \param relative Whether the source is relative.
 530  * \return Whether the action succeeded.
 531  */
 532 extern void AUD_setRelativeSequence(AUD_SEntry* entry, char relative);
 533
 534 /**
 535  * Sets the sound of the entry.
 536  * \param entry The sequenced entry.
 537  * \param sound The new sound.
 538  */
 539 extern void AUD_updateSequenceSound(AUD_SEntry* entry, AUD_Sound* sound);
 540
 541 /**
 542  * Writes animation data to a sequenced entry.
 543  * \param entry The sequenced entry.
 544  * \param type The type of animation data.
 545  * \param frame The frame this data is for.
 546  * \param data The data to write.
 547  * \param animated Whether the attribute is animated.
 548  */
 549 extern void AUD_setSequenceAnimData(AUD_SEntry* entry, AUD_AnimateablePropertyType type, int frame, float* data, char animated);
 550
 551 /**
 552  * Writes animation data to a sequenced entry.
 553  * \param sequencer The sound scene.
 554  * \param type The type of animation data.
 555  * \param frame The frame this data is for.
 556  * \param data The data to write.
 557  * \param animated Whether the attribute is animated.
 558  */
 559 extern void AUD_setSequencerAnimData(AUD_Sound* sequencer, AUD_AnimateablePropertyType type, int frame, float* data, char animated);
 560
 561 /**
 562  * Updates all non-animated parameters of the entry.
 563  * \param entry The sequenced entry.
 564  * \param volume_max The maximum volume.
 565  * \param volume_min The minimum volume.
 566  * \param distance_max The maximum distance.
 567  * \param distance_reference The reference distance.
 568  * \param attenuation The attenuation.
 569  * \param cone_angle_outer The outer cone opening angle.
 570  * \param cone_angle_inner The inner cone opening angle.
 571  * \param cone_volume_outer The volume outside the outer cone.
 572  */
 573 extern void AUD_updateSequenceData(AUD_SEntry* entry, float volume_max, float volume_min,
 574                                                                    float distance_max, float distance_reference, float attenuation,
 575                                                                    float cone_angle_outer, float cone_angle_inner, float cone_volume_outer);
 576
 577 /**
 578  * Updates all non-animated parameters of the entry.
 579  * \param sequencer The sound scene.
 580  * \param speed_of_sound The speed of sound for doppler calculation.
 581  * \param factor The doppler factor to control the effect's strength.
 582  * \param model The distance model for distance calculation.
 583  */
 584 extern void AUD_updateSequencerData(AUD_Sound* sequencer, float speed_of_sound,
 585                                                                         float factor, AUD_DistanceModel model);
 586
 587 /**
 588  * Sets the audio output specification of the sound scene to the specs of the
 589  * current playback device.
 590  * \param sequencer The sound scene.
 591  */
 592 extern void AUD_setSequencerDeviceSpecs(AUD_Sound* sequencer);
 593
 594 /**
 595  * Sets the audio output specification of the sound scene.
 596  * \param sequencer The sound scene.
 597  * \param specs The new specification.
 598  */
 599 extern void AUD_setSequencerSpecs(AUD_Sound* sequencer, AUD_Specs specs);
 600
 601 /**
 602  * Seeks sequenced sound scene playback.
 603  * \param handle Playback handle.
 604  * \param time Time in seconds to seek to.
 605  */
 606 extern void AUD_seekSequencer(AUD_Handle* handle, float time);
 607
 608 /**
 609  * Returns the current sound scene playback time.
 610  * \param handle Playback handle.
 611  * \return The playback time in seconds.
 612  */
 613 extern float AUD_getSequencerPosition(AUD_Handle* handle);
 614
 615 /**
 616  * Starts the playback of jack transport if possible.
 617  */
 618 extern void AUD_startPlayback(void);
 619
 620 /**
 621  * Stops the playback of jack transport if possible.
 622  */
 623 extern void AUD_stopPlayback(void);
 624
 625 #ifdef WITH_JACK
 626 /**
 627  * Sets the sync callback for jack transport.
 628  * \param function The callback function.
 629  * \param data The data parameter for the callback.
 630  */
 631 extern void AUD_setSyncCallback(AUD_syncFunction function, void* data);
 632 #endif
 633
 634 /**
 635  * Returns whether jack transport is currently playing.
 636  * \return Whether jack transport is currently playing.
 637  */
 638 extern int AUD_doesPlayback(void);
 639
 640 /**
 641  * Reads a sound into a buffer for drawing at a specific sampling rate.
 642  * \param sound The sound to read.
 643  * \param buffer The buffer to write to. Must have a size of 3*4*length.
 644  * \param length How many samples to read from the sound.
 645  * \param samples_per_second How many samples to read per second of the sound.
 646  * \return How many samples really have been read. Always <= length.
 647  */
 648 extern int AUD_readSound(AUD_Sound* sound, sample_t* buffer, int length, int samples_per_second);
 649
 650 /**
 651  * Copies a sound.
 652  * \param sound Sound to copy.
 653  * \return Copied sound.
 654  */
 655 extern AUD_Sound* AUD_copy(AUD_Sound* sound);
 656
 657 /**
 658  * Frees a handle.
 659  * \param channel Handle to free.
 660  */
 661 extern void AUD_freeHandle(AUD_Handle* channel);
 662
 663 /**
 664  * Creates a new set.
 665  * \return The new set.
 666  */
 667 extern void* AUD_createSet(void);
 668
 669 /**
 670  * Deletes a set.
 671  * \param set The set to delete.
 672  */
 673 extern void AUD_destroySet(void* set);
 674
 675 /**
 676  * Removes an entry from a set.
 677  * \param set The set work on.
 678  * \param entry The entry to remove.
 679  * \return Whether the entry was in the set or not.
 680  */
 681 extern char AUD_removeSet(void* set, void* entry);
 682
 683 /**
 684  * Adds a new entry to a set.
 685  * \param set The set work on.
 686  * \param entry The entry to add.
 687  */
 688 extern void AUD_addSet(void* set, void* entry);
 689
 690 /**
 691  * Removes one entry from a set and returns it.
 692  * \param set The set work on.
 693  * \return The entry or NULL if the set is empty.
 694  */
 695 extern void* AUD_getSet(void* set);
 696
 697 /**
 698  * Mixes a sound down into a file.
 699  * \param sound The sound scene to mix down.
 700  * \param start The start frame.
 701  * \param length The count of frames to write.
 702  * \param buffersize How many samples should be written at once.
 703  * \param filename The file to write to.
 704  * \param specs The file's audio specification.
 705  * \param format The file's container format.
 706  * \param codec The codec used for encoding the audio data.
 707  * \param bitrate The bitrate for encoding.
 708  * \return An error message or NULL in case of success.
 709  */
 710 extern const char* AUD_mixdown(AUD_Sound* sound, unsigned int start, unsigned int length, unsigned int buffersize, const char* filename, AUD_DeviceSpecs specs, AUD_Container format, AUD_Codec codec, unsigned int bitrate);
 711
 712 /**
 713  * Opens a read device and prepares it for mixdown of the sound scene.
 714  * \param specs Output audio specifications.
 715  * \param sequencer The sound scene to mix down.
 716  * \param volume The overall mixdown volume.
 717  * \param start The start time of the mixdown in the sound scene.
 718  * \return The read device for the mixdown.
 719  */
 720 extern AUD_Device* AUD_openMixdownDevice(AUD_DeviceSpecs specs, AUD_Sound* sequencer, float volume, float start);
 721
 722 #ifdef WITH_PYTHON
 723 /**
 724  * Retrieves the python factory of a sound.
 725  * \param sound The sound factory.
 726  * \return The python factory.
 727  */
 728 extern PyObject* AUD_getPythonFactory(AUD_Sound* sound);
 729
 730 /**
 731  * Retrieves the sound factory of a python factory.
 732  * \param sound The python factory.
 733  * \return The sound factory.
 734  */
 735 extern AUD_Sound* AUD_getPythonSound(PyObject* sound);
 736 #endif
 737
 738 #ifdef __cplusplus
 739 }
 740
 741 #include "AUD_Reference.h"
 742 class AUD_IDevice;
 743 class AUD_I3DDevice;
 744
 745 /**
 746  * Returns the current playback device.
 747  * \return The playback device.
 748  */
 749 AUD_Reference<AUD_IDevice> AUD_getDevice();
 750
 751 /**
 752  * Returns the current playback 3D device.
 753  * \return The playback 3D device.
 754  */
 755 AUD_I3DDevice* AUD_get3DDevice();
 756 #endif
 757
 758 #endif //AUD_CAPI