[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-6477":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":40,"readmeContent":41,"aiSummary":42,"trendingCount":16,"starSnapshotCount":16,"syncStatus":17,"lastSyncTime":43,"discoverSource":44},6477,"cava","karlstav\u002Fcava","karlstav","Cross-platform Audio Visualizer","",null,"C",6197,290,39,11,0,2,14,86,9,38.39,"MIT License",false,"master",true,[27,28,29,30,31,32,33,34,35,36,37,38,39],"alsa","audio-visualizer","freebsd","glsl-shaders","linux","macos","ncurses","pipewire","portaudio","pulseaudio","sdl2","sndio","windows","2026-06-12 02:01:25","CAVA [![Build Status](https:\u002F\u002Fgithub.com\u002Fkarlstav\u002Fcava\u002Fworkflows\u002Fbuild-and-test\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fkarlstav\u002Fcava\u002Factions)\n====================\n\n**C**ross-platform **A**udio **V**isu**a**lizer\n\nby [Karl Stavestrand](mailto:karl@stavestrand.no)\n\nNow also supports [dumb terminals](https:\u002F\u002Fgithub.com\u002Fkarlstav\u002Fcava\u002Fblob\u002Fmaster\u002FTERMINAL.md)!\n\n![spectrum](https:\u002F\u002Fgithub.com\u002Fkarlstav\u002Fcava\u002Fblob\u002Fmaster\u002Fexample_files\u002Fcava.gif \"spectrum\")\n\n[Demo video](https:\u002F\u002Fyoutu.be\u002F9PSp8VA6yjU)\n\n- [What it is](#what-it-is)\n- [Installing](#installing)\n  - [From Source](#from-source)\n  - [Package managers](#package-managers)\n- [Capturing audio](#capturing-audio)\n  - [Pulseaudio](#pulseaudio)\n  - [Pipewire](#pipewire)\n  - [ALSA](#alsa)\n  - [MPD](#mpd)\n  - [Sndio](#sndio)\n  - [OSS](#oss)\n  - [JACK](#jack)\n  - [squeezelite](#squeezelite)\n  - [macOS](#macos-1)\n  - [Windows](#windows)\n- [Running via ssh](#running-via-ssh)\n- [Troubleshooting](#troubleshooting)\n- [Usage](#usage)\n  - [Controls](#controls)\n- [Configuration](#configuration)\n- [Using cava in other applications](#using-cava-in-other-applications)\n  - [cavacore](#cavacore-library)\n  - [Raw Output](#raw-output)\n- [Contribution](#contribution)\n\n\n\nWhat it is\n----------\n\nCava is a bar spectrum audio visualizer for terminal or desktop (SDL).\n\nworks on:\n* Linux\n* FreeBSD\n* macOS\n* Windows\n\nThis program is not intended for scientific use. It's written to look responsive and aesthetic when used to visualize music.\n\n\nInstalling\n------------------\n\n### From Source\n\n#### Installing Build Requirements\n\nRequired components:\n* [FFTW](http:\u002F\u002Fwww.fftw.org\u002F)\n* libtool\n* automake\n* pkgconf\n* build-essentials\n* [iniparser](https:\u002F\u002Fgithub.com\u002Fndevilla\u002Finiparser)\n\n\nRecommended components:\n\nThe development lib of one of these audio frameworks, depending on your distro:\n* ALSA\n* Pulseaudio\n* Pipewire\n* Portaudio\n* Sndio\n* JACK\n\n\nOptional components:\n* SDL2 dev files\n* autoconf-archive (needed for setting up OpenGL)\n* [ncursesw dev files](http:\u002F\u002Fwww.gnu.org\u002Fsoftware\u002Fncurses\u002F) (bundled in ncurses in arch)\n\nOnly 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.\n\nNcurses can be used as an alternative output method if you have issues with the default one. But it is not required.\n\nAll the requirements can be installed easily in all major distros:\n\nFreeBSD\n\n    pkg install autoconf automake fftw3 iniparser jackit libglvnd libtool pkgconf psftools sdl2 sndio\n\nAdditionally, run these commands on FreeBSD before building:\n\n    export CFLAGS=\"-I\u002Fusr\u002Flocal\u002Finclude\"\n    export LDFLAGS=\"-L\u002Fusr\u002Flocal\u002Flib\"\n\n\nDebian\u002FUbuntu:\n\n    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\n\n\nArchLinux:\n\n    pacman -S base-devel fftw alsa-lib iniparser pulseaudio pkgconf\n\n\nopenSUSE:\n\n    zypper install alsa-devel fftw3-devel libpulse-devel libtool pkgconf\n\n\nFedora:\n\n    dnf install alsa-lib-devel fftw3-devel pulseaudio-libs-devel libtool iniparser-devel pkgconf\n\n\nmacOS:\n\nFirst install homebrew if you have't already:\n\n    \u002Fusr\u002Fbin\u002Fruby -e \"$(curl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FHomebrew\u002Finstall\u002Fmaster\u002Finstall)\"\n\nThen install prerequisites:\n\n    brew install fftw libtool automake pkgconf portaudio iniparser\n\nThe installation location for Homebrew packages is different between Intel Macs and Apple Silicon Macs.\nAs such, the commands will be a little bit different.\nYou can find out which type you have [here](https:\u002F\u002Fsupport.apple.com\u002Fen-us\u002FHT211814#:~:text=To%20open%20About%20This%20Mac,as%20an%20Intel%2Dbased%20Mac.)\n\nFor both machines, run these commands to fix macOS not finding libtool:\n\n    export LIBTOOL=`which glibtool`\n    export LIBTOOLIZE=`which glibtoolize`\n    ln -s `which glibtoolize` \u002Fusr\u002Flocal\u002Fbin\u002Flibtoolize\n\nNote that the file name may be a little bit different depending on the versions, but the directory should be the same.\n\nAdditionally, run these commands on Apple Silicon Macs so that .\u002Fconfigure can find the Homebrew packages:\n\n    export LDFLAGS=\"-L\u002Fopt\u002Fhomebrew\u002Flib\"\n    export CPPFLAGS=\"-I\u002Fopt\u002Fhomebrew\u002Finclude\"\n\nIntel Mac instructions tested on macOS Big Sur.\n\nApple Silicon instructions tested on macOS Ventura.\n\n\nWindows:\n\nDependencies can be resolved with vcpkg in the cmake\n\n    cmake --preset vcpkg\n    cd build\n    cmake --build . --config Release\n\npacman (msys2\u002Fmingw) can also be used\n    pacboy cc cmake fftw glew ninja SDL2\n    cmake -bin\n    cmake --build bin\n1\n\n#### Building\n First of all clone this repo and cd in to it, then run:\n\n    .\u002Fautogen.sh\n    .\u002Fconfigure\n    make\n\nIf 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).\n\nFor windows there is a VS solution file in the `cava_win` folder.\n\n#### Installing\n\nInstall `cava` to default `\u002Fusr\u002Flocal`:\n\n    make install\n\nOr you can change `PREFIX`, for example:\n\n   .\u002Fconfigure --prefix=PREFIX\n\n#### Uninstalling\n\n    make uninstall\n\n\n### Package managers\n\nAll distro specific installation sources might be out of date. Please check version before reporting any issues here.\n\n\n#### FreeBSD\n\n    pkg install cava\n\n#### openSUSE\n\nTumbleweed users have cava in their repo. They can just use:\n\n    zypper in cava\n\nLeap users need to add the multimedia:apps repository first:\n\n    zypper ar -f obs:\u002F\u002Fmultimedia:apps\u002FopenSUSE_Leap_42.2 multimedia\n\nIf you use another version just replace *openSUSE_Leap_42.2* with *openSUSE_13.2*, adjust it to your version.\n\n#### Fedora\n\nCava is available in Fedora 26 and later.  You can install Cava by\nrunning:\n\n    dnf install cava\n\n#### Arch\n\nCava is available in Arch Linux official repo:\n\n    pacman -S cava\n\n#### Ubuntu\u002FDebian\n\n##### Ubuntu 20.10 or more recent \u002F Debian 12 (Bookworm)\n\n    sudo apt install cava\n\n##### Older Ubuntu\n\nHarshal Sheth has added CAVA to his PPA, it can be installed with:\n\n    add-apt-repository ppa:hsheth2\u002Fppa\n    apt update\n    apt install cava\n\n#### macOS\n\ncava is in homebrew.\n\n    brew install cava\n\n\n\nCapturing audio\n---------------\n\nAll config options are set in the [config file](#configuration).\n\n### Pipewire\n\n    method = pipewire\n\nThis is the default input method if supported on your system. The default source is `auto` and will most likely be your currently selected output.\nIf you run wireplumber you can use `wpctl` to get the `object.path` or `object.serial` of the desired device to visualize.\n\ne.g.\n\n    source = alsa:pcm:3:front:3:playback\n\n\n### Pulseaudio\n\n    method = pulse\n\nThe default source is `auto` and should be your currently selected output.\n\nIf nothing happens you might have to use a different source than the default. The default might also be your microphone.\n\n\n### ALSA\n\n    method = alsa\n\n\nALSA 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.\n\nTo create a loopback interface simply run:\n\n`sudo modprobe snd_aloop`\n\nHopefully your `aplay -l` should now contain a loopback interface.\n\nTo make it persistent across boot add the line `snd-aloop` to \"\u002Fetc\u002Fmodules\". To keep it from being loaded as the first soundcard add the line `options snd-aloop index=1` to \"\u002Fetc\u002Fmodprobe.d\u002Falsa-base.conf\", this will load it at '1'. You can replace '1' with whatever makes most sense in your audio setup.\n\nPlaying 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.\n\nLook at the included example file `example_files\u002Fetc\u002Fasound.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.\n\nRead more about the ALSA method [here](http:\u002F\u002Fstackoverflow.com\u002Fquestions\u002F12984089\u002Fcapture-playback-on-play-only-sound-card-with-alsa).\n\nIf you are having problems with the alsa method on Raspberry PI, try enabling `mmap` by adding the following line to `\u002Fboot\u002Fconfig.txt` and reboot:\n\n```\ndtoverlay=i2s-mmap\n```\n\n#### dmix\n\n@reluekiss, was able to make cava work with dmix. Check out the example config in `example_files\u002Fetc\u002Fasound_dmix.conf` and issue [534](https:\u002F\u002Fgithub.com\u002Fkarlstav\u002Fcava\u002Fissues\u002F534).\n\n\n\n### mpd\n\nAdd these lines in mpd:\n\n    audio_output {\n        type                    \"fifo\"\n        name                    \"my_fifo\"\n        path                    \"\u002Ftmp\u002Fmpd.fifo\"\n        format                  \"44100:16:2\"\n    }\n\nUncomment and change input method to `fifo` in the [config](#configuration) file.\n\nThe path of the fifo can be specified with the `source` parameter.\n\nI had some trouble with sync (the visualizer was ahead of the sound). Reducing the ALSA buffer in mpd fixed it:\n\n    audio_output {\n            type            \"alsa\"\n            name            \"My ALSA\"\n            buffer_time     \"50000\"   # (50ms); default is 500000 microseconds (0.5s)\n    }\n\n### Sndio\n\n    method = sndio\n\nSndio is the audio framework used on OpenBSD, but it's also available on FreeBSD, NetBSD and Linux.\nSo far this is only tested on FreeBSD, but it's probably very similar on other operating systems. The\nfollowing example demonstrates how to setup CAVA for sndio on FreeBSD (please consult the [OSS](#oss)\nsection for a deeper explanation of the various `pcmX` sound devices and the corresponding `\u002Fdev\u002FdspX`\naudio devices in this example).\n```sh\n$ cat \u002Fdev\u002Fsndstat\nInstalled devices:\npcm0: \u003CRealtek ALC1220 (Rear Analog)> (play\u002Frec) default\npcm1: \u003CRealtek ALC1220 (Front Analog Mic)> (rec)\npcm2: \u003CUSB audio> (play\u002Frec)\nNo devices installed from userspace.\n```\nSndio operates on device descriptors. In general for every `\u002Fdev\u002FdspX` audio device there is a corresponding\n`rsnd\u002FX` sndio raw device descriptor. In this example there are `rsnd\u002F0`, `rsnd\u002F1` and `rsnd\u002F2` (they\nare not listed in `\u002Fdev`, sndio uses these descriptors to access the corresponding audio devices internally).\nSndio also handles the implicit `default` device descriptor, which acts like a symlink to the raw device\ndescriptor corresponding to the default audio device `\u002Fdev\u002Fdsp`. In this example it acts like a symlink\nto `rsnd\u002F0` because the default audio device `\u002Fdev\u002Fdsp` symlinks to `\u002Fdev\u002Fdsp0`. Sndio also evaluates\nthe environment variables `AUDIODEVICE` and `AUDIORECDEVICE`. If one of these is set (`AUDIORECDEVICE`\noverrides `AUDIODEVICE` if both are set) and a sndio-aware program tries to open the `default` device\ndescriptor or an unspecified device descriptor, then the program will use the device descriptor specified\nin the environment variable.\n\nNow in order to visualize the mic input in CAVA, the `source` value in the configuration file must\nbe set to the corresponding audio descriptor:\n\n    source = default    # default; symlink to rsnd\u002F0 in this example; AUDIORECDEVICE and AUDIODEVICE evaluation\n    source =            # unspecified device descriptor; same as default above\n    source = rsnd\u002F0     # for the pcm0 mic on the rear\n    source = rsnd\u002F1     # for the pcm1 mic on the front\n    source = rsnd\u002F2     # for the pcm2 mic on the USB headset\n\nWith `source = default` one can switch the visualization on the commandline without changing the configuration\nfile again:\n```sh\n$ AUDIODEVICE=rsnd\u002F0 cava\n$ AUDIODEVICE=rsnd\u002F1 cava\n$ AUDIODEVICE=rsnd\u002F2 cava\n```\nSndio can't record the played back audio with just the raw device descriptors, i.e. the sounds from\na music player or a browser which play on the external stereo speakers through `rsnd\u002F0` are not visualized\nin CAVA. For this to work the sndio server has to be started and a monitoring sub-device has to be\ncreated. The following example shows how to start the server and create a monitoring sub-device `snd\u002F0`\nfrom `rsnd\u002F0` and then start CAVA with `AUDIODEVICE` pointing to the new monitoring sub-device:\n```sh\n$ sndiod -f rsnd\u002F0 -m play,mon\n$ AUDIODEVICE=snd\u002F0 cava\n```\nSwitch between the speakers and the USB headset:\n```sh\n$ sndiod -f rsnd\u002F2 -m play,mon -s usb -f rsnd\u002F0 -m play,mon -s speakers\n$ AUDIODEVICE=snd\u002Fusb cava\n$ AUDIODEVICE=snd\u002Fspeakers cava\n```\nConsult the manpage `sndiod(8)` for further information regarding configuration and startup of a sndio\nserver.\n\n### OSS\n\n    method = oss\n\nThe audio system used on FreeBSD is the Open Sound System (OSS).\nThe following example demonstrates how to setup CAVA for OSS on FreeBSD:\n```sh\n$ cat \u002Fdev\u002Fsndstat\nInstalled devices:\npcm0: \u003CRealtek ALC1220 (Rear Analog)> (play\u002Frec) default\npcm1: \u003CRealtek ALC1220 (Front Analog Mic)> (rec)\npcm2: \u003CUSB audio> (play\u002Frec)\nNo devices installed from userspace.\n```\nThe system has three `pcm` sound devices, `pcm0`, `pcm1` and `pcm2`. `pcm0` corresponds to the analog\noutput jack on the rear, in which external stereo speakers are plugged in, and the analog input jack,\nin which one could plug in a microphone. Because it encapsulates both, output and input, it is marked\nas `play\u002Frec`. It is also set as the `default` sound device. `pcm1` corresponds to another analog input\njack for a mic on the front side and is marked `rec`. A USB headset with an integrated mic is plugged\nin an USB port and the system has created the `pcm2` sound device with `play\u002Frec` capabilities for\nit.\n\nIn general for every `pcmX` device there is a corresponding `\u002Fdev\u002FdspX` audio device. In this example\nthere are `\u002Fdev\u002Fdsp0`, `\u002Fdev\u002Fdsp1` and `\u002Fdev\u002Fdsp2` (the system creates them when needed, they are not\nlisted via `ls \u002Fdev` if they are currently not in use). The system also creates an implicit `\u002Fdev\u002Fdsp`,\nwhich acts like a symlink to the `default` audio device, in this example to `\u002Fdev\u002Fdsp0`.\n\nNow in order to visualize the mic input in CAVA, the `source` value in the configuration file must\nbe set to the corresponding audio device:\n\n    source = \u002Fdev\u002Fdsp     # default; symlink to \u002Fdev\u002Fdsp0 in this example\n    source = \u002Fdev\u002Fdsp0    # for the pcm0 mic on the rear\n    source = \u002Fdev\u002Fdsp1    # for the pcm1 mic on the front\n    source = \u002Fdev\u002Fdsp2    # for the pcm2 mic on the USB headset\n\nOSS can't record the outgoing audio on its own, i.e. the sounds from a music player or a browser which\nplay on the external stereo speakers through `\u002Fdev\u002Fdsp0` are not visualized in CAVA. A solution is\nto use Virtual OSS. It can create virtual audio devices from existing audio devices, in particular\nit can create a loopback audio device from `\u002Fdev\u002Fdsp0` and from which the played back audio can be\nfed into CAVA:\n```sh\n$ doas pkg install virtual_oss\n$ doas virtual_oss -r44100 -b16 -c2 -s4ms -O \u002Fdev\u002Fdsp0 -R \u002Fdev\u002Fnull -T \u002Fdev\u002Fsndstat -l dsp.cava\n\n$ cat \u002Fdev\u002Fsndstat\nInstalled devices:\npcm0: \u003CRealtek ALC1220 (Rear Analog)> (play\u002Frec) default\npcm1: \u003CRealtek ALC1220 (Front Analog Mic)> (rec)\npcm2: \u003CUSB audio> (play\u002Frec)\nInstalled devices from userspace:\ndsp.cava: \u003CVirtual OSS> (play\u002Frec)\n```\nIt created a virtual loopback device `\u002Fdev\u002Fdsp.cava` from `\u002Fdev\u002Fdsp0`. Now the audio is visualized\nin CAVA with `source = \u002Fdev\u002Fdsp.cava` in the configuration file. The playback program must have a configuration\nto use the `\u002Fdev\u002Fdsp.cava` device. For programs where this is not possible, e.g. which always use `\u002Fdev\u002Fdsp`,\nreplace `-l dsp.cava` with `-l dsp`. Virtual OSS can be configured and started as a service on FreeBSD.\n\n### JACK\n\n    method = jack\n\nThe JACK Audio Connection Kit (JACK) is a professional sound server API which is available on several\noperating systems, e.g. FreeBSD and Linux.\n\nCAVA is a JACK client with the base client name `cava` and adheres to the standard server start and\nstop behaviour, i.e. CAVA starts a JACK server if none is already running and the environment variable\n`JACK_START_SERVER` is defined, in which case the server also stops when all clients have exited. The\n`source` in the CAVA configuration file specifies the name of the JACK server to which CAVA tries to\nconnect to. The default value is `default`, which is also the default JACK server name. The value can\nbe empty, in which case it implies `default`. Therefore the following three entries are equivalent:\n\n    ; source = default\n    source = default\n    source =\n\nOne exception is the combination of an empty `source` entry and the environment variable `JACK_DEFAULT_SERVER`.\nIf the environment variable is defined, e.g. `export JACK_DEFAULT_SERVER=foo`, then the following entries\nare equivalent:\n\n    source = foo\n    source =\n\nConsult the manpage `jackd(1)` for further information regarding configuration and startup of a JACK\nserver.\n\nCAVA creates terminal audio-typed (so no MIDI support) input ports. These ports can connect to output\nports of other JACK clients, e.g. connect to the output ports of a music player and CAVA will visualize\nthe music. Currently CAVA supports up to two input ports, i.e. it supports mono and stereo. The number\nof input ports can be controlled via the `channels` option in the input section of the configuration\nfile:\n\n    channels = 1    # one input port, mono\n    channels = 2    # two input ports, stereo (default)\n\nThe port's short name is simply `M` for mono, and `L` and `R` for stereo. The full name of the input\nport according to the base client name is `cava:M` for mono, and `cava:L` and `cava:R` for stereo.\n\nThe option `autoconnect` controls the connection strategy for CAVA's ports to other client's ports:\n\n    autoconnect = 0    # don't connect to other ports automatically\n    autoconnect = 1    # only connect to other ports during startup\n    autoconnect = 2    # reconnect to new ports regularly (default)\n\nThe automatic connection strategies scan the physical terminal input-ports, i.e. the real audio device\nwhich actually outputs the sound, and applies the same connections to CAVA's ports. In this way CAVA\nvisualizes the played back audio from JACK clients by default.\n\nIn order to control and manage the connection between CAVA's ports and ports of other client programs,\nthere are connection management programs for JACK. Some well known connection managers with a graphical\nuser interface are QjackCtl and Cadence. The JACK package itself often comes with CLI tools. Depending\non the operating system it could be necessary to install them separately, e.g. on FreeBSD:\n```sh\n$ doas pkg install jack-example-tools\n```\nAmong the tools are the programs `jack_lsp` and `jack_connect`. These two tools are enough to list\nand connect ports on the commandline. The following example demonstrates how to setup connections with\nthese tools:\n```sh\n$ jack_lsp\nsystem:capture_1\nsystem:capture_2\nsystem:playback_1\nsystem:playback_2\ncava:L\nmoc:output0\nmoc:output1\ncava:R\n```\nThis listing shows all full port names that are currently available. These correspond to two external\nJACK clients, `cava` and `moc`, and one internal JACK client `system`. The types and current active\nconnections between the ports can be listed with the `-p` and `-c` switches for `jack_lsp`. In order\nto connect the ports of CAVA and MOC, `jack_connect` is used:\n```sh\n$ jack_connect cava:L moc:output0\n$ jack_connect cava:R moc:output1\n```\nNow CAVA visualizes the outgoing audio from MOC.\n\n### squeezelite\n[squeezelite](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FSqueezelite) is one of several software clients available for the Logitech Media Server. Squeezelite can export its audio data as shared memory, which is what this input module uses.\nJust adapt your [config](#configuration):\n```\nmethod = shmem\nsource = \u002Fsqueezelite-AA:BB:CC:DD:EE:FF\n```\nwhere `AA:BB:CC:DD:EE:FF` is squeezelite's MAC address (check the LMS Web GUI (Settings>Information) if unsure).\nNote: squeezelite must be started with the `-v` flag to enable visualizer support.\n\n### macOS\n```\nmethod = coreaudio\n```\n\nCore Audio is now the default input backend on macOS. You can list input devices with:\n\n```\nmethod = coreaudio\nsource = list\n```\n\nThen select a device by name, by 1-based device index, or keep `source = auto` for the default output device.\nUse `source = auto_input` if you want the default input device instead.\n\nOn macOS 14.2+ (when built with CoreAudio tap support), you can capture system output directly without creating a loopback interface:\n\n```\nmethod = coreaudio\nsource = tap\n```\n\nUse `source = tap_mono` for a mono mixdown.\n\nOn systems without CoreAudio tap support, macOS does not expose system output mix directly to applications, so you need a loopback device to visualize speaker output. The same loopback options used with portaudio also work with coreaudio:\n\n**Background Music**\n\nInstall [Background Music](https:\u002F\u002Fgithub.com\u002Fkyleneideck\u002FBackgroundMusic) which provides a loopback interface automatically. Once installed and running just edit your [config](#configuration) to use this interface with portaudio:\n\n```\nsource = \"Background Music\"\n```\n\n**BlackHole**\n\nInstall [BlackHole](https:\u002F\u002Fgithub.com\u002FExistentialAudio\u002FBlackHole) and create a [Multi Output Device](https:\u002F\u002Fgithub.com\u002FExistentialAudio\u002FBlackHole\u002Fwiki\u002FMulti-Output-Device), making sure you have your speaker as the first output device in the list, and BlackHole as second (check the ⚠️ note under [4. Select Output Devices](https:\u002F\u002Fgithub.com\u002FExistentialAudio\u002FBlackHole\u002Fwiki\u002FMulti-Output-Device#4-select-output-devices) on the linked wiki page). Once installed and running just edit your [config](#configuration) to use this interface with portaudio (changing `2ch` to `16ch` or `64ch` if you're using those):\n\n```\nsource = \"BlackHole 2ch\"\n```\n\n**Sound Flower**\n\n[Soundflower](https:\u002F\u002Fgithub.com\u002Fmattingalls\u002FSoundflower) also works to create a loopback interface. Use Audio MIDI Setup to configure a virtual interface that outputs audio to both your speakers and the loopback interface, following [this](https:\u002F\u002Fgithub.com\u002FRogueAmoeba\u002FSoundflower-Original\u002Fissues\u002F44#issuecomment-151586106) recipe. By creating a multi-output device you lose the ability to control the volume on your keyboard. Because of this, we recommend the Background Music app which still gives you keyboard controls.\n\nThen edit your [config](#configuration) to use this interface with portaudio:\n\n```\nmethod = portaudio\nsource = \"Soundflower (2ch)\"\n```\n\n\n\nNote: Cava doesn't render correctly within the default macOS terminal. In order to achieve an optimal display, install [Kitty](https:\u002F\u002Fsw.kovidgoyal.net\u002Fkitty\u002Findex.html). Beware that you may run in to the issue presented in #109; however, it can be resolved with [this](https:\u002F\u002Fstackoverflow.com\u002Fquestions\u002F7165108\u002Fin-os-x-lion-lang-is-not-set-to-utf-8-how-to-fix-it).\n\n\n### Windows\n\nShould capture the audio from the default output device automatically. No config needed.\n\nDifferent `source` can be set in config.\n\n\nRunning via ssh\n---------------\n\nTo run via ssh to an external monitor, redirect output to `\u002Fdev\u002Fconsole`:\n\n     ~# .\u002Fcava  \u003C> \u002Fdev\u002Fconsole >&0 2>&1\n\nexit with ctrl+z then run 'bg' to keep it running after you log out.\n\n(You must be root to redirect to console. Simple sudo is not enough: Run `sudo su` first.)\n\n\n## Troubleshooting\n\n### No bars in terminal\n\nMost likely issue [#399](https:\u002F\u002Fgithub.com\u002Fkarlstav\u002Fcava\u002Fissues\u002F399). Locale settings need to be set correctly in order for cava to work.\n\n### Bars not moving\n\nRead the chapter on [capturing audio](#capturing-audio). Depending on your system this might not work automatically. For example if you have pipewire dev files on your system, but are still using pulseaudio, you will have to specify `pulse` as your input method in the cava config file.\n\n### Visualizer reacts to microphone instead of output\n\nThis is a known issue with pipewire. Try the workaround described [here](https:\u002F\u002Fgithub.com\u002Fkarlstav\u002Fcava\u002Fissues\u002F422#issuecomment-994270910)\n\n### Vertical lines in bars\n\nThis is either an issue with the font, or line spacing being enabled in the terminal emulator. Try to change font or disable line spacing.\n\n### Low resolution\n\nSince the graphics are simply based on characters, try decreasing the font size.\n\n### Low frame rate\n\nSome terminal emulators are just slow. Cava will look best in a GPU based terminal like kitty or alacritty. You can also try to increase the font size\n\n### Font is changed in ttys after exit\n\nIf you run cava in a TTY (like ctrl+alt+F2) the program will change the font to the included `cava.psf` (actually a slightly modified \"unifont\").\n\nIn 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\u002F8 - 7\u002F8 blocks used on the top of each bar to increase resolution).\n\nSo 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`.\n\nActually, `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.\n\n### Gradient not working in Konsole\n\nKonsole simply does not support this. [#194](https:\u002F\u002Fgithub.com\u002Fkarlstav\u002Fcava\u002Fissues\u002F194)\n\nUsage\n-----\n\n    Usage : cava [options]\n    Visualize audio input in terminal.\n\n    Options:\n    \t    -p          path to config file\n    \t    -v          print version\n\n\n\nExit with ctrl+c or q.\n\nIf cava quits unexpectedly or is force killed, echo must be turned on manually with `stty -echo`.\n\n### Controls\n\n| Key | Description |\n| --- | ----------- |\n| \u003Ckbd>up\u003C\u002Fkbd> \u002F \u003Ckbd>down\u003C\u002Fkbd>| increase\u002Fdecrease sensitivity |\n| \u003Ckbd>left\u003C\u002Fkbd> \u002F \u003Ckbd>right\u003C\u002Fkbd>| increase\u002Fdecrease bar width |\n| \u003Ckbd>f\u003C\u002Fkbd> \u002F \u003Ckbd>b\u003C\u002Fkbd>| change foreground\u002Fbackground color |\n| \u003Ckbd>r\u003C\u002Fkbd> | Reload configuration |\n| \u003Ckbd>c\u003C\u002Fkbd> | Reload colors only |\n| \u003Ckbd>q\u003C\u002Fkbd> or \u003Ckbd>CTRL-C\u003C\u002Fkbd>| Quit C.A.V.A. |\n\nConfiguration\n-------------\n\nBy default a configuration file is created upon first launch in `$XDG_CONFIG_HOME\u002Fcava\u002Fconfig` or `$HOME\u002F.config\u002Fcava\u002Fconfig`, but cava can also be made to use a different file with the `-p` option.\n\nSending cava a SIGUSR1 signal, will force cava to reload its configuration file. Thus, it behaves as if the user pressed \u003Ckbd>r\u003C\u002Fkbd> in the terminal. One might send a SIGUSR1 signal using `pkill` or `killall`.\nFor example:\n```\n$ pkill -USR1 cava\n```\n\nSimilarly, sending cava a SIGUSR2 signal will only reload the colors from the configuration file, which is the same as pressing \u003Ckbd>c\u003C\u002Fkbd> in the terminal. This is slightly faster than reloading the entire config as the audio processing does not need to reinitialize.\n```\n$ pkill -USR2 cava\n```\n\nColors can be loaded from a separate file by using the `theme` option in the config.\n\n**Examples on how the equalizer works:**\n\n    [eq]\n    1=0\n    2=1\n    3=0\n    4=1\n    5=0\n\n![3_138](https:\u002F\u002Fcloud.githubusercontent.com\u002Fassets\u002F6376571\u002F8670183\u002Fa54a851e-29e8-11e5-9eff-346bf6ed91e0.png)\n\n    [eq]\n    1=2\n    2=2\n    3=1\n    4=1\n    5=0.5\n\n![3_139](https:\u002F\u002Fcloud.githubusercontent.com\u002Fassets\u002F6376571\u002F8670181\u002F9db0ef50-29e8-11e5-81bc-3e2bb9892da0.png)\n\n\nUsing cava in other applications\n--------------------------------\n\n### cavacore library\n\nThe core processing engine in cava has been split into a separate library `cavacore`. See CAVACORE.md for details.\n\n### Raw Output\n\nYou can also use Cava's output for other programs by using raw output mode, which will write bar data to `STDOUT` that can be piped into other processes. More information on this option is documented in [the example config file](\u002Fexample_files\u002Fconfig).\n\nA useful starting point example script written in python that consumes raw data can be found [here](https:\u002F\u002Fgithub.com\u002Fkarlstav\u002Fcava\u002Fissues\u002F123#issuecomment-307891020).\n\n### [cava2sse](https:\u002F\u002Fcodeberg.org\u002Fdnalor\u002Fcava2sse)\nis a stand-alone component for making Cava's raw values available as [server-sent events](https:\u002F\u002Fen.wikipedia.org\u002Fwiki\u002FServer-sent_events). With this, any application can use CAVA's output data over the network.\n\nContribution\n------\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.\n\nThanks to:\n* [CelestialWalrus](https:\u002F\u002Fgithub.com\u002FCelestialWalrus)\n* [anko](https:\u002F\u002Fgithub.com\u002Fanko)\n* [livibetter](https:\u002F\u002Fgithub.com\u002Flivibetter)\n\nfor major contributions in the early development of this project.\n\nAlso thanks to [dpayne](https:\u002F\u002Fgithub.com\u002Fdpayne\u002F) for figuring out how to find the pulseaudio default sink name.\n","CAVA 是一个跨平台的音频可视化工具，支持终端和桌面环境（通过SDL）。其核心功能包括使用多种音频框架如Pulseaudio、Pipewire、ALSA等来捕获音频，并以频谱图的形式展示。技术上，CAVA利用FFTW库进行快速傅里叶变换处理音频信号，并可通过配置文件自定义视觉效果。此外，它还支持多种操作系统，包括Linux、FreeBSD、macOS及Windows，使得用户能够灵活选择适合自己的平台。特别适用于音乐播放时提供美观且响应迅速的视觉反馈场景中，为用户提供更丰富的听觉体验。","2026-06-11 03:07:09","top_language"]