libcm is a C development framework with an emphasis on audio signal processing applications.
Você não pode selecionar mais de 25 tópicos Os tópicos devem começar com uma letra ou um número, podem incluir traços ('-') e podem ter até 35 caracteres.

cmFeatFile.h 13KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275
  1. //( { file_desc:" Audio file acoustic feature analyzer and accompanying file reader." kw:[audio analysis file]}
  2. //
  3. //
  4. #ifndef cmFeatFile_h
  5. #define cmFeatFile_h
  6. #ifdef __cplusplus
  7. extern "C" {
  8. #endif
  9. // Result codes for all functions in cmFeatFile.h
  10. enum
  11. {
  12. kOkFtRC = cmOkRC,
  13. kCfgParseFailFtRC,
  14. kFileSysFailFtRC,
  15. kJsonFailFtRC,
  16. kDspProcFailFtRC,
  17. kDirCreateFailFtRC,
  18. kFileNotFoundFtRC,
  19. kAudioFileOpenFailFtRC,
  20. kFrameFileFailFtRC,
  21. kChIdxInvalidFtRC,
  22. kParamRangeFtRC,
  23. kParamErrorFtRC,
  24. kFrameWriteFailFtRC,
  25. kEofFtRC,
  26. kPlviewFailFtRC,
  27. kSerialFailFtRC,
  28. kInvalidFeatIdFtRC,
  29. kFileFailFtRC,
  30. kInvalidFrmIdxFtRC
  31. };
  32. // Feature Id's
  33. enum
  34. {
  35. kInvalidFtId, // 0
  36. kAmplFtId, // 1 Fourier transform amplitude
  37. kDbAmplFtId, // 2 Fourier transform decibel
  38. kPowFtId, // 3 Fourier transform power
  39. kDbPowFtId, // 4 Fourier transform power decibel
  40. kPhaseFtId, // 5 Fourier transform phase (not unwrapped)
  41. kBfccFtId, // 6 Bark Frequency Cepstral Coeffcients
  42. kMfccFtId, // 7 Mel Frequency Cepstral Coefficients
  43. kCepsFtId, // 8 Cepstral Coefficients
  44. kConstQFtId, // 9 Constant-Q transform
  45. kLogConstQFtId, // 10 Log Constant-Q transform
  46. kRmsFtId, // 11 Root means square of the audio signal
  47. kDbRmsFtId, // 12 RMS in decibels
  48. kD1AmplFtId, // 13 1st order difference over time of the Fourier transform amplitude
  49. kD1DbAmplFtId, // 14 1st order difference over time of the Fourier transform decibel
  50. kD1PowFtId, // 15 1st order difference over time of the Fourier transform power
  51. kD1DbPowFtId, // 16 1st order difference over time of the Fourier transform power decibel
  52. kD1PhaseFtId, // 17 1st order difference over time of the Fourier transform phase (not unwrapped)
  53. kD1BfccFtId, // 18 1st order difference over time of the Bark Frequency Cepstral Coeffcients
  54. kD1MfccFtId, // 19 1st order difference over time of the Mel Frequency Cepstral Coefficients
  55. kD1CepsFtId, // 20 1st order difference over time of the Cepstral Coefficients
  56. kD1ConstQFtId, // 21 1st order difference over time of the Constant-Q transform
  57. kD1LogConstQFtId, // 22 1st order difference over time of the Log Constant-Q transform
  58. kD1RmsFtId, // 23 1st order difference over time of the Root means square of the audio signal
  59. kD1DbRmsFtId, // 24 1st order difference over time of the RMS in decibels
  60. };
  61. // User defined feature parameters
  62. typedef struct
  63. {
  64. unsigned id; // feature id
  65. unsigned cnt; // length of feature vector
  66. bool normFl; // normalize this feature
  67. bool enableFl; // true if this feature is enabled
  68. } cmFtAttr_t;
  69. // Skip input audio range record
  70. typedef struct
  71. {
  72. unsigned smpIdx; // Index of first sample to skip
  73. unsigned smpCnt; // Count of successive samples to skip.
  74. } cmFtSkip_t;
  75. // Analysis parameters
  76. typedef struct
  77. {
  78. const char* audioFn; // Audio file name.
  79. const char* featFn; // Feature file name.
  80. unsigned chIdx; // Audio file channel index
  81. cmReal_t wndMs; // Length of the analysis window in milliseconds.
  82. unsigned hopFact; // Analysis window overlap factor 1 = 1:1 2=2:1 ...
  83. bool normAudioFl; // Normalize the audio over the length of the audio file
  84. cmMidiByte_t constQMinPitch; // Used to determine the base const-q octave.
  85. cmMidiByte_t constQMaxPitch; // Used to determine the maximum const-q frequency of interest.
  86. unsigned constQBinsPerOctave; // Bands per const-q octave.
  87. unsigned onsetMedFiltWndSmpCnt; // Complex onset median filter
  88. cmReal_t onsetThreshold; // Complex onset threshold
  89. cmReal_t minDb; // Fourier Transform magnitude values below minDb are set to minDb.
  90. cmReal_t floorThreshDb; // Frames with an RMS below this value will be skipped
  91. cmFtSkip_t* skipArray; // skipArray[skipCnt] user defined sample skip ranges
  92. unsigned skipCnt; // Count of records in skipArray[].
  93. cmFtAttr_t* attrArray; // attrArray[attrCnt] user defined parameter array
  94. unsigned attrCnt; // Count of records in attrArray[].
  95. } cmFtParam_t;
  96. // Feature summary information
  97. typedef struct
  98. {
  99. unsigned id; // feature id (same as associated cmFtAttr.id)
  100. unsigned cnt; // length of each feature vector (same as associated cmFtAttr.cnt)
  101. // The raw feature summary values are calculated prior to normalization.
  102. cmReal_t* rawMinV; // Vector of min value over time for each feature element.
  103. cmReal_t* rawMaxV; // Vector of max value over time for each feature element.
  104. cmReal_t* rawAvgV; // Vector of avg value over time for each feature element.
  105. cmReal_t* rawSdvV; // Vector of standard deviation values over time for each feature element.
  106. cmReal_t rawMin; // Min value of all values for this feature. Equivalent to min(rawMinV).
  107. cmReal_t rawMax; // Max value of all values for this feature. Equivalent to max(rawMaxV).
  108. // normalized feature summary values
  109. cmReal_t* normMinV; // Vector of min value over time for each feature element.
  110. cmReal_t* normMaxV; // Vector of max value over time for each feature element.
  111. cmReal_t* normAvgV; // Vector of avg value over time for each feature element.
  112. cmReal_t* normSdvV; // Vector of standard deviation values over time for each feature element.
  113. cmReal_t normMin; // Min value of all values for this feature. Equivalent to min(normMinV).
  114. cmReal_t normMax; // Max value of all values for this feature. Equivalent to max(rawMaxV).
  115. } cmFtSumm_t;
  116. // Feature file info record
  117. typedef struct
  118. {
  119. unsigned frmCnt; // count of frames in the file
  120. cmReal_t srate; // audio sample rate
  121. unsigned smpCnt; // audio sample count
  122. unsigned fftSmpCnt; // FFT window length (always power of 2)
  123. unsigned hopSmpCnt; // audio sample hop count
  124. unsigned binCnt; // FFT bin count (always fftSmpCnt/2 + 1)
  125. unsigned skipFrmCnt; // count of frames skipped based on user skip array
  126. unsigned floorFrmCnt; // count of frames skipped because below floorThreshDb
  127. cmFtParam_t param; // analysis parameter record used to form this feature file
  128. cmFtSumm_t* summArray; // summArray[ param.attrCnt ] feature summary information
  129. } cmFtInfo_t;
  130. // Data structure returned by cmFtReaderAdvance().
  131. typedef struct
  132. {
  133. unsigned smpIdx; // The audio signal sample index this frames information is based on.
  134. unsigned frmIdx; // The frame index relative to other frames in this feature file.
  135. } cmFtFrameDesc_t;
  136. typedef cmHandle_t cmFtH_t; // Analyzer handle
  137. typedef cmHandle_t cmFtFileH_t; // Feature file handle.
  138. typedef unsigned cmFtRC_t; // Result code type used by all functions in cmFeatFile.h.
  139. extern cmFtH_t cmFtNullHandle; // A NULL handle useful for indicating an uninitialized analyzer.
  140. extern cmFtFileH_t cmFtFileNullHandle; // A NULL handle useful for indicating an uninitialized feature file.
  141. // Given a feature type id return the associated label.
  142. const char* cmFtFeatIdToLabel( unsigned featId );
  143. // Given a feature type label return the associated id.
  144. unsigned cmFtFeatLabelToId( const char* label );
  145. // Feature Analyzer Related functions
  146. // Initialize the feature analyzer. The memory manager and file system must
  147. // be initialized (cmMdInitialize(), cmFsInitialize()) prior to calling this function.
  148. cmFtRC_t cmFtInitialize( cmFtH_t* hp, cmCtx_t* ctx );
  149. // Finalize a feature analyzer.
  150. cmFtRC_t cmFtFinalize( cmFtH_t* h );
  151. // Return true if the handle represents an initialized feature analyzer.
  152. bool cmFtIsValid( cmFtH_t h );
  153. // Parse a JSON file containing a set of analysis parameters.
  154. cmFtRC_t cmFtParse( cmFtH_t h, const char* cfgFn );
  155. // Run the analyzer.
  156. cmFtRC_t cmFtAnalyze( cmFtH_t h );
  157. // If cmFtAnalyze() is being run in a seperate thread this function
  158. // can be used to access the analyzers progress.
  159. const char* cmFtAnalyzeProgress( cmFtH_t h, unsigned* passPtr, cmReal_t* percentPtr );
  160. // Feature File Related Functions
  161. // Open a feature file.
  162. // Note that inforPtrPtr is optional and will be ignored if it is set to NULL.
  163. cmFtRC_t cmFtReaderOpen( cmFtH_t h, cmFtFileH_t* hp, const char* featFn, const cmFtInfo_t** infoPtrPtr );
  164. // Close a feature file.
  165. cmFtRC_t cmFtReaderClose( cmFtFileH_t* hp );
  166. // Return true if the handle reprents an open feature file.
  167. bool cmFtReaderIsValid( cmFtFileH_t h );
  168. // Return the count of features types this file contains.
  169. unsigned cmFtReaderFeatCount( cmFtFileH_t h );
  170. // Return the feature type id associated with the specified index.
  171. unsigned cmFtReaderFeatId( cmFtFileH_t h, unsigned index );
  172. // Reset the current file location to the first frame but do not load it.
  173. // The next call to cmFtReadAdvance() will load the next frame.
  174. cmFtRC_t cmFtReaderRewind( cmFtFileH_t h );
  175. // Make frmIdx the current file location.
  176. cmFtRC_t cmFtReaderSeek( cmFtFileH_t h, unsigned frmIdx );
  177. // Load the current frame, advance the current file position, and return
  178. // a pointer to a cmFtFrameDesc_t record for the loaded frame.
  179. // Returns kEofFtRC upon reaching end of file.
  180. // The frameDescPtr is optional.
  181. cmFtRC_t cmFtReaderAdvance( cmFtFileH_t h, cmFtFrameDesc_t* frameDescPtr );
  182. // Returns a pointer to a data matrix in the feature identified by featId in the current feature frame.
  183. cmReal_t* cmFtReaderData( cmFtFileH_t h, unsigned featId, unsigned* cntPtr );
  184. // Copy the contents of a given set of frames into buf[frmCnt*elePerFrmCnt].
  185. cmFtRC_t cmFtReaderCopy( cmFtFileH_t h, unsigned featId, unsigned frmIdx, cmReal_t* buf, unsigned frmCnt, unsigned elePerFrmCnt, unsigned* outEleCntPtr );
  186. // Data structure used to specify multiple features for use by cmFtReaderMultiSetup().
  187. typedef struct
  188. {
  189. unsigned featId; // Feature id of feature to include in the feature vector
  190. unsigned cnt; // Set to count of feat ele's for this feat. Error if greater than avail. Set to -1 to use all avail ele's.
  191. // returned with actual count used
  192. unsigned id0; // Ignored on input. Used internally by cmFtReaderXXX()
  193. unsigned id1; // Ignored on input. Used internally by cmFtReaderXXX()
  194. } cmFtMulti_t;
  195. // Setup an array of cmFtMulti_t records. The cmFtMulti_t array
  196. // used by cmFtReaderMulitData() must be initialized by this function.
  197. cmFtRC_t cmFtReaderMultiSetup( cmFtFileH_t h, cmFtMulti_t* multiArray, unsigned multiCnt, unsigned* featVectEleCntPtr );
  198. // Fill outV[outN] with a consecutive data from the features specified in the cmFtMulti_t array.
  199. // Use cmFtReaderMultiSetup() to configure the cmFtMulti_t array prior to calling this function.
  200. cmFtRC_t cmFtReaderMultiData( cmFtFileH_t h, const cmFtMulti_t* multiArray, unsigned multiCnt, cmReal_t* outV, unsigned outN );
  201. // Report summary information for the specified feature.
  202. cmFtRC_t cmFtReaderReport( cmFtFileH_t h, unsigned featId );
  203. // Identical to cmFtReaderReport() except the feature file is identified from a file name rather than an open cmFtFileH_t.
  204. cmFtRC_t cmFtReaderReportFn( cmFtH_t h, const cmChar_t* fn, unsigned featId );
  205. // Report feature data for the specified set of feature frames.
  206. cmFtRC_t cmFtReaderReportFeature( cmFtFileH_t h, unsigned featId, unsigned frmIdx, unsigned frmCnt );
  207. // Write a feature into a binary file.
  208. // Set 'frmCnt' to the cmInvalidCnt to include all frames past frmIdx.
  209. // The first three unsigned values in the output file
  210. // contain the row count, maximum column count, and the count of bytes in each data element (4=float,8=double).
  211. // Each row of the file begins with the count of elements in the row and is followed by a data array.
  212. cmFtRC_t cmFtReaderToBinary( cmFtFileH_t h, unsigned featId, unsigned frmIdx, unsigned frmCnt, const cmChar_t* outFn );
  213. // Identical to cmFtReaderToBinary() except it takes a feature file name instead of a file handle.
  214. cmFtRC_t cmFtReaderToBinaryFn( cmFtH_t h, const cmChar_t* fn, unsigned featId, unsigned frmIdx, unsigned frmCnt, const cmChar_t* outFn );
  215. //)
  216. #ifdef __cplusplus
  217. }
  218. #endif
  219. #endif