libcm is a C development framework with an emphasis on audio signal processing applications.
Vous ne pouvez pas sélectionner plus de 25 sujets Les noms de sujets doivent commencer par une lettre ou un nombre, peuvent contenir des tirets ('-') et peuvent comporter jusqu'à 35 caractères.

cmAudioFile.h 14KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305
  1. /// \file cmAudioFile.h
  2. /// \brief Audio file reader/writer class.
  3. ///
  4. /// This class supports reading uncompressed AIFF and WAV files and writing uncompressed AIFF files.
  5. /// The reading and writing routines are known to work with 8,16,24, and 32 bit integer sample formats.
  6. ///
  7. /// Testing and example usage for this API can be found in cmProcTest.c cmAudioReadWriteTest().
  8. ///
  9. /// Usage example:
  10. /// \snippet cmAudioFile.c cmAudioFileExample
  11. #ifndef cmAudioFile_h
  12. #define cmAudioFile_h
  13. #ifdef __cplusplus
  14. extern "C" {
  15. #endif
  16. #ifndef cmAudioFile_MAX_FRAME_READ_CNT
  17. /// Maximum number of samples which will be read in one call to fread().
  18. /// This value is only significant in that an internal buffer is created on the stack
  19. /// whose size must be limited to prevent stack overflows.
  20. #define cmAudioFile_MAX_FRAME_READ_CNT (8192)
  21. #endif
  22. /// Audio file result codes.
  23. enum
  24. {
  25. kOkAfRC = 0,
  26. kOpenFailAfRC,
  27. kReadFailAfRC,
  28. kWriteFailAfRC,
  29. kSeekFailAfRC,
  30. kCloseFailAfRC,
  31. kNotAiffAfRC,
  32. kInvalidBitWidthAfRC,
  33. kInvalidFileModeAfRC,
  34. kInvalidHandleAfRC,
  35. kUnknownErrAfRC
  36. };
  37. /// Informational flags used by audioFileInfo
  38. enum
  39. {
  40. kAiffAfFl = 0x01, ///< this is an AIFF file
  41. kWavAfFl = 0x02, ///< this is a WAV file
  42. kSwapAfFl = 0x04, ///< file header bytes must be swapped
  43. kAifcAfFl = 0x08, ///< this is an AIFC file
  44. kSwapSamplesAfFl = 0x10 ///< file sample bytes must be swapped
  45. };
  46. /// Constants
  47. enum
  48. {
  49. kAudioFileLabelCharCnt = 256,
  50. kAfBextDescN = 256,
  51. kAfBextOriginN = 32,
  52. kAfBextOriginRefN = 32,
  53. kAfBextOriginDateN = 10,
  54. kAfBextOriginTimeN = 8
  55. };
  56. /// Aiff marker record
  57. typedef struct
  58. {
  59. unsigned id;
  60. unsigned frameIdx;
  61. char label[kAudioFileLabelCharCnt];
  62. } cmAudioFileMarker_t;
  63. /// Broadcast WAV header record As used by ProTools audio files. See http://en.wikipedia.org/wiki/Broadcast_Wave_Format
  64. /// When generated from Protools the timeRefLow/timeRefHigh values appear to actually refer
  65. /// to the position on the Protools time-line rather than the wall clock time.
  66. typedef struct
  67. {
  68. char desc[ kAfBextDescN + 1 ];
  69. char origin[ kAfBextOriginN + 1 ];
  70. char originRef[ kAfBextOriginRefN + 1 ];
  71. char originDate[kAfBextOriginDateN + 1 ];
  72. char originTime[kAfBextOriginTimeN + 1 ];
  73. unsigned timeRefLow; // sample count since midnight low word
  74. unsigned timeRefHigh; // sample count since midnight high word
  75. } cmAudioFileBext_t;
  76. /// Audio file information record used by audioFileNew and audioFileOpen
  77. typedef struct
  78. {
  79. unsigned bits; ///< bits per sample
  80. unsigned chCnt; ///< count of audio file channels
  81. double srate; ///< audio file sample rate in samples per second
  82. unsigned frameCnt; ///< total number of sample frames in the audio file
  83. unsigned flags; ///< informational flags
  84. unsigned markerCnt; ///< count of markers in markerArray
  85. cmAudioFileMarker_t* markerArray; ///< array of markers
  86. cmAudioFileBext_t bextRecd; ///< only used with Broadcast WAV files
  87. } cmAudioFileInfo_t;
  88. typedef cmHandle_t cmAudioFileH_t; ///< opaque audio file handle
  89. extern cmAudioFileH_t cmNullAudioFileH; ///< NULL audio file handle
  90. /// Create an audio file handle and optionally use the handle to open an audio file.
  91. ///
  92. /// \param fn The audio file name to open or NULL to create the audio file handle without opening the file.
  93. /// \param infoPtr A pointer to an audioFileInfo record to be filled when the file is open or NULL to ignore.
  94. /// \param rcPtr A pointer to a result code to be set in the event of a runtime error or NULL to ignore.
  95. /// \param rpt A pointer to a cmRpt_t object which error messages from this class will be directed to.
  96. /// \retval cmAudioFileH_t A new audio file handle.
  97. ///
  98. cmAudioFileH_t cmAudioFileNewOpen( const cmChar_t* fn, cmAudioFileInfo_t* infoPtr, cmRC_t* rcPtr, cmRpt_t* rpt );
  99. /// Open an audio file for writing
  100. cmAudioFileH_t cmAudioFileNewCreate( const cmChar_t* fn, double srate, unsigned bits, unsigned chCnt, cmRC_t* rcPtr, cmRpt_t* rpt );
  101. /// Open an audio file for reading using a handle returned from an earlier call to audioFileNewXXX().
  102. ///
  103. /// \param h A file handle returned from and earlier call to cmAudioFileNewOpen() or cmAudioFileNewCreate().
  104. /// \param fn The audio file name to open or NULL to create the audio file handle without opening the file.
  105. /// \param infoPtr A pointer to an audioFileInfo record to be filled when the file is open or NULL to ignore.
  106. /// \retval Returns an cmRC_t value indicating the success (kOkAfRC) or failure of the call.
  107. ///
  108. /// If the audio file handle 'h' refers to an open file then it is automatically closed prior to being
  109. /// reopened with the new file.
  110. cmRC_t cmAudioFileOpen( cmAudioFileH_t h, const cmChar_t* fn, cmAudioFileInfo_t* infoPtr );
  111. /// Open an audio file for writing.
  112. cmRC_t cmAudioFileCreate(
  113. cmAudioFileH_t h, ///< Handle returned from an earlier call to cmAudioFileNewCreate() or cmAudioFileNewOpen().
  114. const cmChar_t* fn, ///< File name of the new file.
  115. double srate, ///< Sample rate of the new file.
  116. unsigned bits, ///< Sample word width for the new file in bits (must be 8,16,24 or 32).
  117. unsigned chCnt ///< Audio channel count for the new file.
  118. );
  119. /// Close a the file associated with handle 'h' but do not release the handle.
  120. /// If the file was opened for writing (cmAudioFileCreate()) then this function will
  121. /// write the file header prior to closing the file.
  122. cmRC_t cmAudioFileClose( cmAudioFileH_t* h );
  123. /// Close the file associated with handle 'h' (via an internal call to
  124. /// cmAudioFileClose()) and release the handle and any resources
  125. /// associated with it. This is the complement to cmAudioFileOpen/Create().
  126. cmRC_t cmAudioFileDelete( cmAudioFileH_t* h );
  127. /// Return true if the handle is not closed or deleted.
  128. bool cmAudioFileIsValid( cmAudioFileH_t h );
  129. /// Return true if the handle is open.
  130. bool cmAudioFileIsOpen( cmAudioFileH_t h );
  131. /// Return true if the current file position is at the end of the file.
  132. bool cmAudioFileIsEOF( cmAudioFileH_t h );
  133. /// Return the current file position as a frame index.
  134. unsigned cmAudioFileTell( cmAudioFileH_t h );
  135. /// Set the current file position as an offset from the first frame.
  136. cmRC_t cmAudioFileSeek( cmAudioFileH_t h, unsigned frmIdx );
  137. /// \name Sample Reading Functions.
  138. ///@{
  139. /// Fill a user suppled buffer with up to frmCnt samples.
  140. /// If less than frmCnt samples are available at the specified audio file location then the unused
  141. /// buffer space is set to zero. Check *actualFrmCntPtr for the count of samples actually available
  142. /// in the return buffer. Functions which do not include a begFrmIdx argument begin reading from
  143. /// the current file location (see cmAudioFileSeek()). The buf argument is always a pointer to an
  144. /// array of pointers of length chCnt. Each channel buffer specified in buf[] must contain at least
  145. /// frmCnt samples.
  146. ///
  147. /// \param h An audio file handle returned from an earlier call to audioFileNew()
  148. /// \param fn The name of the audio file to read.
  149. /// \param begFrmIdx The frame index of the first sample to read. Functions that do not use this parameter begin reading at the current file location (See cmAudioFileTell()).
  150. /// \param frmCnt The number of samples allocated in buf.
  151. /// \param chIdx The index of the first channel to read.
  152. /// \param chCnt The count of channels to read.
  153. /// \param buf An array containing chCnt pointers to arrays of frmCnt samples.
  154. /// \param actualFrmCntPtr The number of frames actually written to the return buffer (ignored if NULL)
  155. cmRC_t cmAudioFileReadInt( cmAudioFileH_t h, unsigned frmCnt, unsigned chIdx, unsigned chCnt, int** buf, unsigned* actualFrmCntPtr );
  156. cmRC_t cmAudioFileReadFloat( cmAudioFileH_t h, unsigned frmCnt, unsigned chIdx, unsigned chCnt, float** buf, unsigned* actualFrmCntPtr );
  157. cmRC_t cmAudioFileReadDouble( cmAudioFileH_t h, unsigned frmCnt, unsigned chIdx, unsigned chCnt, double** buf, unsigned* actualFrmCntPtr );
  158. cmRC_t cmAudioFileGetInt( const char* fn, unsigned begFrmIdx, unsigned frmCnt, unsigned chIdx, unsigned chCnt, int** buf, unsigned* actualFrmCntPtr, cmAudioFileInfo_t* afInfoPtr, cmRpt_t* rpt );
  159. cmRC_t cmAudioFileGetFloat( const char* fn, unsigned begFrmIdx, unsigned frmCnt, unsigned chIdx, unsigned chCnt, float** buf, unsigned* actualFrmCntPtr, cmAudioFileInfo_t* afInfoPtr, cmRpt_t* rpt );
  160. cmRC_t cmAudioFileGetDouble( const char* fn, unsigned begFrmIdx, unsigned frmCnt, unsigned chIdx, unsigned chCnt, double** buf, unsigned* actualFrmCntPtr, cmAudioFileInfo_t* afInfoPtr, cmRpt_t* rpt );
  161. ///@}
  162. /// \name Sum the returned samples into the output buffer.
  163. ///@{
  164. cmRC_t cmAudioFileReadSumInt( cmAudioFileH_t h, unsigned frmCnt, unsigned chIdx, unsigned chCnt, int** buf, unsigned* actualFrmCntPtr );
  165. cmRC_t cmAudioFileReadSumFloat( cmAudioFileH_t h, unsigned frmCnt, unsigned chIdx, unsigned chCnt, float** buf, unsigned* actualFrmCntPtr );
  166. cmRC_t cmAudioFileReadSumDouble( cmAudioFileH_t h, unsigned frmCnt, unsigned chIdx, unsigned chCnt, double** buf, unsigned* actualFrmCntPtr );
  167. cmRC_t cmAudioFileGetSumInt( const char* fn, unsigned begFrmIdx, unsigned frmCnt, unsigned chIdx, unsigned chCnt, int** buf, unsigned* actualFrmCntPtr, cmAudioFileInfo_t* afInfoPtr, cmRpt_t* rpt );
  168. cmRC_t cmAudioFileGetSumFloat( const char* fn, unsigned begFrmIdx, unsigned frmCnt, unsigned chIdx, unsigned chCnt, float** buf, unsigned* actualFrmCntPtr, cmAudioFileInfo_t* afInfoPtr, cmRpt_t* rpt );
  169. cmRC_t cmAudioFileGetSumDouble( const char* fn, unsigned begFrmIdx, unsigned frmCnt, unsigned chIdx, unsigned chCnt, double** buf, unsigned* actualFrmCntPtr, cmAudioFileInfo_t* afInfoPtr, cmRpt_t* rpt );
  170. ///@}
  171. ///@}
  172. /// \name Sample Writing Functions
  173. ///@{
  174. cmRC_t cmAudioFileWriteInt( cmAudioFileH_t h, unsigned frmCnt, unsigned chCnt, int** bufPtrPtr );
  175. cmRC_t cmAudioFileWriteFloat( cmAudioFileH_t h, unsigned frmCnt, unsigned chCnt, float** bufPtrPtr );
  176. cmRC_t cmAudioFileWriteDouble( cmAudioFileH_t h, unsigned frmCnt, unsigned chCnt, double** bufPtrPtr );
  177. cmRC_t cmAudioFileWriteFileInt( const char* fn, double srate, unsigned bit, unsigned frmCnt, unsigned chCnt, int** bufPtrPtr, cmRpt_t* rpt );
  178. cmRC_t cmAudioFileWriteFileFloat( const char* fn, double srate, unsigned bit, unsigned frmCnt, unsigned chCnt, float** bufPtrPtr, cmRpt_t* rpt );
  179. cmRC_t cmAudioFileWriteFileDouble( const char* fn, double srate, unsigned bit, unsigned frmCnt, unsigned chCnt, double** bufPtrPtr, cmRpt_t* rpt );
  180. ///@}
  181. /// \name cmSample_t and cmReal_t Alias Macros
  182. ///@{
  183. /// Alias the cmSample_t and cmReal_t sample reading and writing functions to the appropriate
  184. /// type based on #CM_FLOAT_SMP and #CM_FLOAT_REAL.
  185. #if CM_FLOAT_SMP == 1
  186. #define cmAudioFileReadSample cmAudioFileReadFloat
  187. #define cmAudioFileReadSumSample cmAudioFileReadSumFloat
  188. #define cmAudioFileGetSample cmAudioFileGetFloat
  189. #define cmAudioFileGetSumSample cmAudioFileGetSumFloat
  190. #define cmAudioFileWriteSample cmAudioFileWriteFloat
  191. #define cmAudioFileWriteFileSample cmAudioFileWriteFileFloat
  192. #else
  193. #define cmAudioFileReadSample cmAudioFileReadDouble
  194. #define cmAudioFileReadSumSample cmAudioFileReadSumDouble
  195. #define cmAudioFileGetSample cmAudioFileGetDouble
  196. #define cmAudioFileGetSumSample cmAudioFileGetSumDouble
  197. #define cmAudioFileWriteSample cmAudioFileWriteDouble
  198. #define cmAudioFileWriteFileSample cmAudioFileWriteFileDouble
  199. #endif
  200. #if CM_FLOAT_REAL == 1
  201. #define cmAudioFileReadReal cmAudioFileReadFloat
  202. #define cmAudioFileReadSumReal cmAudioFileReadSumFloat
  203. #define cmAudioFileGetReal cmAudioFileGetFloat
  204. #define cmAudioFileGetSumReal cmAudioFileGetSumFloat
  205. #define cmAudioFileWriteReal cmAudioFileWriteFloat
  206. #define cmAudioFileWriteFileReal cmAudioFileWriteFileFloat
  207. #else
  208. #define cmAudioFileReadReal cmAudioFileReadDouble
  209. #define cmAudioFileReadSumReal cmAudioFileReadSumDouble
  210. #define cmAudioFileGetReal cmAudioFileGetDouble
  211. #define cmAudioFileGetSumReal cmAudioFileGetSumDouble
  212. #define cmAudioFileWriteReal cmAudioFileWriteDouble
  213. #define cmAudioFileWriteFileReal cmAudioFileWriteFileDouble
  214. #endif
  215. ///@}
  216. /// \name Minimum, Maximum, Mean
  217. ///@{
  218. /// Scan an entire audio file and return the minimum, maximum and mean sample value.
  219. /// On error *minPtr, *maxPtr, and *meanPtr are set to -acSample_MAX, cmSample_MAX, and 0 respectively
  220. cmRC_t cmAudioFileMinMaxMean( cmAudioFileH_t h, unsigned chIdx, cmSample_t* minPtr, cmSample_t* maxPtr, cmSample_t* meanPtr );
  221. cmRC_t cmAudioFileMinMaxMeanFn( const cmChar_t* fn, unsigned chIdx, cmSample_t* minPtr, cmSample_t* maxPtr, cmSample_t* meanPtr, cmRpt_t* rpt );
  222. ///@}
  223. /// Return the file name associated with a audio file handle.
  224. const cmChar_t* cmAudioFileName( cmAudioFileH_t h );
  225. /// Given an error code return the associated message.
  226. const char* cmAudioFileErrorMsg( unsigned rc );
  227. /// \name Get information about an audio file
  228. ///@{
  229. /// Return the cmAudioFileInfo_t record associated with a file.
  230. cmRC_t cmAudioFileGetInfo( const cmChar_t* fn, cmAudioFileInfo_t* infoPtr, cmRpt_t* rpt );
  231. /// Print the cmAudioFileInfo_t to a file.
  232. void cmAudioFilePrintInfo( const cmAudioFileInfo_t* infoPtr, cmRpt_t* );
  233. /// Print the file header information and frmCnt sample values beginning at frame index frmIdx.
  234. cmRC_t cmAudioFileReport( cmAudioFileH_t h, cmRpt_t* rpt, unsigned frmIdx, unsigned frmCnt );
  235. /// Print the file header information and frmCnt sample values beginning at frame index frmIdx.
  236. cmRC_t cmAudioFileReportFn( const cmChar_t* fn, unsigned frmIdx, unsigned frmCnt, cmRpt_t* rpt );
  237. ///@}
  238. /// Testing and example routine for functions in cmAudioFile.h.
  239. /// Also see cmProcTest.c cmAudioFileReadWriteTest()
  240. void cmAudioFileTest( const cmChar_t* audioFn, const cmChar_t* outFn, cmRpt_t* rpt );
  241. #ifdef __cplusplus
  242. }
  243. #endif
  244. #endif