{"id":24277,"library":"pvporcupine","title":"Porcupine Wake Word Engine","description":"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.","status":"active","version":"4.0.2","language":"python","source_language":"en","source_url":"https://github.com/Picovoice/porcupine","tags":["wake-word","keyword-spotting","voice","audio","speech-recognition"],"install":[{"cmd":"pip install pvporcupine","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Required for audio input from microphone in demos.","package":"pyaudio","optional":true}],"imports":[{"note":"","wrong":"","symbol":"Porcupine","correct":"from pvporcupine import Porcupine"},{"note":"The top-level package is pvporcupine, not porcupine.","wrong":"import porcupine","symbol":"porcupine","correct":"import pvporcupine"}],"quickstart":{"code":"import pvporcupine\n\naccess_key = os.environ.get('PICOVOICE_ACCESS_KEY', '')\n\n# Shortcuts for built-in wake words: 'Hey Google', 'Alexa', etc.\nporcupine = pvporcupine.create(access_key=access_key, keywords=['picovoice'])\n\n# The object is ready to process audio frames\nprint(f\"Sample rate: {porcupine.sample_rate}\")\nprint(f\"Frame length: {porcupine.frame_length}\")\nprint(f\"Version: {porcupine.version}\")\n\nporcupine.delete()","lang":"python","description":"Initialize Porcupine with a built-in keyword. Requires a Picovoice Access Key from console.picovoice.ai."},"warnings":[{"fix":"Use keyword_paths=[\"/path/to/keyword.ppn\"] instead of a single string or path object.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Check the actual sample_rate and frame_length from the Porcupine instance after creation.","message":"v4.0 changed the default audio sample rate and frame length. Code relying on old constants may break.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Pass arguments as library_path and model_path (singular).","message":"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.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Always use a try-finally block or a context manager if available.","message":"You must call porcupine.delete() to release resources. Failure to do so causes memory leaks and might lock audio devices.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure audio frames are decoded to 16-bit signed integers. For example, using struct.unpack or pvrecorder.","message":"The process() method expects numpy int16 arrays. Mismatched types cause silent failures or high CPU usage.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run 'pip install pvporcupine' in the active virtual environment.","cause":"Package not installed or installed in a different environment (e.g., Conda).","error":"ImportError: No module named 'pvporcupine'"},{"fix":"Sign up at console.picovoice.ai and use the generated AccessKey string.","cause":"Using the demo access key without purchasing or obtaining a valid key.","error":"pvporcupine.PorcupineInvalidArgumentError: Invalid access key 'demo'."},{"fix":"Install pyaudio ('pip install pyaudio') and ensure your OS is supported (x86_64, arm64, etc.).","cause":"Missing or incompatible audio library, or the platform architecture is unsupported.","error":"RuntimeError: Porcupine engine failed to initialise."},{"fix":"Upgrade to the latest version: 'pip install --upgrade pvporcupine'.","cause":"Using an old version of pvporcupine (<2.0) that used a different API.","error":"AttributeError: module 'pvporcupine' has no attribute 'create'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}