From 4dff1d4b2bd9038c22a329df04368fe36045d77b Mon Sep 17 00:00:00 2001 From: Viktar Lukashonak Date: Wed, 19 Jul 2023 20:44:52 +0300 Subject: [PATCH] cava man page Signed-off-by: Viktar Lukashonak --- man/waybar-cava.5.scd | 182 ++++++++++++++++++++++++++++++++++++++++++ man/waybar.5.scd.in | 1 + meson.build | 1 + 3 files changed, 184 insertions(+) create mode 100644 man/waybar-cava.5.scd diff --git a/man/waybar-cava.5.scd b/man/waybar-cava.5.scd new file mode 100644 index 00000000..3d3762bf --- /dev/null +++ b/man/waybar-cava.5.scd @@ -0,0 +1,182 @@ +waybar-cava(5) "waybar-cava" "User Manual" + +# NAME + +cava + +# DESCRIPTION + +*cava* module for karlstav/cava project. See it on github: https://github.com/karlstav/cava. + + +# FILES + +$XDG_CONFIG_HOME/waybar/config ++ + Per user configuration file + +# ADDITIONAL FILES + +libcava lives in: + +. /usr/lib/libcava.so or /usr/lib64/libcava.so +. /usr/lib/pkgconfig/cava.pc or /usr/lib64/pkgconfig/cava.pc +. /usr/include/cava + +# CONFIGURATION + +[- *Option* +:- *Typeof* +:- *Default* +:- *Description* +|[ *cava_config* +:[ string +:[ +:< Path where cava configuration file is placed to +|[ *framerate* +:[ integer +:[ 30 +:[ rames per second. Is used as a replacement for *interval* +|[ *autosens* +:[ integer +:[ 1 +:[ Will attempt to decrease sensitivity if the bars peak +|[ *sensitivity* +:[ integer +:[ 100 +:[ Manual sensitivity in %. It's recommended to be omitted when *autosens* = 1 +|[ *bars* +:[ integer +:[ 12 +:[ The number of bars +|[ *lower_cutoff_freq* +:[ long integer +:[ 50 +:[ Lower cutoff frequencies for lowest bars the bandwidth of the visualizer +|[ *higher_cutoff_freq* +:[ long integer +:[ 10000 +:[ Higher cutoff frequencies for highest bars the bandwidth of the visualizer +|[ *sleep_timer* +:[ integer +:[ 5 +:[ Seconds with no input before cava main thread goes to sleep mode +|[ *method* +:[ string +:[ pulse +:[ Audio capturing method. Possible methods are: pipewire, pulse, alsa, fifo, sndio or shmem +|[ *source* +:[ string +:[ auto +:[ See cava configuration +|[ *sample_rate* +:[ long integer +:[ 44100 +:[ See cava configuration +|[ *sample_bits* +:[ integer +:[ 16 +:[ See cava configuration +|[ *stereo* +:[ bool +:[ true +:[ Visual channels +|[ *reverse* +:[ bool +:[ false +:[ Displays frequencies the other way around +|[ *bar_delimiter* +:[ integer +:[ 0 +:[ Each bar is separated by a delimiter. Use decimal value in ascii table(i.e. 59 = ";"). 0 means no delimiter +|[ *monstercat* +:[ bool +:[ false +:[ Disables or enables the so-called "Monstercat smoothing" with of without "waves" +|[ *waves* +:[ bool +:[ false +:[ Disables or enables the so-called "Monstercat smoothing" with of without "waves" +|[ *noise_reduction* +:[ double +:[ 0.77 +:[ Range between 0 - 1. The raw visualization is very noisy, this factor adjust the integral and gravity filters to keep the signal smooth. 1 - will be very slow and smooth, 0 - will be fast but noisy +|[ *input_delay* +:[ integer +:[ 2 +:[ Sets the delay before fetching audio source thread start working. On author machine Waybar starts much faster then pipewire audio server, and without a little delay cava module fails due to pipewire is not ready +|[ *ascii_max_range* +:[ integer +:[ 7 +:[ It's impossible to set it directly. The value is dictated by the number of icons in the array *format-icons* +|[ *data_format* +:[ string +:[ asci +:[ It's impossible to set it. Waybar sets it to = asci for internal needs +|[ *raw_target* +:[ string +:[ /dev/stdout +:[ It's impossible to set it. Waybar sets it to = /dev/stdout for internal needs + +Configuration can be provided as: +- The only cava configuration file which is provided through *cava_config*. The rest configuration can be skipped +- Without cava configuration file. In such case cava should be configured through provided list of the configuration option +- Mix. When provided both And cava configuration file And configuration options. In such case waybar applies configuration file first then overrides particular options by the provided list of configuration options + +# ACTIONS + +[- *String* +:- *Action* +|[ *mode* +:< Switch main cava thread and fetching audio source thread from/to pause/resume + +# DEPENDENCIES + +- iniparser +- fftw3 + +# SOLVING ISSUES + +. On start Waybar throws an exception "error while loading shared libraries: libcava.so: cannot open shared object file: No such file or directory". + It might happen when libcava for some reason hasn't been registered in the system. sudo ldconfig should help +. Waybar is starting but cava module doesn't react on the music + 1. In such case for at first need to make sure usual cava application is working as well + 2. If so, need to comment all configuration options. Uncomment cava_config and provide the path to the working cava config + 3. You might set too huge or too small input_delay. Try to setup to 4 seconds, restart waybar and check again 4 seconds past. Usual even on weak machines it should be enough + 4. You might accidentally switched action mode to pause mode + +# RISING ISSUES + +For clear understanding: this module is a cava API's consumer. So for any bugs related to cava engine you should contact to Cava upstream(https://github.com/karlstav/cava) ++ +with the one Exception. Cava upstream doesn't provide cava as a shared library. For that this module author made a fork libcava(https://github.com/LukashonakV/cava). ++ +So the order is: +. cava upstream +. libcava upstream. +In case when cava releases new version and you're wanna get it, it should be raised an issue to libcava(https://github.com/LukashonakV/cava) with title ++ +\[Bump\]x.x.x where x.x.x is cava release version. + +# EXAMPLES + +``` +"cava": { +// "cava_config": "$XDG_CONFIG_HOME/cava/cava.conf", + "framerate": 30, + "autosens": 1, +// "sensitivity": 100, + "bars": 14, + "lower_cutoff_freq": 50, + "higher_cutoff_freq": 10000, + "method": "pulse", + "source": "auto", + "stereo": true, + "reverse": false, + "bar_delimiter": 0, + "monstercat": false, + "waves": false, + "noise_reduction": 0.77, + "input_delay": 2, + "format-icons" : ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█" ], + "actions": { + "on-click-right": "mode" + } + }, +``` diff --git a/man/waybar.5.scd.in b/man/waybar.5.scd.in index 0b3dc748..a8376697 100644 --- a/man/waybar.5.scd.in +++ b/man/waybar.5.scd.in @@ -268,6 +268,7 @@ Valid options for the (optional) "orientation" property are: "horizontal", "vert - *waybar-backlight(5)* - *waybar-battery(5)* - *waybar-bluetooth(5)* +- *waybar-cava(5)* - *waybar-clock(5)* - *waybar-cpu(5)* - *waybar-custom(5)* diff --git a/meson.build b/meson.build index f8b4a2d6..a4592b10 100644 --- a/meson.build +++ b/meson.build @@ -423,6 +423,7 @@ if scdoc.found() main_manpage_path, 'waybar-backlight.5.scd', 'waybar-battery.5.scd', + 'waybar-cava.5.scd', 'waybar-clock.5.scd', 'waybar-cpu.5.scd', 'waybar-custom.5.scd',