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ů.

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