PocketSphinx  5.0.0rc5
A small speech recognizer
Typedefs | Functions
search.h File Reference

Search modules. More...

#include <pocketsphinx/model.h>
#include <pocketsphinx/alignment.h>

Go to the source code of this file.

Typedefs

typedef struct ps_search_iter_s ps_search_iter_t
 
typedef struct ps_decoder_s ps_decoder_t
 

Functions

POCKETSPHINX_EXPORT int ps_activate_search (ps_decoder_t *ps, const char *name)
 
const POCKETSPHINX_EXPORT char * ps_current_search (ps_decoder_t *ps)
 
POCKETSPHINX_EXPORT int ps_remove_search (ps_decoder_t *ps, const char *name)
 
POCKETSPHINX_EXPORT ps_search_iter_tps_search_iter (ps_decoder_t *ps)
 
POCKETSPHINX_EXPORT ps_search_iter_tps_search_iter_next (ps_search_iter_t *itor)
 
const POCKETSPHINX_EXPORT char * ps_search_iter_val (ps_search_iter_t *itor)
 
POCKETSPHINX_EXPORT void ps_search_iter_free (ps_search_iter_t *itor)
 
POCKETSPHINX_EXPORT ngram_model_tps_get_lm (ps_decoder_t *ps, const char *name)
 
POCKETSPHINX_EXPORT int ps_add_lm (ps_decoder_t *ps, const char *name, ngram_model_t *lm)
 
POCKETSPHINX_EXPORT int ps_add_lm_file (ps_decoder_t *ps, const char *name, const char *path)
 
POCKETSPHINX_EXPORT fsg_model_tps_get_fsg (ps_decoder_t *ps, const char *name)
 
POCKETSPHINX_EXPORT int ps_add_fsg (ps_decoder_t *ps, const char *name, fsg_model_t *fsg)
 
POCKETSPHINX_EXPORT int ps_add_jsgf_file (ps_decoder_t *ps, const char *name, const char *path)
 
POCKETSPHINX_EXPORT int ps_add_jsgf_string (ps_decoder_t *ps, const char *name, const char *jsgf_string)
 
const POCKETSPHINX_EXPORT char * ps_get_kws (ps_decoder_t *ps, const char *name)
 
POCKETSPHINX_EXPORT int ps_add_kws (ps_decoder_t *ps, const char *name, const char *keyfile)
 
POCKETSPHINX_EXPORT int ps_add_keyphrase (ps_decoder_t *ps, const char *name, const char *keyphrase)
 
POCKETSPHINX_EXPORT int ps_add_allphone (ps_decoder_t *ps, const char *name, ngram_model_t *lm)
 
POCKETSPHINX_EXPORT int ps_add_allphone_file (ps_decoder_t *ps, const char *name, const char *path)
 
POCKETSPHINX_EXPORT int ps_set_align_text (ps_decoder_t *ps, const char *words)
 
POCKETSPHINX_EXPORT int ps_set_alignment (ps_decoder_t *ps, ps_alignment_t *al)
 
POCKETSPHINX_EXPORT ps_alignment_tps_get_alignment (ps_decoder_t *ps)
 

Detailed Description

Search modules.

User can configure several "search" objects with different grammars and language models and switch them in runtime to provide interactive experience for the user.

There are different possible search modes:

Each search module has a name and can be referenced by name. These names are application-specific. The function ps_activate_search() activates a search module previously added by a name. Only one search module can be activated at time.

To add the search module one needs to point to the grammar/language model describing the search. The location of the grammar is specific to the application.

The exact design of a searches depends on your application. For example, you might want to listen for activation keyphrase first and once keyphrase is recognized switch to ngram search to recognize actual command. Once you have recognized the command, you can switch to grammar search to recognize the confirmation and then switch back to keyphrase listening mode to wait for another command.

If only a simple recognition is required it is sufficient to add a single search or just configure the required mode with configuration options.

Typedef Documentation

◆ ps_search_iter_t

typedef struct ps_search_iter_s ps_search_iter_t

PocketSphinx search iterator.

Function Documentation

◆ ps_activate_search()

POCKETSPHINX_EXPORT int ps_activate_search ( ps_decoder_t ps,
const char *  name 
)

Actives search with the provided name.

Parameters
nameName of search module to activate. This must have been previously added by either ps_add_fsg(), ps_add_lm(), or ps_add_kws(). If NULL, it will re-activate the default search, which is useful when running second-pass alignment, for instance.
Returns
0 on success, -1 on failure

◆ ps_add_allphone()

POCKETSPHINX_EXPORT int ps_add_allphone ( ps_decoder_t ps,
const char *  name,
ngram_model_t lm 
)

Adds new search based on phone N-gram language model.

Associates N-gram search with the provided name. The search can be activated using ps_activate_search().

See also
ps_activate_search.

◆ ps_add_allphone_file()

POCKETSPHINX_EXPORT int ps_add_allphone_file ( ps_decoder_t ps,
const char *  name,
const char *  path 
)

Adds new search based on phone N-gram language model.

Convenient method to load N-gram model and create a search.

See also
ps_add_allphone

◆ ps_add_fsg()

POCKETSPHINX_EXPORT int ps_add_fsg ( ps_decoder_t ps,
const char *  name,
fsg_model_t fsg 
)

Adds new search based on finite state grammar.

Associates FSG search with the provided name. The search can be activated using ps_activate_search().

See also
ps_activate_search

◆ ps_add_jsgf_file()

POCKETSPHINX_EXPORT int ps_add_jsgf_file ( ps_decoder_t ps,
const char *  name,
const char *  path 
)

Adds new search using JSGF model.

Convenient method to load JSGF model and create a search.

See also
ps_add_fsg

◆ ps_add_jsgf_string()

POCKETSPHINX_EXPORT int ps_add_jsgf_string ( ps_decoder_t ps,
const char *  name,
const char *  jsgf_string 
)

Adds new search using JSGF model.

Convenience method to parse JSGF model from string and create a search.

See also
ps_add_fsg

◆ ps_add_keyphrase()

POCKETSPHINX_EXPORT int ps_add_keyphrase ( ps_decoder_t ps,
const char *  name,
const char *  keyphrase 
)

Adds new keyphrase to spot

Associates KWS search with the provided name. The search can be activated using ps_activate_search().

See also
ps_activate_search

◆ ps_add_kws()

POCKETSPHINX_EXPORT int ps_add_kws ( ps_decoder_t ps,
const char *  name,
const char *  keyfile 
)

Adds keyphrases from a file to spotting

Associates KWS search with the provided name. The search can be activated using ps_activate_search().

See also
ps_activate_search

◆ ps_add_lm()

POCKETSPHINX_EXPORT int ps_add_lm ( ps_decoder_t ps,
const char *  name,
ngram_model_t lm 
)

Adds new search based on N-gram language model.

Associates N-gram search with the provided name. The search can be activated using ps_activate_search().

See also
ps_activate_search.

◆ ps_add_lm_file()

POCKETSPHINX_EXPORT int ps_add_lm_file ( ps_decoder_t ps,
const char *  name,
const char *  path 
)

Adds new search based on N-gram language model.

Convenient method to load N-gram model and create a search.

See also
ps_add_lm

◆ ps_current_search()

const POCKETSPHINX_EXPORT char* ps_current_search ( ps_decoder_t ps)

Returns name of current search in decoder

See also
ps_activate_search

◆ ps_get_alignment()

POCKETSPHINX_EXPORT ps_alignment_t* ps_get_alignment ( ps_decoder_t ps)

Get the alignment associated with the current search module.

As noted above, if decoding has not been run, this will contain invalid durations, but that may still be useful if you just want to know the state sequence.

Returns
Current alignment, or NULL if none. This pointer is owned by the decoder, so you must call ps_alignment_retain() on it if you wish to keep it outside the lifetime of the decoder.

◆ ps_get_fsg()

POCKETSPHINX_EXPORT fsg_model_t* ps_get_fsg ( ps_decoder_t ps,
const char *  name 
)

Get the finite-state grammar set object associated with a search.

  • name Name of FSG search, or NULL for current search.
    Returns
    The current FSG set object for this decoder, or NULL if name does not correspond to an FSG search.

◆ ps_get_kws()

const POCKETSPHINX_EXPORT char* ps_get_kws ( ps_decoder_t ps,
const char *  name 
)

Get the keyphrase associated with a KWS search

  • name Name of KWS search, or NULL for current search.
    Returns
    The current keyphrase to spot, or NULL if name does not correspond to a KWS search

◆ ps_get_lm()

POCKETSPHINX_EXPORT ngram_model_t* ps_get_lm ( ps_decoder_t ps,
const char *  name 
)

Get the language model or lmset object associated with a search.

  • name Name of language model search, or NULL for current search.
    Returns
    The language model (possibly set of language models) object for this decoder. The decoder retains ownership of this pointer, so you should not attempt to free it manually. Use ngram_model_retain() if you wish to reuse it elsewhere.

◆ ps_remove_search()

POCKETSPHINX_EXPORT int ps_remove_search ( ps_decoder_t ps,
const char *  name 
)

Removes a search module and releases its resources.

Removes a search module previously added with using ps_add_fsg(), ps_add_lm(), ps_add_kws(), etc.

See also
ps_add_fsg
ps_add_lm
ps_add_kws

◆ ps_search_iter()

POCKETSPHINX_EXPORT ps_search_iter_t* ps_search_iter ( ps_decoder_t ps)

Returns iterator over current searches

See also
ps_activate_search

◆ ps_search_iter_free()

POCKETSPHINX_EXPORT void ps_search_iter_free ( ps_search_iter_t itor)

Delete an unfinished search iterator

See also
ps_activate_search

◆ ps_search_iter_next()

POCKETSPHINX_EXPORT ps_search_iter_t* ps_search_iter_next ( ps_search_iter_t itor)

Updates search iterator to point to the next position.

This function automatically frees the iterator object upon reaching the final entry.

See also
ps_activate_search

◆ ps_search_iter_val()

const POCKETSPHINX_EXPORT char * ps_search_iter_val ( ps_search_iter_t itor)

Retrieves the name of the search the iterator points to.

See also
ps_activate_search

Updates search iterator to point to the next position.

This function automatically frees the iterator object upon reaching the final entry.

See also
ps_activate_search

◆ ps_set_align_text()

POCKETSPHINX_EXPORT int ps_set_align_text ( ps_decoder_t ps,
const char *  words 
)

Set up decoder to force-align a word sequence.

Unlike the ps_add_* functions, this activates the search module immediately, since force-alignment is nearly always a single shot. Currently "under the hood" this is an FSG search but you shouldn't depend on that.

Decoding proceeds as normal, though only this word sequence will be recognized, with silences and alternate pronunciations inserted. Word alignments are available with ps_seg_iter(). To obtain phoneme or state segmentations, you must subsequently call ps_set_alignment() and re-run decoding. It's tough son, but it's life.

Parameters
psDecoder
wordsString containing whitespace-separated words for alignment. These words are assumed to exist in the current dictionary.

◆ ps_set_alignment()

POCKETSPHINX_EXPORT int ps_set_alignment ( ps_decoder_t ps,
ps_alignment_t al 
)

Set up decoder to run phone and state-level alignment.

Unlike the ps_add_* functions, this activates the search module immediately, since force-alignment is nearly always a single shot.

To align, run or re-run decoding as usual, then call ps_get_alignment() to get the resulting alignment. Note that if you call this function before rerunning decoding, you can obtain the phone and state sequence, but the durations will be invalid (phones and states will inherit the parent word's duration).

Parameters
psDecoder object.
alUsually NULL, which means to construct an alignment from the current search hypothesis (this does not work with allphone or keyword spotting). You can also pass a ps_alignment_t here if you have one. The search will retain but not copy it, so after running decoding it will be updated with new durations. You can set starts and durations for words or phones (not states) to constrain the alignment.
Returns
0 for success, -1 for error (if there is no search hypothesis, or it cannot be aligned due to missing word IDs)