include/feat.h File Reference

compute the dynamic coefficients from the cepstral vector. More...

#include <stdio.h>
#include <sphinxbase_export.h>
#include <prim_type.h>
#include <fe.h>
#include <cmn.h>
#include <agc.h>

Go to the source code of this file.

Data Structures

struct  feat_s

Defines

#define LIVEBUFBLOCKSIZE   256
#define S3_MAX_FRAMES   15000
#define cepstral_to_feature_command_line_macro()
#define feat_name(f)   ((f)->name)
 Name of feature type.
#define feat_cepsize(f)   ((f)->cepsize)
 Input dimensionality of feature.
#define feat_window_size(f)   ((f)->window_size)
 Size of dynamic feature window.
#define feat_n_stream(f)   ((f)->n_stream)
 Number of feature streams.
#define feat_stream_len(f, i)   ((f)->stream_len[i])
 Length of feature stream i.
#define feat_dimension1(f)   ((f)->n_sv ? (f)->n_sv : f->n_stream)
 Number of streams or subvectors in feature output.
#define feat_dimension2(f, i)   ((f)->sv_len ? (f)->sv_len[i] : f->stream_len[i])
 Dimensionality of stream/subvector i in feature output.
#define feat_dimension(f)   ((f)->out_dim)
 Total dimensionality of feature output.

Typedefs

typedef struct feat_s feat_t

Functions

SPHINXBASE_EXPORT int32 ** parse_subvecs (char const *str)
 Parse subvector specification string.
SPHINXBASE_EXPORT void subvecs_free (int32 **subvecs)
 Free array of subvector specs.
SPHINXBASE_EXPORT int32 feat_s2mfc_read (char *file, int32 win, int32 sf, int32 ef, mfcc_t ***out_mfc, int32 maxfr, int32 cepsize)
 Read Sphinx-II format mfc file (s2mfc = Sphinx-II format MFC data).
SPHINXBASE_EXPORT mfcc_t *** feat_array_alloc (feat_t *fcb, int32 nfr)
 Allocate an array to hold several frames worth of feature vectors.
SPHINXBASE_EXPORT void feat_array_free (mfcc_t ***feat)
 Free a buffer allocated with feat_array_alloc().
SPHINXBASE_EXPORT feat_tfeat_init (char const *type, cmn_type_t cmn, int32 varnorm, agc_type_t agc, int32 breport, int32 cepsize)
 Initialize feature module to use the selected type of feature stream.
SPHINXBASE_EXPORT int32 feat_read_lda (feat_t *feat, const char *ldafile, int32 dim)
 Add an LDA transformation to the feature module from a file.
SPHINXBASE_EXPORT void feat_lda_transform (feat_t *fcb, mfcc_t ***inout_feat, uint32 nfr)
 Transform a block of features using the feature module's LDA transform.
SPHINXBASE_EXPORT int feat_set_subvecs (feat_t *fcb, int32 **subvecs)
 Add a subvector specification to the feature module.
SPHINXBASE_EXPORT void feat_print (feat_t *fcb, mfcc_t ***feat, int32 nfr, FILE *fp)
 Print the given block of feature vectors to the given FILE.
SPHINXBASE_EXPORT int32 feat_s2mfc2feat (feat_t *fcb, const char *file, const char *dir, const char *cepext, int32 sf, int32 ef, mfcc_t ***feat, int32 maxfr)
 Read a specified MFC file (or given segment within it), perform CMN/AGC as indicated by fcb, and compute feature vectors.
SPHINXBASE_EXPORT int32 feat_s2mfc2feat_live (feat_t *fcb, mfcc_t **uttcep, int32 *inout_ncep, int32 beginutt, int32 endutt, mfcc_t ***ofeat)
 Feature computation routine for live mode decoder.
SPHINXBASE_EXPORT feat_tfeat_retain (feat_t *f)
 Retain ownership of feat_t.
SPHINXBASE_EXPORT int feat_free (feat_t *f)
 Release resource associated with feat_t.
SPHINXBASE_EXPORT void feat_report (feat_t *f)
 Report the feat_t data structure.


Detailed Description

compute the dynamic coefficients from the cepstral vector.

Definition in file feat.h.


Define Documentation

#define feat_n_stream (  )     ((f)->n_stream)

Number of feature streams.

Deprecated:
Do not use this, use feat_dimension1() instead.

Definition at line 219 of file feat.h.

#define feat_stream_len ( f,
 )     ((f)->stream_len[i])

Length of feature stream i.

Deprecated:
Do not use this, use feat_dimension2() instead.

Definition at line 225 of file feat.h.


Function Documentation

SPHINXBASE_EXPORT mfcc_t*** feat_array_alloc ( feat_t fcb,
int32  nfr 
)

Allocate an array to hold several frames worth of feature vectors.

The returned value is the mfcc_t ***data array, organized as follows:

  • data[0][0] = frame 0 stream 0 vector, data[0][1] = frame 0 stream 1 vector, ...
  • data[1][0] = frame 1 stream 0 vector, data[0][1] = frame 1 stream 1 vector, ...
  • data[2][0] = frame 2 stream 0 vector, data[0][1] = frame 2 stream 1 vector, ...
  • ...

NOTE: For I/O convenience, the entire data area is allocated as one contiguous block.

Returns:
pointer to the allocated space if successful, NULL if any error.
Parameters:
fcb In: Descriptor from feat_init(), used to obtain number of streams and stream sizes
nfr In: Number of frames for which to allocate

Definition at line 517 of file feat.c.

References ckd_calloc, ckd_calloc_2d, feat_array_alloc(), feat_dimension, feat_dimension1, and feat_dimension2.

Referenced by feat_array_alloc().

SPHINXBASE_EXPORT int feat_free ( feat_t f  ) 

Release resource associated with feat_t.

Returns:
new reference count (0 if freed)
Parameters:
f In: feat_t

Definition at line 1335 of file feat.c.

References agc_free(), ckd_free(), ckd_free_2d(), ckd_free_3d(), feat_free(), and subvecs_free().

Referenced by feat_free().

SPHINXBASE_EXPORT feat_t* feat_init ( char const *  type,
cmn_type_t  cmn,
int32  varnorm,
agc_type_t  agc,
int32  breport,
int32  cepsize 
)

Initialize feature module to use the selected type of feature stream.

One-time only initialization at the beginning of the program. Input type is a string defining the kind of input->feature conversion desired:

  • "s2_4x": s2mfc->Sphinx-II 4-feature stream,
  • "1s_c_d_dd": s2mfc->Sphinx 3.x single feature stream,
  • "s3_1x39": s2mfc->Sphinx 3.0 single feature stream,
  • "n1,n2,n3,...": Explicit feature vector layout spec. with comma-separated feature stream lengths. In this case, the input data is already in the feature format and there is no conversion necessary.

Returns:
(feat_t *) descriptor if successful, NULL if error. Caller must not directly modify the contents of the returned value.
Parameters:
type In: Type of feature stream
cmn In: Type of cepstram mean normalization to be done before feature computation; can be CMN_NONE (for none)
varnorm In: (boolean) Whether variance normalization done on each utt; only applicable if CMN also done
agc In: Type of automatic gain control to be done before feature computation
breport In: Whether to show a report for feat_t
cepsize Number of components in the input vector (or 0 for the default for this feature type, which is usually 13)

Definition at line 838 of file feat.c.

References agc_emax_set(), agc_init(), agc_type_str, ckd_calloc, ckd_calloc_2d, ckd_free(), ckd_salloc, cmn_type_str, E_ERROR, E_FATAL, E_INFO, feat_cepsize, feat_init(), and feat_window_size.

Referenced by feat_init().

SPHINXBASE_EXPORT void feat_lda_transform ( feat_t fcb,
mfcc_t ***  inout_feat,
uint32  nfr 
)

Transform a block of features using the feature module's LDA transform.

Parameters:
fcb In: Descriptor from feat_init()
inout_feat Feature block to transform.
nfr In: Number of frames in inout_feat.

Definition at line 139 of file lda.c.

References ckd_calloc, ckd_free(), feat_dimension, and feat_lda_transform().

Referenced by feat_lda_transform(), and feat_s2mfc2feat_live().

SPHINXBASE_EXPORT void feat_print ( feat_t fcb,
mfcc_t ***  feat,
int32  nfr,
FILE *  fp 
)

Print the given block of feature vectors to the given FILE.

Parameters:
fcb In: Descriptor from feat_init()
feat In: Feature data to be printed
nfr In: Number of frames of feature data above
fp In: Output file pointer

Definition at line 1007 of file feat.c.

References feat_dimension1, feat_dimension2, and feat_print().

Referenced by feat_print().

SPHINXBASE_EXPORT int32 feat_read_lda ( feat_t feat,
const char *  ldafile,
int32  dim 
)

Add an LDA transformation to the feature module from a file.

Returns:
0 for success or -1 if reading the LDA file failed.
Parameters:
feat In: Descriptor from feat_init()
ldafile In: File to read the LDA matrix from.
dim In: Dimensionality of LDA output.

Definition at line 61 of file lda.c.

References bio_fread_3d(), bio_hdrarg_free(), bio_readhdr(), ckd_free_3d(), E_ERROR, E_ERROR_SYSTEM, E_WARN, and feat_read_lda().

Referenced by feat_read_lda().

SPHINXBASE_EXPORT void feat_report ( feat_t f  ) 

Report the feat_t data structure.

Parameters:
f In: feat_t

Definition at line 1366 of file feat.c.

References E_INFO_NOFN, E_INFOCONT, and feat_report().

Referenced by feat_report().

SPHINXBASE_EXPORT feat_t* feat_retain ( feat_t f  ) 

Retain ownership of feat_t.

Returns:
pointer to retained feat_t.

Definition at line 1328 of file feat.c.

References feat_retain().

Referenced by feat_retain().

SPHINXBASE_EXPORT int32 feat_s2mfc2feat ( feat_t fcb,
const char *  file,
const char *  dir,
const char *  cepext,
int32  sf,
int32  ef,
mfcc_t ***  feat,
int32  maxfr 
)

Read a specified MFC file (or given segment within it), perform CMN/AGC as indicated by fcb, and compute feature vectors.

Feature vectors are computed for the entire segment specified, by including additional surrounding or padding frames to accommodate the feature windows.

Returns:
Number of frames of feature vectors computed if successful; -1 if any error. If feat is NULL, then no actual computation will be done, and the number of frames which must be allocated will be returned.
A note on how the file path is constructed: If the control file already specifies extension or absolute path, then these are not applied. The default extension is defined by the application.
Parameters:
fcb In: Descriptor from feat_init()
file In: File to be read
dir In: Directory prefix for file, if needed; can be NULL
cepext In: Extension of the cepstrum file.It cannot be NULL
feat Out: Computed feature vectors; caller must allocate this space
maxfr In: Available space (number of frames) in above feat array; it must be sufficient to hold the result. Pass -1 for no limit.

Definition at line 1105 of file feat.c.

References ckd_free_2d(), E_ERROR, E_INFO, feat_s2mfc2feat(), feat_s2mfc_read(), and feat_window_size.

Referenced by feat_s2mfc2feat().

SPHINXBASE_EXPORT int32 feat_s2mfc2feat_live ( feat_t fcb,
mfcc_t **  uttcep,
int32 *  inout_ncep,
int32  beginutt,
int32  endutt,
mfcc_t ***  ofeat 
)

Feature computation routine for live mode decoder.

This function computes features for blocks of incoming data. It retains an internal buffer for computing deltas, which means that the number of output frames will not necessarily equal the number of input frames.

It is very important to realize that the number of output frames can be greater than the number of input frames, specifically when endutt is true. It is guaranteed to never exceed *inout_ncep + feat_window_size(fcb). You MUST have allocated at least that many frames in ofeat, or you will experience a buffer overflow.

If beginutt and endutt are both true, CMN_CURRENT and AGC_MAX will be done. Otherwise only CMN_PRIOR and AGC_EMAX will be done.

If beginutt is false, endutt is true, and the number of input frames exceeds the input size, then end-of-utterance processing won't actually be done. This condition can easily be checked, because *inout_ncep will equal the return value on exit, and will also be smaller than the value of *inout_ncep on entry.

Returns:
The number of output frames actually computed.
Parameters:
fcb In: Descriptor from feat_init()
uttcep In: Incoming cepstral buffer
inout_ncep In: Size of incoming buffer. Out: Number of incoming frames consumed.
beginutt In: Begining of utterance flag
endutt In: End of utterance flag
ofeat In: Output feature buffer. See VERY IMPORTANT note about the size of this buffer above.

Definition at line 1212 of file feat.c.

References feat_cepsize, feat_lda_transform(), feat_s2mfc2feat_live(), and feat_window_size.

Referenced by feat_s2mfc2feat_live().

SPHINXBASE_EXPORT int32 feat_s2mfc_read ( char *  file,
int32  win,
int32  sf,
int32  ef,
mfcc_t ***  out_mfc,
int32  maxfr,
int32  cepsize 
)

Read Sphinx-II format mfc file (s2mfc = Sphinx-II format MFC data).

Returns:
# frames read (plus padding) if successful, -1 if error (e.g., mfc array too small). If out_mfc is NULL, no actual reading will be done, and the number of frames (plus padding) that would be read is returned.
Parameters:
win In: Sphinx-II format MFC file to be read
sf In: Size of dynamic feature window to add to the input. Padding will be added if necessary.
out_mfc In: Start/end frames (range) to be read from file; Can use 0,-1 to read entire file. Note that the window will be added on either side of these.
maxfr Out: 2-D array to be filled with read data; this will be allocated internally and must be freed with ckd_free_2d().
cepsize In: Number of frames of mfc array allocated; error if attempt to read more than this amount. Pass -1 to read as many frames as available. In: Length of each MFC vector.

Definition at line 359 of file feat.c.

References ckd_calloc, ckd_calloc_2d, ckd_free(), E_ERROR, E_INFO, E_WARN, feat_s2mfc_read(), fread_retry(), and stat_retry().

Referenced by feat_s2mfc2feat(), and feat_s2mfc_read().

SPHINXBASE_EXPORT int feat_set_subvecs ( feat_t fcb,
int32 **  subvecs 
)

Add a subvector specification to the feature module.

The subvector splitting will be performed after dynamic feature computation, CMN, AGC, and any LDA transformation. The number of streams in the dynamic feature type must be one, as with LDA.

After adding a subvector specification, the output of feature computation will be split into multiple subvectors, and feat_array_alloc() will allocate pointers accordingly. The number of streams will remain the

Parameters:
fcb the feature descriptor.
subvecs subvector specification. This pointer is retained by the feat_t and should not be freed manually.
Returns:
0 for success or -1 if the subvector specification was invalid.

Definition at line 276 of file feat.c.

References ckd_calloc, ckd_free(), E_ERROR, feat_dimension, feat_set_subvecs(), and subvecs_free().

Referenced by feat_set_subvecs().

SPHINXBASE_EXPORT int32** parse_subvecs ( char const *  str  ) 

Parse subvector specification string.

Format of specification:

  • '/' separated list of subvectors
  • each subvector is a ',' separated list of subranges
  • each subrange is a single
    <number> 
    or
    <number>-<number> 
    (inclusive), where
    <number> 
    is a feature vector dimension specifier.
E.g., "24,0-11/25,12-23/26,27-38" has:
  • 3 subvectors
  • the 1st subvector has feature dims: 24, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, and 11.
  • etc.
Parameters:
str subvector specification string.
Returns:
allocated 2-D array of subvector specs (free with subvecs_free()). If there are N subvectors specified, subvec[N] = NULL; and each subvec[0]..subvec[N-1] is -1 terminated vector of feature dims.

Definition at line 168 of file feat.c.

References ckd_calloc, E_FATAL, glist_add_int32(), glist_add_ptr(), glist_count(), glist_free(), gnode_ptr, and parse_subvecs().

Referenced by parse_subvecs().


Generated on Mon Aug 24 16:07:55 2009 for SphinxBase by  doxygen 1.5.8