cava: add doce

3 files changed, 131 insertions, 5 deletions

diff --git a/docs/guide/libraries/cava.md b/docs/guide/libraries/cava.md
new file mode 100644
index 0000000..bbd5f4f
--- /dev/null
+++ b/docs/guide/libraries/cava.md
@@ -0,0 +1,91 @@
+# Cava
+
+Audio visualizer using [cava](https://github.com/karlstav/cava).
+
+## Installation
+
+1. install dependencies
+
+Note that it requires [libcava](https://github.com/LukashonakV/cava), a fork of cava, which provides cava as a shared library.
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson vala gobject-introspection
+paru -S libcava
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+# Not yet documented
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+# Not yet documented
+```
+
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/cava
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [Cava reference](https://aylur.github.io/libastal/cava).
+
+### CLI
+
+There is no CLI for this library, use the one provided by cava.
+
+```sh
+cava
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import Wp from "gi://AstalCava"
+
+const cava = Cava.get_default()
+
+cava.connect("notify::values", () => {
+    print(cava.get_values())
+})
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+# Not yet documented
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+-- Not yet documented
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented
+```
+
+:::
diff --git a/docs/vitepress.config.ts b/docs/vitepress.config.ts
index 25d9e36..a76388b 100644
--- a/docs/vitepress.config.ts
+++ b/docs/vitepress.config.ts
@@ -82,6 +82,7 @@ export default defineConfig({
                     { text: "Auth", link: "/guide/libraries/auth" },
                     { text: "Battery", link: "/guide/libraries/battery" },
                     { text: "Bluetooth", link: "/guide/libraries/bluetooth" },
+                    { text: "Cava", link: "/guide/libraries/cava" },
                     { text: "Hyprland", link: "/guide/libraries/hyprland" },
                     { text: "Mpris", link: "/guide/libraries/mpris" },
                     { text: "Network", link: "/guide/libraries/network" },
diff --git a/lib/cava/cava.c b/lib/cava/cava.c
index 4a70c90..27d201b 100644
--- a/lib/cava/cava.c
+++ b/lib/cava/cava.c
@@ -412,14 +412,18 @@ static void astal_cava_cava_init(AstalCavaCava* self) {
 /**
  * astal_cava_get_default
  *
- * Returns: (nullable) (transfer none): gets the default Cava object.
+ * gets the default Cava object.
+ *
+ * Returns: (nullable) (transfer none):
  */
 AstalCavaCava* astal_cava_get_default() { return astal_cava_cava_get_default(); }
 
 /**
  * astal_cava_cava_get_default
  *
- * Returns: (nullable) (transfer none): gets the default Cava object.
+ * gets the default Cava object.
+ *
+ * Returns: (nullable) (transfer none):
  */
 AstalCavaCava* astal_cava_cava_get_default() {
     static AstalCavaCava* self = NULL;
@@ -453,31 +457,61 @@ static void astal_cava_cava_class_init(AstalCavaCavaClass* class) {
     object_class->finalize = astal_cava_cava_finalize;
 
     /**
-     * AstalCava:values: (type GArray(gdouble))
+     * AstalCavaCava:values: (type GArray(gdouble))
      *
-     * A list of values
+     * A list of values, each represent the height of one bar. The values are generally between 0 and 1 but can overshoot occasionally, in which case the sensitivity will be decreased automatically if [[email protected]:autosens] is set. The array will have [[email protected]:bars] entries. If [[email protected]:stereo] is set, the first half of the array will represent the left channel and the second half the right channel, so there will be only bars/2 bars per channel. If the number of bars is odd, the last value will be 0.
      */
     astal_cava_cava_properties[ASTAL_CAVA_CAVA_PROP_VALUES] =
         g_param_spec_pointer("values", "values", "a list of values", G_PARAM_READABLE);
+    /**
+    * AstalCavaCava:active:
+    *
+    * whether or not the audio capture and visualization is running. if false the values array will not be updated.
+    */
     astal_cava_cava_properties[ASTAL_CAVA_CAVA_PROP_ACTIVE] = g_param_spec_boolean(
         "active", "active", "active", TRUE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
+    /**
+    * AstalCavaCava:bars:
+    *
+    * the number of bars the visualizer should create. 
+    */
     astal_cava_cava_properties[ASTAL_CAVA_CAVA_PROP_BARS] =
         g_param_spec_int("bars", "bars", "number of bars per channel", 1, G_MAXINT, 20,
                          G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
+    /**
+     * AstalCavaCava:autosens:
+     *
+     * When set, the sensitivity will automatically be adjusted.
+    */
     astal_cava_cava_properties[ASTAL_CAVA_CAVA_PROP_AUTOSENS] =
         g_param_spec_boolean("autosens", "autosens", "dynamically adjust sensitivity", TRUE,
                              G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
+    /**
+    * AstalCavaCava:cava:
+    *
+    * When set the output will contain visualization data for both channels.
+    */
     astal_cava_cava_properties[ASTAL_CAVA_CAVA_PROP_STEREO] = g_param_spec_boolean(
         "stereo", "stereo", "stereo", FALSE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
     astal_cava_cava_properties[ASTAL_CAVA_CAVA_PROP_NOISE] =
-        g_param_spec_double("noise_reduction", "noise_reduction", "noise reduction", 0, G_MAXDOUBLE,
+        g_param_spec_double("noise_reduction", "noise_reduction", "noise reduction", 0, 1,
                             0.77, G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
     astal_cava_cava_properties[ASTAL_CAVA_CAVA_PROP_FRAMERATE] =
         g_param_spec_int("framerate", "framerate", "framerate", 1, G_MAXINT, 60,
                          G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
+    /**
+    * AstalCavaCava:input: (type AstalCavaInput)
+    *
+    * specifies which audio server should be used.
+    */
     astal_cava_cava_properties[ASTAL_CAVA_CAVA_PROP_INPUT] =
         g_param_spec_enum("input", "input", "input", ASTAL_CAVA_TYPE_INPUT,
                           ASTAL_CAVA_INPUT_PIPEWIRE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
+    /**
+    * AstalCavaCava:source:
+    *
+    * specifies which audio source should be used. Refer to the cava docs on how to use this property.
+    */
     astal_cava_cava_properties[ASTAL_CAVA_CAVA_PROP_SOURCE] = g_param_spec_string(
         "source", "source", "source", "auto", G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
     g_object_class_install_properties(object_class, ASTAL_CAVA_CAVA_N_PROPERTIES,