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.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153
  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. kParamRangeErrorApRC,
  39. kThreadFailApRC
  40. };
  41. // cmApAudioPacket_t flags
  42. enum
  43. {
  44. kInterleavedApFl = 0x01, ///< The audio samples are interleaved.
  45. kFloatApFl = 0x02 ///< The audio samples are single precision floating point values.
  46. };
  47. /// Audio packet record used by the cmApAudioPacket_t callback.
  48. /// Audio ports send and receive audio using this data structure.
  49. typedef struct
  50. {
  51. unsigned devIdx; ///< device associated with packet
  52. unsigned begChIdx; ///< first device channel
  53. unsigned chCnt; ///< count of channels
  54. unsigned audioFramesCnt; ///< samples per channel (see note below)
  55. unsigned bitsPerSample; ///< bits per sample word
  56. unsigned flags; ///< kInterleavedApFl | kFloatApFl
  57. void* audioBytesPtr; ///< pointer to sample data
  58. void* userCbPtr; ///< user defined value passed in cmApDeviceSetup()
  59. cmTimeSpec_t timeStamp; ///< Packet time stamp.
  60. } cmApAudioPacket_t;
  61. /// Audio port callback signature.
  62. /// inPktArray[inPktCnt] are full packets of audio coming from the ADC to the application.
  63. /// outPktArray[outPktCnt] are empty packets of audio which will be filled by the application
  64. /// and then sent to the DAC.
  65. ///
  66. /// The value of audioFrameCnt gives the number of samples per channel which are available
  67. /// in the packet data buffer 'audioBytesPtr'. The callback function may decrease this number in
  68. /// output packets if the number of samples available is less than the size of the buffer.
  69. /// It is the responsibility of the calling audio port to notice this change and pass the new,
  70. /// decreased number of samples to the hardware.
  71. ///
  72. /// In general it should be assmed that this call is made from a system thread which is not
  73. /// the same as the application thread.
  74. /// The usual thread safety precautions should therefore be taken if this function implementation
  75. /// interacts with data structures also handled by the application. The audio buffer class (\see cmApBuf.h)
  76. /// is designed to provide a safe and efficient way to communicate between
  77. /// the audio thread and the application.
  78. typedef void (*cmApCallbackPtr_t)( cmApAudioPacket_t* inPktArray, unsigned inPktCnt, cmApAudioPacket_t* outPktArray, unsigned outPktCnt );
  79. /// Setup the audio port management object for this machine.
  80. cmApRC_t cmApInitialize( cmRpt_t* rpt );
  81. /// Stop all audio devices and release any resources held
  82. /// by the audio port management object.
  83. cmApRC_t cmApFinalize();
  84. /// Return the count of audio devices attached to this machine.
  85. unsigned cmApDeviceCount();
  86. /// Get a textual description of the device at index 'devIdx'.
  87. const char* cmApDeviceLabel( unsigned devIdx );
  88. /// Given an audio device label return the associated device index.
  89. unsigned cmApDeviceLabelToIndex( const cmChar_t* label );
  90. /// Get the count of audio input or output channesl on device at index 'devIdx'.
  91. unsigned cmApDeviceChannelCount( unsigned devIdx, bool inputFl );
  92. /// Get the current sample rate of a device. Note that if the device has both
  93. /// input and output capability then the sample rate is the same for both.
  94. double cmApDeviceSampleRate( unsigned devIdx );
  95. /// Get the count of samples per callback for the input or output for this device.
  96. unsigned cmApDeviceFramesPerCycle( unsigned devIdx, bool inputFl );
  97. /// Configure a device.
  98. /// All devices must be setup before they are started.
  99. /// framesPerCycle is the requested number of samples per audio callback. The
  100. /// actual number of samples made from a callback may be smaller. See the note
  101. /// regarding this in cmApAudioPacket_t.
  102. /// If the device cannot support the requested configuration then the function
  103. /// will return an error code.
  104. /// If the device is started when this function is called then it will be
  105. /// automatically stopped and then restarted following the reconfiguration.
  106. /// If the reconfiguration fails then the device may not be restared.
  107. cmApRC_t cmApDeviceSetup(
  108. unsigned devIdx,
  109. double srate,
  110. unsigned framesPerCycle,
  111. cmApCallbackPtr_t callbackPtr,
  112. void* userCbPtr );
  113. /// Start a device. Note that the callback may be made prior to this function returning.
  114. cmApRC_t cmApDeviceStart( unsigned devIdx );
  115. /// Stop a device.
  116. cmApRC_t cmApDeviceStop( unsigned devIdx );
  117. /// Return true if the device is currently started.
  118. bool cmApDeviceIsStarted( unsigned devIdx );
  119. /// Print a report of all the current audio device configurations.
  120. void cmApReport( cmRpt_t* rpt );
  121. /// Test the audio port by synthesizing a sine signal or passing audio through
  122. /// from the input to the output. This is also a good example of how to
  123. /// use all of the functions in the interface.
  124. /// Set runFl to false to print a report without starting any audio devices.
  125. /// See cmAudiotPortTest.c for usage example for this function.
  126. int cmApPortTest(bool runFl, cmRpt_t* rpt, int argc, const char* argv[] );
  127. #ifdef __cplusplus
  128. }
  129. #endif
  130. #endif