Metadata-Version: 2.2
Name: ringr
Version: 0.1.6
Summary: Sound event detection system
Author-email: Alberto Alcolea <albertoalcolea@gmail.com>
License: GNU General Public License v3 (GPLv3)
Project-URL: source, https://github.com/albertoalcolea/ringr
Project-URL: changelog, https://github.com/albertoalcolea/ringr/releases
Project-URL: issues, https://github.com/albertoalcolea/ringr/issues
Project-URL: documentation, https://albertoalcolea.com/blog/ringr-a-sound-event-detection-system/
Keywords: ringr,ring,sound,sound detection,audio,audio detection,frequency analyzer,peak detection,home assistant
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sounddevice==0.4.6
Requires-Dist: numpy==1.26.2
Requires-Dist: paho-mqtt==1.6.1
Provides-Extra: dev
Requires-Dist: flake8>=4.0.1; extra == "dev"
Requires-Dist: build>=1.2.2.post1; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"

# ringr

[![Build Status](https://github.com/albertoalcolea/ringr/workflows/Tests/badge.svg)](https://github.com/albertoalcolea/ringr/actions?query=workflow%3ATests)
[![Latest PyPI Version](https://img.shields.io/pypi/v/ringr.svg)](https://pypi.python.org/pypi/ringr)
[![PyPI pyversions](https://img.shields.io/pypi/pyversions/ringr.svg)](https://pypi.python.org/pypi/ringr)

Sound event detection system based on the open-source cross-platform PortAudio API.

It supports multiple notification backends, and it has been designed to run on low-specs and inexpensive hardware like the lowest range of raspberry products (RPi 1, RPi Zero, RPi Zero 2, etc).

## Use cases

Some interesting use cases where to use *ringr* to automate your smart home and help disabled people:
* Intercom and doorbell detection
* Detection of the end-of-program audible warning of some appliances such as washing machines, clothes dryers or dishwashers
* Baby crying detection
* Dog bark detection

## Design considerations and constraints

This has born as a personal project for a very concrete use case that can be extrapolated to multiple other contexts and needs.

Some of my personal requirements and constraints include:
* It must run on an old Raspberry Pi 1 that I have stored in a drawer and unused for some many years to give it a new life.
* It must run with very cheap and low quality microphones.
* It must be able to detect the intercom and doorbell notification sounds without false positives warnings.
* It must notify states to my personal Home Assistant installation and provide support to add more notification backends in the future.

More information about the concept and design of *ringr* in [this post on my personal blog](https://albertoalcolea.com/blog/ringr-a-sound-event-detection-system/).

## Installation

On all systems, install *ringr* by using `pip`:

```
pip install ringr
```

If you install *ringr* on macOS and Windows, the PortAudio library will be installed automatically. On other platforms, you might have to install PortAudio with your package manager (the package might be called `libportaudio2` or similar).

### Systemd

Copy the file `ringr.service` available in this repository to `/etc/systemd/system/ringr.service`

Edit the service and modify the application path, the user and the group if needed.

Reload the systemd daemon to load the new service by executing `systemctl daemon-reload`.

Start the service with `systemctl start ringr.service` and enable it if you want to run it automatically at startup: `systemctl enable ringr.service`

### Docker

Alternatively to a native installation you can use Docker.

A Dockerfile is provided to build a Docker image for *ringr*.

```
docker build -t ringr .
```

No volumes are needed as *ringr* is a stateless service.

Remember you need to add the host sound device to your container with `--device`

```
docker run -d \
  --name=ringr \
  --device=/dev/snd:/dev/snd
  -e TZ=Europe/Madrid \
  -e PUID=1000 \
  -e GUID=1000 \
  -e RINGR_DETECTOR_DEVICE='1' \
  -e RINGR_DETECTOR_THRESHOLD='65' \
  -e RINGR_DETECTOR_PEAK_DURATION='0.8' \
  -e RINGR_DETECTOR_FREQUENCY='1000' \
  -e RINGR_DETECTOR_ACCEPTANCE_RATIO='90' \
  -e RINGR_DETECTOR_GAIN='200' \
  -e RINGR_DETECTOR_LATENCY='0.1' \
  -e RINGR_DETECTOR_COOLDOWN='15' \
  -e RINGR_NOTIFIER_TYPE='ha' \
  -e RINGR_NOTIFIER_MQTT_HOST='10.10.0.50' \
  -e RINGR_NOTIFIER_USER='ringr' \
  -e RINGR_NOTIFIER_PASS='secret' \
  --restart unless-stopped \
  ringr:latest
```

#### docker-compose

Example of a *docker-compose* file:

```
version: '3'
services:
  ringr:
    container_name: ringr
    image: ringr:latest
    devices:
      - '/dev/snd:/dev/snd'
    environment:
      TZ: 'Europe/Madrid'
      PUID: '1000'
      GUID: '1000'
      RINGR_DETECTOR_DEVICE: '1'
      RINGR_DETECTOR_THRESHOLD: '65'
      RINGR_DETECTOR_PEAK_DURATION: '0.8'
      RINGR_DETECTOR_FREQUENCY: '1000'
      RINGR_DETECTOR_ACCEPTANCE_RATIO: '90'
      RINGR_DETECTOR_GAIN: '200'
      RINGR_DETECTOR_LATENCY: '0.1'
      RINGR_DETECTOR_COOLDOWN: '15'
      RINGR_NOTIFIER_TYPE: 'ha'
      RINGR_NOTIFIER_MQTT_HOST: '10.10.0.50'
      RINGR_NOTIFIER_USER: 'ringr'
      RINGR_NOTIFIER_PASS: 'secret'
    restart: unless-stopped
```

## Usage

Use the `ringr` command to launch the application.

It supports the following optional parameters:
* `-c`, `--conf`: configuration file. By default it uses `/etc/ringr/ringr.conf`
* `-v`, `--verbose`: configure the log level of the logger in debug level

## Configuration

*ringr* can be configured through a configuration file or with environment variables, useful if you run it  within a docker container.

The expected path to the configuration file is `/etc/ringr/ringr.conf`.

### Detector

The configuration of the detector is defined inside the `[detector]` section of the configuration files.

It supports the following options:

#### device

| Option | Environment variable | Data type | Unit | Default |
| --- | --- | --- | --- | --- |
| `device` | `RINGR_DETECTOR_DEVICE` | integer | | |

Index of the input sound device.

You can get the list of PortAudio sound devices and their index with the following command:

```
$ python -m sounddevice
  0 sof-hda-dsp: - (hw:1,0), ALSA (2 in, 2 out)
  1 sof-hda-dsp: - (hw:1,4), ALSA (0 in, 2 out)
  2 sof-hda-dsp: - (hw:1,5), ALSA (0 in, 2 out)
  3 sof-hda-dsp: - (hw:1,6), ALSA (2 in, 0 out)
  4 sof-hda-dsp: - (hw:1,7), ALSA (2 in, 0 out)
  5 pulse, ALSA (32 in, 32 out)
* 6 default, ALSA (32 in, 32 out)
```

#### threshold

| Option | Environment variable | Data type | Unit | Default |
| --- | --- |-----------|------| --- |
| `threshold` | `RINGR_DETECTOR_THRESHOLD` | float     | %  | |

Relative amplitude threshold for the event detection.  It must be a value in the range [0,100].

#### peak_duration

| Option | Environment variable | Data type | Unit  | Default |
| --- | --- |-----------|-------| --- |
| `peak_duration` | `RINGR_DETECTOR_PEAK_DURATION` | float     | secs. | |

Duration of the signal over the threshold amplitude before to be considered an event.

#### frequency

| Option      | Environment variable       | Data type | Unit | Default |
|-------------|----------------------------|-----------|---| --- |
| `frequency` | `RINGR_DETECTOR_FREQUENCY` | int       | Hz | |

Frequency where to analyze the event.

The event will be analyzed inside a frequency range where the highest frequency will be the closest possible frequency to the desired frequency based on the number of frequency bins used.

#### frequency_bins

| Option           | Environment variable            | Data type | Unit | Default |
|------------------|---------------------------------|-----------|-|---------|
| `frequency_bins` | `RINGR_DETECTOR_FREQUENCY_BINS` | int       | | 256     |

Number of frequency bins in which divide the range of audible frequencies.

The detector will analyze the frequency bin whose highest frequency is closest to the desired frequency.

For example, with `frequency = 1000` and `frequency_bins` = 256, the detector will analyze the range between 951 Hz and 1037 Hz.

#### acceptance_ratio

| Option           | Environment variable              | Data type | Unit | Default |
|------------------|-----------------------------------|-----------|------|---------|
| `acceptance_ratio` | `RINGR_DETECTOR_ACCEPTANCE_RATIO` | float     | %    | 100     |

Number of samples that must be above the amplitude threshold in the desired frequency range during the `peak_duration` time.

#### gain

| Option | Environment variable  | Data type | Unit | Default |
|--------|-----------------------|-----------|------|--------|
| `gain` | `RINGR_DETECTOR_GAIN` | int       |     | 0     |

Some input devices may capture very low signals. Use this parameter to boost them to have more control on its amplitude.

#### latency

| Option    | Environment variable     | Data type | Unit  | Default |
|-----------|--------------------------|-----------|-------|---------|
| `latency` | `RINGR_DETECTOR_LATENCY` | float     | secs. | *high*  |

Input latency of capture.

Higher values will prevent input overflow errors that will discard samples and produce more robust and predictable results.

By default, it will use the predefined high input latency of your input sound device.

You can query that value using the following command replacing the argument in the `query_devices` method by the device index of your device:

```
$ python -c 'import sounddevice as sd; print(sd.query_devices(1))'
{'name': 'default', 'index': 11, 'hostapi': 0, 'max_input_channels': 32, 'max_output_channels': 32, 'default_low_input_latency': 0.008684807256235827, 'default_low_output_latency': 0.008684807256235827, 'default_high_input_latency': 0.034807256235827665, 'default_high_output_latency': 0.034807256235827665, 'default_samplerate': 44100.0}
```

#### cooldown

| Option     | Environment variable      | Data type | Unit  | Default |
|------------|---------------------------|-----------|-------|---------|
| `cooldown` | `RINGR_DETECTOR_COOLDOWN` | float     | secs. | 10      |

Cooldown time in seconds after a detection.  Any sample during this period will be discarded and will not be analyzed.

#### block_duration

| Option    | Environment variable           | Data type | Unit       | Default |
|-----------|--------------------------------|-----------|------------|---------|
| `block_duration` | `RINGR_DETECTOR_BLOCK_DURATION` | float     | millisecs. | 50      |

Duration of the sample to analyze.

Higher values may provoke input overflow errors.

#### log_analysis

| Option         | Environment variable          | Data type | Unit       | Default |
|----------------|-------------------------------|-----------|------------|---------|
| `log_analysis` | `RINGR_DETECTOR_LOG_ANALYSIS` | bool      |  | False   |


Verbose output of analysis. Use with log level = debug

### Notification backends

The configuration of the chosen notification backend is defined inside the `[notifier]` section of the configuration file.

All notification backends share one option: `type` which specifies the notification backend to use. The corresponding environment variable for this option is `RINGR_NOTIFIER_TYPE`


Available notification backends:

| Name | Type | Description |
| --- | --- | --- |
| Home Assistant | `ha` | Auto-discoverable MQTT device for Home Assistant |
| Telegram | `telegram` | Telegram Bot |


#### Home Assistant

Use `type: ha`

| Option      | Environment variable         | Data type | Default    | Description                                                                                                             |
|-------------|------------------------------|-----------|------------|-------------------------------------------------------------------------------------------------------------------------|
| `device_id` | `RINGR_NOTIFIER_DEVICE_ID`   | str       | ringr_01   | Unique device id. Override this value if you run multiple instances of *ringr*                                          |
| `device_name` | `RINGR_NOTIFIER_DEVICE_NAME` | str       | ringr 01   | Device name. Override this value if you run multiple instances of *ringr* or to use a custom name within Home Assistant |
| `mqtt_host` | `RINGR_NOTIFIER_MQTT_HOST`   | str       |            | Host of the MQTT broker                                                                                                 |
| `mqtt_port` | `RINGR_NOTIFIER_MQTT_PORT`   | int       | 1883       | Port of the MQTT broker                                                                                                 |
| `mqtt_user` | `RINGR_NOTIFIER_MQTT_USER`   | str       |            | Optional username to authenticate with the MQTT broker. Use it together with `mqtt_pass`                                |
| `mqtt_pass` | `RINGR_NOTIFIER_MQTT_PASS`   | str       |            | Optional password to authenticate with the MQTT broker. Use it together with `mqtt_user`                                |
| `mqtt_client_id` | `RINGR_NOTIFIER_MQTT_CLIENT_ID` | str | `ringr_01` | Client id of the MQTT client. Override this value if you run multiple instances of *ringr*                              |
| `mqtt_qos` | `RINGR_NOTIFIER_MQTT_QOS` | int | 1          | MQTT QoS of published messages                                                                                          |

#### Telegram

Use `type: telegram`

| Option      | Environment variable         | Data type | Default    | Description |
|-------------|------------------------------|-----------|------------|---|
| `api_token` | `RINGR_NOTIFIER_API_TOKEN` | str | | Telegram Bot API Token |
| `chat_id` | `RINGR_NOTIFIER_CHAT_ID` | str | | Telegram Chat ID |
| `message` | `RINGR_NOTIFIER_MESSAGE` | str  | Event detected | Message to send where an event is detected |

### Full example

Configuration file:

```python
[detector]
device: 1
threshold: 65
peak_duration: 0.8
frequency: 1000
acceptance_ratio: 90
gain: 200
latency: 0.1
cooldown: 15

[notifier]
type: ha
mqtt_host: 10.10.0.50
mqtt_user: ringr
mqtt_pass: secret
```

Or, by using environment variables:

```bash
RINGR_DETECTOR_DEVICE='1'
RINGR_DETECTOR_THRESHOLD='65'
RINGR_DETECTOR_PEAK_DURATION='0.8'
RINGR_DETECTOR_FREQUENCY='1000'
RINGR_DETECTOR_ACCEPTANCE_RATIO='90'
RINGR_DETECTOR_GAIN='200'
RINGR_DETECTOR_LATENCY='0.1'
RINGR_DETECTOR_COOLDOWN='15'

RINGR_NOTIFIER_TYPE='ha'
RINGR_NOTIFIER_MQTT_HOST='10.10.0.50'
RINGR_NOTIFIER_USER='ringr'
RINGR_NOTIFIER_PASS='secret'
```
