Porcupine - Python API

This document outlines how to integrate Porcupine wake word engine within an application using its Python API.

Requirements

• Python3

Installation

Porcupine can be installed either via its PIP package or by cloning its repository directly.

Integration

Below are code snippets showcasing how Porcupine can be integrated into different applications.

PIP

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
print(pvporcupine.KEYWORDS)

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

import pvporcupine
handle = pvporcupine.create(keyword_file_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():
    pass
while True:
    keyword_index = handle.process(get_next_audio_frame())
    if keyword_index >= 0:
        # detection event logic/callback
        pass

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

handle.delete()

Repository

binding/python/porcupine.py provides a Python binding for Porcupine library. Below is a quick demonstration of how to construct an instance of it to detect multiple keywords concurrently.

library_path = ... # Path to Porcupine's C library available under lib/
model_file_path = ... # It is available at lib/common/porcupine_params.pv
keyword_file_paths = ['path/to/keyword/1', 'path/to/keyword/2', ...]
sensitivities = [0.5, 0.4, ...]
handle = Porcupine(
    library_path,
    model_file_path,
    keyword_file_paths=keyword_file_paths,
    sensitivities=sensitivities)

Sensitivity is the parameter that enables developers to trade miss rate for false alarm. It is a floating number within [0, 1]. A higher sensitivity reduces miss rate at cost of increased false alarm rate.

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():
    pass
while True:
    keyword_index = handle.process(get_next_audio_frame())
    if keyword_index >= 0:
        # detection event logic/callback
        pass

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

handle.delete()

Creating Custom Wake Words

Enterprises who are engaged with Picovoice can create custom wake word models using Picovoice Console.