From fc4a0ffb9f96f177afdfa17739527b41174c15f4 Mon Sep 17 00:00:00 2001
From: Nick Mowen <nickmowen213@gmail.com>
Date: Sat, 1 Jul 2023 06:56:05 -0600
Subject: [PATCH] Add audio detectors docs

---
 docs/docs/configuration/audio_detectors.md    | 63 +++++++++++++++++++
 .../{detectors.md => object_detectors.md}     |  6 +-
 docs/sidebars.js                              |  3 +-
 3 files changed, 68 insertions(+), 4 deletions(-)
 create mode 100644 docs/docs/configuration/audio_detectors.md
 rename docs/docs/configuration/{detectors.md => object_detectors.md} (99%)

diff --git a/docs/docs/configuration/audio_detectors.md b/docs/docs/configuration/audio_detectors.md
new file mode 100644
index 000000000..ef1d8227c
--- /dev/null
+++ b/docs/docs/configuration/audio_detectors.md
@@ -0,0 +1,63 @@
+---
+id: audio_detectors
+title: Audio Detectors
+---
+
+Frigate provides a builtin audio detector which runs on the CPU. Compared to object detection in images, audio detection is a relatively lightweight operation so the only option is to run the detection on a CPU.
+
+## Configuration
+
+Audio events work by detecting a type of audio and creating an event, the event will end once the type of audio has not been heard for the configured amount of time. Audio events save a snapshot at the beginning of the event as well as recordings throughout the event. The recordings are retained using the configured recording retention.
+
+### Enabling Audio Events
+
+Audio events can be enabled for all cameras or only for specific cameras.
+
+```yaml
+
+audio: # <- enable audio events for all camera
+  enabled: True
+
+cameras:
+  front_camera:
+    ffmpeg:
+    ...
+    audio:
+      enabled: True # <- enable audio events for the front_camera
+```
+
+If you are using multiple streams then you must set the `audio` role on the stream that is going to be used for audio detection, this can be any stream but the stream must have audio included.
+
+:::note
+
+The ffmpeg process for capturing audio will be a separate connection to the camera along with the other roles assigned to the camera, for this reason it is recommended that the go2rtc restream is used for this purpose. See [the restream docs](/configuration/restream.md) for more information.
+
+:::
+
+```yaml
+cameras:
+  front_camera:
+    ffmpeg:
+      inputs:
+        - path: rtsp://.../main_stream
+          roles:
+            - record
+        - path: rtsp://.../sub_stream # <- this stream must have audio enabled
+          roles:
+            - audio
+            - detect
+```
+
+### Configuring Audio Events
+
+The included audio model has over 500 different types of audio that can be detected, many of which are not practical. By default `bark`, `speech`, `yell`, and `scream` are enabled but these can be customized.
+
+```yaml
+audio:
+  enabled: True
+  listen:
+    - bark
+    - scream
+    - speech
+    - yell
+```
diff --git a/docs/docs/configuration/detectors.md b/docs/docs/configuration/object_detectors.md
similarity index 99%
rename from docs/docs/configuration/detectors.md
rename to docs/docs/configuration/object_detectors.md
index 84507321c..3f48423bc 100644
--- a/docs/docs/configuration/detectors.md
+++ b/docs/docs/configuration/object_detectors.md
@@ -1,6 +1,6 @@
 ---
-id: detectors
-title: Detectors
+id: object_detectors
+title: Object Detectors
 ---
 
 Frigate provides the following builtin detector types: `cpu`, `edgetpu`, `openvino`, and `tensorrt`. By default, Frigate will use a single CPU detector. Other detectors may require additional configuration as described below. When using multiple detectors they will run in dedicated processes, but pull from a common queue of detection requests from across all cameras.
@@ -275,6 +275,6 @@ detectors:
     api_timeout: 0.1 # seconds
 ```
 
-Replace `<your_codeproject_ai_server_ip>` and `<port>` with the IP address and port of your CodeProject.AI server. 
+Replace `<your_codeproject_ai_server_ip>` and `<port>` with the IP address and port of your CodeProject.AI server.
 
 To verify that the integration is working correctly, start Frigate and observe the logs for any error messages related to CodeProject.AI. Additionally, you can check the Frigate web interface to see if the objects detected by CodeProject.AI are being displayed and tracked properly.
\ No newline at end of file
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 41628f2ed..35ce2bee3 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -16,7 +16,8 @@ module.exports = {
     ],
     Configuration: [
       "configuration/index",
-      "configuration/detectors",
+      "configuration/object_detectors",
+      "configuration/audio_detectors",
       "configuration/cameras",
       "configuration/masks",
       "configuration/record",