Sensory TrulyHandsfree WakeWord Engine

About the Project

This project provides plug-in keyword spotting for the Alexa AVS sample app Raspberry Pi project, using Sensory's TrulyHandsfree technology. It includes speaker-independent recognizers for the phrase "Alexa".

License

The TrulyHandsfree library is provided for non-commercial development use only. See LICENSE.txt for details.

The libsnsr.a library is time-limited: code linked against it will stop working when the library expires. The library included in this repository will, at all times, have an expiration date that is at least 120 days in the future. To continue development after a library has expired, pull the latest update from the repository and re-link.

Please contact Sensory Sales if you wish to use this code in a product. We have solutions available for a large number of architectures, including low-power DSP ports suitable for continuous listening on battery-powered devices. Sensory also offers additional technologies, such as enrolled speaker-specific triggers and speaker verification.

Getting Started

This project is a plug-in for the Alexa AVS sample app project. Please follow the build and configuration instructions for that project.

Model selection

The models/ subdirectory contains recognition models with a selection of operating points.

Model	Size MiB	Pi 2 CPU %	Pi 3 CPU %	Description
spot-alexa-rpi-21000.snsr	1.0	18.0	8.2	low false fire
spot-alexa-rpi-31000.snsr	1.0	18.0	8.2	higher acceptance

Adding noise tech may improve poor SNR from longer distances, or improve the acceptance rate of the lower false fire model.

Note that spot-alexa-rpi-20500 is included for compatibility with the parent project's automated_install.sh script. It is the same file as spot-alexa-rpi-21000.snsr.

Key:

Size: The file size of the keyword spotter model in Mebibytes. This is also an estimate of the runtime RAM requirement.
Pi 2 CPU %: Raspberry Pi 2 model B CPU resource usage expressed as a percentage of real-time. 50% is half of one CPU core: Such a recognizer processes audio at twice the rate it arrives from the microphone.
Pi 3 CPU %: Raspberry Pi 3 model B CPU resource usage.

Frequently Asked Questions

How do I report a problem with this plug-in?
- Open a GitHub issue and include detail on how to trigger the unexpected behavior.

The library license key has expired. How do I extend it?

In samples/wakeWordAgent/sensory/alexa-rpi/, issue these commands:

git reset --hard
git pull
./bin/license.sh; # accept license agreement
cp ./lib/libsnsr.a ../../ext/lib/
cp ./include/snsr.h ../../ext/include/
cp ./models/*.snsr ../../ext/resources/
cp ./models/spot-alexa-rpi-31000.snsr ../../ext/resources/spot-alexa-rpi.snsr
cd ../../src
make
./wakeWordAgent -e sensory

What can I do to address audio recording problems?
- The project uses ALSA for audio recording. It will open a capture session from the default audio device, and record 16-bit signed integers at 16 kHz.
- There is an example /etc/asound.conf included in the config/ subdirectory in this repository. This file configures ALSA to use the USB microphone as the default input source, and the analog audio jack as the default output. We recommend that you use this configuration as a starting point for your audio routing.
- Verify that your audio configuration is suitable by running this command to make a ten second long audio recording: arecord -d 10 -f S16_LE -r 16000 test.wav
- Listen to the test recording and verify that it is clear: aplay test.wav
- If the recording volume is low, experiment with adjusting the recording levels using alsamixer. Run sudo alsactl store to make these settings permanent.
Which ARM architectures are supported?
- The libsnsr.a TrulyHandsfree library is compiled for ARMv7, and will use NEON instructions on the Rasperry Pi 2 and 3.
- The Raspberry Pi 1 and Raspberry Pi Zero use an ARM1176JZF-S CPU, which supports ARMv6 instructions only. These are not supported in this plug-in.

Change Log

5.0.0-beta.10.2 - 2017-05-25

Added
- Support for application-driven audio pipeline.
Changed
- New models with improved wakeword performance.

5.0.0-avs.4 - 2017-02-06

Changed
- snsrNew() validates snsr.h version.
- snsrStreamFromAudioDevice() tries to recover from snd_pcm_readi() errors.
- Larger ALSA capture buffer.
Fixed
- snsrRun() and snsrForEach() return SNSR_RC_ERROR when the SnsrCallback function returned SNSR_RC_INTERRUPTED.

5.0.0-avs.3 - 2017-02-01

Fixed
- Handling of zero ALSA reads. This addresses spurious end-of-stream errors during audio capture.
- Push iteration limit exceeded errors, which stopped the WakeWord Engine 74.5 hours after the last "Alexa" spot.

5.0.0-avs.2 - 2017-01-26

Added
- Change log section in README.md.
Fixed
- Reporting of ALSA errors.
- Handling of short ALSA reads. This addresses spurious end-of-stream errors during audio capture.
- Push iteration limit exceeded errors, which occasionally stopped the the WakeWord Engine after it had been running for a couple of days.

5.0.0-avs.1 - 2016-09-12

Added
- Initial release.

kangshifu / alexa-rpi