CAVA

Cross-platform Audio Visualizer

by Karl Stavestrand

Now also supports dumb terminals!

Demo video

• What it is
• Installing
  • From Source
  • Package managers
• Capturing audio
  • Pulseaudio
  • Pipewire
  • ALSA
  • MPD
  • Sndio
  • OSS
  • JACK
  • squeezelite
  • macOS
  • Windows
• Running via ssh
• Troubleshooting
• Usage
  • Controls
• Configuration
• Using cava in other applications
  • cavacore
  • Raw Output
• Contribution

What it is

Cava is a bar spectrum audio visualizer for terminal or desktop (SDL).

works on:

• Linux
• FreeBSD
• macOS
• Windows

This program is not intended for scientific use. It's written to look responsive and aesthetic when used to visualize music.

Installing

From Source

Installing Build Requirements

Required components:

• FFTW
• libtool
• automake
• pkgconf
• build-essentials
• iniparser

Recommended components:

The development lib of one of these audio frameworks, depending on your distro:

• ALSA
• Pulseaudio
• Pipewire
• Portaudio
• Sndio
• JACK

Optional components:

• SDL2 dev files
• autoconf-archive (needed for setting up OpenGL)
• ncursesw dev files (bundled in ncurses in arch)

Only FFTW, iniparser and the build tools are actually required for CAVA to compile, but this will only give you the ability to read from fifo files. To capture audio directly from your system pipewire, pulseaudio, alsa, sndio, jack or portaudio dev files are required (depending on what audio system you are using).

Ncurses can be used as an alternative output method if you have issues with the default one. But it is not required.

All the requirements can be installed easily in all major distros:

FreeBSD

pkg install autoconf automake fftw3 iniparser jackit libglvnd libtool pkgconf psftools sdl2 sndio

Additionally, run these commands on FreeBSD before building:

export CFLAGS="-I/usr/local/include"
export LDFLAGS="-L/usr/local/lib"

Debian/Ubuntu:

sudo apt install build-essential libfftw3-dev libasound2-dev libpulse-dev libtool automake libiniparser-dev libsdl2-2.0-0 libsdl2-dev libpipewire-0.3-dev libjack-jackd2-dev pkgconf

ArchLinux:

pacman -S base-devel fftw alsa-lib iniparser pulseaudio pkgconf

openSUSE:

zypper install alsa-devel fftw3-devel libpulse-devel libtool pkgconf

Fedora:

dnf install alsa-lib-devel fftw3-devel pulseaudio-libs-devel libtool iniparser-devel pkgconf

macOS:

First install homebrew if you have't already:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Then install prerequisites:

brew install fftw libtool automake pkgconf portaudio iniparser

The installation location for Homebrew packages is different between Intel Macs and Apple Silicon Macs. As such, the commands will be a little bit different. You can find out which type you have here

For both machines, run these commands to fix macOS not finding libtool:

export LIBTOOL=`which glibtool`
export LIBTOOLIZE=`which glibtoolize`
ln -s `which glibtoolize` /usr/local/bin/libtoolize

Note that the file name may be a little bit different depending on the versions, but the directory should be the same.

Additionally, run these commands on Apple Silicon Macs so that ./configure can find the Homebrew packages:

export LDFLAGS="-L/opt/homebrew/lib"
export CPPFLAGS="-I/opt/homebrew/include"

Intel Mac instructions tested on macOS Big Sur.

Apple Silicon instructions tested on macOS Ventura.

Windows:

Dependencies can be resolved with vcpkg in the cmake

cmake --preset vcpkg
cd build
cmake --build . --config Release

pacman (msys2/mingw) can also be used pacboy cc cmake fftw glew ninja SDL2 cmake -bin cmake --build bin 1

Building

First of all clone this repo and cd in to it, then run:

./autogen.sh
./configure
make

If you have a recommended component installed, but do not wish to use it (perhaps if building a binary on one machine to be used on another), then the corresponding feature can be disabled during configuration (see configure --help for details).

For windows there is a VS solution file in the cava_win folder.

Installing

Install cava to default /usr/local:

make install

Or you can change PREFIX, for example:

./configure --prefix=PREFIX

Uninstalling

make uninstall

Package managers

All distro specific installation sources might be out of date. Please check version before reporting any issues here.

FreeBSD

pkg install cava

openSUSE

Tumbleweed users have cava in their repo. They can just use:

zypper in cava

Leap users need to add the multimedia:apps repository first:

zypper ar -f obs://multimedia:apps/openSUSE_Leap_42.2 multimedia

If you use another version just replace openSUSE_Leap_42.2 with openSUSE_13.2, adjust it to your version.

Fedora

Cava is available in Fedora 26 and later. You can install Cava by running:

dnf install cava

Arch

Cava is available in Arch Linux official repo:

pacman -S cava

Ubuntu/Debian

Ubuntu 20.10 or more recent / Debian 12 (Bookworm)

sudo apt install cava

Older Ubuntu

Harshal Sheth has added CAVA to his PPA, it can be installed with:

add-apt-repository ppa:hsheth2/ppa
apt update
apt install cava

macOS

cava is in homebrew.

brew install cava

Capturing audio

All config options are set in the config file.

Pipewire

method = pipewire

This is the default input method if supported on your system. The default source is auto and will most likely be your currently selected output. If you run wireplumber you can use wpctl to get the object.path or object.serial of the desired device to visualize.

e.g.

source = alsa:pcm:3:front:3:playback

Pulseaudio

method = pulse

The default source is auto and should be your currently selected output.

If nothing happens you might have to use a different source than the default. The default might also be your microphone.

ALSA

method = alsa

ALSA can be difficult because there is no native way to grab audio from an output. If you want to capture audio straight from the output (not just mic or line-in), you must create an ALSA loopback interface, then output the audio simultaneously to both the loopback and your normal interface.

To create a loopback interface simply run:

sudo modprobe snd_aloop

Hopefully your aplay -l should now contain a loopback interface.

To make it persistent across boot add the line snd-aloop to "/etc/modules". To keep it from being loaded as the first soundcard add the line options snd-aloop index=1 to "/etc/modprobe.d/alsa-base.conf", this will load it at '1'. You can replace '1' with whatever makes most sense in your audio setup.

Playing the audio through your Loopback interface makes it possible for cava to capture it, but there will be no sound in your speakers. In order to play audio on the loopback interface and your actual interface you must make use of the ALSA multi channel.

Look at the included example file example_files/etc/asound.conf on how to use the multi channel. I was able to make this work with an HD Audio Intel PCH sound card, but I had no luck with a USB DAC.

Read more about the ALSA method here.

If you are having problems with the alsa method on Raspberry PI, try enabling mmap by adding the following line to /boot/config.txt and reboot:

dtoverlay=i2s-mmap

dmix

@reluekiss, was able to make cava work with dmix. Check out the example config in example_files/etc/asound_dmix.conf and issue 534.

mpd

Add these lines in mpd:

audio_output {
    type                    "fifo"
    name                    "my_fifo"
    path                    "/tmp/mpd.fifo"
    format                  "44100:16:2"
}

Uncomment and change input method to fifo in the config file.

The path of the fifo can be specified with the source parameter.

I had some trouble with sync (the visualizer was ahead of the sound). Reducing the ALSA buffer in mpd fixed it:

audio_output {
        type            "alsa"
        name            "My ALSA"
        buffer_time     "50000"   # (50ms); default is 500000 microseconds (0.5s)
}

Sndio

method = sndio

Sndio is the audio framework used on OpenBSD, but it's also available on FreeBSD, NetBSD and Linux. So far this is only tested on FreeBSD, but it's probably very similar on other operating systems. The following example demonstrates how to setup CAVA for sndio on FreeBSD (please consult the OSS section for a deeper explanation of the various pcmX sound devices and the corresponding /dev/dspX audio devices in this example).

$ ca