waybar-cava(5)

💖 waybar-cava — the manual page, but make it cute 💖

okay bestie, gather round 🫶 this is waybar-cava(5), from the User Manual, and it's literally the glow-up your status bar has been waiting for. it's giving audio visualiser but make it fashion. ✨

---

🌈 NAME 🌈

waybar — the cava module 🎀

---

🦋 DESCRIPTION 🦋

okay so. this is the cava module, made for the karlstav/cava project. no cap, that's the whole vibe. 🎵

if you wanna go look at it on github (and honestly, you should, it's iconic):

https://github.com/karlstav/cava

go on, peek. i'll wait. 💅

---

🎀 FILES 🎀

• $XDG_CONFIG_HOME/waybar/config — the per user configuration file 🫶

like, this is your config, bestie. your personal file. your main character document. 💖

---

✨ ADDITIONAL FILES ✨

so libcava lives in these places — it's lowkey just vibing in your filesystem, here's exactly where to find it: 🔍

1. /usr/lib/libcava.so or /usr/lib64/libcava.so
2. /usr/lib/pkgconfig/cava.pc or /usr/lib64/pkgconfig/cava.pc
3. /usr/include/cava

---

part 1 done, bestie — more coming, don't go anywhere 🧚💜

✨ CONFIGURATION ✨

okay bestie, this is the config tea ☕ — every option, its type, its default, and what it actually does. no skips, no cap. if you're following along from the earlier sections, we're picking up right here. 💅

• cava_config — type: string, default: (empty) — the path where the cava configuration file is placed to. 🎀
• framerate — type: integer, default: 30 — frames per second. it's used as a replacement for interval. ✨
• autosens — type: integer, default: 1 — will attempt to decrease sensitivity if the bars peak. 🦋
• sensitivity — type: integer, default: 100 — manual sensitivity in %. it's recommended to be omitted when autosens = 1. 🌸
• bars — type: integer, default: 12 — the number of bars. 💖
• lower_cutoff_freq — type: long integer, default: 50 — lower cutoff frequencies for lowest bars the bandwidth of the visualizer. iykyk 💜
• higher_cutoff_freq — type: long integer, default: 10000 — higher cutoff frequencies for highest bars the bandwidth of the visualizer. 🌈
• sleep_timer — type: integer, default: 5 — seconds with no input before cava main thread goes to sleep mode. 😴
• hide_on_silence — type: bool, default: false — hides the widget if no input (after sleep_timer elapsed). 🙈
• method — type: string, default: pulse — audio capturing method. possible methods are: pipewire, pulse, alsa, fifo, sndio or shmem. 🔥
• source — type: string, default: auto — see cava configuration. 👑
• sample_rate — type: long integer, default: 44100 — see cava configuration. ⭐
• sample_bits — type: integer, default: 16 — see cava configuration. 🍓
• stereo — type: bool, default: true — visual channels. 🎧
• reverse — type: bool, default: false — displays frequencies the other way around. 🔄
• bar_delimiter — type: integer, default: 0 — each bar is separated by a delimiter. use decimal value in ascii table (i.e. 59 = ";"). 0 means no delimiter. 💅
• monstercat — type: bool, default: false — disables or enables the so-called "Monstercat smoothing" with or without "waves". 🐱
• waves — type: bool, default: false — disables or enables the so-called "Monstercat smoothing" with or without "waves". 🌊
• noise_reduction — type: double, default: 0.77 — range between 0 - 1. the raw visualization is very noisy, this factor adjusts 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, defaults to 2. This sets the delay before the fetch-audio-source thread starts doing its thing. Here's the tea: on the author's machine, Waybar boots up way faster than the pipewire audio server does, and without a lil' delay the cava module just 💀s because pipewire isn't ready yet.
• ascii_max_range — integer, defaults to 7. You literally cannot set this one directly, bestie. The value is dictated by how many icons are chilling in the format-icons array. It's giving "the icons decide your fate" ✨
• data_format — string, defaults to asci. Also impossible to set. Waybar hard-sets it to = asci for its own internal needs. Not your business, not your problem 💅
• raw_target — string, defaults to /dev/stdout. Same situation: you can't set it. Waybar sets it to = /dev/stdout for internal needs. Periodt.

---

Configuration can be provided as:

• The only cava configuration file, handed over via cava_config. Everything else in the config can just be skipped, no thoughts head empty 🫶
• Without a cava configuration file. In that case cava has to be configured through the provided list of configuration options.
• Mix. When you provide both a cava configuration file and configuration options. In that case, Waybar applies the configuration file first, and then overrides the particular options with the provided list of configuration options. Layers, bestie. Onion energy 🧅

---

🌈 ACTIONS 🌈

So basically: the one action string you get is mode, and it flips the main cava thread and the fetch-audio-source thread back and forth between pause and resume. Toggle queen 👑

---

✨ DEPENDENCIES ✨

• iniparser
• fftw3

Those two are the whole entourage. No extras, no hangers-on 💖

---

🛠️ SOLVING ISSUES 🛠️

1. On start, Waybar throws an exception that says:

error while loading shared libraries: libcava.so: cannot open shared object file: No such file or directory

This can happen when libcava hasn't been registered in the system for some reason. sudo ldconfig should help. Slay, fixed 🔥

2. Waybar is starting, but the cava module doesn't react to the music. Rude. In such cases:
   1. First, you need to make sure the usual cava application is working as well.
   2. If it is, you need to comment out all configuration options. Uncomment cava_config and provide the path to the working cava config.
   3. You might have set too huge or too small an input_delay. Try setting it up to 4 seconds, restart waybar, and check again 4 seconds past. Usually, even on weak machines, it should be enough.
   4. You might have accidentally switched the action mode to pause mode. 🙈 Been there.

---

🚨 RISING ISSUES 🚨

For clear understanding: this module is a cava API's consumer. So for any bugs related to the cava engine, you should contact the Cava upstream (https://github.com/karlstav/cava) — with 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:

1. cava upstream
2. libcava upstream.

In case cava releases a new version and you're wanna get it, you should raise an issue to libcava (https://github.com/LukashonakV/cava) with the title [Bump]x.x.x where x.x.x is the cava release version. Title format matters, bestie, don't freestyle it 💅

---

💖 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"
     }
},

---

And that's a wrap on the whole page, babes 🎀 that last footer line was waybar-cava — the waybar-cava manual page, section 5 — dated 2024-04-01. Go make your bars bounce, you absolute icon 👑✨