libcm is a C development framework with an emphasis on audio signal processing applications.
Du kannst nicht mehr als 25 Themen auswählen Themen müssen mit entweder einem Buchstaben oder einer Ziffer beginnen. Sie können Bindestriche („-“) enthalten und bis zu 35 Zeichen lang sein.

cmAudioFile.h 15KB

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