libcm is a C development framework with an emphasis on audio signal processing applications.
Nelze vybrat více než 25 témat Téma musí začínat písmenem nebo číslem, může obsahovat pomlčky („-“) a může být dlouhé až 35 znaků.

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