---

name: porcupine description: "Operate Picovoice Porcupine wake-word detection across Python, Node.js, Web, mobile, managed SDK, C, and embedded workflows." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Porcupine

Use this repo skill when a task involves Picovoice Porcupine wake-word detection, custom keyword assets, SDK integration, file or microphone wake-word loops, device selection, or Porcupine platform troubleshooting.

Porcupine detects one or more static wake phrases from 16-bit PCM audio. Most detection workflows need a Picovoice AccessKey at engine initialization; safe package/import/device checks usually do not.

Start here

1. Read references/compatibility-and-assets.md to identify the SDK family, audio contract, AccessKey boundary, and asset/platform vocabulary.
2. Run scripts/check_porcupine_install.py --help when the task starts with a Python install/import/device check.
3. Route to the narrow sub-skill below for API details, recipes, scripts, and workflow-specific troubleshooting.
4. Use references/troubleshooting.md for cross-cutting AccessKey, asset, audio-frame, package, and backend failures.
5. Use references/repo-provenance.md before deciding whether this generated skill is stale for a checkout.

Install and safe Python smoke

For Python tasks:

pip install pvporcupine
python - <<'PY'
import pvporcupine
print(sorted(pvporcupine.KEYWORDS)[:10])
print(pvporcupine.available_devices())
PY

Or run the bundled safe helper:

python scripts/check_porcupine_install.py

Detection and training still require a valid AccessKey.

Route by task

Task	Read
Python API, pvporcupine.create, Porcupine.process, file WAV checks, Python exceptions, Python device enumeration	sub-skills/python-and-cli/SKILL.md
Node.js server-side JavaScript/TypeScript, @picovoice/porcupine-node, native .node loading, Int16Array frame loops	sub-skills/nodejs-server/SKILL.md
Browser/WebAssembly, @picovoice/porcupine-web, React usePorcupine, WASM workers, public-path/base64 assets, browser microphone permissions	sub-skills/web-and-react/SKILL.md
Java, Android, iOS Swift, .NET, Flutter, React Native package selection, manager-vs-engine APIs, app permissions, lifecycle and callbacks	sub-skills/managed-and-mobile-sdks/SKILL.md
Built-in keyword inventory, non-English .pv models, custom .ppn platform matching, training API, AccessKey/network/quota boundaries	sub-skills/custom-keywords-and-assets/SKILL.md
C API, headers/libraries, linker/load issues, file/mic C recipes, MCU/STM32 static asset embedding	sub-skills/c-and-embedded/SKILL.md

Cross-cutting operating rules

• Keep AccessKeys out of generated code, logs, and committed files.
• Choose built-in keywords only when the phrase is exposed by the target SDK/platform; otherwise use explicit custom .ppn paths.
• Pair custom/non-English keyword files with the matching platform and language model.
• Feed exact frame_length / frameLength frames at sample_rate / sampleRate; buffer or resample before calling process.
• Use manager APIs for platform microphone callbacks; use low-level engines when the caller owns PCM frames.
• Stop recorders/managers before deleting/releasing Porcupine.
• Treat microphone, browser, mobile, MCU, network training, and AccessKey-backed native detections as optional verification unless the user explicitly supplies the required resources.

Bundled helpers

• scripts/check_porcupine_install.py: safe Python import/asset/device check, no AccessKey.
• sub-skills/python-and-cli/scripts/porcupine_file_check.py: Python WAV-file checker; --help and --list-devices are safe, detection needs AccessKey.
• sub-skills/nodejs-server/scripts/porcupine_node_file_template.js: Node.js file-processing template/helper.
• sub-skills/c-and-embedded/scripts/porcupine_binary_to_c_array.py: convert .ppn, .pv, or other binary assets to C arrays for embedded workflows.
• sub-skills/web-and-react/scripts/web_asset_manifest_template.json: template for planning browser public-path/base64 assets.

Verification notes

The generated skill was drafted from repository docs/source/tests and a verified Python inspection environment for pvporcupine 4.0.3. Safe checks verified import, package metadata, built-in keyword enumeration, library/model path existence, and available_devices() on Linux. Credentialed detections, training requests, browser/mobile UI tests, and MCU board runs remain optional because they require AccessKeys, network, devices, or platform build stacks.