cava

CAVA [![Build Status](https://github.com/karlstav/cava/workflows/build-and-test/badge.svg)](https://github.com/karlstav/cava/actions)
====================

**C**ross-platform **A**udio **V**isu**a**lizer

by [Karl Stavestrand](mailto:karl@stavestrand.no)

Now also supports [dumb terminals](https://github.com/karlstav/cava/blob/master/TERMINAL.md)!

![spectrum](https://github.com/karlstav/cava/blob/master/example_files/cava.gif "spectrum")

[Demo video](https://youtu.be/9PSp8VA6yjU)

- [What it is](#what-it-is)
- [Installing](#installing)
  - [From Source](#from-source)
  - [Package managers](#package-managers)
- [Capturing audio](#capturing-audio)
  - [Pulseaudio](#pulseaudio)
  - [Pipewire](#pipewire)
  - [ALSA](#alsa)
  - [MPD](#mpd)
  - [Sndio](#sndio)
  - [OSS](#oss)
  - [JACK](#jack)
  - [squeezelite](#squeezelite)
  - [macOS](#macos-1)
  - [Windows](#windows)
- [Running via ssh](#running-via-ssh)
- [Troubleshooting](#troubleshooting)
- [Usage](#usage)
  - [Controls](#controls)
- [Configuration](#configuration)
- [Using cava in other applications](#using-cava-in-other-applications)
  - [cavacore](#cavacore-library)
  - [Raw Output](#raw-output)
- [Contribution](#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](http://www.fftw.org/)
* libtool
* automake
* pkgconf
* build-essentials
* [iniparser](https://github.com/ndevilla/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](http://www.gnu.org/software/ncurses/) (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, additional audio development files may be needed depending on your input backend (pipewire, pulseaudio, alsa, sndio, jack or portaudio). On macOS, the built-in Core Audio framework is supported without extra audio capture libraries.

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 libasound