280 satır
13 KiB
C
280 satır
13 KiB
C
/// \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
|