CLI based audio visualizer
C++ Makefile Python Other
Clone or download

Table of Contents generated with DocToc


Coverity Scan Build Status


Command line visualizer. Supports mpd, with experimental support for alsa and pulseaudio.

This project was heavily inspired by C.A.V.A, ncmpcpp, and rainbow





Installing Pre-requisites

fftw and ncursesw libraries are required to build. Note that ncurses with wide character support is needed.

A C++ compiler that supports C++14 is also needed. On arch linux, the latest g++ or clang++ will work.

256 Colors

In order to show the colors, you need a terminal with 256 color support.rxvt-unicode out of the box.

For xterm, the default $TERM setting needs to be changed to rxvt-256color. To change this run

export TERM=rxvt-256color

Setting TERM to xterm-256color may also work but seems to cause issues with rendering of the visualizers in some terminals.


sudo apt-get install libfftw3-dev libncursesw5-dev

For pulseaudio support, the pulseaudio library also needs to be installed

sudo apt-get install libpulse-dev

Older versions of Ubuntu also need newer a newer gcc compiler. Note, while this should be safe, it will upgrade some base libc libraries that might break your system.

sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install gcc-4.9 g++-4.9

Arch Linux

In arch, the ncursesw is bundled with the ncurses package.

sudo pacman -S ncurses fftw


sudo dnf install fftw-devel ncurses-devel pulseaudio-libs-devel


Solus requires a handful of development packages and creating a link for libtinfo before installing.

sudo eopkg it -c system.devel
sudo eopkg install fftw fftw-devel ncurses ncurses-devel pulseaudio-devel
sudo ln -s /usr/lib/ /usr/lib/ # Should already be there, but just in case.
sudo ln -s /usr/lib/ /usr/lib/


Mac OS X

Mac os x has a version of ncurses builtin, but a newer version is required.

brew install fftw
brew tap homebrew/dupes
brew install ncurses


After the pre-requisites have been installed, run the install script.


The configuration file is installed under "~/.config/vis/config".

Older version of Ubuntu need to compile with the newer g++ compiler.

export CXX=g++-4.9

Arch Linux

The Arch Linux install is much simpler since an AUR package exist for cli-visualizer.

yaourt -S cli-visualizer

You will have to copy config and colors manually.


At least one of the following needs to be configured (and linked in the config): mpd, alsa and pulseaudio

MPD Setup

The visualizer needs to use mpd's fifo output file to read in the audio stream. To do this, add the following lines to your mpd config file.

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

If you have any sync issues with the audio where the visualizer either get ahead or behind the music, try lowering the audio buffer in your mpd config.

audio_output {
    #this sets the buffer time to 50,000 microseconds
    buffer_time     "50000"

ALSA Setup

WARNING: alsa support is very very experimental. It is very possible that it will be completely broken on various systems and could cause weird/bad behaviour.

Similar to the MPD setup, the visualizer needs to use a fifo output file to read in the alsa audio stream. To do this, add the following lines to your alsa config file, usually at /etc/asound.conf. If the file does not exist create it under /etc/asound.conf.

pcm.!default {
    type file               # File PCM
    slave.pcm "hw:0,0"      # This should match the playback device at /proc/asound/devices
    file "|safe_fifo /tmp/audio" #safe_fifo will be in the cli-visualizer/bin/safe_fifo directory
    format raw              # File format ("raw" or "wav")
    perm 0666               # Output file permission (octal, def. 0600)

Next change the visualizer config ~/.config/vis/config to point to the new fifo file


A normal fifo file can not be used since otherwise no sound would work unless the fifo file is being read. This effectively means that no sound would be played if the visualizer is not running. To get around this issue a helper program safe_fifo is used. The safe_fifo program is essentially a non-blocking fifo file, it takes stdin and writes it to a fifo files given as the first parameter. If the fifo buffer is full, it clears the buffer and writes again.

Note that alsa support is still very experimental. There are a couple of caveats with this approach. Firstly safe_fifo must in a location alsa can find it. If you are building from source it us under cli-visualizer/bin/safe_fifo. Secondly slave.pcm must match whatever your alsa playback device is.

ALSA with dmix

On sound cards that do not support hardware level mixing, alsa uses dmix to allow playback from multiple applications at once. In order to make this work with the visualizer a dmixer plugin needs to be defined in /etc/asound.conf and the visualizer pcm set to use dmixer instead of the hardware device directly. This configuration might will change slightly depending on the system.

This is an example asound.conf for Intel HD Audio.

pcm.dmixer { 
    type dmix 
    ipc_key 1024
    ipc_key_add_uid false
    ipc_perm 0666            # mixing for all users
    slave { 
        pcm "hw:0,0" 
        period_time 0 
        period_size 1024 
        buffer_size 8192
        rate 44100
    bindings { 
        0 0 
        1 1 

pcm.dsp0 { 
    type plug 
    slave.pcm "dmixer" 

pcm.!default { 
    type plug 
    slave.pcm "dmixer" 

pcm.default { 
   type plug 
   slave.pcm "dmixer" 

ctl.mixer0 { 
    type hw 
    card 0 

pcm.!default {
    type file               # File PCM
    slave.pcm "dmixer"      # Use the dmixer plugin as the slave pcm
    file "|safe_fifo /tmp/audio"
    format raw              # File format ("raw" or "wav")
    perm 0666               # Output file permission (octal, def. 0600)

Pulse Audio Setup (Easy)

Pulse audio should be the easiest to setup out of all the options. In order for this to work pulseaudio must be installed and vis must be built with pulseaudio enabled. To build with pulseaudio support run make ENABLE_PULSE=1.

To enable pulse audio in the vis config set audio sources to pulse with


If this does not work, then vis has most likely not guess the correct sink to use. Try switching the pulseaudio source vis uses. A list can be found by running the command pacmd list-sinks | grep -e 'name:' -e 'index'. The correct pulseaudio source can then be set with



Start with



Key Description
space Switch visualizers
q or CTRL-C Quit
r Reload config
c Next color scheme
s Toggle Mono/Stereo Mode
+ Increase scaling by 10%
- Decrease scaling by 10%


Reloading Config

The config can be reload while vis is running by either pressing the r key or by sending the USR1 signal to vis. Sending the USR1 signal can be done with killall -USR1 vis, this is useful if you want to dynamically reload colors from a script.


The display colors and their order can be changed by switching the color scheme in the config under colors.scheme. This is a comma separated list of color schemes. Each color scheme must be defined at ~/.config/vis/colors/<name_of_the_color_scheme>. There are three different ways to specific a color within the scheme: by name, by hex number, and by index.

An example color scheme configuration with only one scheme would be


Using two color schemes


Note, vis does not override or change any of the terminal colors. All colors will be influenced by whatever terminal settings are set by the users terminal. Usually these colors are specified in .Xdefaults.

Color Schemes by Visualizer

Each visualizer supports its own list of color schemes. This will control the colors of a particular visualizer without effecting the others and will override the global defined by colors.scheme.

An example of settings the spectrums visualizer to rainbow color scheme and the default for other visualizers to the blue color scheme.


Color Gradients

Gradients are turned on by default. To disable gradients add gradient=false to the top of the color scheme file. Note this is NOT in the main config but instead in the color scheme file.

Color scheme example with gradients disabled.


Color scheme example with gradients enabled that blends red to blue.


RGB colors

The color scheme can be defined in two ways with RGB values or by index. The RGB values are defined as a hex color code, they are useful for creating a 256 bit color scheme. The displayed color will not be the true color, but instead an approximation of the color based on 256-bit terminal colors.

RGB color scheme example


Color indexes

The second way to define a color scheme is by the color index. Specifically this is the exact color index used by ncurses. Color indexes are useful for creating a visualizer that matches the terminal's set color scheme.

Color index color scheme example



All the basic 16 terminal colors from 0-16 in-order. The spectrum colors can be ordered in any you want, this example was done in order to show all colors.

Color names

The third way to define a color scheme is by the color name. Only 8 color names are supported: black, blue, cyan, green, yellow, red, magenta, white. Note that these 8 colors are the basic terminal colors and are often set by a terminal's color scheme. This means that the color name might not match the color shown since the terminal theme might change it. For example, dark themes often set white to something dark since white is usually the default color for the terminal background.


A color scheme with only one color blue.


The spectrum visualizer allows for many different configuration options.


There are three different smoothing modes, monstercat, sgs, none.

#Available smoothing options are monstercat, sgs, none.
Sgs Smoothing

SGS smoothing Savitzky-Golay filter. There are a couple of options for sgs smoothing.

The first option is controlling the number of smoothing passes done when rendering the bars. Increasing this number with make the spectrum smoother. This is set with visualizer.sgs.smoothing.passes.

The second option is the number of neighbors to look at when smoothing. This is set with visualizer.sgs.smoothing.points. This should always be an odd number. A larger number will generally increase the smoothing since more neighbors will be looked at.


Default sgs smoothing.


Sgs smoothing with number of passes set to 5.

MonsterCat Smoothing

Monster cat smoothing is inspired by the monster cat youtube channel ( To control the amount of smoothing for montercat use visualizer.monstercat.smoothing.factor. The default smoothing factor for monstercat is 1.5. Increase the smoothing factor by a lot could hurt performance.


No Smoothing

Smoothing can be completely turned off by setting the smoothing option to none.


Spectrum with smoothing off



This configures the falloff effect on the spectrum visualizer. This effect creates a slow fall in bar height. Available falloff options are fill,top,none. The default falloff option is fill.


With the top setting the falloff effect is only applied to the top character in the bar. This creates a gap between the main bar and the top falloff character.


top falloff effect with the spectrum character set to #.

The fill option leaves no gaps between the very top character and the rest of the bar.


fill falloff effect with the spectrum character set to #.

The none option removing the falloff effect entirely..


Falloff effect removed with the spectrum character set to #.

Spectrum Appearance

Certain aspects of the spectrum appearance can be controlled through the config.

The bar width can be controlled to make it wider or narrower. The default is 2.


Bar width set to 5.

The spacing between bars can also be controlled to make it wider or narrower. The default is 1.


Bar spacing set to 0.

The margin widths of the spectrum visualizer can also be controlled. The margins are set in percent of total screen for spectrum visualizer. All margin percentages default to 0.0.


Spectrum with the top margin set to 0.30, stereo mode set to false, and the left right margins set to 0.10.

Turn stereo mode off to show only one set of bars.


Normally the bars are ordered so that the lowest frequencies are handled by the left most bars and the highest frequencies by the right most bars. The reversed option gives the option to reverse this so that the highest frequencies come first.



Spectrum with reverse set to true.


The spectrum visualizer should auto-scale, but for lorenz and ellipse visualizers scaling is based off volume. If your music volume is a lot lower than the system volume then you can scale the visualizers with the settings


This setting can also be controlled with +/- keys.

Full configuration example

#Refresh rate of the visualizers. A really high refresh rate may cause screen tearing. Default is 20.

#Defaults to "/tmp/mpd.fifo"

#If set to false the visualizers will use mono mode instead of stereo. Some visualizers will
#behave differently when mono is enabled. For example, spectrum show two sets of bars.

#Specifies how often the visualizer will change in seconds. 0 means do not rotate. Default is 0.

#Configures the samples rate and the cutoff frequencies.

##Applies scaling factor to both lorenz and ellipse visualizers. This is useful when the system audio is set
#to a low volume.

#Configures the visualizers and the order they are in. Available visualizers are spectrum,lorenz,ellipse.
#Defaults to spectrum,ellipse,lorenz

#Configures what character the spectrum visualizer will use. Specifying a space (e.g " ") means the
#background will be colored instead of the character. Defaults to " ".

#Spectrum bar width. Defaults to 1.

#The amount of space between each bar in the spectrum visualizer. Defaults to 1. It's possible to set this to
#zero to have no space between bars

#Available smoothing options are monstercat, sgs, none. Defaults to sgs.

#This configures the falloff effect on the spectrum visualizer. Available falloff options are fill,top,none.
#Defaults to "fill"

#Configures how fast the falloff character falls. This is an exponential falloff so values usually look
#best 0.9+ and small changes in this value can have a large effect. Defaults to 0.95

#Margins in percent of total screen for spectrum visualizer. All margins default to 0

#Reverses the direction of the spectrum so that high freqs are first and low freqs last. Defaults to false.

#Sets the audio sources to use. Currently available ones are "mpd" and "alsa"Sets the audio sources to use.
#Currently available ones are "mpd", "pulse", and "alsa". Defaults to "mpd".

##vis tries to find the correct pulseaudio sink, however this will not work on all systems.
#If pulse audio is not working with vis try switching the audio source. A list can be found by running the
#command pacmd list-sinks  | grep -e 'name:'  -e 'index'

#This configures the sgs smoothing effect on the spectrum visualizer. More points spreads out the smoothing
#effect and increasing passes runs the smoother multiple times on reach run. Defaults are points=3 and passes=2.

#Configures what character the ellipse visualizer will use. Specifying a space (e.g " ") means the
#background will be colored instead of the character. Defaults to " ".

#The radius of each color ring in the ellipse visualizer. Defaults to 2.

## Turns off overriding the user's terminal colors

#Specifies the color scheme. The color scheme must be in ~/.config/vis/colors/ directory. Default is "colors"

Trouble Shooting


vis is overwriting my terminal colorscheme

Turn off overriding terminal colors.


Due to the way terminal color schemes work, there is no portable way for ncurses to get the original color scheme. By default it overrides the user's terminal colors with the visualizer colors. It does this to get a smoother transition between gradients, however this overrides the user's terminal color scheme.

Tearing our corrupt output

This is usually and issue with ncurses versions past versions 6.0+20170729. Try changing the TERM variable to rxvt with

export TERM=rxvt-256color


vis hangs with no output

It is possible there is a naming conflict with an existing BSD tool vis. Try running vis -h. If the output looks something like

mac ❯❯❯ vis -h
vis: illegal option -- h
usage: vis [-cbflnostw] [-F foldwidth] [file ...]

then there is a naming conflict with cli-visualizer. To fix this issue, put /usr/local/bin before /usr/bin/ in $PATH.