| 1 |
/* -*- c-basic-offset:4; indent-tabs-mode: nil -*- */ |
| 2 |
/* ==================================================================== |
| 3 |
* Copyright (c) 1999-2008 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 |
* |
| 19 |
* THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND |
| 20 |
* ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, |
| 21 |
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
| 22 |
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY |
| 23 |
* NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 24 |
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 25 |
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 26 |
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 27 |
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 28 |
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| 29 |
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 30 |
* |
| 31 |
* ==================================================================== |
| 32 |
* |
| 33 |
*/ |
| 34 |
/** |
| 35 |
* @file pocketsphinx.h Main header file for the PocketSphinx decoder. |
| 36 |
* |
| 37 |
* This is the only header file you should need to include in order to |
| 38 |
* write code using PocketSphinx. The documentation for its various |
| 39 |
* functions and structures is actually located on the pages for those |
| 40 |
* structures, and because Doxygen does not seem smart enough to put |
| 41 |
* links in the "Typedefs" list above, here they are for your |
| 42 |
* convenience: |
| 43 |
* |
| 44 |
* - \ref ps_config_t |
| 45 |
* - \ref ps_arg_t |
| 46 |
* - \ref ps_decoder_t |
| 47 |
* - \ref ps_nbest_t |
| 48 |
* - \ref ps_seg_t |
| 49 |
* |
| 50 |
* There are also a few other structures you should be aware of, which |
| 51 |
* can be useful in writing speech applications: |
| 52 |
* |
| 53 |
* - \ref ps_endpointer_t |
| 54 |
* - \ref ps_vad_t |
| 55 |
* - \ref jsgf_t |
| 56 |
* - \ref ngram_model_t |
| 57 |
* |
| 58 |
* Finally, to learn about switching language models and grammars, see |
| 59 |
* <pocketsphinx/search.h> |
| 60 |
*/ |
| 61 |
|
| 62 |
#ifndef __POCKETSPHINX_H__ |
| 63 |
#define __POCKETSPHINX_H__ |
| 64 |
|
| 65 |
/* System headers */ |
| 66 |
#include <stdio.h> |
| 67 |
|
| 68 |
/* PocketSphinx utility headers */ |
| 69 |
#include <pocketsphinx/sphinx_config.h> |
| 70 |
#include <pocketsphinx/prim_type.h> |
| 71 |
#include <pocketsphinx/logmath.h> |
| 72 |
#include <pocketsphinx/err.h> |
| 73 |
|
| 74 |
/* PocketSphinx API headers */ |
| 75 |
#include <pocketsphinx/vad.h> |
| 76 |
#include <pocketsphinx/endpointer.h> |
| 77 |
#include <pocketsphinx/model.h> |
| 78 |
#include <pocketsphinx/search.h> |
| 79 |
#include <pocketsphinx/export.h> |
| 80 |
#include <pocketsphinx/lattice.h> |
| 81 |
#include <pocketsphinx/alignment.h> |
| 82 |
#include <pocketsphinx/mllr.h> |
| 83 |
|
| 84 |
/* Namum manglium ii domum */ |
| 85 |
#ifdef __cplusplus |
| 86 |
extern "C" { |
| 87 |
#endif |
| 88 |
#if 0 |
| 89 |
} |
| 90 |
#endif |
| 91 |
|
| 92 |
/* Transparent structures */ |
| 93 |
/** |
| 94 |
* @enum ps_type_e |
| 95 |
* @brief Types of configuration parameters. |
| 96 |
*/ |
| 97 |
typedef enum ps_type_e { |
| 98 |
ARG_REQUIRED = (1<<0), /*<< Bit indicating required argument. */ |
| 99 |
ARG_INTEGER = (1<<1), /*<< Integer up to 64 bits. */ |
| 100 |
ARG_FLOATING = (1<<2), /*<< Double-precision floating point. */ |
| 101 |
ARG_STRING = (1<<3), /*<< String. */ |
| 102 |
ARG_BOOLEAN = (1<<4), /*<< Boolean (true/false). */ |
| 103 |
REQARG_INTEGER = (ARG_INTEGER | ARG_REQUIRED), |
| 104 |
REQARG_FLOATING = (ARG_FLOATING | ARG_REQUIRED), |
| 105 |
REQARG_STRING = (ARG_STRING | ARG_REQUIRED), |
| 106 |
REQARG_BOOLEAN = (ARG_BOOLEAN | ARG_REQUIRED) |
| 107 |
} ps_type_t; |
| 108 |
/** |
| 109 |
* @typedef ps_type_t |
| 110 |
* @brief Types of configuration parameters. |
| 111 |
*/ |
| 112 |
|
| 113 |
/** |
| 114 |
* @struct ps_arg_t |
| 115 |
* @brief Definition of a configuration parameter. |
| 116 |
*/ |
| 117 |
typedef struct ps_arg_s { |
| 118 |
char const *name; /**< Name of the command line switch */ |
| 119 |
int type; /**< Type of the argument in question */ |
| 120 |
char const *deflt; /**< Default value (as a character string), or NULL if none */ |
| 121 |
char const *doc; /**< Documentation/description string */ |
| 122 |
} ps_arg_t; |
| 123 |
|
| 124 |
/* Opaque structures */ |
| 125 |
|
| 126 |
/** |
| 127 |
* @struct ps_config_t |
| 128 |
* @brief configuration object. |
| 129 |
*/ |
| 130 |
typedef struct cmd_ln_s ps_config_t; |
| 131 |
|
| 132 |
/** |
| 133 |
* @struct ps_decoder_t |
| 134 |
* @brief Speech recognizer object. |
| 135 |
*/ |
| 136 |
typedef struct ps_decoder_s ps_decoder_t; |
| 137 |
|
| 138 |
/** |
| 139 |
* @struct ps_nbest_t |
| 140 |
* @brief N-best hypothesis iterator object. |
| 141 |
*/ |
| 142 |
typedef struct ps_astar_s ps_nbest_t; |
| 143 |
|
| 144 |
/** |
| 145 |
* @struct ps_seg_t |
| 146 |
* @brief Segmentation iterator object. |
| 147 |
*/ |
| 148 |
typedef struct ps_seg_s ps_seg_t; |
| 149 |
|
| 150 |
/** |
| 151 |
* Create a configuration with default values. |
| 152 |
* |
| 153 |
* @memberof ps_config_t |
| 154 |
* @param defn Array of ps_arg_t defining and describing parameters, |
| 155 |
* terminated by an ps_arg_t with `name == NULL`. You should usually |
| 156 |
* just pass NULL here, which will result in the standard set of |
| 157 |
* parameters being used. |
| 158 |
* @return Newly created configuration or NULL on failure (should not |
| 159 |
* happen, but check it anyway). |
| 160 |
*/ |
| 161 |
POCKETSPHINX_EXPORT |
| 162 |
ps_config_t *ps_config_init(const ps_arg_t *defn); |
| 163 |
|
| 164 |
/** |
| 165 |
* Retain a pointer to a configuration object. |
| 166 |
* @memberof ps_config_t |
| 167 |
*/ |
| 168 |
POCKETSPHINX_EXPORT |
| 169 |
ps_config_t *ps_config_retain(ps_config_t *config); |
| 170 |
|
| 171 |
/** |
| 172 |
* Release a configuration object. |
| 173 |
* @memberof ps_config_t |
| 174 |
*/ |
| 175 |
POCKETSPHINX_EXPORT |
| 176 |
int ps_config_free(ps_config_t *config); |
| 177 |
|
| 178 |
/** |
| 179 |
* Validate configuration. |
| 180 |
* |
| 181 |
* Currently this just checks that you haven't specified multiple |
| 182 |
* types of grammars or language models at the same time. |
| 183 |
* |
| 184 |
* @memberof ps_config_t |
| 185 |
* @return 0 for success, <0 for failure. |
| 186 |
*/ |
| 187 |
int ps_config_validate(ps_config_t *config); |
| 188 |
|
| 189 |
/** |
| 190 |
* Create or update a configuration by parsing slightly extended JSON. |
| 191 |
* |
| 192 |
* This function parses a JSON object in non-strict mode to produce a |
| 193 |
* ps_config_t. Configuration parameters are given *without* a |
| 194 |
* leading dash, and do not need to be quoted, nor does the object |
| 195 |
* need to be enclosed in curly braces, nor are commas necessary |
| 196 |
* between key/value pairs. Basically, it's degenerate YAML. So, for |
| 197 |
* example, this is accepted: |
| 198 |
* |
| 199 |
* hmm: fr-fr |
| 200 |
* samprate: 8000 |
| 201 |
* keyphrase: "hello world" |
| 202 |
* |
| 203 |
* Of course, valid JSON is also accepted, but who wants to use that. |
| 204 |
* |
| 205 |
* Well, mostly. Unicode escape sequences (e.g. `"\u0020"`) are *not* |
| 206 |
* supported at the moment, so please don't use them. |
| 207 |
* |
| 208 |
* @memberof ps_config_t |
| 209 |
* @arg config Previously existing ps_config_t to update, or NULL to |
| 210 |
* create a new one. |
| 211 |
* @arg json JSON serialized object as null-terminated UTF-8, |
| 212 |
* containing configuration parameters. |
| 213 |
* @return Newly created configuration or NULL on failure (such as |
| 214 |
* invalid or missing parameters). |
| 215 |
*/ |
| 216 |
POCKETSPHINX_EXPORT |
| 217 |
ps_config_t *ps_config_parse_json(ps_config_t *config, const char *json); |
| 218 |
|
| 219 |
/** |
| 220 |
* Construct JSON from a configuration object. |
| 221 |
* |
| 222 |
* Unlike ps_config_parse_json(), this actually produces valid JSON ;-) |
| 223 |
* |
| 224 |
* @memberof ps_config_t |
| 225 |
* @arg config Configuration object |
| 226 |
* @return Newly created null-terminated JSON string. The ps_config_t |
| 227 |
* retains ownership of this pointer, which is only valid until the |
| 228 |
* next call to ps_config_serialize_json(). You must copy it if you |
| 229 |
* wish to retain it. |
| 230 |
*/ |
| 231 |
POCKETSPHINX_EXPORT |
| 232 |
const char *ps_config_serialize_json(ps_config_t *config); |
| 233 |
|
| 234 |
/** |
| 235 |
* Access the type of a configuration parameter. |
| 236 |
* |
| 237 |
* @memberof ps_config_t |
| 238 |
* @param config Configuration object. |
| 239 |
* @param name Name of the parameter to retrieve. |
| 240 |
* @return the type of the parameter (as a combination of the ARG_* |
| 241 |
* bits), or 0 if no such parameter exists. |
| 242 |
*/ |
| 243 |
POCKETSPHINX_EXPORT |
| 244 |
ps_type_t ps_config_typeof(ps_config_t *config, char const *name); |
| 245 |
|
| 246 |
/** |
| 247 |
* Access the value of a configuration parameter. |
| 248 |
* |
| 249 |
* To actually do something with the value, you will need to know its |
| 250 |
* type, which can be obtained with ps_config_typeof(). This function |
| 251 |
* is thus mainly useful for dynamic language bindings, and you should |
| 252 |
* use ps_config_int(), ps_config_float(), or ps_config_str() instead. |
| 253 |
* |
| 254 |
* @memberof ps_config_t |
| 255 |
* @param config Configuration object. |
| 256 |
* @param name Name of the parameter to retrieve. |
| 257 |
* @return Pointer to the parameter's value, or NULL if the parameter |
| 258 |
* does not exist. Note that a string parameter can also have NULL as |
| 259 |
* a value, in which case the `ptr` field in the return value is NULL. |
| 260 |
* This pointer (and any pointers inside it) is owned by the ps_config_t. |
| 261 |
*/ |
| 262 |
POCKETSPHINX_EXPORT |
| 263 |
const anytype_t *ps_config_get(ps_config_t *config, const char *name); |
| 264 |
|
| 265 |
/** |
| 266 |
* Set or unset the value of a configuration parameter. |
| 267 |
* |
| 268 |
* This will coerce the value to the proper type, so you can, for |
| 269 |
* example, pass it a string with ARG_STRING as the type when adding |
| 270 |
* options from the command-line. Note that the return pointer will |
| 271 |
* *not* be the same as the one passed in the value. |
| 272 |
* |
| 273 |
* @memberof ps_config_t |
| 274 |
* @param config Configuration object. |
| 275 |
* @param name Name of the parameter to set. Must exist. |
| 276 |
* @param val Pointer to the value (strings will be copied) inside an |
| 277 |
* anytype_t union. On 64-bit little-endian platforms, you *can* cast |
| 278 |
* a pointer to int, long, double, or char* here, but that doesn't |
| 279 |
* necessarily mean that you *should*. As a convenience, you can pass |
| 280 |
* NULL here to reset a parameter to its default value. |
| 281 |
* @param t Type of the value in `val`, will be coerced to the type of |
| 282 |
* the actual parameter if necessary. |
| 283 |
* @return Pointer to the parameter's value, or NULL on failure |
| 284 |
* (unknown parameter, usually). This pointer (and any pointers |
| 285 |
* inside it) is owned by the ps_config_t. |
| 286 |
*/ |
| 287 |
POCKETSPHINX_EXPORT |
| 288 |
const anytype_t *ps_config_set(ps_config_t *config, const char *name, |
| 289 |
const anytype_t *val, ps_type_t t); |
| 290 |
|
| 291 |
/** |
| 292 |
* Get an integer-valued parameter. |
| 293 |
* |
| 294 |
* If the parameter does not have an integer or boolean type, this |
| 295 |
* will print an error and return 0. So don't do that. |
| 296 |
* |
| 297 |
* @memberof ps_config_t |
| 298 |
*/ |
| 299 |
POCKETSPHINX_EXPORT |
| 300 |
long ps_config_int(ps_config_t *config, const char *name); |
| 301 |
|
| 302 |
/** |
| 303 |
* Get a boolean-valued parameter. |
| 304 |
* |
| 305 |
* If the parameter does not have an integer or boolean type, this |
| 306 |
* will print an error and return 0. The return value is either 0 or |
| 307 |
* 1 (if the parameter has an integer type, any non-zero value will |
| 308 |
* return 1). |
| 309 |
* |
| 310 |
* @memberof ps_config_t |
| 311 |
*/ |
| 312 |
POCKETSPHINX_EXPORT |
| 313 |
int ps_config_bool(ps_config_t *config, const char *name); |
| 314 |
|
| 315 |
/** |
| 316 |
* Get a floating-point parameter. |
| 317 |
* |
| 318 |
* If the parameter does not have a floating-point type, this will |
| 319 |
* print an error and return 0. |
| 320 |
* |
| 321 |
* @memberof ps_config_t |
| 322 |
*/ |
| 323 |
POCKETSPHINX_EXPORT |
| 324 |
double ps_config_float(ps_config_t *config, const char *name); |
| 325 |
|
| 326 |
/** |
| 327 |
* Get a string parameter. |
| 328 |
* |
| 329 |
* If the parameter does not have a string type, this will print an |
| 330 |
* error and return NULL. Notably, it will *NOT* format an integer or |
| 331 |
* float for you, because that would involve allocating memory. So |
| 332 |
* don't do that. |
| 333 |
* |
| 334 |
* @memberof ps_config_t |
| 335 |
*/ |
| 336 |
POCKETSPHINX_EXPORT |
| 337 |
const char *ps_config_str(ps_config_t *config, const char *name); |
| 338 |
|
| 339 |
/** |
| 340 |
* Set an integer-valued parameter. |
| 341 |
* |
| 342 |
* If the parameter does not have an integer or boolean type, this |
| 343 |
* will convert `val` appropriately. |
| 344 |
* |
| 345 |
* @memberof ps_config_t |
| 346 |
*/ |
| 347 |
POCKETSPHINX_EXPORT |
| 348 |
const anytype_t *ps_config_set_int(ps_config_t *config, const char *name, long val); |
| 349 |
|
| 350 |
/** |
| 351 |
* Set a boolean-valued parameter. |
| 352 |
* |
| 353 |
* If the parameter does not have an integer or boolean type, this |
| 354 |
* will convert `val` appropriately. |
| 355 |
* |
| 356 |
* @memberof ps_config_t |
| 357 |
*/ |
| 358 |
POCKETSPHINX_EXPORT |
| 359 |
const anytype_t *ps_config_set_bool(ps_config_t *config, const char *name, int val); |
| 360 |
|
| 361 |
/** |
| 362 |
* Set a floating-point parameter. |
| 363 |
* |
| 364 |
* If the parameter does not have a floating-point type, this will |
| 365 |
* convert `val` appropriately. |
| 366 |
* |
| 367 |
* @memberof ps_config_t |
| 368 |
*/ |
| 369 |
POCKETSPHINX_EXPORT |
| 370 |
const anytype_t *ps_config_set_float(ps_config_t *config, const char *name, double val); |
| 371 |
|
| 372 |
/** |
| 373 |
* Set a string-valued parameter. |
| 374 |
* |
| 375 |
* If the parameter does not have a string type, this will convert |
| 376 |
* `val` appropriately. For boolean parameters, any string matching |
| 377 |
* `/^[yt1]/` will be true, while any string matching `/^[nf0]/` will |
| 378 |
* be false. NULL is also false. |
| 379 |
* |
| 380 |
* This function is used for configuration from JSON, you may want to |
| 381 |
* use it for your own configuration files too. |
| 382 |
* |
| 383 |
* @memberof ps_config_t |
| 384 |
*/ |
| 385 |
POCKETSPHINX_EXPORT |
| 386 |
const anytype_t *ps_config_set_str(ps_config_t *config, const char *name, const char *val); |
| 387 |
|
| 388 |
/** |
| 389 |
* Set configuration parameters (actually just sample rate) from a |
| 390 |
* sound file. |
| 391 |
* |
| 392 |
* If the file is unreadable, unsupported or incompatible with the |
| 393 |
* existing feature extraction parameters, this will print an error |
| 394 |
* message and fail (return -1). |
| 395 |
* |
| 396 |
* If it is of an unknown type, it will be treated as raw data. So |
| 397 |
* beware! Currently we only support WAV and NIST Sphere files. We |
| 398 |
* attempt to recognize Ogg, MP3 (but not really, because it is very |
| 399 |
* difficult to do reliably), and FLAC, but do not support them. For |
| 400 |
* everything else, there's SoX (tm). |
| 401 |
* |
| 402 |
* Currently, the file must be seekable, so you can't use this on |
| 403 |
* standard input, for instance. |
| 404 |
* |
| 405 |
* @memberof ps_config_t |
| 406 |
* @param config Configuration to update from file. |
| 407 |
* @param fh Previously opened file handle. |
| 408 |
* @param file Name of open file handle for logging (optional, can be NULL) |
| 409 |
*/ |
| 410 |
POCKETSPHINX_EXPORT |
| 411 |
int ps_config_soundfile(ps_config_t *config, FILE *fh, const char *file); |
| 412 |
|
| 413 |
/** |
| 414 |
* Read a WAV header and set configuration parameters. |
| 415 |
* |
| 416 |
* This works like ps_config_soundfile() but assumes that you already |
| 417 |
* know it's a WAV file. |
| 418 |
* |
| 419 |
* Unlike ps_config_soundfile(), the file does *not* have to be seekable. |
| 420 |
* |
| 421 |
* @memberof ps_config_t |
| 422 |
* @param config Configuration to update from file. |
| 423 |
* @param infh Previously opened file handle. |
| 424 |
* @param file Name of open file handle for logging (optional, can be NULL) |
| 425 |
*/ |
| 426 |
POCKETSPHINX_EXPORT |
| 427 |
int ps_config_wavfile(ps_config_t *config, FILE *infh, const char *file); |
| 428 |
|
| 429 |
/** |
| 430 |
* Read a NIST header and set configuration parameters. |
| 431 |
* |
| 432 |
* This works like ps_config_soundfile() but assumes that you already |
| 433 |
* know it's a NIST file. |
| 434 |
* |
| 435 |
* Unlike ps_config_soundfile(), the file does *not* have to be seekable. |
| 436 |
* |
| 437 |
* @memberof ps_config_t |
| 438 |
* @param config Configuration to update from file. |
| 439 |
* @param infh Previously opened file handle. |
| 440 |
* @param file Name of open file handle for logging (optional, can be NULL) |
| 441 |
*/ |
| 442 |
POCKETSPHINX_EXPORT |
| 443 |
int ps_config_nistfile(ps_config_t *config, FILE *infh, const char *file); |
| 444 |
|
| 445 |
/** |
| 446 |
* Sets default acoustic and language model if they are not set explicitly. |
| 447 |
* |
| 448 |
* This function fills in the configuration with the default acoustic |
| 449 |
* and language models and dictionary, if (and this is a badly |
| 450 |
* implemented heuristic) they do not seem to be already filled in. |
| 451 |
* It is preferable for you to call this *before* doing any other |
| 452 |
* configuration to avoid confusion. |
| 453 |
* |
| 454 |
* The default models are looked for in the directory returned by |
| 455 |
* ps_default_modeldir(), or, if the `POCKETSPHINX_PATH` environment |
| 456 |
* variable is set, this function will look there instead. |
| 457 |
* |
| 458 |
* If no global model directory was defined at compilation time (this |
| 459 |
* is useful for relocatable installs such as the Python module) and |
| 460 |
* `POCKETSPHINX_PATH` is not set, this will simply do nothing. |
| 461 |
* |
| 462 |
* @memberof ps_config_t |
| 463 |
*/ |
| 464 |
POCKETSPHINX_EXPORT |
| 465 |
void ps_default_search_args(ps_config_t *config); |
| 466 |
|
| 467 |
/** |
| 468 |
* Sets default file paths and parameters based on configuration. |
| 469 |
* |
| 470 |
* @memberof ps_config_t |
| 471 |
*/ |
| 472 |
POCKETSPHINX_EXPORT |
| 473 |
void ps_expand_model_config(ps_config_t *config); |
| 474 |
|
| 475 |
/** |
| 476 |
* Gets the system default model directory, if any exists. |
| 477 |
* |
| 478 |
* @relates ps_config_t |
| 479 |
* @return system model directory defined at compile time, or NULL if |
| 480 |
* not defined (usually in a relocatable installation such as |
| 481 |
* a Python module). |
| 482 |
*/ |
| 483 |
POCKETSPHINX_EXPORT |
| 484 |
const char *ps_default_modeldir(void); |
| 485 |
|
| 486 |
/** |
| 487 |
* Initialize the decoder from a configuration object. |
| 488 |
* |
| 489 |
* @memberof ps_config_t |
| 490 |
* @note The decoder retains ownership of the pointer |
| 491 |
* <code>config</code>, so if you are not going to use it |
| 492 |
* elsewhere, you can free it. |
| 493 |
* @param config a configuration object. If NULL, the |
| 494 |
* decoder will be allocated but not initialized. You can |
| 495 |
* proceed to initialize it with ps_reinit(). |
| 496 |
*/ |
| 497 |
POCKETSPHINX_EXPORT |
| 498 |
ps_decoder_t *ps_init(ps_config_t *config); |
| 499 |
|
| 500 |
/** |
| 501 |
* Reinitialize the decoder with updated configuration. |
| 502 |
* |
| 503 |
* This function allows you to switch the acoustic model, dictionary, |
| 504 |
* or other configuration without creating an entirely new decoding |
| 505 |
* object. |
| 506 |
* |
| 507 |
* @note Since the acoustic model will be reloaded, changes made to |
| 508 |
* feature extraction parameters may be overridden if a `feat.params` |
| 509 |
* file is present. |
| 510 |
* @note Any searches created with ps_set_search() or words added to |
| 511 |
* the dictionary with ps_add_word() will also be lost. To avoid this |
| 512 |
* you can use ps_reinit_feat(). |
| 513 |
* @note The decoder retains ownership of the pointer |
| 514 |
* <code>config</code>, so you should free it when no longer used. |
| 515 |
* |
| 516 |
* @memberof ps_decoder_t |
| 517 |
* @param ps Decoder. |
| 518 |
* @param config An optional new configuration to use. If this is |
| 519 |
* NULL, the previous configuration will be reloaded, |
| 520 |
* with any changes applied. |
| 521 |
* @return 0 for success, <0 for failure. |
| 522 |
*/ |
| 523 |
POCKETSPHINX_EXPORT |
| 524 |
int ps_reinit(ps_decoder_t *ps, ps_config_t *config); |
| 525 |
|
| 526 |
/** |
| 527 |
* Reinitialize only the feature computation with updated configuration. |
| 528 |
* |
| 529 |
* This function allows you to switch the feature computation |
| 530 |
* parameters without otherwise affecting the decoder configuration. |
| 531 |
* For example, if you change the sample rate or the frame rate, and |
| 532 |
* do not want to reconfigure the rest of the decoder. |
| 533 |
* |
| 534 |
* Note that if you have set a custom cepstral mean with ps_set_cmn(), |
| 535 |
* it will be overridden. |
| 536 |
* |
| 537 |
* @note The decoder retains ownership of the pointer `config`, so you |
| 538 |
* should free it when no longer used. |
| 539 |
* |
| 540 |
* @memberof ps_decoder_t |
| 541 |
* @param ps Decoder. |
| 542 |
* @param config An optional new configuration to use. If this is |
| 543 |
* NULL, the previous configuration will be reloaded, |
| 544 |
* with any changes to feature computation applied. |
| 545 |
* @return 0 for success, <0 for failure (usually an invalid parameter) |
| 546 |
*/ |
| 547 |
POCKETSPHINX_EXPORT |
| 548 |
int ps_reinit_feat(ps_decoder_t *ps, ps_config_t *config); |
| 549 |
|
| 550 |
/** |
| 551 |
* Get the current cepstral mean as a string. |
| 552 |
* |
| 553 |
* This is the string representation of the current cepstral mean, |
| 554 |
* which represents the acoustic channel conditions in live |
| 555 |
* recognition. This can be used to initialize the decoder with the |
| 556 |
* `cmninit` option, e.g.: |
| 557 |
* |
| 558 |
* config = ps_config_parse_json(NULL, "cmninit: 42,-1,0"); |
| 559 |
* |
| 560 |
* @memberof ps_decoder_t |
| 561 |
* @param ps Decoder |
| 562 |
* @param update Update the cepstral mean using data processed so far. |
| 563 |
* @return String representation of cepstral mean, as |
| 564 |
* `ps_config_get_int(config, "ceplen")` comma-separated |
| 565 |
* numbers. This pointer is owned by the decoder and only |
| 566 |
* valid until the next call to ps_get_cmn(), ps_set_cmn() or |
| 567 |
* ps_end_utt(). |
| 568 |
*/ |
| 569 |
POCKETSPHINX_EXPORT |
| 570 |
const char *ps_get_cmn(ps_decoder_t *ps, int update); |
| 571 |
|
| 572 |
/** |
| 573 |
* Set the current cepstral mean from a string. |
| 574 |
* |
| 575 |
* This does the same thing as setting `cmninit` with |
| 576 |
* ps_config_set_string() and running `ps_reinit_feat()` but is more |
| 577 |
* efficient, and can also be done in the middle of an utterance if |
| 578 |
* you like. |
| 579 |
* |
| 580 |
* @memberof ps_decoder_t |
| 581 |
* @param ps Decoder |
| 582 |
* @param cmn String representation of cepstral mean, as up to |
| 583 |
* `ps_config_get_int(config, "ceplen")` -separated numbers |
| 584 |
* (any missing values will be zero-filled). @return 0 for |
| 585 |
* success of -1 for invalid input. |
| 586 |
*/ |
| 587 |
POCKETSPHINX_EXPORT |
| 588 |
int ps_set_cmn(ps_decoder_t *ps, const char *cmn); |
| 589 |
|
| 590 |
/** |
| 591 |
* Returns the argument definitions used in ps_config_init(). |
| 592 |
* |
| 593 |
* This is here to avoid exporting global data, which is problematic |
| 594 |
* on Win32 and Symbian (and possibly other platforms). |
| 595 |
* |
| 596 |
* @related ps_config_t |
| 597 |
*/ |
| 598 |
POCKETSPHINX_EXPORT |
| 599 |
ps_arg_t const *ps_args(void); |
| 600 |
|
| 601 |
/** |
| 602 |
* Retain a pointer to the decoder. |
| 603 |
* |
| 604 |
* This increments the reference count on the decoder, allowing it to |
| 605 |
* be shared between multiple parent objects. In general you will not |
| 606 |
* need to use this function, ever. It is mainly here for the |
| 607 |
* convenience of scripting language bindings. |
| 608 |
* |
| 609 |
* @memberof ps_decoder_t |
| 610 |
* @return pointer to retained decoder. |
| 611 |
*/ |
| 612 |
POCKETSPHINX_EXPORT |
| 613 |
ps_decoder_t *ps_retain(ps_decoder_t *ps); |
| 614 |
|
| 615 |
/** |
| 616 |
* Finalize the decoder. |
| 617 |
* |
| 618 |
* This releases all resources associated with the decoder. |
| 619 |
* |
| 620 |
* @memberof ps_decoder_t |
| 621 |
* @param ps Decoder to be freed. |
| 622 |
* @return New reference count (0 if freed). |
| 623 |
*/ |
| 624 |
POCKETSPHINX_EXPORT |
| 625 |
int ps_free(ps_decoder_t *ps); |
| 626 |
|
| 627 |
/** |
| 628 |
* Get the configuration object for this decoder. |
| 629 |
* |
| 630 |
* @memberof ps_decoder_t |
| 631 |
* @return The configuration object for this decoder. The decoder |
| 632 |
* owns this pointer, so you should not attempt to free it |
| 633 |
* manually. Use ps_config_retain() if you wish to reuse it |
| 634 |
* elsewhere. |
| 635 |
*/ |
| 636 |
POCKETSPHINX_EXPORT |
| 637 |
ps_config_t *ps_get_config(ps_decoder_t *ps); |
| 638 |
|
| 639 |
/** |
| 640 |
* Get the log-math computation object for this decoder. |
| 641 |
* |
| 642 |
* @memberof ps_decoder_t |
| 643 |
* @return The log-math object for this decoder. The decoder owns |
| 644 |
* this pointer, so you should not attempt to free it |
| 645 |
* manually. Use logmath_retain() if you wish to reuse it |
| 646 |
* elsewhere. |
| 647 |
*/ |
| 648 |
POCKETSPHINX_EXPORT |
| 649 |
logmath_t *ps_get_logmath(ps_decoder_t *ps); |
| 650 |
|
| 651 |
/** |
| 652 |
* Adapt current acoustic model using a linear transform. |
| 653 |
* |
| 654 |
* @memberof ps_decoder_t |
| 655 |
* @param mllr The new transform to use, or NULL to update the |
| 656 |
* existing transform. The decoder retains ownership of |
| 657 |
* this pointer, so you may free it if you no longer need |
| 658 |
* it. |
| 659 |
* @return The updated transform object for this decoder, or |
| 660 |
* NULL on failure. |
| 661 |
*/ |
| 662 |
POCKETSPHINX_EXPORT |
| 663 |
ps_mllr_t *ps_update_mllr(ps_decoder_t *ps, ps_mllr_t *mllr); |
| 664 |
|
| 665 |
/** |
| 666 |
* Reload the pronunciation dictionary from a file. |
| 667 |
* |
| 668 |
* This function replaces the current pronunciation dictionary with |
| 669 |
* the one stored in `dictfile`. This also causes the active search |
| 670 |
* module(s) to be reinitialized, in the same manner as calling |
| 671 |
* ps_add_word() with update=TRUE. |
| 672 |
* |
| 673 |
* @memberof ps_decoder_t |
| 674 |
* @param dictfile Path to dictionary file to load. |
| 675 |
* @param fdictfile Path to filler dictionary to load, or NULL to keep |
| 676 |
* the existing filler dictionary. |
| 677 |
* @param format Format of the dictionary file, or NULL to determine |
| 678 |
* automatically (currently unused,should be NULL) |
| 679 |
*/ |
| 680 |
POCKETSPHINX_EXPORT |
| 681 |
int ps_load_dict(ps_decoder_t *ps, char const *dictfile, |
| 682 |
char const *fdictfile, char const *format); |
| 683 |
|
| 684 |
/** |
| 685 |
* Dump the current pronunciation dictionary to a file. |
| 686 |
* |
| 687 |
* This function dumps the current pronunciation dictionary to a text file. |
| 688 |
* |
| 689 |
* @memberof ps_decoder_t |
| 690 |
* @param dictfile Path to file where dictionary will be written. |
| 691 |
* @param format Format of the dictionary file, or NULL for the |
| 692 |
* default (text) format (currently unused, should be NULL) |
| 693 |
*/ |
| 694 |
POCKETSPHINX_EXPORT |
| 695 |
int ps_save_dict(ps_decoder_t *ps, char const *dictfile, char const *format); |
| 696 |
|
| 697 |
/** |
| 698 |
* Add a word to the pronunciation dictionary. |
| 699 |
* |
| 700 |
* This function adds a word to the pronunciation dictionary and the |
| 701 |
* current language model (but, obviously, not to the current FSG if |
| 702 |
* FSG mode is enabled). If the word is already present in one or the |
| 703 |
* other, it does whatever is necessary to ensure that the word can be |
| 704 |
* recognized. |
| 705 |
* |
| 706 |
* @memberof ps_decoder_t |
| 707 |
* @param word Word string to add. |
| 708 |
* @param phones Whitespace-separated list of phoneme strings |
| 709 |
* describing pronunciation of <code>word</code>. |
| 710 |
* @param update If TRUE, update the search module (whichever one is |
| 711 |
* currently active) to recognize the newly added word. |
| 712 |
* If adding multiple words, it is more efficient to |
| 713 |
* pass FALSE here in all but the last word. |
| 714 |
* @return The internal ID (>= 0) of the newly added word, or <0 on |
| 715 |
* failure. |
| 716 |
*/ |
| 717 |
POCKETSPHINX_EXPORT |
| 718 |
int ps_add_word(ps_decoder_t *ps, |
| 719 |
char const *word, |
| 720 |
char const *phones, |
| 721 |
int update); |
| 722 |
|
| 723 |
/** |
| 724 |
* Look up a word in the dictionary and return phone transcription |
| 725 |
* for it. |
| 726 |
* |
| 727 |
* @memberof ps_decoder_t |
| 728 |
* @param ps Pocketsphinx decoder |
| 729 |
* @param word Word to look for |
| 730 |
* |
| 731 |
* @return Whitespace-spearated phone string describing the pronunciation of the <code>word</code> |
| 732 |
* or NULL if word is not present in the dictionary. The string is |
| 733 |
* allocated and must be freed by the user. |
| 734 |
*/ |
| 735 |
POCKETSPHINX_EXPORT |
| 736 |
char *ps_lookup_word(ps_decoder_t *ps, |
| 737 |
const char *word); |
| 738 |
|
| 739 |
/** |
| 740 |
* Decode a raw audio stream. |
| 741 |
* |
| 742 |
* No headers are recognized in this files. The configuration |
| 743 |
* parameters <tt>-samprate</tt> and <tt>-input_endian</tt> are used |
| 744 |
* to determine the sampling rate and endianness of the stream, |
| 745 |
* respectively. Audio is always assumed to be 16-bit signed PCM. |
| 746 |
* |
| 747 |
* @memberof ps_decoder_t |
| 748 |
* @param ps Decoder. |
| 749 |
* @param rawfh Previously opened file stream. |
| 750 |
* @param maxsamps Maximum number of samples to read from rawfh, or -1 |
| 751 |
* to read until end-of-file. |
| 752 |
* @return Number of samples of audio. |
| 753 |
*/ |
| 754 |
POCKETSPHINX_EXPORT |
| 755 |
long ps_decode_raw(ps_decoder_t *ps, FILE *rawfh, |
| 756 |
long maxsamps); |
| 757 |
|
| 758 |
/** |
| 759 |
* Decode a senone score dump file. |
| 760 |
* |
| 761 |
* @memberof ps_decoder_t |
| 762 |
* @param ps Decoder |
| 763 |
* @param senfh Previously opened file handle positioned at start of file. |
| 764 |
* @return Number of frames read. |
| 765 |
*/ |
| 766 |
POCKETSPHINX_EXPORT |
| 767 |
int ps_decode_senscr(ps_decoder_t *ps, FILE *senfh); |
| 768 |
|
| 769 |
/** |
| 770 |
* Start processing of the stream of speech. |
| 771 |
* |
| 772 |
* @deprecated This function is retained for compatibility, but its |
| 773 |
* only effect is to reset the noise removal statistics, which are |
| 774 |
* otherwise retained across utterances. You do not need to call it. |
| 775 |
* |
| 776 |
* @memberof ps_decoder_t |
| 777 |
* @return 0 for success, <0 on error. |
| 778 |
*/ |
| 779 |
POCKETSPHINX_EXPORT |
| 780 |
int ps_start_stream(ps_decoder_t *ps); |
| 781 |
|
| 782 |
/** |
| 783 |
* Check in-speech status of decoder. |
| 784 |
* |
| 785 |
* @deprecated This function is retained for compatibility but should |
| 786 |
* not be considered a reliable voice activity detector. It will |
| 787 |
* always return 1 between calls to ps_start_utt() and ps_end_utt(). |
| 788 |
* You probably want ps_endpointer_t, but for single frames of data |
| 789 |
* you can also use \ref ps_vad_t. |
| 790 |
* |
| 791 |
* @memberof ps_decoder_t |
| 792 |
* @param ps Decoder. |
| 793 |
* @return 1 if last buffer contained speech, 0 - otherwise |
| 794 |
*/ |
| 795 |
POCKETSPHINX_EXPORT |
| 796 |
int ps_get_in_speech(ps_decoder_t *ps); |
| 797 |
|
| 798 |
/** |
| 799 |
* Start utterance processing. |
| 800 |
* |
| 801 |
* This function should be called before any utterance data is passed |
| 802 |
* to the decoder. It marks the start of a new utterance and |
| 803 |
* reinitializes internal data structures. |
| 804 |
* |
| 805 |
* @memberof ps_decoder_t |
| 806 |
* @param ps Decoder to be started. |
| 807 |
* @return 0 for success, <0 on error. |
| 808 |
*/ |
| 809 |
POCKETSPHINX_EXPORT |
| 810 |
int ps_start_utt(ps_decoder_t *ps); |
| 811 |
|
| 812 |
/** |
| 813 |
* Decode raw audio data. |
| 814 |
* |
| 815 |
* @memberof ps_decoder_t |
| 816 |
* @param ps Decoder. |
| 817 |
* @param data Audio data, as 16-bit linear PCM. |
| 818 |
* @param n_samples Number of samples (not bytes) in `data`. |
| 819 |
* @param no_search If non-zero, perform feature extraction but don't |
| 820 |
* do any recognition yet. This may be necessary if |
| 821 |
* your processor has trouble doing recognition in |
| 822 |
* real-time. |
| 823 |
* @param full_utt If non-zero, this block of data is a full utterance |
| 824 |
* worth of data. This may allow the recognizer to |
| 825 |
* produce more accurate results. |
| 826 |
* @return Number of frames of data searched, or <0 for error. |
| 827 |
*/ |
| 828 |
POCKETSPHINX_EXPORT |
| 829 |
int ps_process_raw(ps_decoder_t *ps, |
| 830 |
int16 const *data, |
| 831 |
size_t n_samples, |
| 832 |
int no_search, |
| 833 |
int full_utt); |
| 834 |
|
| 835 |
/** |
| 836 |
* Decode acoustic feature data. |
| 837 |
* |
| 838 |
* @memberof ps_decoder_t |
| 839 |
* @param ps Decoder. |
| 840 |
* @param data Acoustic feature data, a 2-dimensional array of 32-bit |
| 841 |
* floating-point values. Note that this is not a standard |
| 842 |
* 2-dimesional C array but rather an array of pointers to |
| 843 |
* floats, each of which is one vector (or frame) of |
| 844 |
* `ps_config_get_int("ceplen")` values. |
| 845 |
* @param n_frames Number of vectors in `data`. |
| 846 |
* @param no_search If non-zero, perform feature extraction but don't |
| 847 |
* do any recognition yet. This may be necessary if |
| 848 |
* your processor has trouble doing recognition in |
| 849 |
* real-time. |
| 850 |
* @param full_utt If non-zero, this block of data is a full utterance |
| 851 |
* worth of data. This may allow the recognizer to |
| 852 |
* produce more accurate results. |
| 853 |
* @return Number of frames of data searched, or <0 for error. |
| 854 |
*/ |
| 855 |
POCKETSPHINX_EXPORT |
| 856 |
int ps_process_cep(ps_decoder_t *ps, |
| 857 |
float32 **data, |
| 858 |
int n_frames, |
| 859 |
int no_search, |
| 860 |
int full_utt); |
| 861 |
|
| 862 |
/** |
| 863 |
* Get the number of frames of data searched. |
| 864 |
* |
| 865 |
* Note that there is a delay between this and the number of frames of |
| 866 |
* audio which have been input to the system. This is due to the fact |
| 867 |
* that acoustic features are computed using a sliding window of |
| 868 |
* audio, and dynamic features are computed over a sliding window of |
| 869 |
* acoustic features. |
| 870 |
* |
| 871 |
* @memberof ps_decoder_t |
| 872 |
* @param ps Decoder. |
| 873 |
* @return Number of frames of speech data which have been recognized |
| 874 |
* so far. |
| 875 |
*/ |
| 876 |
POCKETSPHINX_EXPORT |
| 877 |
int ps_get_n_frames(ps_decoder_t *ps); |
| 878 |
|
| 879 |
/** |
| 880 |
* End utterance processing. |
| 881 |
* |
| 882 |
* @memberof ps_decoder_t |
| 883 |
* @param ps Decoder. |
| 884 |
* @return 0 for success, <0 on error |
| 885 |
*/ |
| 886 |
POCKETSPHINX_EXPORT |
| 887 |
int ps_end_utt(ps_decoder_t *ps); |
| 888 |
|
| 889 |
/** |
| 890 |
* Get hypothesis string and path score. |
| 891 |
* |
| 892 |
* @memberof ps_decoder_t |
| 893 |
* @param ps Decoder. |
| 894 |
* @param out_best_score Output: path score corresponding to returned string. |
| 895 |
* @return String containing best hypothesis at this point in |
| 896 |
* decoding. NULL if no hypothesis is available. This string is owned |
| 897 |
* by the decoder and only valid for the current hypothesis, so you |
| 898 |
* should copy it if you need to hold onto it. |
| 899 |
*/ |
| 900 |
POCKETSPHINX_EXPORT |
| 901 |
char const *ps_get_hyp(ps_decoder_t *ps, int32 *out_best_score); |
| 902 |
|
| 903 |
/** |
| 904 |
* Get posterior probability. |
| 905 |
* |
| 906 |
* @note Unless the -bestpath option is enabled, this function will |
| 907 |
* always return zero (corresponding to a posterior probability of |
| 908 |
* 1.0). Even if -bestpath is enabled, it will also return zero when |
| 909 |
* called on a partial result. Ongoing research into effective |
| 910 |
* confidence annotation for partial hypotheses may result in these |
| 911 |
* restrictions being lifted in future versions. |
| 912 |
* |
| 913 |
* @memberof ps_decoder_t |
| 914 |
* @param ps Decoder. |
| 915 |
* @return Posterior probability of the best hypothesis. |
| 916 |
*/ |
| 917 |
POCKETSPHINX_EXPORT |
| 918 |
int32 ps_get_prob(ps_decoder_t *ps); |
| 919 |
|
| 920 |
/** |
| 921 |
* Get word lattice. |
| 922 |
* |
| 923 |
* @memberof ps_decoder_t |
| 924 |
* @param ps Decoder. |
| 925 |
* @return Word lattice object containing all hypotheses so far. NULL |
| 926 |
* if no hypotheses are available. This pointer is owned by |
| 927 |
* the decoder and you should not attempt to free it manually. |
| 928 |
* It is only valid until the next utterance, unless you use |
| 929 |
* ps_lattice_retain() to retain it. |
| 930 |
*/ |
| 931 |
POCKETSPHINX_EXPORT |
| 932 |
ps_lattice_t *ps_get_lattice(ps_decoder_t *ps); |
| 933 |
|
| 934 |
/** |
| 935 |
* Get an iterator over the word segmentation for the best hypothesis. |
| 936 |
* |
| 937 |
* @memberof ps_decoder_t |
| 938 |
* @param ps Decoder. |
| 939 |
* @return Iterator over the best hypothesis at this point in |
| 940 |
* decoding. NULL if no hypothesis is available. |
| 941 |
*/ |
| 942 |
POCKETSPHINX_EXPORT |
| 943 |
ps_seg_t *ps_seg_iter(ps_decoder_t *ps); |
| 944 |
|
| 945 |
/** |
| 946 |
* Get the next segment in a word segmentation. |
| 947 |
* |
| 948 |
* @memberof ps_seg_t |
| 949 |
* @param seg Segment iterator. |
| 950 |
* @return Updated iterator with the next segment. NULL at end of |
| 951 |
* utterance (the iterator will be freed in this case). |
| 952 |
*/ |
| 953 |
POCKETSPHINX_EXPORT |
| 954 |
ps_seg_t *ps_seg_next(ps_seg_t *seg); |
| 955 |
|
| 956 |
/** |
| 957 |
* Get word string from a segmentation iterator. |
| 958 |
* |
| 959 |
* @memberof ps_seg_t |
| 960 |
* @param seg Segment iterator. |
| 961 |
* @return Read-only string giving string name of this segment. This |
| 962 |
* is only valid until the next call to ps_seg_next(). |
| 963 |
*/ |
| 964 |
POCKETSPHINX_EXPORT |
| 965 |
char const *ps_seg_word(ps_seg_t *seg); |
| 966 |
|
| 967 |
/** |
| 968 |
* Get inclusive start and end frames from a segmentation iterator. |
| 969 |
* |
| 970 |
* @note These frame numbers are inclusive, i.e. the end frame refers |
| 971 |
* to the last frame in which the given word or other segment was |
| 972 |
* active. Therefore, the actual duration is *out_ef - *out_sf + 1. |
| 973 |
* |
| 974 |
* @memberof ps_seg_t |
| 975 |
* @param seg Segment iterator. |
| 976 |
* @param out_sf Output: First frame index in segment. |
| 977 |
* @param out_ef Output: Last frame index in segment. |
| 978 |
*/ |
| 979 |
POCKETSPHINX_EXPORT |
| 980 |
void ps_seg_frames(ps_seg_t *seg, int *out_sf, int *out_ef); |
| 981 |
|
| 982 |
/** |
| 983 |
* Get language, acoustic, and posterior probabilities from a |
| 984 |
* segmentation iterator. |
| 985 |
* |
| 986 |
* @note Unless the -bestpath option is enabled, this function will |
| 987 |
* always return zero (corresponding to a posterior probability of |
| 988 |
* 1.0). Even if -bestpath is enabled, it will also return zero when |
| 989 |
* called on a partial result. Ongoing research into effective |
| 990 |
* confidence annotation for partial hypotheses may result in these |
| 991 |
* restrictions being lifted in future versions. |
| 992 |
* |
| 993 |
* @memberof ps_seg_t |
| 994 |
* @param out_ascr Output: acoustic model score for this segment. |
| 995 |
* @param out_lscr Output: language model score for this segment. |
| 996 |
* @param out_lback Output: language model backoff mode for this |
| 997 |
* segment (i.e. the number of words used in |
| 998 |
* calculating lscr). This field is, of course, only |
| 999 |
* meaningful for N-Gram models. |
| 1000 |
* @return Log posterior probability of current segment. Log is |
| 1001 |
* expressed in the log-base used in the decoder. To convert |
| 1002 |
* to linear floating-point, use logmath_exp(ps_get_logmath(), |
| 1003 |
* pprob). |
| 1004 |
*/ |
| 1005 |
POCKETSPHINX_EXPORT |
| 1006 |
int32 ps_seg_prob(ps_seg_t *seg, int32 *out_ascr, int32 *out_lscr, int32 *out_lback); |
| 1007 |
|
| 1008 |
/** |
| 1009 |
* Finish iterating over a word segmentation early, freeing resources. |
| 1010 |
* @memberof ps_seg_t |
| 1011 |
*/ |
| 1012 |
POCKETSPHINX_EXPORT |
| 1013 |
void ps_seg_free(ps_seg_t *seg); |
| 1014 |
|
| 1015 |
/** |
| 1016 |
* Get an iterator over the best hypotheses. The function may also |
| 1017 |
* return a NULL which means that there is no hypothesis available for this |
| 1018 |
* utterance. |
| 1019 |
* |
| 1020 |
* @memberof ps_decoder_t |
| 1021 |
* @param ps Decoder. |
| 1022 |
* @return Iterator over N-best hypotheses or NULL if no hypothesis is available |
| 1023 |
*/ |
| 1024 |
POCKETSPHINX_EXPORT |
| 1025 |
ps_nbest_t *ps_nbest(ps_decoder_t *ps); |
| 1026 |
|
| 1027 |
/** |
| 1028 |
* Move an N-best list iterator forward. |
| 1029 |
* |
| 1030 |
* @memberof ps_nbest_t |
| 1031 |
* @param nbest N-best iterator. |
| 1032 |
* @return Updated N-best iterator, or NULL if no more hypotheses are |
| 1033 |
* available (iterator is freed ni this case). |
| 1034 |
*/ |
| 1035 |
POCKETSPHINX_EXPORT |
| 1036 |
ps_nbest_t *ps_nbest_next(ps_nbest_t *nbest); |
| 1037 |
|
| 1038 |
/** |
| 1039 |
* Get the hypothesis string from an N-best list iterator. |
| 1040 |
* |
| 1041 |
* @memberof ps_nbest_t |
| 1042 |
* @param nbest N-best iterator. |
| 1043 |
* @param out_score Output: Path score for this hypothesis. |
| 1044 |
* @return String containing next best hypothesis. Note that this |
| 1045 |
* pointer is only valid for the current iteration. |
| 1046 |
*/ |
| 1047 |
POCKETSPHINX_EXPORT |
| 1048 |
char const *ps_nbest_hyp(ps_nbest_t *nbest, int32 *out_score); |
| 1049 |
|
| 1050 |
/** |
| 1051 |
* Get the word segmentation from an N-best list iterator. |
| 1052 |
* |
| 1053 |
* @memberof ps_nbest_t |
| 1054 |
* @param nbest N-best iterator. |
| 1055 |
* @return Iterator over the next best hypothesis. |
| 1056 |
*/ |
| 1057 |
POCKETSPHINX_EXPORT |
| 1058 |
ps_seg_t *ps_nbest_seg(ps_nbest_t *nbest); |
| 1059 |
|
| 1060 |
/** |
| 1061 |
* Finish N-best search early, releasing resources. |
| 1062 |
* |
| 1063 |
* @memberof ps_nbest_t |
| 1064 |
* @param nbest N-best iterator. |
| 1065 |
*/ |
| 1066 |
POCKETSPHINX_EXPORT |
| 1067 |
void ps_nbest_free(ps_nbest_t *nbest); |
| 1068 |
|
| 1069 |
/** |
| 1070 |
* Get performance information for the current utterance. |
| 1071 |
* |
| 1072 |
* @memberof ps_decoder_t |
| 1073 |
* @param ps Decoder. |
| 1074 |
* @param out_nspeech Output: Number of seconds of speech. |
| 1075 |
* @param out_ncpu Output: Number of seconds of CPU time used. |
| 1076 |
* @param out_nwall Output: Number of seconds of wall time used. |
| 1077 |
*/ |
| 1078 |
POCKETSPHINX_EXPORT |
| 1079 |
void ps_get_utt_time(ps_decoder_t *ps, double *out_nspeech, |
| 1080 |
double *out_ncpu, double *out_nwall); |
| 1081 |
|
| 1082 |
/** |
| 1083 |
* Get overall performance information. |
| 1084 |
* |
| 1085 |
* @memberof ps_decoder_t |
| 1086 |
* @param ps Decoder. |
| 1087 |
* @param out_nspeech Output: Number of seconds of speech. |
| 1088 |
* @param out_ncpu Output: Number of seconds of CPU time used. |
| 1089 |
* @param out_nwall Output: Number of seconds of wall time used. |
| 1090 |
*/ |
| 1091 |
POCKETSPHINX_EXPORT |
| 1092 |
void ps_get_all_time(ps_decoder_t *ps, double *out_nspeech, |
| 1093 |
double *out_ncpu, double *out_nwall); |
| 1094 |
|
| 1095 |
/** |
| 1096 |
* @mainpage PocketSphinx API Documentation |
| 1097 |
* @author David Huggins-Daines <[email protected]> |
| 1098 |
* @version 5.1.0 |
| 1099 |
* @date May 4th, 2026 |
| 1100 |
* |
| 1101 |
* @tableofcontents{HTML:1} |
| 1102 |
* |
| 1103 |
* @section intro_sec Introduction |
| 1104 |
* |
| 1105 |
* This is the documentation for the PocketSphinx speech recognition |
| 1106 |
* engine. The main API calls are documented in \ref ps_decoder_t and |
| 1107 |
* \ref ps_config_t. The organization of this document is not optimal |
| 1108 |
* due to the limitations of Doxygen, so if you know of a better tool |
| 1109 |
* for documenting object-oriented interfaces in C, please let me know. |
| 1110 |
* |
| 1111 |
* @section install_sec Installation |
| 1112 |
* |
| 1113 |
* To install from source, you will need a C compiler and a recent |
| 1114 |
* version of CMake. If you wish to use an integrated development |
| 1115 |
* environment, Visual Studio Code will automate most of this process |
| 1116 |
* for you once you have installed C++ and CMake support as described |
| 1117 |
* at https://code.visualstudio.com/docs/languages/cpp |
| 1118 |
* |
| 1119 |
* The easiest way to program PocketSphinx is with the Python module. |
| 1120 |
* See http://pocketsphinx.readthedocs.io/ for installation and usage |
| 1121 |
* instructions. |
| 1122 |
* |
| 1123 |
* @subsection unix_install Unix-like systems |
| 1124 |
* |
| 1125 |
* From the top-level source directory, use CMake to generate a build |
| 1126 |
* directory: |
| 1127 |
* |
| 1128 |
* cmake -S . -B build |
| 1129 |
* |
| 1130 |
* Now you can compile and run the tests, and install the code: |
| 1131 |
* |
| 1132 |
* cmake --build build |
| 1133 |
* cmake --build build --target check |
| 1134 |
* cmake --build build --target install |
| 1135 |
* |
| 1136 |
* By default CMake will try to install things in `/usr/local`, which |
| 1137 |
* you might not have access to. If you want to install somewhere |
| 1138 |
* else you need to set `CMAKE_INSTALL_PREFIX` *when running cmake for |
| 1139 |
* the first time*, for example: |
| 1140 |
* |
| 1141 |
* cmake -S . -B build -DCMAKE_INSTALL_PREFIX=$HOME/.local |
| 1142 |
* |
| 1143 |
* @subsection windows_install Windows |
| 1144 |
* |
| 1145 |
* On Windows, the process is similar, but you will need to tell CMake |
| 1146 |
* what build tool you are using with the `-G` option, and there are |
| 1147 |
* many of them. The build is known to work with `nmake` but it is |
| 1148 |
* easiest just to use Visual Studio Code, which should automatically |
| 1149 |
* detect and offer to run the build when you add the source directory |
| 1150 |
* to your list of directories. Once built, you will find the EXE |
| 1151 |
* files in `build\Debug` or `build\Release` depending on your build |
| 1152 |
* type. |
| 1153 |
* |
| 1154 |
* @subsection build_options Compilation options |
| 1155 |
* |
| 1156 |
* By default, PocketSphinx does *not* build shared libraries, as |
| 1157 |
* there are not very many executables, and the library is quite smol. |
| 1158 |
* If you insist on building them, you can add `BUILD_SHARED_LIBS=ON` |
| 1159 |
* to the CMake configuration. This is done either in the CMake GUI, |
| 1160 |
* in Visual Studio Code, or with the `-D` option to the first CMake |
| 1161 |
* command-line above, e.g.: |
| 1162 |
* |
| 1163 |
* cmake -S. -B build -DBUILD_SHARED_LIBS=ON |
| 1164 |
* |
| 1165 |
* GStreamer support is not built by default, but can be enabled with |
| 1166 |
* `BUILD_GSTREAMER=ON`. |
| 1167 |
* |
| 1168 |
* PocketSphinx uses a mixture of fixed and floating-point computation |
| 1169 |
* by default, but can be configured to use fixed-point (nearly) |
| 1170 |
* exclusively with `FIXED_POINT=ON`. |
| 1171 |
* |
| 1172 |
* @section programming_sec Using the Library |
| 1173 |
* |
| 1174 |
* Minimally, to do speech recognition, you must first create a |
| 1175 |
* configuration, using \ref ps_config_t and its associated functions. |
| 1176 |
* This configuration is then passed to ps_init() to initialize the |
| 1177 |
* decoder, which is returned as a \ref ps_decoder_t. Note that you must |
| 1178 |
* ultimately release the configuration with ps_config_free() to avoid |
| 1179 |
* memory leaks. |
| 1180 |
* |
| 1181 |
* At this point, you can start an "utterance" (a section of speech |
| 1182 |
* you wish to recognize) with ps_start_utt() and pass audio data to |
| 1183 |
* the decoder with ps_process_raw(). When finished, call |
| 1184 |
* ps_end_utt() to finalize recognition. The result can then be |
| 1185 |
* obtained with ps_get_hyp(). To get a detailed word segmentation, |
| 1186 |
* use ps_seg_iter(). To get the N-best results, use ps_nbest(). |
| 1187 |
* |
| 1188 |
* When you no longer need the decoder, release its memory with |
| 1189 |
* ps_free(). |
| 1190 |
* |
| 1191 |
* A concrete example can be found in \ref simple.c. |
| 1192 |
* |
| 1193 |
* You may, however, wish to do more interesting things like |
| 1194 |
* segmenting and recognizing speech from an audio stream. As |
| 1195 |
* described below, PocketSphinx will *not* handle the details of |
| 1196 |
* microphone input for you, because doing this in a reliable and |
| 1197 |
* portable way is outside the scope of a speech recognizer. In |
| 1198 |
* theory, [PortAudio](http://www.portaudio.com/) should work across |
| 1199 |
* many platforms. An example using it is in \ref live_portaudio.c. |
| 1200 |
* |
| 1201 |
* On Windows, an example of using the [Waveform Audio |
| 1202 |
* API](https://learn.microsoft.com/en-us/windows/win32/multimedia/waveform-audio) |
| 1203 |
* can be found in \ref live_win32.c. |
| 1204 |
* |
| 1205 |
* On GNU/Linux and some other platforms, audio might be handled by |
| 1206 |
* the PulseAudio library/server, in which case you can also use the |
| 1207 |
* technique in \ref live_pulseaudio.c. |
| 1208 |
* |
| 1209 |
* Finally, if you have `sox` on your platform, you can simply use the |
| 1210 |
* method shown in \ref live.c. |
| 1211 |
* |
| 1212 |
* @section faq_sec Frequently Asked Questions |
| 1213 |
* |
| 1214 |
* @subsection faq_api My code no longer compiles! Why? |
| 1215 |
* |
| 1216 |
* Some APIs were intentionally broken by the 5.0.0 release. The most |
| 1217 |
* likely culprit here is the configuration API, where the old |
| 1218 |
* "options" which started with a `-` are now "parameters" which do |
| 1219 |
* not, and instead of a `cmd_ln_t` it is now a `ps_config_t`. There |
| 1220 |
* is no backward compatibility, you have to change your code |
| 1221 |
* manually. This is straightforward for the most part. For example, |
| 1222 |
* instead of writing: |
| 1223 |
* |
| 1224 |
* cmdln = cmd_ln_init(NULL, "-samprate", "16000", NULL); |
| 1225 |
* cmd_ln_set_int32_r(NULL, "-maxwpf", 40); |
| 1226 |
* |
| 1227 |
* You should write: |
| 1228 |
* |
| 1229 |
* config = ps_config_init(NULL); |
| 1230 |
* ps_config_set_int(config, "samprate", 16000); |
| 1231 |
* ps_config_set_int(config, "maxwpf", 40); |
| 1232 |
* |
| 1233 |
* Another likely suspect is the \ref pocketsphinx/search.h |
| 1234 |
* "search module API" where the function names have been changed to be more |
| 1235 |
* intuitive. Wherever you had `ps_set_search` you can use |
| 1236 |
* ps_activate_search(), it is the same function. Likewise, anything |
| 1237 |
* that was `ps_set_*` is now `ps_add_*`, e.g. ps_add_lm(), |
| 1238 |
* ps_add_fsg(), ps_add_keyphrase(). |
| 1239 |
* |
| 1240 |
* @subsection faq_path What does ERROR: "acmod.c, line NN: ..." mean? |
| 1241 |
* |
| 1242 |
* In general you will get "Acoustic model definition is not |
| 1243 |
* specified" or "Folder does not contain acoustic model definition" |
| 1244 |
* errors if PocketSphinx cannot find a model. If you are trying to |
| 1245 |
* use the default module, perhaps you have not installed |
| 1246 |
* PocketSphinx. Unfortunately it is not designed to run "in-place", |
| 1247 |
* but you can get around this by setting the `POCKETSPHINX_PATH` |
| 1248 |
* environment variable, e.g. |
| 1249 |
* |
| 1250 |
* cmake --build build |
| 1251 |
* POCKETSPHINX_PATH=$PWD/model build/pocketsphinx single foo.wav |
| 1252 |
* |
| 1253 |
* @subsection faq_blank There is literally no output! |
| 1254 |
* |
| 1255 |
* If by this you mean it doesn't spew copious logging output like it |
| 1256 |
* used to, you can solve this by passing `-loglevel INFO` on the |
| 1257 |
* command-line, or setting the `loglevel` parameter to `"INFO"`, or |
| 1258 |
* calling err_set_loglevel() with `ERR_INFO`. |
| 1259 |
* |
| 1260 |
* If you mean that you just don't have any recognition result, you |
| 1261 |
* may have forgotten to configure a dictionary. Or see \ref |
| 1262 |
* faq_error "below" for other reasons the output could be blank. |
| 1263 |
* |
| 1264 |
* @subsection faq_audio Why doesn't my audio device work? |
| 1265 |
* |
| 1266 |
* Because it's an audio device. They don't work, at least for things |
| 1267 |
* other than making annoying "beep boop" noises and playing Video |
| 1268 |
* Games. More generally, I cannot solve this problem for you, |
| 1269 |
* because every single computer, operating system, sound card, |
| 1270 |
* microphone, phase of the moon, and day of the week is different |
| 1271 |
* when it comes to recording audio. That's why I suggest you use |
| 1272 |
* SoX, because (a) it usually works, and (b) whoever wrote it seems |
| 1273 |
* to have retired long ago, so you can't bother them. |
| 1274 |
* |
| 1275 |
* @subsection faq_error The recognized text is wrong. |
| 1276 |
* |
| 1277 |
* That's not a question! But since this isn't Jeopardy, and my name |
| 1278 |
* is not Watson, I'll try to answer it anyway. Be aware that the |
| 1279 |
* answer depends on many things, first and foremost what you mean by |
| 1280 |
* "wrong". |
| 1281 |
* |
| 1282 |
* If it *sounds* the same, e.g. "wreck a nice beach" when you said |
| 1283 |
* "recognize speech" then the issue is that the **language model** is |
| 1284 |
* not appropriate for the task, domain, dialect, or whatever it is |
| 1285 |
* you're trying to recognize. You may wish to consider writing a |
| 1286 |
* JSGF grammar and using it instead of the default language model |
| 1287 |
* (with the `jsgf` parameter). Or you can get an N-best list or word |
| 1288 |
* lattice and rescore it with a better language model, such as a |
| 1289 |
* recurrent neural network or a human being. |
| 1290 |
* |
| 1291 |
* If it is total nonsense, or if it is just blank, or if it's the |
| 1292 |
* same word repeated, e.g. "a a a a a a", then there is likely a |
| 1293 |
* problem with the input audio. The sampling rate could be wrong, or |
| 1294 |
* even if it's correct, you may have narrow-band data. Try to look |
| 1295 |
* at the spectrogram (Audacity can show you this) and see if it looks |
| 1296 |
* empty or flat below the frequency in the `upperf` parameter. |
| 1297 |
* Alternately it could just be very noisy. In particular, if the |
| 1298 |
* noise consists of other people talking, automatic speech |
| 1299 |
* recognition will nearly always fail. |
| 1300 |
* |
| 1301 |
* @subsection faq_tech Why don't you support (pick one or more: WFST, fMLLR, SAT, DNN, CTC, LAS, CNN, RNN, LSTM, etc)? |
| 1302 |
* |
| 1303 |
* Not because there's anything wrong with those things (except LAS, |
| 1304 |
* which is kind of a dumb idea) but simply because PocketSphinx does |
| 1305 |
* not do them, or anything like them, and there is no point in adding |
| 1306 |
* them to it when other systems exist. Many of them are also heavily |
| 1307 |
* dependent on distasteful and wasteful platforms like C++, CUDA, |
| 1308 |
* TensorFlow, PyTorch, and so on. |
| 1309 |
* |
| 1310 |
* @section thanks_sec Acknowledgements |
| 1311 |
* |
| 1312 |
* PocketSphinx was originally released by David Huggins-Daines, but |
| 1313 |
* is largely based on the previous Sphinx-II and Sphinx-III systems, |
| 1314 |
* developed by a large number of contributors at Carnegie Mellon |
| 1315 |
* University, and released as open source under a BSD-like license |
| 1316 |
* thanks to Kevin Lenzo. For some time, it was maintained by |
| 1317 |
* Nickolay Shmyrev and others at Alpha Cephei, Inc. See the |
| 1318 |
* `AUTHORS` file for a list of contributors. |
| 1319 |
*/ |
| 1320 |
|
| 1321 |
#ifdef __cplusplus |
| 1322 |
} /* extern "C" */ |
| 1323 |
#endif |
| 1324 |
|
| 1325 |
#endif /* __POCKETSPHINX_H__ */ |