libcm is a C development framework with an emphasis on audio signal processing applications.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151
  1. /// \file cmAudioPort.h
  2. /// \brief Cross platform audio I/O interface.
  3. ///
  4. /// This interface provides data declarations for platform dependent
  5. /// audio I/O functions. The implementation for the functions are
  6. /// in platform specific modules. See cmAudioPortOsx.c and cmAudioPortAlsa.c.
  7. ///
  8. /// ALSA Notes:
  9. /// Assign capture device to line or mic input:
  10. /// amixer -c 0 cset iface=MIXER,name='Input Source',index=0 Mic
  11. /// amixer -c 0 cset iface=MIXER,name='Input Source',index=0 Line
  12. ///
  13. /// -c 0 select the first card
  14. /// -iface=MIXER the cset is targetting the MIXER component
  15. /// -name='Input Source',index=0 the control to set is the first 'Input Source'
  16. /// Note that the 'Capture' control sets the input gain.
  17. ///
  18. /// See alsamixer for a GUI to accomplish the same thing.
  19. ///
  20. ///
  21. /// Usage example and testing code:
  22. /// See cmApPortTest() and cmAudioSysTest().
  23. /// \snippet cmAudioPort.c cmAudioPortExample
  24. ///
  25. #ifndef cmAudioPort_h
  26. #define cmAudioPort_h
  27. #ifdef __cplusplus
  28. extern "C" {
  29. #endif
  30. typedef unsigned cmApRC_t; ///< Audio port interface result code.
  31. typedef float cmApSample_t; ///< Audio sample type.
  32. enum
  33. {
  34. kOkApRC =0,
  35. kSysErrApRC,
  36. kInvalidDevIdApRC,
  37. kAudioPortFileFailApRC,
  38. kThreadFailApRC
  39. };
  40. // cmApAudioPacket_t flags
  41. enum
  42. {
  43. kInterleavedApFl = 0x01, ///< The audio samples are interleaved.
  44. kFloatApFl = 0x02 ///< The audio samples are single precision floating point values.
  45. };
  46. /// Audio packet record used by the cmApAudioPacket_t callback.
  47. /// Audio ports send and receive audio using this data structure.
  48. typedef struct
  49. {
  50. unsigned devIdx; ///< device associated with packet
  51. unsigned begChIdx; ///< first device channel
  52. unsigned chCnt; ///< count of channels
  53. unsigned audioFramesCnt; ///< samples per channel (see note below)
  54. unsigned bitsPerSample; ///< bits per sample word
  55. unsigned flags; ///< kInterleavedApFl | kFloatApFl
  56. void* audioBytesPtr; ///< pointer to sample data
  57. void* userCbPtr; ///< user defined value passed in cmApDeviceSetup()
  58. } cmApAudioPacket_t;
  59. /// Audio port callback signature.
  60. /// inPktArray[inPktCnt] are full packets of audio coming from the ADC to the application.
  61. /// outPktArray[outPktCnt] are empty packets of audio which will be filled by the application
  62. /// and then sent to the DAC.
  63. ///
  64. /// The value of audioFrameCnt gives the number of samples per channel which are available
  65. /// in the packet data buffer 'audioBytesPtr'. The callback function may decrease this number in
  66. /// output packets if the number of samples available is less than the size of the buffer.
  67. /// It is the responsibility of the calling audio port to notice this change and pass the new,
  68. /// decreased number of samples to the hardware.
  69. ///
  70. /// In general it should be assmed that this call is made from a system thread which is not
  71. /// the same as the application thread.
  72. /// The usual thread safety precautions should therefore be taken if this function implementation
  73. /// interacts with data structures also handled by the application. The audio buffer class (\see cmApBuf.h)
  74. /// is designed to provide a safe and efficient way to communicate between
  75. /// the audio thread and the application.
  76. typedef void (*cmApCallbackPtr_t)( cmApAudioPacket_t* inPktArray, unsigned inPktCnt, cmApAudioPacket_t* outPktArray, unsigned outPktCnt );
  77. /// Setup the audio port management object for this machine.
  78. cmApRC_t cmApInitialize( cmRpt_t* rpt );
  79. /// Stop all audio devices and release any resources held
  80. /// by the audio port management object.
  81. cmApRC_t cmApFinalize();
  82. /// Return the count of audio devices attached to this machine.
  83. unsigned cmApDeviceCount();
  84. /// Get a textual description of the device at index 'devIdx'.
  85. const char* cmApDeviceLabel( unsigned devIdx );
  86. /// Given an audio device label return the associated device index.
  87. unsigned cmApDeviceLabelToIndex( const cmChar_t* label );
  88. /// Get the count of audio input or output channesl on device at index 'devIdx'.
  89. unsigned cmApDeviceChannelCount( unsigned devIdx, bool inputFl );
  90. /// Get the current sample rate of a device. Note that if the device has both
  91. /// input and output capability then the sample rate is the same for both.
  92. double cmApDeviceSampleRate( unsigned devIdx );
  93. /// Get the count of samples per callback for the input or output for this device.
  94. unsigned cmApDeviceFramesPerCycle( unsigned devIdx, bool inputFl );
  95. /// Configure a device.
  96. /// All devices must be setup before they are started.
  97. /// framesPerCycle is the requested number of samples per audio callback. The
  98. /// actual number of samples made from a callback may be smaller. See the note
  99. /// regarding this in cmApAudioPacket_t.
  100. /// If the device cannot support the requested configuration then the function
  101. /// will return an error code.
  102. /// If the device is started when this function is called then it will be
  103. /// automatically stopped and then restarted following the reconfiguration.
  104. /// If the reconfiguration fails then the device may not be restared.
  105. cmApRC_t cmApDeviceSetup(
  106. unsigned devIdx,
  107. double srate,
  108. unsigned framesPerCycle,
  109. cmApCallbackPtr_t callbackPtr,
  110. void* userCbPtr );
  111. /// Start a device. Note that the callback may be made prior to this function returning.
  112. cmApRC_t cmApDeviceStart( unsigned devIdx );
  113. /// Stop a device.
  114. cmApRC_t cmApDeviceStop( unsigned devIdx );
  115. /// Return true if the device is currently started.
  116. bool cmApDeviceIsStarted( unsigned devIdx );
  117. /// Print a report of all the current audio device configurations.
  118. void cmApReport( cmRpt_t* rpt );
  119. /// Test the audio port by synthesizing a sine signal or passing audio through
  120. /// from the input to the output. This is also a good example of how to
  121. /// use all of the functions in the interface.
  122. /// Set runFl to false to print a report without starting any audio devices.
  123. /// See cmAudiotPortTest.c for usage example for this function.
  124. int cmApPortTest(bool runFl, cmRpt_t* rpt, int argc, const char* argv[] );
  125. #ifdef __cplusplus
  126. }
  127. #endif
  128. #endif