ps_search.h File Reference

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

`#include <sphinxbase/fsg_model.h>`
`#include <sphinxbase/ngram_model.h>`

Go to the source code of this file.

## Typedefs

typedef struct ps_search_iter_s | ps_search_iter_t
| PocketSphinx search iterator.

## Functions

POCKETSPHINX_EXPORT int | ps_set_search (ps_decoder_t *ps, const char *name)
| Actives search with the provided name. More...
POCKETSPHINX_EXPORT const char * | ps_get_search (ps_decoder_t *ps)
| Returns name of curent search in decoder. More...
POCKETSPHINX_EXPORT int | ps_unset_search (ps_decoder_t *ps, const char *name)
| Unsets the search and releases related resources. More...
POCKETSPHINX_EXPORT ps_search_iter_t * | ps_search_iter (ps_decoder_t *ps)
| Returns iterator over current searches. More...
POCKETSPHINX_EXPORT ps_search_iter_t * | ps_search_iter_next (ps_search_iter_t *itor)
| Updates search iterator to point to the next position. More...
POCKETSPHINX_EXPORT const char * | ps_search_iter_val (ps_search_iter_t *itor)
| Retrieves the name of the search the iterator points to. More...
POCKETSPHINX_EXPORT void | ps_search_iter_free (ps_search_iter_t *itor)
| Delete an unfinished search iterator. More...
POCKETSPHINX_EXPORT ngram_model_t * | ps_get_lm (ps_decoder_t *ps, const char *name)
| Get the language model set object for this decoder. More...
POCKETSPHINX_EXPORT int | ps_set_lm (ps_decoder_t *ps, const char *name, ngram_model_t *lm)
| Adds new search based on N-gram language model. More...
POCKETSPHINX_EXPORT int | ps_set_lm_file (ps_decoder_t *ps, const char *name, const char *path)
| Adds new search based on N-gram language model. More...
POCKETSPHINX_EXPORT fsg_model_t * | ps_get_fsg (ps_decoder_t *ps, const char *name)
| Get the finite-state grammar set object for this decoder. More...
POCKETSPHINX_EXPORT int | ps_set_fsg (ps_decoder_t *ps, const char *name, fsg_model_t *fsg)
| Adds new search based on finite state grammar. More...
POCKETSPHINX_EXPORT int | ps_set_jsgf_file (ps_decoder_t *ps, const char *name, const char *path)
| Adds new search using JSGF model. More...
POCKETSPHINX_EXPORT int | ps_set_jsgf_string (ps_decoder_t *ps, const char *name, const char *jsgf_string)
| Adds new search using JSGF model. More...
POCKETSPHINX_EXPORT const char * | ps_get_kws (ps_decoder_t *ps, const char *name)
| Get the current Key phrase to spot. More...
POCKETSPHINX_EXPORT int | ps_set_kws (ps_decoder_t *ps, const char *name, const char *keyfile)
| Adds keyphrases from a file to spotting. More...
POCKETSPHINX_EXPORT int | ps_set_keyphrase (ps_decoder_t *ps, const char *name, const char *keyphrase)
| Adds new keyphrase to spot. More...
POCKETSPHINX_EXPORT int | ps_set_allphone (ps_decoder_t *ps, const char *name, ngram_model_t *lm)
| Adds new search based on phone N-gram language model. More...
POCKETSPHINX_EXPORT int | ps_set_allphone_file (ps_decoder_t *ps, const char *name, const char *path)
| Adds new search based on phone N-gram language model. More...

## Detailed Description

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

There are different possible search modes:

- keyphrase - efficiently looks for keyphrase and ignores other speech. allows to configure detection threshold.
- grammar - recognizes speech according to JSGF grammar. Unlike keyphrase grammar search doesn't ignore words which are not in grammar but tries to recognize them.
- ngram/lm - recognizes natural speech with a language model.
- allphone - recognizes phonemes with a phonetic language model.

Each search has a name and can be referenced by a name, names are application-specific. The function ps_set_search allows to activate the search previously added by a name. Only single search can be activated at time.

To add the search 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 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.

Definition in file ps_search.h.

## Function Documentation

## 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 for this decoder.

If FSG decoding is not enabled, this returns NULL. Call ps_set_fsgset() to enable it.

Returns
  The current FSG set object for this decoder, or NULL if none is available.

Definition at line 552 of file pocketsphinx.c.

## ps_get_kws()

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

Get the current Key phrase to spot.

If KWS is not enabled, this returns NULL. Call ps_update_kws() to enable it.

Returns
  The current keyphrase to spot

Definition at line 561 of file pocketsphinx.c.

## ps_get_lm()

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

Get the language model set object for this decoder.

If N-Gram decoding is not enabled, this will return NULL. You will need to enable it using ps_set_lmset().

Returns
  The language model set 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.

Definition at line 543 of file pocketsphinx.c.

## ps_get_search()

POCKETSPHINX_EXPORT const char* ps_get_search | ( | ps_decoder_t * | ps | ) |

Returns name of curent search in decoder.

See also
  ps_set_search

Definition at line 492 of file pocketsphinx.c.

References ps_decoder_s::search, and ps_decoder_s::searches.

## ps_search_iter()

POCKETSPHINX_EXPORT ps_search_iter_t* ps_search_iter | ( | ps_decoder_t * | ps | ) |

Returns iterator over current searches.

See also
  ps_set_search

Definition at line 519 of file pocketsphinx.c.

References ps_decoder_s::searches.

## ps_search_iter_free()

POCKETSPHINX_EXPORT void ps_search_iter_free | ( | ps_search_iter_t * | itor | ) |

Delete an unfinished search iterator.

See also
  ps_set_search

Definition at line 537 of file pocketsphinx.c.

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

Definition at line 525 of file pocketsphinx.c.

## ps_search_iter_val()

POCKETSPHINX_EXPORT const char * ps_search_iter_val | ( | ps_search_iter_t * | itor | ) |

Retrieves the name of the search the iterator points to.

Updates search iterator to point to the next position.

See also
  ps_set_search

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

See also
  ps_set_search

Definition at line 531 of file pocketsphinx.c.

## ps_set_allphone()

POCKETSPHINX_EXPORT int ps_set_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_set_search().

See also
  ps_set_search.

Definition at line 609 of file pocketsphinx.c.

References ps_decoder_s::acmod, ps_decoder_s::config, ps_decoder_s::d2p, and ps_decoder_s::dict.

Referenced by ps_set_allphone_file().

## ps_set_allphone_file()

POCKETSPHINX_EXPORT int ps_set_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_set_allphone

Definition at line 617 of file pocketsphinx.c.

References ps_decoder_s::config, ps_decoder_s::lmath, and ps_set_allphone().

## ps_set_fsg()

POCKETSPHINX_EXPORT int ps_set_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_set_search().

See also
  ps_set_search

Definition at line 648 of file pocketsphinx.c.

References ps_decoder_s::acmod, ps_decoder_s::config, ps_decoder_s::d2p, and ps_decoder_s::dict.

Referenced by ps_set_jsgf_file(), and ps_set_jsgf_string().

## ps_set_jsgf_file()

POCKETSPHINX_EXPORT int ps_set_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_set_fsg

Definition at line 656 of file pocketsphinx.c.

References ps_decoder_s::config, ps_decoder_s::lmath, and ps_set_fsg().

## ps_set_jsgf_string()

POCKETSPHINX_EXPORT int ps_set_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_set_fsg

Definition at line 695 of file pocketsphinx.c.

References ps_decoder_s::config, ps_decoder_s::lmath, and ps_set_fsg().

## ps_set_keyphrase()

POCKETSPHINX_EXPORT int ps_set_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_set_search().

See also
  ps_set_search

Definition at line 640 of file pocketsphinx.c.

References ps_decoder_s::acmod, ps_decoder_s::config, ps_decoder_s::d2p, and ps_decoder_s::dict.

## ps_set_kws()

POCKETSPHINX_EXPORT int ps_set_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_set_search().

See also
  ps_set_search

Definition at line 632 of file pocketsphinx.c.

References ps_decoder_s::acmod, ps_decoder_s::config, ps_decoder_s::d2p, and ps_decoder_s::dict.

## ps_set_lm()

POCKETSPHINX_EXPORT int ps_set_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_set_search().

See also
  ps_set_search.

Definition at line 586 of file pocketsphinx.c.

References ps_decoder_s::acmod, ps_decoder_s::config, ps_decoder_s::d2p, ps_decoder_s::dict, and ngram_search_init().

Referenced by ps_set_lm_file().

## ps_set_lm_file()

POCKETSPHINX_EXPORT int ps_set_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_set_lm

Definition at line 594 of file pocketsphinx.c.

References ps_decoder_s::config, ps_decoder_s::lmath, and ps_set_lm().

## ps_set_search()

POCKETSPHINX_EXPORT int ps_set_search | ( | ps_decoder_t * | ps,
|  | const char * | name
| ) |  |

Actives search with the provided name.

Activates search with the provided name. The search must be added before using either ps_set_fsg(), ps_set_lm() or ps_set_kws().

Returns
  0 on success, -1 on failure

Definition at line 467 of file pocketsphinx.c.

References ps_decoder_s::acmod, ACMOD_ENDED, ACMOD_IDLE, ps_decoder_s::search, and acmod_s::state.

## ps_unset_search()

POCKETSPHINX_EXPORT int ps_unset_search | ( | ps_decoder_t * | ps,
|  | const char * | name
| ) |  |

Unsets the search and releases related resources.

Unsets the search previously added with using either ps_set_fsg(), ps_set_lm() or ps_set_kws().

See also
  ps_set_fsg
  ps_set_lm
  ps_set_kws

Definition at line 507 of file pocketsphinx.c.

References ps_decoder_s::search, and ps_decoder_s::searches.