Porcupine Wake Word Engine

4.0.2 verified Fri May 01 auth: no python

Porcupine is a highly accurate and lightweight wake word (hotword / keyword) detection engine, developed by Picovoice. It enables real-time voice trigger detection in Python with support for multiple platforms and languages. The current version is 4.0.2, requiring Python >=3.9.

pip install pvporcupine

Common errors

error ImportError: No module named 'pvporcupine' ↓

cause Package not installed or installed in a different environment (e.g., Conda).

fix

Run 'pip install pvporcupine' in the active virtual environment.

error pvporcupine.PorcupineInvalidArgumentError: Invalid access key 'demo'. ↓

cause Using the demo access key without purchasing or obtaining a valid key.

fix

error RuntimeError: Porcupine engine failed to initialise. ↓

cause Missing or incompatible audio library, or the platform architecture is unsupported.

fix

Install pyaudio ('pip install pyaudio') and ensure your OS is supported (x86_64, arm64, etc.).

error AttributeError: module 'pvporcupine' has no attribute 'create' ↓

cause Using an old version of pvporcupine (<2.0) that used a different API.

fix

Upgrade to the latest version: 'pip install --upgrade pvporcupine'.

Warnings

breaking v4.0 removed support for custom keyword files (.ppn) via file path. You must use the new 'builtin_keywords' or 'keyword_paths' list of strings for paths. ↓

fix Use keyword_paths=["/path/to/keyword.ppn"] instead of a single string or path object.

breaking v4.0 changed the default audio sample rate and frame length. Code relying on old constants may break. ↓

fix Check the actual sample_rate and frame_length from the Porcupine instance after creation.

deprecated The 'library_path' and 'model_file_path' parameters were deprecated in v3.0 and removed in v4.0. Use 'library_path' and 'model_path' instead. ↓

fix Pass arguments as library_path and model_path (singular).

gotcha You must call porcupine.delete() to release resources. Failure to do so causes memory leaks and might lock audio devices. ↓

fix Always use a try-finally block or a context manager if available.

gotcha The process() method expects numpy int16 arrays. Mismatched types cause silent failures or high CPU usage. ↓

fix Ensure audio frames are decoded to 16-bit signed integers. For example, using struct.unpack or pvrecorder.

Imports

Porcupine
```
from pvporcupine import Porcupine
```
porcupine
wrong
```
import porcupine
```
correct
```
import pvporcupine
```
The top-level package is pvporcupine, not porcupine.

Quickstart

Initialize Porcupine with a built-in keyword. Requires a Picovoice Access Key from console.picovoice.ai.

import pvporcupine

access_key = os.environ.get('PICOVOICE_ACCESS_KEY', '')

# Shortcuts for built-in wake words: 'Hey Google', 'Alexa', etc.
porcupine = pvporcupine.create(access_key=access_key, keywords=['picovoice'])

# The object is ready to process audio frames
print(f"Sample rate: {porcupine.sample_rate}")
print(f"Frame length: {porcupine.frame_length}")
print(f"Version: {porcupine.version}")

porcupine.delete()