# clap-detector

> Clap detection for node js (linux, raspberry systems)

Latest version **0.5.3** (published 2021-03-10) · 0 weekly downloads

## Install

```sh
npm install clap-detector
pnpm add clap-detector
yarn add clap-detector
bun add clap-detector
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 0.5.3 |
| Published | 2021-03-10 |
| First published | 2015-11-09 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 21.2 KB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 56 |
| Author | tom-s |
| Maintainers | tom-s |
| Keywords | node, js, clap, trigger, detection, sox, alsa, microphone, raspberry, raspbian |

## Links

- npm: https://www.npmjs.com/package/clap-detector
- Repository: https://github.com/tom-s/clapDetector
- Homepage: https://github.com/tom-s/clapDetector#readme
- Issues: https://github.com/tom-s/clapDetector/issues
- npm.io page: https://npm.io/package/clap-detector

## Dependencies (2)

- [lodash](https://npm.io/package/lodash.md) 4.17.21
- [app-root-path](https://npm.io/package/app-root-path.md) 2.1.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.5.3 (latest) — 2021-03-10
- 0.5.1 — 2019-01-22
- 0.5.0 — 2018-12-30
- 0.4.1 — 2016-12-07
- 0.4.0 — 2016-01-18
- 0.3.2 — 2016-01-09
- 0.3.1 — 2015-11-28
- 0.3.0 — 2015-11-28
- 0.2.1 — 2015-11-11
- 0.2.0 — 2015-11-11
- 0.1.9 — 2015-11-11
- 0.1.8 — 2015-11-11
- 0.1.7 — 2015-11-11
- 0.1.6 — 2015-11-09
- 0.1.5 — 2015-11-09
- … 5 more at https://npm.io/package/clap-detector/versions

## README

Clap detection module for node js
===

## Synopsis

ClapDetector is a hand clap detection module for nodejs (iojs). It detects a clap or a series of claps and allows you to trigger callbacks whenever these events happen.
I created this module for my personal assistant project on a Raspberry Pi (raspbian). The clap detection allows me to activate the assistant whenever I need it (and prevents it from continuously listening out for instructions or interpreting random noises as instructions)

## Requirements
This module works on linux based OS (raspbian, Ubuntu, Debian...) using alsa for audio and a working microphone or Mac OS X using coreaudio.

## Installation

This module requires sox, "the Swiss Army knife of sound processing programs" (http://sox.sourceforge.net/) to be installed
### Linux
```bash
sudo apt-get install sox
```
### Mac OS X
```bash
brew install sox
```

### npm install
You can simply add this module to your node.js project with
```bash
npm install --save clap-detector
```

## Usage

First, create an instance of the ClapDetector class:
```bash
const clap = new ClapDetector()
```

Then register a callback that will be triggered whenever a series of hand claps is detected. Your callback will be provided with an array of claps and their associated timestamps as arguments.


```bash
const disposableOneClapListener = clap.addClapsListener(claps => {
  console.log("heard 1 clap", claps)
}, { number: 1, delay: 0 })
```

You can dispose (remove) a clap listener by calling the disposable method returned by addClapsListeners

```bash
disposableOneClapListener() // dispose the clap listener
```

Finally  you can call the dispose() method when you want to stop all clap detection and free associated resources

```bash
clap.dispose()
```

### addClapsListener
* Type : *Function*
* Arguments: *(callback [Function], options [Object])*

###### list of options
| Option  | Description |Default value |
| ------------- | ------------- |  ------------- |
| number  | Number of claps  | 1  |
| delay  | Period within the specified number of claps must be heard (ms)  |  1000 |
| force  | If true, trigger callback every time even if a listener with a higher number is triggered  |false  |

## Real life example
```bash
import ClapDetector from 'clap-detector'

const clap = new ClapDetector()

clap.addClapsListener(claps => {
  console.log("change tv channel")
}, { number: 1, delay: 0 })

clap.addClapsListener(claps => {
  console.log("turn tv on", claps)
}, { number: 2, delay: 1000 })

clap.addClapsListener(claps => {
  console.log("turn tv off", claps)
}, { number: 3, delay: 1000 })
```

## Full example
```bash
import ClapDetector from 'clap-detector'

const clap = new ClapDetector()
const disposableOneClapListener = clap.addClapsListener(claps => {
  console.log("heard 1 clap (force)", claps)
}, { number: 1, delay: 0, force: true })

const disposableOneClapForceListener = clap.addClapsListener(claps => {
  console.log("heard 1 clap", claps)
}, { number: 1, delay: 1000 })

const disposableTwoClapsListener = clap.addClapsListener(claps => {
  console.log("heard 2 claps", claps)
}, { number: 2, delay: 1000 })

const disposableThreeClapsListener = clap.addClapsListener(claps => {
  console.log("heard 3 claps", claps)
}, { number: 3, delay: 1000 })

// Cancel some clap listeners
// Cancel alls claps listener but 2 claps after 10 seconds
setTimeout(() => {
  console.log("only listen to 2 claps now")
  disposableOneClapListener()
  disposableOneClapForceListener()
  disposableThreeClapsListener()
}, 10000)

// Dispose (stop sox process and listeners) after 30s
setTimeout(() => {
  console.log("dispose all listeners and free ressources")
  clap.dispose()
}, 30000)
```

## Configuration

You can pass a configuration object and override the default values when you create an instance of the ClapDetector class. If you don't the following config will be used.

```bash
// DEFAULT CONFIG
var CONFIG = {
  AUDIO_SOURCE: 'hw:1,0', // this is your microphone input. If you dont know it you can refer to this thread (http://www.voxforge.org/home/docs/faq/faq/linux-how-to-determine-your-audio-cards-or-usb-mics-maximum-sampling-rate)
  DETECTION_PERCENTAGE_START : '5%', // minimum noise percentage threshold necessary to start recording sound
  DETECTION_PERCENTAGE_END: '5%',  // minimum noise percentage threshold necessary to stop recording sound
  CLAP_AMPLITUDE_THRESHOLD: 0.7, // minimum amplitude threshold to be considered as clap
  CLAP_ENERGY_THRESHOLD: 0.3,  // maximum energy threshold to be considered as clap
  MAX_HISTORY_LENGTH: 10 // all claps are stored in history, this is its max length
}
const clap = new ClapDetector(CONFIG)
```

If you wish to improve the clap detection you can fiddle with the CLAP_AMPLITUDE_THRESHOLD and CLAP_ENERGY_THRESHOLD values. Depending on your microphone these might need to be modified.

## Tests

These will be added soon. Please do not hesitate to submit some Ò!

## About the Author

I am a full-stack Javascript developer based in Lyon, France.

[Check out my website](http://www.thomschell.com)

## License

clap-detector is dual licensed under the MIT license and GPL.
For more information click [here](https://opensource.org/licenses/MIT).

---
_Source: https://npm.io/package/clap-detector · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._