libcm/cmAudioPort.h

/// \file cmAudioPort.h
/// \brief Cross platform audio I/O interface.
///
/// This interface provides data declarations for platform dependent 
/// audio I/O functions. The implementation for the functions are
/// in platform specific modules. See cmAudioPortOsx.c and cmAudioPortAlsa.c.
///
/// ALSA Notes:  
/// Assign capture device to line or mic input:
/// amixer -c 0 cset iface=MIXER,name='Input Source',index=0 Mic
/// amixer -c 0 cset iface=MIXER,name='Input Source',index=0 Line
///
/// -c 0                            select the first card
/// -iface=MIXER                    the cset is targetting the MIXER component
/// -name='Input Source',index=0    the control to set is the first 'Input Source'
/// Note that the 'Capture' control sets the input gain.
///
/// See alsamixer for a GUI to accomplish the same thing.
///
///
/// Usage example and testing code:
/// See cmApPortTest() and cmAudioSysTest().
/// \snippet cmAudioPort.c cmAudioPortExample
///
#ifndef cmAudioPort_h
#define cmAudioPort_h

#ifdef __cplusplus
extern "C" {
#endif

  typedef unsigned cmApRC_t;      ///< Audio port interface result code.
  typedef float    cmApSample_t;  ///< Audio sample type.

  enum 
  { 
    kOkApRC =0, 
    kSysErrApRC,
    kInvalidDevIdApRC,
    kAudioPortFileFailApRC,
    kParamRangeErrorApRC,
    kThreadFailApRC
  };

  // cmApAudioPacket_t flags
  enum
  {
    kInterleavedApFl = 0x01,  ///< The audio samples are interleaved.
    kFloatApFl       = 0x02   ///< The audio samples are single precision floating point values.
  };

  /// Audio packet record used by the cmApAudioPacket_t callback.
  /// Audio ports send and receive audio using this data structure. 
  typedef struct
  {
    unsigned devIdx;         ///< device associated with packet
    unsigned begChIdx;       ///< first device channel 
    unsigned chCnt;          ///< count of channels
    unsigned audioFramesCnt; ///< samples per channel (see note below)
    unsigned bitsPerSample;  ///< bits per sample word
    unsigned flags;          ///< kInterleavedApFl | kFloatApFl
    void*    audioBytesPtr;  ///< pointer to sample data
    void*    userCbPtr;      ///< user defined value passed in cmApDeviceSetup()
    cmTimeSpec_t timeStamp;  ///< Packet time stamp.
  }  cmApAudioPacket_t; 


  /// Audio port callback signature. 
  /// inPktArray[inPktCnt] are full packets of audio coming from the ADC to the application.
  /// outPktArray[outPktCnt] are empty packets of audio which will be filled by the application 
  /// and then sent to the DAC.
  ///
  /// The value of audioFrameCnt  gives the number of samples per channel which are available
  /// in the packet data buffer 'audioBytesPtr'.  The callback function may decrease this number in
  /// output packets if the number of samples available is less than the size of the buffer.
  /// It is the responsibility of the calling audio port to notice this change and pass the new,
  /// decreased number of samples to the hardware.
  ///
  /// In general it should be assmed that this call is made from a system thread which is not 
  /// the same as the application thread.
  /// The usual thread safety precautions should therefore be taken if this function implementation
  /// interacts with data structures also handled by the application. The audio buffer class (\see cmApBuf.h) 
  /// is designed to provide a safe and efficient way to communicate between
  /// the audio thread and the application.
  typedef void (*cmApCallbackPtr_t)( cmApAudioPacket_t* inPktArray, unsigned inPktCnt, cmApAudioPacket_t* outPktArray, unsigned outPktCnt );

  /// Setup the audio port management object for this machine.
  cmApRC_t      cmApInitialize( cmRpt_t* rpt );

  /// Stop all audio devices and release any resources held 
  /// by the audio port management object.
  cmApRC_t      cmApFinalize();

  /// Return the count of audio devices attached to this machine.
  unsigned      cmApDeviceCount();

  /// Get a textual description of the device at index 'devIdx'.
  const char*   cmApDeviceLabel(          unsigned devIdx );

  /// Given an audio device label return the associated device index.
  unsigned      cmApDeviceLabelToIndex( const cmChar_t* label );

  /// Get the count of audio input or output channesl on device at index 'devIdx'.
  unsigned      cmApDeviceChannelCount(   unsigned devIdx, bool inputFl );

  /// Get the current sample rate of a device.  Note that if the device has both
  /// input and output capability then the sample rate is the same for both.
  double        cmApDeviceSampleRate(     unsigned devIdx );

  /// Get the count of samples per callback for the input or output for this device.
  unsigned      cmApDeviceFramesPerCycle( unsigned devIdx, bool inputFl );

  /// Configure a device.  
  /// All devices must be setup before they are started.
  /// framesPerCycle is the requested number of samples per audio callback. The
  /// actual number of samples made from a callback may be smaller. See the note
  /// regarding this in cmApAudioPacket_t.
  /// If the device cannot support the requested configuration then the function
  /// will return an error code.
  /// If the device is started when this function is called then it will be 
  /// automatically stopped and then restarted following the reconfiguration.
  /// If the reconfiguration fails then the device may not be restared.
  cmApRC_t      cmApDeviceSetup(          
    unsigned          devIdx, 
    double            srate, 
    unsigned          framesPerCycle, 
    cmApCallbackPtr_t callbackPtr,
    void*             userCbPtr );

  /// Start a device. Note that the callback may be made prior to this function returning.
  cmApRC_t      cmApDeviceStart( unsigned devIdx );

  /// Stop a device.
  cmApRC_t      cmApDeviceStop(  unsigned devIdx );

  /// Return true if the device is currently started.
  bool          cmApDeviceIsStarted( unsigned devIdx );

  /// Print a report of all the current audio device configurations.
  void          cmApReport( cmRpt_t* rpt );

  /// Test the audio port by synthesizing a sine signal or passing audio through
  /// from the input to the output.  This is also a good example of how to 
  /// use all of the functions in the interface.
  /// Set runFl to false to print a report without starting any audio devices.
  /// See cmAudiotPortTest.c for usage example for this function.
  int           cmApPortTest(bool runFl, cmRpt_t* rpt, int argc, const char* argv[] );

#ifdef __cplusplus
}
#endif

#endif