SphinxBase  5prealpha
feat.h File Reference

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

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

Go to the source code of this file.

Data Structures

struct  feat_s
 

Macros

#define LIVEBUFBLOCKSIZE
 
#define S3_MAX_FRAMES   15000 /* RAH, I believe this is still too large, but better than before */
 
#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. More...
 
#define feat_stream_len(f, i)   ((f)->stream_len[i])
 Length of feature stream i. More...
 
#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)->lda ? (f)->out_dim : ((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.
 
#define feat_stream_lengths(f)   ((f)->lda ? (&(f)->out_dim) : (f)->sv_len ? (f)->sv_len : f->stream_len)
 Array with stream/subvector lengths.
 

Typedefs

typedef struct feat_s feat_t
 

Functions

SPHINXBASE_EXPORT int32 ** parse_subvecs (char const *str)
 Parse subvector specification string. More...
 
SPHINXBASE_EXPORT void subvecs_free (int32 **subvecs)
 Free array of subvector specs.
 
SPHINXBASE_EXPORT mfcc_t *** feat_array_alloc (feat_t *fcb, int32 nfr)
 Allocate an array to hold several frames worth of feature vectors. More...
 
SPHINXBASE_EXPORT mfcc_t *** feat_array_realloc (feat_t *fcb, mfcc_t ***old_feat, int32 ofr, int32 nfr)
 Realloate the array of features. More...
 
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. More...
 
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. More...
 
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. More...
 
SPHINXBASE_EXPORT int feat_set_subvecs (feat_t *fcb, int32 **subvecs)
 Add a subvector specification to the feature module. More...
 
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. More...
 
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. More...
 
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. More...
 
SPHINXBASE_EXPORT void feat_update_stats (feat_t *fcb)
 Update the normalization stats, possibly in the end of utterance. More...
 
SPHINXBASE_EXPORT feat_tfeat_retain (feat_t *f)
 Retain ownership of feat_t. More...
 
SPHINXBASE_EXPORT int feat_free (feat_t *f)
 Release resource associated with feat_t. More...
 
SPHINXBASE_EXPORT void feat_report (feat_t *f)
 Report the feat_t data structure. More...
 

Detailed Description

compute the dynamic coefficients from the cepstral vector.

Definition in file feat.h.

Macro Definition Documentation

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

Number of feature streams.

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

Definition at line 181 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 187 of file feat.h.

#define LIVEBUFBLOCKSIZE
Value:
256

Definition at line 64 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
fcbIn: Descriptor from feat_init(), used to obtain number of streams and stream sizes
nfrIn: Number of frames for which to allocate

Definition at line 356 of file feat.c.

References ckd_calloc, ckd_calloc_2d, feat_dimension, feat_dimension1, and feat_dimension2.

Referenced by feat_array_realloc().

SPHINXBASE_EXPORT mfcc_t*** feat_array_realloc ( feat_t fcb,
mfcc_t ***  old_feat,
int32  ofr,
int32  nfr 
)

Realloate the array of features.

Requires us to know the old size

Parameters
fcbIn: Descriptor from feat_init(), used to obtain number of streams and stream sizes
old_featFeature array. Freed
ofrIn: Previous number of frames
nfrIn: Number of frames for which to allocate

Definition at line 389 of file feat.c.

References feat_array_alloc(), feat_array_free(), and feat_dimension.

SPHINXBASE_EXPORT int feat_free ( feat_t f)

Release resource associated with feat_t.

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

Definition at line 1442 of file feat.c.

References agc_free(), ckd_free(), ckd_free_2d(), ckd_free_3d(), and subvecs_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
typeIn: Type of feature stream
cmnIn: Type of cepstram mean normalization to be done before feature computation; can be CMN_NONE (for none)
varnormIn: (boolean) Whether variance normalization done on each utt; only applicable if CMN also done
agcIn: Type of automatic gain control to be done before feature computation
breportIn: Whether to show a report for feat_t
cepsizeNumber of components in the input vector (or 0 for the default for this feature type, which is usually 13)

Definition at line 705 of file feat.c.

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

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
fcbIn: Descriptor from feat_init()
inout_featFeature block to transform.
nfrIn: Number of frames in inout_feat.

Definition at line 139 of file lda.c.

References ckd_calloc, ckd_free(), and feat_dimension.

Referenced by 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
fcbIn: Descriptor from feat_init()
featIn: Feature data to be printed
nfrIn: Number of frames of feature data above
fpIn: Output file pointer

Definition at line 896 of file feat.c.

References feat_dimension1, and feat_dimension2.

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
featIn: Descriptor from feat_init()
ldafileIn: File to read the LDA matrix from.
dimIn: 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_FATAL, and E_WARN.

SPHINXBASE_EXPORT void feat_report ( feat_t f)

Report the feat_t data structure.

Parameters
fIn: feat_t

Definition at line 1473 of file feat.c.

References E_INFO_NOFN, and E_INFOCONT.

SPHINXBASE_EXPORT feat_t* feat_retain ( feat_t f)

Retain ownership of feat_t.

Returns
pointer to retained feat_t.

Definition at line 1435 of file feat.c.

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
fcbIn: Descriptor from feat_init()
fileIn: File to be read
dirIn: Directory prefix for file, if needed; can be NULL
cepextIn: Extension of the cepstrum file.It cannot be NULL
featOut: Computed feature vectors; caller must allocate this space
maxfrIn: 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 1170 of file feat.c.

References ckd_calloc, ckd_free(), ckd_free_2d(), ckd_realloc, E_ERROR, E_INFO, and feat_window_size.

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
fcbIn: Descriptor from feat_init()
uttcepIn: Incoming cepstral buffer
inout_ncepIn: Size of incoming buffer. Out: Number of incoming frames consumed.
beginuttIn: Begining of utterance flag
enduttIn: End of utterance flag
ofeatIn: Output feature buffer. See VERY IMPORTANT note about the size of this buffer above.

Definition at line 1308 of file feat.c.

References feat_cepsize, feat_lda_transform(), and feat_window_size.

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
fcbthe feature descriptor.
subvecssubvector 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 277 of file feat.c.

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

SPHINXBASE_EXPORT void feat_update_stats ( feat_t fcb)

Update the normalization stats, possibly in the end of utterance.

Definition at line 1424 of file feat.c.

References agc_emax_update(), and cmn_live_update().

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
strsubvector 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 169 of file feat.c.

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