/// \file cmFeatFile.h /// \brief Audio file acoustic feature analyzer and accompanying file reader. /// /// #ifndef cmFeatFile_h #define cmFeatFile_h #ifdef __cplusplus extern "C" { #endif /// Result codes for all functions in cmFeatFile.h enum { kOkFtRC = cmOkRC, kCfgParseFailFtRC, kFileSysFailFtRC, kJsonFailFtRC, kDspProcFailFtRC, kDirCreateFailFtRC, kFileNotFoundFtRC, kAudioFileOpenFailFtRC, kFrameFileFailFtRC, kChIdxInvalidFtRC, kParamRangeFtRC, kParamErrorFtRC, kFrameWriteFailFtRC, kEofFtRC, kPlviewFailFtRC, kSerialFailFtRC, kInvalidFeatIdFtRC, kFileFailFtRC, kInvalidFrmIdxFtRC }; /// Feature Id's enum { kInvalidFtId, ///< 0 kAmplFtId, ///< 1 Fourier transform amplitude kDbAmplFtId, ///< 2 Fourier transform decibel kPowFtId, ///< 3 Fourier transform power kDbPowFtId, ///< 4 Fourier transform power decibel kPhaseFtId, ///< 5 Fourier transform phase (not unwrapped) kBfccFtId, ///< 6 Bark Frequency Cepstral Coeffcients kMfccFtId, ///< 7 Mel Frequency Cepstral Coefficients kCepsFtId, ///< 8 Cepstral Coefficients kConstQFtId, ///< 9 Constant-Q transform kLogConstQFtId, ///< 10 Log Constant-Q transform kRmsFtId, ///< 11 Root means square of the audio signal kDbRmsFtId, ///< 12 RMS in decibels kD1AmplFtId, ///< 13 1st order difference over time of the Fourier transform amplitude kD1DbAmplFtId, ///< 14 1st order difference over time of the Fourier transform decibel kD1PowFtId, ///< 15 1st order difference over time of the Fourier transform power kD1DbPowFtId, ///< 16 1st order difference over time of the Fourier transform power decibel kD1PhaseFtId, ///< 17 1st order difference over time of the Fourier transform phase (not unwrapped) kD1BfccFtId, ///< 18 1st order difference over time of the Bark Frequency Cepstral Coeffcients kD1MfccFtId, ///< 19 1st order difference over time of the Mel Frequency Cepstral Coefficients kD1CepsFtId, ///< 20 1st order difference over time of the Cepstral Coefficients kD1ConstQFtId, ///< 21 1st order difference over time of the Constant-Q transform kD1LogConstQFtId, ///< 22 1st order difference over time of the Log Constant-Q transform kD1RmsFtId, ///< 23 1st order difference over time of the Root means square of the audio signal kD1DbRmsFtId, ///< 24 1st order difference over time of the RMS in decibels }; /// User defined feature parameters typedef struct { unsigned id; ///< feature id unsigned cnt; ///< length of feature vector bool normFl; ///< normalize this feature bool enableFl; ///< true if this feature is enabled } cmFtAttr_t; /// Skip input audio range record typedef struct { unsigned smpIdx; ///< Index of first sample to skip unsigned smpCnt; ///< Count of successive samples to skip. } cmFtSkip_t; /// Analysis parameters typedef struct { const char* audioFn; ///< Audio file name. const char* featFn; ///< Feature file name. unsigned chIdx; ///< Audio file channel index cmReal_t wndMs; ///< Length of the analysis window in milliseconds. unsigned hopFact; ///< Analysis window overlap factor 1 = 1:1 2=2:1 ... bool normAudioFl; ///< Normalize the audio over the length of the audio file cmMidiByte_t constQMinPitch; ///< Used to determine the base const-q octave. cmMidiByte_t constQMaxPitch; ///< Used to determine the maximum const-q frequency of interest. unsigned constQBinsPerOctave; ///< Bands per const-q octave. unsigned onsetMedFiltWndSmpCnt; ///< Complex onset median filter cmReal_t onsetThreshold; ///< Complex onset threshold cmReal_t minDb; ///< Fourier Transform magnitude values below minDb are set to minDb. cmReal_t floorThreshDb; ///< Frames with an RMS below this value will be skipped cmFtSkip_t* skipArray; ///< skipArray[skipCnt] user defined sample skip ranges unsigned skipCnt; ///< Count of records in skipArray[]. cmFtAttr_t* attrArray; ///< attrArray[attrCnt] user defined parameter array unsigned attrCnt; ///< Count of records in attrArray[]. } cmFtParam_t; /// Feature summary information typedef struct { unsigned id; ///< feature id (same as associated cmFtAttr.id) unsigned cnt; ///< length of each feature vector (same as associated cmFtAttr.cnt) /// The raw feature summary values are calculated prior to normalization. cmReal_t* rawMinV; ///< Vector of min value over time for each feature element. cmReal_t* rawMaxV; ///< Vector of max value over time for each feature element. cmReal_t* rawAvgV; ///< Vector of avg value over time for each feature element. cmReal_t* rawSdvV; ///< Vector of standard deviation values over time for each feature element. cmReal_t rawMin; ///< Min value of all values for this feature. Equivalent to min(rawMinV). cmReal_t rawMax; ///< Max value of all values for this feature. Equivalent to max(rawMaxV). /// normalized feature summary values cmReal_t* normMinV; ///< Vector of min value over time for each feature element. cmReal_t* normMaxV; ///< Vector of max value over time for each feature element. cmReal_t* normAvgV; ///< Vector of avg value over time for each feature element. cmReal_t* normSdvV; ///< Vector of standard deviation values over time for each feature element. cmReal_t normMin; ///< Min value of all values for this feature. Equivalent to min(normMinV). cmReal_t normMax; ///< Max value of all values for this feature. Equivalent to max(rawMaxV). } cmFtSumm_t; /// Feature file info record typedef struct { unsigned frmCnt; ///< count of frames in the file cmReal_t srate; ///< audio sample rate unsigned smpCnt; ///< audio sample count unsigned fftSmpCnt; ///< FFT window length (always power of 2) unsigned hopSmpCnt; ///< audio sample hop count unsigned binCnt; ///< FFT bin count (always fftSmpCnt/2 + 1) unsigned skipFrmCnt; ///< count of frames skipped based on user skip array unsigned floorFrmCnt; ///< count of frames skipped because below floorThreshDb cmFtParam_t param; ///< analysis parameter record used to form this feature file cmFtSumm_t* summArray; ///< summArray[ param.attrCnt ] feature summary information } cmFtInfo_t; /// Data structure returned by cmFtReaderAdvance(). typedef struct { unsigned smpIdx; ///< The audio signal sample index this frames information is based on. unsigned frmIdx; ///< The frame index relative to other frames in this feature file. } cmFtFrameDesc_t; typedef cmHandle_t cmFtH_t; ///< Analyzer handle typedef cmHandle_t cmFtFileH_t; ///< Feature file handle. typedef unsigned cmFtRC_t; ///< Result code type used by all functions in cmFeatFile.h. extern cmFtH_t cmFtNullHandle; ///< A NULL handle useful for indicating an uninitialized analyzer. extern cmFtFileH_t cmFtFileNullHandle; ///< A NULL handle useful for indicating an uninitialized feature file. /// Given a feature type id return the associated label. const char* cmFtFeatIdToLabel( unsigned featId ); /// Given a feature type label return the associated id. unsigned cmFtFeatLabelToId( const char* label ); /// \name Feature Analyzer Related functions ///@{ /// Initialize the feature analyzer. The memory manager and file system must /// be initialized (cmMdInitialize(), cmFsInitialize()) prior to calling this function. cmFtRC_t cmFtInitialize( cmFtH_t* hp, cmCtx_t* ctx ); /// Finalize a feature analyzer. cmFtRC_t cmFtFinalize( cmFtH_t* h ); /// Return true if the handle represents an initialized feature analyzer. bool cmFtIsValid( cmFtH_t h ); /// Parse a JSON file containing a set of analysis parameters. cmFtRC_t cmFtParse( cmFtH_t h, const char* cfgFn ); /// Run the analyzer. cmFtRC_t cmFtAnalyze( cmFtH_t h ); /// If cmFtAnalyze() is being run in a seperate thread this function /// can be used to access the analyzers progress. const char* cmFtAnalyzeProgress( cmFtH_t h, unsigned* passPtr, cmReal_t* percentPtr ); ///@} /// \name Feature File Related Functions ///@{ /// Open a feature file. /// Note that inforPtrPtr is optional and will be ignored if it is set to NULL. cmFtRC_t cmFtReaderOpen( cmFtH_t h, cmFtFileH_t* hp, const char* featFn, const cmFtInfo_t** infoPtrPtr ); /// Close a feature file. cmFtRC_t cmFtReaderClose( cmFtFileH_t* hp ); /// Return true if the handle reprents an open feature file. bool cmFtReaderIsValid( cmFtFileH_t h ); /// Return the count of features types this file contains. unsigned cmFtReaderFeatCount( cmFtFileH_t h ); /// Return the feature type id associated with the specified index. unsigned cmFtReaderFeatId( cmFtFileH_t h, unsigned index ); /// Reset the current file location to the first frame but do not load it. /// The next call to cmFtReadAdvance() will load the next frame. cmFtRC_t cmFtReaderRewind( cmFtFileH_t h ); /// Make frmIdx the current file location. cmFtRC_t cmFtReaderSeek( cmFtFileH_t h, unsigned frmIdx ); /// Load the current frame, advance the current file position, and return /// a pointer to a cmFtFrameDesc_t record for the loaded frame. /// Returns kEofFtRC upon reaching end of file. /// The frameDescPtr is optional. cmFtRC_t cmFtReaderAdvance( cmFtFileH_t h, cmFtFrameDesc_t* frameDescPtr ); /// Returns a pointer to a data matrix in the feature identified by featId in the current feature frame. cmReal_t* cmFtReaderData( cmFtFileH_t h, unsigned featId, unsigned* cntPtr ); /// Copy the contents of a given set of frames into buf[frmCnt*elePerFrmCnt]. cmFtRC_t cmFtReaderCopy( cmFtFileH_t h, unsigned featId, unsigned frmIdx, cmReal_t* buf, unsigned frmCnt, unsigned elePerFrmCnt, unsigned* outEleCntPtr ); /// Data structure used to specify multiple features for use by cmFtReaderMultiSetup(). typedef struct { unsigned featId; ///< Feature id of feature to include in the feature vector 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. /// returned with actual count used unsigned id0; ///< Ignored on input. Used internally by cmFtReaderXXX() unsigned id1; ///< Ignored on input. Used internally by cmFtReaderXXX() } cmFtMulti_t; /// Setup an array of cmFtMulti_t records. The cmFtMulti_t array /// used by cmFtReaderMulitData() must be initialized by this function. cmFtRC_t cmFtReaderMultiSetup( cmFtFileH_t h, cmFtMulti_t* multiArray, unsigned multiCnt, unsigned* featVectEleCntPtr ); /// Fill outV[outN] with a consecutive data from the features specified in the cmFtMulti_t array. /// Use cmFtReaderMultiSetup() to configure the cmFtMulti_t array prior to calling this function. cmFtRC_t cmFtReaderMultiData( cmFtFileH_t h, const cmFtMulti_t* multiArray, unsigned multiCnt, cmReal_t* outV, unsigned outN ); /// Report summary information for the specified feature. cmFtRC_t cmFtReaderReport( cmFtFileH_t h, unsigned featId ); /// Identical to cmFtReaderReport() except the feature file is identified from a file name rather than an open cmFtFileH_t. cmFtRC_t cmFtReaderReportFn( cmFtH_t h, const cmChar_t* fn, unsigned featId ); /// Report feature data for the specified set of feature frames. cmFtRC_t cmFtReaderReportFeature( cmFtFileH_t h, unsigned featId, unsigned frmIdx, unsigned frmCnt ); /// Write a feature into a binary file. /// Set 'frmCnt' to the cmInvalidCnt to include all frames past frmIdx. /// The first three unsigned values in the output file /// contain the row count, maximum column count, and the count of bytes in each data element (4=float,8=double). /// Each row of the file begins with the count of elements in the row and is followed by a data array. cmFtRC_t cmFtReaderToBinary( cmFtFileH_t h, unsigned featId, unsigned frmIdx, unsigned frmCnt, const cmChar_t* outFn ); /// Identical to cmFtReaderToBinary() except it takes a feature file name instead of a file handle. cmFtRC_t cmFtReaderToBinaryFn( cmFtH_t h, const cmChar_t* fn, unsigned featId, unsigned frmIdx, unsigned frmCnt, const cmChar_t* outFn ); ///@} #ifdef __cplusplus } #endif #endif