PocketSphinx Documentation

The PocketSphinx examples demonstrate three primary modes of operation:

1. Simplest possible example (simple.c, simple.py): Reads an entire WAV audio file and recognizes it as a single utterance.
2. Segmentation (segment.py): Uses voice activity detection (VAD) to segment an input stream into speech-like regions.
3. Live recognition (live.c, live.py): Performs online segmentation and recognition (real-time processing).

PocketSphinx uses a Mersenne Twister random number generator for tasks like audio dithering. To ensure thread safety and prevent race conditions when using PocketSphinx in multi-threaded applications, you must use a build where thread-local storage is enabled. This allows each thread to maintain its own independent RNG state without locks or synchronization.

Thread-local storage is enabled by default when building with CMake on supported platforms. If you need to explicitly configure this behavior, use the PS_THREAD_LOCAL_RNG CMake flag.

For recent Python versions and platforms, you can install PocketSphinx directly using pip:

pip3 install pocketsphinx

To install the PocketSphinx Python interface, use pip. This installation is "batteries-included," meaning it includes a default model and dictionary specifically for US/Canadian English.

pip install pocketsphinx

If you want to compile a C example (like simple.c) manually without using the standard build system, you can use the following methods depending on your environment.

Option 1: Building from the source directory If you are building within the source tree:

cmake -DBUILD_SHARED_LIBS=OFF .. && make
cc -o simple simple.c -I../include -Iinclude -L. -lpocketsphinx -lm

Option 2: Using pkg-config (if installed) If PocketSphinx is already installed on your system:

cc -o simple simple.c $(pkg-config --static --libs --cflags pocketsphinx)

If PocketSphinx is not installed on your system, you must set the POCKETSPHINX_PATH environment variable to point to the model directory when running the compiled example.

POCKETSPHINX_PATH=../model ./simple

To run the suite of regression and unit tests, use CMake:

cmake --build build --target check

For faster execution using parallel processes:

cd build && ctest -j4

To install the PocketSphinx Python module in a virtual environment, run the following commands from the top-level directory of the repository. Replace ~/ve_pocketsphinx with your desired virtual environment path.

python3 -m venv ~/ve_pocketsphinx
. ~/ve_pocketsphinx/bin/activate
pip install .

To compile PocketSphinx from the source tree, it is highly recommended to use a virtual environment. Run these commands from the top-level directory:

python3 -m venv ~/ve_pocketsphinx
. ~/ve_pocketsphinx/bin/activate
pip3 install .

On Debian GNU/Linux and its derivatives (such as Raspberry Pi OS, Ubuntu, etc), you can install the following dependencies required to run the example code using apt:

sudo apt install \
    ffmpeg \
    libasound2-dev \
    libportaudio2 \
    libportaudiocpp0 \
    libpulse-dev \
    libsox-fmt-all \
    portaudio19-dev \
    sox