cli-visualizer 0,1 travis-ci

CLI based audio visualizer

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 xterm-256color. To change this run

export TERM=xterm-256color


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

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


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. The color scheme must be defined at ~/.config/vis/colors/color_scheme directory. There are three different ways to specific a color, by name, by hex number, and by index.

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. There are three different ways to specific a color, by name, by hex number, and by index.

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 and the left and right margins set to 0.10.

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.

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.

#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.

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

Trouble Shooting


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.

Related Repositories



CLI based audio visualizer ...

Top Contributors

dpayne jgkamat Kaligule atyoung DuckThom juliosueiras


-   v1.1 zip tar
-   1.2 zip tar