C.A.V.A. (M.P.)

Console-based Audio Visualizer for ALSA (MPD and Pulseaudio)

Now with more colors! Use hex codes in config, for example:

background = '#253552'
foreground = '#FF479C'

(hex code must be within '')

thanks to anko for the gif, here is the recipe.

Demo video

Table of Contents generated with DocToc

What it is
Build requirements
Getting started
- Installing manually
- Uninstalling
- openSUSE
- Fedora
- Arch
- Ubuntu
Capturing audio
Running via ssh
Font notes
- In ttys
- In terminal emulators
Latency notes
Usage
- Controls
Configuration
- GUI Options
Thanks

What it is

C.A.V.A. is a bar spectrum audio visualizer for the Linux terminal using ALSA, pulseaudio or fifo buffer for input.

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

Build requirements

FFTW
ncursesw dev files (bundled in ncurses in arch)
Xlib/X11 dev files
SDL2 dev files
ALSA dev files
Pulseaudio dev files
libtool

Only FFTW is actually required for CAVA to compile, but for maximum usage and performance ncurses and pulseaudio and/or alsa dev files are recommended. Not sure how to get the pulseaudio dev files for other distros than debian/ubuntu or if they are bundled in pulseaudio.

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

Debian/Raspbian:

apt-get install libfftw3-dev libasound2-dev libncursesw5-dev libpulse-dev libtool libx11-dev libsdl2-dev

ArchLinux:

pacman -S base-devel fftw ncurses libx11 sdl2

openSUSE:

zypper install alsa-devel ncurses-devel fftw3-devel libX11-devel libSDL2-devel libtool

Fedora:

dnf install alsa-lib-devel ncurses-devel fftw3-devel xorg-x11-devel SDL2-devel pulseaudio-libs-devel libtool

Iniparser is also required, but if it is not already installed, a bundled version will be used.

To run the autogen script you will also need automake, libtool and git.

Getting started

./autogen.sh
./configure
make

You can use the following for compilation options:

--enable-debug          	enable debug messages and frequency table output
--enable-legacy_iniparser	enable legacy iniparser mode necessary to build cava with iniparser < 4.0

For example, turning on debugging messages:

./configure --enable-debug

Installing manually

Install cava to default /usr/local:

make install

Or you can change PREFIX, for example:

./configure --prefix=PREFIX

Uninstalling

make uninstall

openSUSE

On openSUSE you need to add jubalh's home repository to install cava via zypper. For example for Tumbleweed do:

zypper ar -f http://download.opensuse.org/repositories/home:/jubalh/openSUSE_Tumbleweed/home:jubalh.repo
zypper in cava

If you use 13.2 or 13.1 just replace openSUSE_Tumbleweed with openSUSE_13.2, adjust it to your version.

Fedora

RPM spec file

Arch

Cava is in AUR.

yaourt -S cava

The GUI branch (this) is also in AUR.

yaourt -S cava-gui-git

Ubuntu

Michael Nguyen has added CAVA to his PPA, it can be installed with:

sudo add-apt-repository ppa:tehtotalpwnage/ppa
sudo apt-get update
sudo apt-get install cava

All distro specific instalations sources might be out of date.

Capturing audio

From Pulseaudio monitor source (Easy, default if supported)

First make sure you have installed pulseaudio dev files and that cava has been built with pulseaudio support (it should be automatically if the dev files are found).

If you're lucky all you have to do is to uncomment this line in the config file under input:

method = pulse

If nothing happens you might have to use a different source than the default. The default might also be your microphone. Look at the config file for help.

From ALSA-loopback device (Tricky)

Set

method = alsa

in the config file.

ALSA can be difficult because there is no native way to grab audio from an output. If you want to capture audio straight fom 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 presistent across boot add the line snd-aloop to "/etc/modules". To keep it form beeing 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 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 on my laptop (an Asus UX31 running Ubuntu), but I had no luck with the ALSA method on my Rasberry PI (Rasbian) with an USB DAC. The PulseAudio method however works perfectly on my PI.

From mpd's fifo output

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)
}

Running via ssh

To run via ssh to an external monitor, redirect output to /dev/console:

 ~# ./cava  <> /dev/console >&0 2>&1

exit with ctrl+z then run 'bg' to keep it running after you log out.

(You must be root to redirect to console. Simple sudo is not enough: Run sudo su first.)

Font notes

Since the graphics are simply based on characters, performance is dependent on the terminal font. Unless you are running in x mode, the performance is pixel/resolution-based.

In ttys

If you run this in a TTY the program will change the font to the included cava.psf (actually a slightly modified "unifont").

In console fonts it seems that only 256 Unicode characters are supported, probably because they are bitmap fonts. I could not find a font with Unicode characters 2581-2587 (the 1/8 - 7/8 blocks used on the top of each bar to increase resolution).

So in cava.psf, the characters 1-7 are actually replaced by Unicode characters 2581-2587. When cava exits, it changes the font back. If cava exits abnormally and you notice that 1-7 are replaced by partial blocks, just change the font with setfont.

Actually, setfont is supposed to return the default font, but this usually isn't set. I haven't found another way to get the current font. So cava sets the font to "Lat2-Fixed16" when interrupted. All major distros should have it. It will revert to your default font at reboot.

In terminal emulators

In terminal emulators like xterm, the font settings is chosen in the software and cannot be changed by an application. So find your terminal settings and try out different fonts and settings. Also character spacing affects the look of the bar spectrum.

Performance is also different, urxvt is the best I found so far, while Gnome-terminal is quite slow.

Cava also disables the terminal cursor, and turns it back on on exit, but in case it terminates unexpectedly, run setterm -cursor on to get it back.

Tip: Cava will look much nicer in small font sizes. Use a second terminal emulator for cava and set the font size to 1. Warning, can cause high CPU usage and latency if the terminal window is too large!

Latency notes

If you see latency issues (sound before image) in a terminal emulator, try increasing the font size. This will reduce the number of characters that have to be shown. But if you are running in either in the graphical modes, you can shrink the window.

If your audio device has a huge buffer, you might experience that cava is actually faster than the audio you hear. This reduces the experience of the visualization. To fix this, try decreasing the buffer settings in your audio playing software.

Usage

Usage : cava [options]
Visualize audio input in terminal. 

Options:
	    -p          path to config file
	    -v          print version

Exit with ctrl+c or q.

If cava quits unexpectedly or is force killed, echo must be turned on manually with stty -echo.

Controls

Key	Description
`up` / `down`	increase/decrease sensitivity
`left` / `right`	increase/decrease bar width
`a` / `s`	increase/decrease bar spacing
`f`	toggle fullscreen (only in window modes)
`c` / `b`	change forground/background color
`r`	Reload configuration
`q` or `CTRL-C`	Quit C.A.V.A.

Configuration

As of version 0.4.0 all options are done in the config file, no more command-line arguments!

By default a configuration file is located in $XDG_CONFIG_HOME/cava/config or $HOME/.config/cava/config, but cava can also be made to use a different file with the -p option. Look in the default config file for details on the different options.

Sending cava a SIGUSR1 signal, will force cava to reload its configuration file. Thus, it behaves as if the user pressed r in the terminal. One might send a SIGUSR1 signal using pkill or killall. For example:

$ pkill -USR1 cava

Examples on how the equalizer works:

[eq]
1=0
2=1
3=0
4=1
5=0

[eq]
1=2
2=2
3=1
4=1
5=0.5

GUI

CAVA (this branch) can now run in grapical modes.

NOTE: All of these options are in the config file (usually) at ~/.config/cava/config

2nd NOTE: Remember to remove ';' in front of the options if you want to change them.

To achieve this you can change the following value to:

output = x

Or preferably:

output = sdl

Just a bit of explination. X11/Xlib utilizes hardware drawing (if availble), while SDL2 utilizes software drawing (this could be changed in the future, however). The only reason why SDL2 is kept as a option is that it works on non X11 display servers (Wayland and such), whereas X doesn't.

In the graphical modes you also have some other features, such as:

Options that are unique to 'sdl' and 'x':

Please use window category instead of general category. As those are NOT compatible

Toggle fullscreen:

fullscreen = (1 for on and 0 for off)

Toggle window border:

border = (1 to enable and 0 to disable)

Change bar width/height (units are in pixels rather than characters):

bar_width = (specify value)

bar_spacing = (specify value)

Assign the window to a specific part of the screen by changing:

alignment = 'value'

Possible values are:

'top_left', 'top', 'top_right'. 'left', 'center', 'right', 'bottom_left', 'bottom', 'bottom_right' and 'none' if you don't want to position the window automaticly.

In addition to window aligment you can adjust the window using the following options:

x_padding = (specify value)

y_padding = (specify value)

NOTE: These options don't apply if "aligment" is set to

'none'

But there are features that are unique for the 'x' mode alone, and one of them is enabling the window background to be transparent. However, you'll need a window composite manager running on your system (WARNING: generally causes slowdowns). This can be enabled by:

 transparency = (0 disable, 1 enable)

A another feature is when you set the foreground color to 'default' in x mode. It will automaticly get the average desktop color and blend in with your background, looks really nice with transparency+no borders. To enable this you just have to change:

foreground = 'default'

A screenshot with the 'default' foreground option with transparency+no borders (in X):

A quick demo showing off what can be done by enabling transparency and disabling window borders:

NOTE: To keep the window below any other (fxp. you want it to run in the background).

You can use:

keep_below = 1

This only works in X mode, however.

Thanks

Contributors:

Also thanks to dpayne for figuring out how to find the pulseaudio default sink name.

huglifetiz / cava Goto Github PK

cava's Introduction