Package: ringr
ringrSound 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 casesSome interesting use cases where to useringrto automate your smart home and help disabled people:Intercom and doorbell detectionDetection of the end-of-program audible warning of some appliances such as washing machines, clothes dryers or dishwashersBaby crying detectionDog bark detectionDesign considerations and constraintsThis 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.InstallationOn all systems, installringrby usingpip:pip install ringrSystemdCopy the fileringr.serviceavailable in this repository to/etc/systemd/system/ringr.serviceEdit the service and modify the application path, the user and the group if needed.Reload the systemd daemon to load the new service by executingsystemctl daemon-reload.Start the service withsystemctl start ringr.serviceand enable it if you want to run it automatically at startup:systemctl enable ringr.serviceDockerAlternatively to a native installation you can use Docker.A Dockerfile is provided to build a Docker image forringr.docker build -t ringr .No volumes are needed asringris a stateless service.Remember you need to add the host sound device to your container with--devicedocker run -d \
  --name=ringr \
  --device=/dev/snd:/dev/snd
  -e TZ=Europe/Madrid \
  -e PUID=1000 \
  -e GUID=1000 \
  -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:latestdocker-composeExample of adocker-composefile: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_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-stoppedUsageUse theringrcommand 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 levelConfigurationringrcan 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.DetectorThe configuration of the detector is defined inside the[detector]section of the configuration files.It supports the following options:deviceOptionEnvironment variableData typeUnitDefaultdeviceRINGR_DETECTOR_DEVICEintegerIndex 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)thresholdOptionEnvironment variableData typeUnitDefaultthresholdRINGR_DETECTOR_THRESHOLDfloat%Relative amplitude threshold for the event detection.  It must be a value in the range [0,100].peak_durationOptionEnvironment variableData typeUnitDefaultpeak_durationRINGR_DETECTOR_PEAK_DURATIONfloatsecs.Duration of the signal over the threshold amplitude before to be considered an event.frequencyOptionEnvironment variableData typeUnitDefaultfrequencyRINGR_DETECTOR_FREQUENCYintHzFrequency 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_binsOptionEnvironment variableData typeUnitDefaultfrequency_binsRINGR_DETECTOR_FREQUENCY_BINSint256Number 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, withfrequency = 1000andfrequency_bins= 256, the detector will analyze the range between 951 Hz and 1037 Hz.acceptance_ratioOptionEnvironment variableData typeUnitDefaultacceptance_ratioRINGR_DETECTOR_ACCEPTANCE_RATIOfloat%100Number of samples that must be above the amplitude threshold in the desired frequency range during thepeak_durationtime.gainOptionEnvironment variableData typeUnitDefaultgainRINGR_DETECTOR_GAINint0Some input devices may capture very low signals. Use this parameter to boost them to have more control on its amplitude.latencyOptionEnvironment variableData typeUnitDefaultlatencyRINGR_DETECTOR_LATENCYfloatsecs.highInput 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 thequery_devicesmethod by the device index of your device:$ python -c 'import sounddevice as sd; print(sd.query_device(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}cooldownOptionEnvironment variableData typeUnitDefaultcooldownRINGR_DETECTOR_COOLDOWNfloatsecs.10Cooldown time in seconds after a detection.  Any sample during this period will be discarded and will not be analyzed.block_durationOptionEnvironment variableData typeUnitDefaultblock_durationRINGR_DETECTOR_BLOCK_DURATIONfloatmillisecs.50Duration of the sample to analyze.Higher values may provoke input overflow errors.log_analysisOptionEnvironment variableData typeUnitDefaultlog_analysisRINGR_DETECTOR_LOG_ANALYSISboolFalseVerbose output of analysis. Use with log level = debugNotification backendsThe configuration of the chosen notification backend is defined inside the[notifier]section of the configuration file.All notification backends share one option:typewhich specifies the notification backend to use. The corresponding environment variable for this option isRINGR_NOTIFIER_TYPEAvailable notification backends:NameTypeDescriptionHome AssistanthaAuto-discoverable MQTT device for Home AssistantTelegram'telegram'Telegram BotHome AssistantUsetype: haOptionEnvironment variableData typeDefaultDescriptiondevice_idRINGR_NOTIFIER_DEVICE_IDstrringr_01Unique device id. Override this value if you run multiple instances ofringrdevice_nameRINGR_NOTIFIER_DEVICE_NAMEstrringr 01Device name. Override this value if you run multiple instances ofringror to use a custom name within Home Assistantmqtt_hostRINGR_NOTIFIER_MQTT_HOSTstrHost of the MQTT brokermqtt_portRINGR_NOTIFIER_MQTT_PORTint1883Port of the MQTT brokermqtt_userRINGR_NOTIFIER_MQTT_USERstrOptional username to authenticate with the MQTT broker. Use it together withmqtt_passmqtt_passRINGR_NOTIFIER_MQTT_PASSstrOptional password to authenticate with the MQTT broker. Use it together withmqtt_usermqtt_client_idRINGR_NOTIFIER_MQTT_CLIENT_IDstrringr_01Client id of the MQTT client. Override this value if you run multiple instances ofringrmqtt_qosRINGR_NOTIFIER_MQTT_QOSint1MQTT QoS of published messagesTelegramUsetype: telegramOptionEnvironment variableData typeDefaultDescriptionapi_tokenRINGR_NOTIFIER_API_TOKENstrTelegram Bot API Tokenchat_idRINGR_NOTIFIER_CHAT_IDstrTelegram Chat IDmessageRINGR_NOTIFIER_MESSAGEstrEvent detectedMessage to send where an event is detectedFull exampleConfiguration file:[detector]threshold:65peak_duration:0.8frequency:1000acceptance_ratio:90gain:200latency:0.1cooldown:15[notifier]type:hamqtt_host:10.10.0.50mqtt_user:ringrmqtt_pass:secretOr, by using environment variables: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'