# Prerequisites

First, consult the prerequisites section of [Python binding](/binding/python). Additionally, demo application
uses [PyAudio](https://people.csail.mit.edu/hubert/pyaudio/) for recording input audio (i.e. microphone).
Consult the installation guide at [PyAudio](https://people.csail.mit.edu/hubert/pyaudio/).

# Microphone-Based Application

Usage information can be found via

```bash
python3 demo/python/porcupine_demo_mic.py --help
```

In the simplest form, a path to a valid wake word file needs to be provided to the script.

```bash
python3 demo/python/porcupine_demo.py --keyword_file_paths resources/keyword_files/${SYSTEM}/blueberry_${SYSTEM}.ppn
``` 

In the above command replace ```${SYSTEM}``` with the operating system (i.e. linux or mac). It starts recording audio
from the default input audio device, initializes an instance of Porcupine library, monitors the incoming audio for the
wake word blueberry, and writes the detection result into the console. This is an example console output on a
 linux machine

````
ALSA lib pcm.c:2266:(snd_pcm_open_noupdate) Unknown PCM cards.pcm.rear
ALSA lib pcm.c:2266:(snd_pcm_open_noupdate) Unknown PCM cards.pcm.center_lfe
ALSA lib pcm.c:2266:(snd_pcm_open_noupdate) Unknown PCM cards.pcm.side
ALSA lib pcm_route.c:867:(find_matching_chmap) Found no matching channel map
Cannot connect to server socket err = No such file or directory
Cannot connect to server request channel
jack server is not running or cannot be started
JackShmReadWritePtr::~JackShmReadWritePtr - Init not done for 4294967295, skipping unlock
JackShmReadWritePtr::~JackShmReadWritePtr - Init not done for 4294967295, skipping unlock
[2018-03-02 16:01:10.638629] detected keyword
[2018-03-02 16:01:18.862524] detected keyword
[2018-03-02 16:01:25.550392] detected keyword
````

There are few lines of output generated by [ALSA](https://en.wikipedia.org/wiki/Advanced_Linux_Sound_Architecture). Don't
be alarmed this is normal. In order to detect a different wake word change the keyword file.

Also, you can detect multiple wake words concurrently (e.g. Blueberry and Raspberry) using

```bash
python3 demo/python/porcupine_demo_mic.py --keyword_file_paths \
resources/keyword_files/${SYSTEM}/blueberry_${SYSTEM}.ppn resources/keyword_files/${SYSTEM}/raspberry_${SYSTEM}.ppn
``` 

## FAQ

#### The demo application does not detect anything. Why?

The most probable cause of this is that the default audio input device recognized by PyAudio is not the one being used.
There are a couple of debugging facilities baked into the demo application to solve this. First, type the following into the
console

```bash
python3 ./demo/python/porcupine_demo_mic.py --show_audio_devices_info
```

It provides information about various audio input devices on the box. On a Linux box, this is the console output

```
'index': '0', 'name': 'HDA Intel PCH: ALC892 Analog (hw:0,0)', 'defaultSampleRate': '44100.0', 'maxInputChannels': '2'
'index': '1', 'name': 'HDA Intel PCH: ALC892 Alt Analog (hw:0,2)', 'defaultSampleRate': '44100.0', 'maxInputChannels': '2'
'index': '2', 'name': 'HDA NVidia: HDMI 0 (hw:1,3)', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '3', 'name': 'HDA NVidia: HDMI 1 (hw:1,7)', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '4', 'name': 'HDA NVidia: HDMI 2 (hw:1,8)', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '5', 'name': 'HDA NVidia: HDMI 3 (hw:1,9)', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '6', 'name': 'HDA NVidia: HDMI 0 (hw:2,3)', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '7', 'name': 'HDA NVidia: HDMI 1 (hw:2,7)', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '8', 'name': 'HDA NVidia: HDMI 2 (hw:2,8)', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '9', 'name': 'HDA NVidia: HDMI 3 (hw:2,9)', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '10', 'name': 'Logitech USB Headset: Audio (hw:3,0)', 'defaultSampleRate': '44100.0', 'maxInputChannels': '1'
'index': '11', 'name': 'sysdefault', 'defaultSampleRate': '48000.0', 'maxInputChannels': '128'
'index': '12', 'name': 'front', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '13', 'name': 'surround21', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '14', 'name': 'surround40', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '15', 'name': 'surround41', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '16', 'name': 'surround50', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '17', 'name': 'surround51', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '18', 'name': 'surround71', 'defaultSampleRate': '44100.0', 'maxInputChannels': '0'
'index': '19', 'name': 'pulse', 'defaultSampleRate': '44100.0', 'maxInputChannels': '32'
'index': '20', 'name': 'dmix', 'defaultSampleRate': '48000.0', 'maxInputChannels': '0'
'index': '21', 'name': 'default', 'defaultSampleRate': '44100.0', 'maxInputChannels': '32'
``` 

It can be seen that the last device (index 21) is considered default. But on this machine, a headset is being used as 
the input device which has an index of 10. After finding the correct index the demo application can be invoked as below

```bash
python3 demo/python/porcupine_demo_mic.py --keyword_file_paths resources/keyword_files/blueberry_linux.ppn \
--input_audio_device_index 10
```

If the problem persists we suggest storing the recorded audio into a file for inspection. This can be achieved by

```bash
python3 demo/python/porcupine_demo_mic.py --keyword_file_paths resources/keyword_files/blueberry_linux.ppn \
--input_audio_device_index 10 --output_path ~/test.wav
```

If after listening to stored file there is no apparent problem detected please open an issue.

# File-Based Application

It allows testing Porcupine on a corpus of audio files. It is mainly useful for quantitative performance benchmarking.
