src/libpocketsphinx/dict.h

   1 /* -*- c-basic-offset: 4; indent-tabs-mode: nil -*- */
   2 /* ====================================================================
   3  * Copyright (c) 1999-2004 Carnegie Mellon University.  All rights
   4  * reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  *
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice, this list of conditions and the following disclaimer.
  12  *
  13  * 2. Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in
  15  *    the documentation and/or other materials provided with the
  16  *    distribution.
  17  *
  18  * This work was supported in part by funding from the Defense Advanced
  19  * Research Projects Agency and the National Science Foundation of the
  20  * United States of America, and the CMU Sphinx Speech Consortium.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND
  23  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  24  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  25  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY
  26  * NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  *
  34  * ====================================================================
  35  *
  36  */
  37
  38 #ifndef _S3_DICT_H_
  39 #define _S3_DICT_H_
  40
  41 /** \file dict.h
  42  * \brief Operations on dictionary.
  43  */
  44
  45 /* SphinxBase headers. */
  46 #include <sphinxbase/hash_table.h>
  47
  48 /* Local headers. */
  49 #include "s3types.h"
  50 #include "bin_mdef.h"
  51 #include "pocketsphinx_export.h"
  52
  53 #define S3DICT_INC_SZ 4096
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58 #if 0
  59 } /* Fool Emacs into not indenting things. */
  60 #endif
  61
  62 /**
  63     \struct dictword_t
  64     \brief a structure for one dictionary word.
  65 */
  66 typedef struct {
  67     char *word;         /**< Ascii word string */
  68     s3cipid_t *ciphone; /**< Pronunciation */
  69     int32 pronlen;      /**< Pronunciation length */
  70     s3wid_t alt;        /**< Next alternative pronunciation id, NOT_S3WID if none */
  71     s3wid_t basewid;    /**< Base pronunciation id */
  72 } dictword_t;
  73
  74 /**
  75     \struct dict_t
  76     \brief a structure for a dictionary.
  77 */
  78
  79 typedef struct {
  80     int refcnt;
  81     bin_mdef_t *mdef;   /**< Model definition used for phone IDs; NULL if none used */
  82     dictword_t *word;   /**< Array of entries in dictionary */
  83     hash_table_t *ht;   /**< Hash table for mapping word strings to word ids */
  84     int32 max_words;    /**< #Entries allocated in dict, including empty slots */
  85     int32 n_word;       /**< #Occupied entries in dict; ie, excluding empty slots */
  86     int32 filler_start; /**< First filler word id (read from filler dict) */
  87     int32 filler_end;   /**< Last filler word id (read from filler dict) */
  88     s3wid_t startwid;   /**< FOR INTERNAL-USE ONLY */
  89     s3wid_t finishwid;  /**< FOR INTERNAL-USE ONLY */
  90     s3wid_t silwid;     /**< FOR INTERNAL-USE ONLY */
  91     int nocase;
  92 } dict_t;
  93
  94
  95 /**
  96  * Initialize a new dictionary.
  97  *
  98  * If config and mdef are supplied, then the dictionary will be read
  99  * from the files specified by the -dict and -fdict options in config,
 100  * with case sensitivity determined by the -dictcase option.
 101  *
 102  * Otherwise an empty case-sensitive dictionary will be created.
 103  *
 104  * Return ptr to dict_t if successful, NULL otherwise.
 105  */
 106 dict_t *dict_init(cmd_ln_t *config, /**< Configuration (-dict, -fdict, -dictcase) or NULL */
 107                   bin_mdef_t *mdef  /**< For looking up CI phone IDs (or NULL) */
 108     );
 109
 110 /**
 111  * Write dictionary to a file.
 112  */
 113 int dict_write(dict_t *dict, char const *filename, char const *format);
 114
 115 /** Return word id for given word string if present.  Otherwise return BAD_S3WID */
 116 POCKETSPHINX_EXPORT
 117 s3wid_t dict_wordid(dict_t *d, const char *word);
 118
 119 /**
 120  * Return 1 if w is a filler word, 0 if not.  A filler word is one that was read in from the
 121  * filler dictionary; however, sentence START and FINISH words are not filler words.
 122  */
 123 int dict_filler_word(dict_t *d,  /**< The dictionary structure */
 124                      s3wid_t w     /**< The word ID */
 125     );
 126
 127 /**
 128  * Test if w is a "real" word, i.e. neither a filler word nor START/FINISH.
 129  */
 130 POCKETSPHINX_EXPORT
 131 int dict_real_word(dict_t *d,  /**< The dictionary structure */
 132                    s3wid_t w     /**< The word ID */
 133     );
 134
 135 /**
 136  * Add a word with the given ciphone pronunciation list to the dictionary.
 137  * Return value: Result word id if successful, BAD_S3WID otherwise
 138  */
 139 s3wid_t dict_add_word(dict_t *d,          /**< The dictionary structure. */
 140                       char const *word,   /**< The word. */
 141                       s3cipid_t const *p, /**< The pronunciation. */
 142                       int32 np            /**< Number of phones. */
 143     );
 144
 145 /**
 146  * Return value: CI phone string for the given word, phone position.
 147  */
 148 const char *dict_ciphone_str(dict_t *d, /**< In: Dictionary to look up */
 149                              s3wid_t wid,       /**< In: Component word being looked up */
 150                              int32 pos          /**< In: Pronunciation phone position */
 151     );
 152
 153 /** Packaged macro access to dictionary members */
 154 #define dict_size(d)            ((d)->n_word)
 155 #define dict_num_fillers(d)   (dict_filler_end(d) - dict_filler_start(d))
 156 /**
 157  * Number of "real words" in the dictionary.
 158  *
 159  * This is the number of words that are not fillers, <s>, or </s>.
 160  */
 161 #define dict_num_real_words(d)                                          \
 162     (dict_size(d) - (dict_filler_end(d) - dict_filler_start(d)) - 2)
 163 #define dict_basewid(d,w)       ((d)->word[w].basewid)
 164 #define dict_wordstr(d,w)       ((w) < 0 ? NULL : (d)->word[w].word)
 165 #define dict_basestr(d,w)       ((d)->word[dict_basewid(d,w)].word)
 166 #define dict_nextalt(d,w)       ((d)->word[w].alt)
 167 #define dict_pronlen(d,w)       ((d)->word[w].pronlen)
 168 #define dict_pron(d,w,p)        ((d)->word[w].ciphone[p]) /**< The CI phones of the word w at position p */
 169 #define dict_filler_start(d)    ((d)->filler_start)
 170 #define dict_filler_end(d)      ((d)->filler_end)
 171 #define dict_startwid(d)        ((d)->startwid)
 172 #define dict_finishwid(d)       ((d)->finishwid)
 173 #define dict_silwid(d)          ((d)->silwid)
 174 #define dict_is_single_phone(d,w)       ((d)->word[w].pronlen == 1)
 175 #define dict_first_phone(d,w)   ((d)->word[w].ciphone[0])
 176 #define dict_second_phone(d,w)  ((d)->word[w].ciphone[1])
 177 #define dict_second_last_phone(d,w)     ((d)->word[w].ciphone[(d)->word[w].pronlen - 2])
 178 #define dict_last_phone(d,w)    ((d)->word[w].ciphone[(d)->word[w].pronlen - 1])
 179
 180 /* Hard-coded special words */
 181 #define S3_START_WORD           "<s>"
 182 #define S3_FINISH_WORD          "</s>"
 183 #define S3_SILENCE_WORD         "<sil>"
 184 #define S3_UNKNOWN_WORD         "<UNK>"
 185
 186 /**
 187  * If the given word contains a trailing "(....)" (i.e., a Sphinx-II style alternative
 188  * pronunciation specification), strip that trailing portion from it.  Note that the given
 189  * string is modified.
 190  * Return value: If string was modified, the character position at which the original string
 191  * was truncated; otherwise -1.
 192  */
 193 int32 dict_word2basestr(char *word);
 194
 195 /**
 196  * Retain a pointer to an dict_t.
 197  */
 198 dict_t *dict_retain(dict_t *d);
 199
 200 /**
 201  * Release a pointer to a dictionary.
 202  */
 203 int dict_free(dict_t *d);
 204
 205 /** Report a dictionary structure */
 206 void dict_report(dict_t *d /**< A dictionary structure */
 207     );
 208
 209 #if 0
 210 { /* Stop indent from complaining */
 211 #endif
 212 #ifdef __cplusplus
 213 }
 214 #endif
 215
 216 #endif