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_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. 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 feat_t * | feat_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 219 of file feat.h.

#define feat_stream_len | ( |  | f,
|  |  | i
| ) |  | ((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.

#define LIVEBUFBLOCKSIZE

Value:
256

Definition at line 102 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 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

  fcb | In: Descriptor from feat_init(), used to obtain number of streams and stream sizes
  old_feat | Feature array. Freed
  ofr | In: Previous number of frames
  nfr | In: 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

  f | In: feat_t

Definition at line 1430 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

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

  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(), 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

  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 895 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

  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_FATAL, and E_WARN.

SPHINXBASE_EXPORT void feat_report | ( | feat_t * | f | ) |

Report the feat_t data structure.

Parameters

  f | In: feat_t

Definition at line 1461 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 1423 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

  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 1169 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

  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 1307 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

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

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

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

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