Debian Codegraph @

include/pocketsphinx.h

raw
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__ */