libcm is a C development framework with an emphasis on audio signal processing applications.
您最多选择25个主题 主题必须以字母或数字开头,可以包含连字符 (-),并且长度不得超过35个字符

cmAudioPort.h 6.3KB

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