pythonPorcupine - Python API

  • End-to-End Voice Platform
  • Offline Voice Recognition
  • Local Speech Recognition
  • Speech-to-Intent
  • Domain-Specific NLU
  • Wake Word Detection
  • Raspberry Pi
  • BeagleBone
  • Linux
  • macOS
  • Windows
  • Python


  • Python 3
  • PIP


  • Linux (x86_64)
  • macOS (x86_64)
  • Windows (x86_64)
  • Raspberry Pi (all variants)
  • BeagleBone.


pip3 install pvporcupine


The PIP package exposes a factory method to create instances of the engine:

import pvporcupine
handle = pvporcupine.create(keywords=['picovoice', 'bumblebee'])

keywords argument is a shorthand for accessing default keyword files shipped with the library. The default keyword files available can be retrieved via:

import pvporcupine

If you wish to use a non-default keyword file you need to identify its path as below

import pvporcupine
handle = pvporcupine.create(keyword_paths=['path/to/non/default/keyword/file'])

When initialized, valid sample rate can be obtained using handle.sample_rate. Expected frame length (number of audio samples in an input array) is handle.frame_length. The object can be used to monitor incoming audio as below.

def get_next_audio_frame():
while True:
keyword_index = handle.process(get_next_audio_frame())
if keyword_index >= 0:
# detection event logic/callback

Finally, when done be sure to explicitly release the resources as the binding class does not rely on the garbage collector.


Custom Wake Word

You can create custom Porcupine wake word models using Picovoice Console.

Non-English Wake Words

In order to detect non-English wake words you need to use the corresponding model file. The model files for all supported languages are available here.

Issue with this doc? Please let us know.