CAVA

跨平台音频可视化工具

作者：Karl Stavestrand

演示视频

• 简介
• 安装
  • 从源码安装
  • 包管理器安装
• 音频捕获
  • Pulseaudio
  • Pipewire
  • ALSA
  • MPD
  • Sndio
  • OSS
  • JACK
  • squeezelite
  • macOS
  • Windows
• 通过SSH运行
• 故障排除
• 使用方法
  • 控制
• 配置
• 在其他应用中使用CAVA
  • cavacore库
  • 原始输出
• 贡献

简介

Cava是一个用于终端或桌面（SDL）的条形频谱音频可视化工具。

支持的平台：

• Linux
• FreeBSD
• macOS
• Windows

该程序不适用于科学用途。它的设计目的是在可视化音乐时呈现出反应灵敏且美观的效果。

安装

从源码安装

安装构建依赖

必需组件：

• FFTW
• libtool
• automake
• autoconf-archive（设置OpenGL所需）
• pkgconf
• build-essentials
• iniparser

推荐组件：

根据您的发行版，安装以下音频框架之一的开发库：

• ALSA
• Pulseaudio
• Pipewire
• Portaudio
• Sndio
• JACK

可选组件：

• SDL2开发文件
• ncursesw开发文件（在Arch Linux中与ncurses捆绑）

实际上，CAVA只需要FFTW、iniparser和构建工具就能编译，但这只能让您从FIFO文件中读取数据。要直接从系统捕获音频，需要安装pipewire、pulseaudio、alsa、sndio、jack或portaudio开发文件（取决于您使用的音频系统）。

如果默认输出方法出现问题，可以使用Ncurses作为替代输出方法，但这不是必需的。

所有主要发行版都可以轻松安装这些依赖：

FreeBSD：

pkg install autoconf autoconf-archive automake fftw3 iniparser jackit libglvnd libtool pkgconf psftools sdl2 sndio

此外，在FreeBSD上构建前还需运行以下命令：

export CFLAGS="-I/usr/local/include"
export LDFLAGS="-L/usr/local/lib"

Debian/Ubuntu：

sudo apt install build-essential libfftw3-dev libasound2-dev libpulse-dev libtool automake autoconf-archive libiniparser-dev libsdl2-2.0-0 libsdl2-dev libpipewire-0.3-dev libjack-jackd2-dev pkgconf

ArchLinux：

pacman -S base-devel fftw alsa-lib iniparser pulseaudio autoconf-archive pkgconf

openSUSE：

zypper install alsa-devel fftw3-devel libpulse-devel libtool autoconf-archive pkgconf

Fedora：

dnf install alsa-lib-devel fftw3-devel pulseaudio-libs-devel libtool autoconf-archive iniparser-devel pkgconf

macOS：

首先安装homebrew（如果尚未安装）：

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

然后安装依赖：

brew install fftw libtool automake autoconf-archive pkgconf portaudio iniparser

Intel Mac和Apple Silicon Mac的Homebrew包安装位置不同。 因此，命令会稍有不同。 您可以在这里查看您的Mac类型。

对于两种机型，运行以下命令以解决macOS无法找到libtool的问题：

export LIBTOOL=`which glibtool`
export LIBTOOLIZE=`which glibtoolize`
ln -s `which glibtoolize` /usr/local/bin/libtoolize

请注意，文件名可能会因版本而略有不同，但目录应该相同。

对于Apple Silicon Mac，还需运行以下命令，使./configure能找到Homebrew包：

export LDFLAGS="-L/opt/homebrew/lib"
export CPPFLAGS="-I/opt/homebrew/include"

Intel Mac说明在macOS Big Sur上测试通过。

Apple Silicon说明在macOS Ventura上测试通过。

Windows：

请查看cava_win文件夹中的单独说明。

构建

首先克隆此仓库并进入目录，然后运行：

./autogen.sh
./configure
make

如果您安装了推荐组件但不想使用它（例如在一台机器上构建二进制文件以在另一台机器上使用），可以在配置过程中禁用相应功能（详情请参阅configure --help）。

对于Windows，cava_win文件夹中有一个VS解决方案文件。

安装

将cava安装到默认的/usr/local：

make install

或者您可以更改PREFIX，例如：

./configure --prefix=PREFIX

卸载

make uninstall

包管理器安装

所有发行版特定的安装源可能已过时。在报告任何问题之前，请检查版本。

FreeBSD

pkg install cava

openSUSE

Tumbleweed 用户可以直接使用以下命令:

zypper in cava

Leap 用户需要先添加 multimedia:apps 仓库:

zypper ar -f obs://multimedia:apps/openSUSE_Leap_42.2 multimedia

如果使用其他版本，只需将 openSUSE_Leap_42.2 替换为 openSUSE_13.2，根据你的版本进行调整。

Fedora

Cava 在 Fedora 26 及更高版本中可用。你可以通过运行以下命令安装 Cava:

dnf install cava

Arch

Cava 在 AUR 中可用。

pacaur -S cava

Ubuntu/Debian

Ubuntu 20.10 或更新版本 / Debian (不稳定版)

sudo apt install cava

较旧的 Ubuntu

Harshal Sheth 已将 CAVA 添加到他的 PPA 中，可以通过以下方式安装:

add-apt-repository ppa:hsheth2/ppa
apt update
apt install cava

macOS

cava 在 homebrew 中可用。

brew install cava

捕获音频

Pulseaudio

确保你已安装 pulseaudio 开发文件，并且 cava 已经构建了 pulseaudio 支持（如果找到开发文件，应该会自动构建）。

如果幸运的话，你只需运行 cava 即可。

如果没有反应，你可能需要使用与默认不同的音源。默认音源可能是你的麦克风。查看配置文件以获取帮助。

Pipewire

设置

method = pipewire

默认音源是 auto，很可能是你当前选择的输出设备。 如果你运行 wireplumber，可以使用 wpctl 获取所需设备的 object.path 或 object.serial 进行可视化。

例如：

source = alsa:pcm:3:front:3:playback

ALSA

在配置文件中设置

method = alsa

ALSA 可能比较困难，因为没有原生方法从输出捕获音频。如果你想直接从输出捕获音频（不仅仅是麦克风或线路输入），你必须创建一个 ALSA 回环接口，然后同时将音频输出到回环和正常接口。

要创建回环接口，只需运行：

sudo modprobe snd_aloop

希望你的 aplay -l 现在包含一个回环接口。

要使其在重启后保持不变，将 snd-aloop 行添加到 "/etc/modules"。为了防止它作为第一个声卡加载，将 options snd-aloop index=1 行添加到 "/etc/modprobe.d/alsa-base.conf"，这将使其在 '1' 处加载。你可以将 '1' 替换为在你的音频设置中最合适的值。

通过回环接口播放音频使 cava 能够捕获它，但扬声器中将没有声音。为了在回环接口和实际接口上播放音频，你必须使用 ALSA 多通道。

查看包含的示例文件 example_files/etc/asound.conf 了解如何使用多通道。我能够使用 HDA Intel PCH 声卡实现这一点，但对 USB DAC 无效。

在这里阅读更多关于 ALSA 方法的信息。

如果你在树莓派上使用 alsa 方法遇到问题，请尝试通过在 /boot/config.txt 中添加以下行并重启来启用 mmap：

dtoverlay=i2s-mmap

dmix

@reluekiss 成功让 cava 与 dmix 一起工作。查看 example_files/etc/asound_dmix.conf 中的示例配置和 issue 534。

mpd

在 mpd 中添加这些行：

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

在配置文件中取消注释并将输入方法更改为 fifo。

可以使用 source 参数指定 fifo 的路径。

我遇到了一些同步问题（可视化器领先于声音）。在 mpd 中减少 ALSA 缓冲区解决了这个问题：

audio_output {
        type            "alsa"
        name            "My ALSA"
        buffer_time     "50000"   # (50ms); 默认为 500000 微秒 (0.5s)
}

Sndio

设置

method = sndio

Sndio 是 OpenBSD 上使用的音频框架，但它也可用于 FreeBSD、NetBSD 和 Linux。 到目前为止，这只在 FreeBSD 上进行了测试，但在其他操作系统上可能非常相似。以下 示例演示了如何在 FreeBSD 上为 sndio 设置 CAVA（请参阅 OSS 部分以深入 了解各种 pcmX 声音设备和本示例中相应的 /dev/dspX 音频设备）。

$ cat /dev/sndstat
Installed devices:
pcm0: <Realtek ALC1220 (Rear Analog)> (play/rec) default
pcm1: <Realtek ALC1220 (Front Analog Mic)> (rec)
pcm2: <USB audio> (play/rec)
No devices installed from userspace.

Sndio 操作设备描述符。通常，每个 /dev/dspX 音频设备都有一个相应的 rsnd/X sndio 原始设备描述符。 在本例中有 rsnd/0、rsnd/1 和 rsnd/2（它们未在 /dev 中列出，sndio 内部使用这些描述符访问 相应的音频设备）。Sndio 还处理隐式 default 设备描述符，它就像一个指向与默认音频设备 /dev/dsp 相对应的原始设备描述符的符号链接。在本例中，它就像一个指向 rsnd/0 的符号链接，因为默认音频设备 /dev/dsp 链接到 /dev/dsp0。Sndio 还评估环境变量 AUDIODEVICE 和 AUDIORECDEVICE。如果设置了 其中之一（如果两者都设置，AUDIORECDEVICE 会覆盖 AUDIODEVICE），并且支持 sndio 的程序尝试打开 default 设备描述符或未指定的设备描述符，那么程序将使用环境变量中指定的设备描述符。

现在，为了在 CAVA 中可视化麦克风输入，配置文件中的 source 值必须设置为相应的音频描述符： source = default # 默认值；在本例中是指向rsnd/0的符号链接；AUDIORECDEVICE和AUDIODEVICE的评估 source = # 未指定设备描述符；等同于上面的默认值 source = rsnd/0 # 用于后部的pcm0麦克风 source = rsnd/1 # 用于前部的pcm1麦克风 source = rsnd/2 # 用于USB耳机的pcm2麦克风

使用source = default可以在不更改配置文件的情况下，在命令行上切换可视化效果：

$ AUDIODEVICE=rsnd/0 cava
$ AUDIODEVICE=rsnd/1 cava
$ AUDIODEVICE=rsnd/2 cava

Sndio无法仅使用原始设备描述符来录制回放的音频，即通过rsnd/0在外部立体声扬声器上播放的音乐播放器或浏览器的声音在CAVA中不会被可视化。要实现这一点，需要启动sndio服务器并创建一个监控子设备。以下示例展示了如何启动服务器，从rsnd/0创建一个监控子设备snd/0，然后启动CAVA，将AUDIODEVICE指向新的监控子设备：

$ sndiod -f rsnd/0 -m play,mon
$ AUDIODEVICE=snd/0 cava

在扬声器和USB耳机之间切换：

$ sndiod -f rsnd/2 -m play,mon -s usb -f rsnd/0 -m play,mon -s speakers
$ AUDIODEVICE=snd/usb cava
$ AUDIODEVICE=snd/speakers cava

有关sndio服务器配置和启动的更多信息，请查阅sndiod(8)手册页。

OSS

设置

method = oss

FreeBSD上使用的音频系统是开放声音系统（OSS）。 以下示例演示了如何在FreeBSD上为OSS设置CAVA：

$ cat /dev/sndstat
已安装设备：
pcm0: <Realtek ALC1220 (后部模拟)> (播放/录音) 默认
pcm1: <Realtek ALC1220 (前部模拟麦克风)> (录音)
pcm2: <USB音频> (播放/录音)
未从用户空间安装任何设备。

系统有三个pcm声音设备，pcm0、pcm1和pcm2。pcm0对应后部的模拟输出插孔（接外部立体声扬声器）和模拟输入插孔（可插入麦克风）。由于它同时包含输出和输入，所以标记为播放/录音。它也被设置为默认声音设备。pcm1对应前部的另一个模拟输入插孔，用于麦克风，标记为录音。一个带集成麦克风的USB耳机插入USB端口，系统为其创建了具有播放/录音功能的pcm2声音设备。

通常，每个pcmX设备都有一个对应的/dev/dspX音频设备。在本例中有/dev/dsp0、/dev/dsp1和/dev/dsp2（系统在需要时创建它们，如果当前未使用，通过ls /dev不会列出）。系统还创建了一个隐式的/dev/dsp，它像是指向默认音频设备的符号链接，在本例中指向/dev/dsp0。

现在要在CAVA中可视化麦克风输入，配置文件中的source值必须设置为相应的音频设备：

source = /dev/dsp     # 默认值；在本例中是指向/dev/dsp0的符号链接
source = /dev/dsp0    # 用于后部的pcm0麦克风
source = /dev/dsp1    # 用于前部的pcm1麦克风
source = /dev/dsp2    # 用于USB耳机的pcm2麦克风

OSS本身无法录制外发音频，即通过/dev/dsp0在外部立体声扬声器上播放的音乐播放器或浏览器的声音在CAVA中不会被可视化。一个解决方案是使用Virtual OSS。它可以从现有音频设备创建虚拟音频设备，特别是可以从/dev/dsp0创建一个回环音频设备，从而将回放的音频输入CAVA：

$ doas pkg install virtual_oss
$ doas virtual_oss -r44100 -b16 -c2 -s4ms -O /dev/dsp0 -R /dev/null -T /dev/sndstat -l dsp.cava

$ cat /dev/sndstat
已安装设备：
pcm0: <Realtek ALC1220 (后部模拟)> (播放/录音) 默认
pcm1: <Realtek ALC1220 (前部模拟麦克风)> (录音)
pcm2: <USB音频> (播放/录音)
从用户空间安装的设备：
dsp.cava: <Virtual OSS> (播放/录音)

它从/dev/dsp0创建了一个虚拟回环设备/dev/dsp.cava。现在在配置文件中设置source = /dev/dsp.cava，音频就可以在CAVA中被可视化。播放程序必须配置为使用/dev/dsp.cava设备。对于无法配置的程序，例如总是使用/dev/dsp的程序，将-l dsp.cava替换为-l dsp。Virtual OSS可以在FreeBSD上配置并作为服务启动。

JACK

设置

method = jack

JACK音频连接套件（JACK）是一个专业的声音服务器API，可用于多个操作系统，如FreeBSD和Linux。

CAVA是一个基本客户端名为cava的JACK客户端，遵循标准的服务器启动和停止行为，即如果没有正在运行的JACK服务器且定义了环境变量JACK_START_SERVER，CAVA会启动一个JACK服务器，在这种情况下，当所有客户端退出时，服务器也会停止。CAVA配置文件中的source指定CAVA尝试连接的JACK服务器名称。默认值是default，这也是默认的JACK服务器名称。该值可以为空，这种情况下隐含default。因此，以下三个条目是等效的：

; source = default
source = default
source =

一个例外是空source条目与环境变量JACK_DEFAULT_SERVER的组合。如果定义了环境变量，例如export JACK_DEFAULT_SERVER=foo，那么以下条目是等效的：

source = foo
source =

有关JACK服务器配置和启动的更多信息，请查阅jackd(1)手册页。 CAVA创建终端音频类型的输入端口（不支持MIDI）。这些端口可以连接到其他JACK客户端的输出端口，例如连接到音乐播放器的输出端口，CAVA就可以可视化音乐。目前CAVA最多支持两个输入端口，即支持单声道和立体声。输入端口的数量可以通过配置文件输入部分的"channels"选项控制：

channels = 1 # 一个输入端口，单声道 channels = 2 # 两个输入端口，立体声（默认）

端口的简称单声道为"M"，立体声为"L"和"R"。根据基本客户端名称，输入端口的完整名称单声道为"cava:M"，立体声为"cava:L"和"cava:R"。

"autoconnect"选项控制CAVA端口与其他客户端端口的连接策略：

autoconnect = 0 # 不自动连接到其他端口 autoconnect = 1 # 仅在启动时连接到其他端口 autoconnect = 2 # 定期重新连接到新端口（默认）

自动连接策略会扫描物理终端输入端口（即实际输出声音的真实音频设备），并将相同的连接应用到CAVA的端口。这样，CAVA默认可以可视化JACK客户端播放的音频。

为了控制和管理CAVA端口与其他客户端程序端口之间的连接，JACK有一些连接管理程序。一些知名的图形用户界面连接管理器有QjackCtl和Cadence。JACK包本身通常带有命令行工具。根据操作系统，可能需要单独安装它们，例如在FreeBSD上：

$ doas pkg install jack-example-tools

这些工具中包括"jack_lsp"和"jack_connect"程序。这两个工具足以在命令行中列出和连接端口。以下示例演示如何使用这些工具设置连接：

$ jack_lsp system:capture_1 system:capture_2 system:playback_1 system:playback_2 cava:L moc:output0 moc:output1 cava:R

这个列表显示了当前可用的所有完整端口名称。它们对应于两个外部JACK客户端"cava"和"moc"，以及一个内部JACK客户端"system"。可以使用"jack_lsp"的"-p"和"-c"开关列出端口的类型和当前活动连接。要连接CAVA和MOC的端口，使用"jack_connect"：

$ jack_connect cava:L moc:output0 $ jack_connect cava:R moc:output1

现在CAVA可以可视化MOC的输出音频。

squeezelite

squeezelite是Logitech Media Server可用的几个软件客户端之一。Squeezelite可以将其音频数据导出为共享内存，这就是此输入模块使用的方式。只需调整你的配置：

method = shmem source = /squeezelite-AA:BB:CC:DD:EE:FF

其中"AA:BB:CC:DD:EE:FF"是squeezelite的MAC地址（如果不确定，请查看LMS Web GUI（设置>信息））。 注意：必须使用"-v"标志启动squeezelite以启用可视化支持。

macOS

注意：Cava在默认的macOS终端中无法正确渲染。为了获得最佳显示效果，请安装Kitty。请注意，你可能会遇到#109中提到的问题；不过，可以通过这个方法解决。

Background Music

安装Background Music，它会自动提供一个回环接口。安装并运行后，只需编辑你的配置以使用portaudio的这个接口：

method = portaudio source = "Background Music"

Sound Flower

Soundflower也可以用来创建回环接口。使用Audio MIDI Setup配置一个虚拟接口，将音频同时输出到扬声器和回环接口，按照这个方法操作。通过创建多输出设备，你将失去在键盘上控制音量的能力。因此，我们推荐使用Background Music应用，它仍然可以通过键盘进行控制。

然后编辑你的配置，使用portaudio的这个接口：

method = portaudio source = "Soundflower (2ch)"

Windows

应该自动捕获默认输出设备的音频。

通过ssh运行

要通过ssh在外部监视器上运行，将输出重定向到"/dev/console"：

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

用ctrl+z退出，然后运行"bg"使其在您注销后继续运行。

（你必须是root才能重定向到控制台。简单的sudo是不够的：先运行"sudo su"。）

故障排除

终端中没有条形图

最可能的问题是#399。需要正确设置区域设置才能使cava正常工作。

可视化器对麦克风而不是输出做出反应

这是pipewire的一个已知问题。尝试这里描述的解决方法。

条形图中的垂直线

这可能是字体问题，或者终端模拟器中启用了行间距。尝试更改字体或禁用行间距。

分辨率低

由于图形仅基于字符，请尝试减小字体大小。

帧率低

一些终端模拟器本身就很慢。Cava在基于GPU的终端（如kitty或alacritty）中表现最佳。你也可以尝试增加字体大小。

退出后TTY中的字体发生变化

如果你在TTY（如ctrl+alt+F2）中运行cava，程序会将字体更改为包含的"cava.psf"（实际上是稍微修改过的"unifont"）。

在控制台字体中，似乎只支持256个Unicode字符，可能是因为它们是位图字体。我找不到包含Unicode字符2581-2587（用于每个条形图顶部的1/8 - 7/8块以增加分辨率）的字体。

因此，在"cava.psf"中，字符1-7实际上被Unicode字符2581-2587替换。当cava退出时，它会将字体改回。如果cava异常退出，你注意到1-7被部分块替换，只需用"setfont"更改字体即可。 实际上，setfont应该返回默认字体，但这通常没有设置。我没有找到其他方法来获取当前字体。因此，当中断时，cava会将字体设置为"Lat2-Fixed16"。所有主要发行版都应该有这个字体。重启后会恢复到您的默认字体。

Konsole中渐变不起作用

Konsole simply不支持这个功能。#194

使用方法

用法：cava [选项]
在终端中可视化音频输入。

选项：
	    -p          配置文件路径
	    -v          打印版本

使用ctrl+c或q退出。

如果cava意外退出或被强制终止，必须手动使用stty -echo打开回显。

控制

配置

从0.4.0版本开始，所有选项都在配置文件中设置，不再使用命令行参数！

默认情况下，首次启动时会在$XDG_CONFIG_HOME/cava/config或$HOME/.config/cava/config创建一个配置文件，但也可以使用-p选项指定cava使用不同的文件。

向cava发送SIGUSR1信号会强制cava重新加载其配置文件。这相当于用户在终端中按下r。可以使用pkill或killall发送SIGUSR1信号。 例如：

$ pkill -USR1 cava

类似地，向cava发送SIGUSR2信号只会从配置文件中重新加载颜色，这相当于在终端中按下c。这比重新加载整个配置稍快，因为不需要重新初始化音频处理。

$ pkill -USR2 cava

均衡器工作原理示例：

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

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

在其他应用程序中使用cava

cavacore库

cava的核心处理引擎已被分离成一个单独的库cavacore。详情请参阅CAVACORE.md。

原始输出

您还可以通过使用原始输出模式将Cava的输出用于其他程序，该模式会将条形数据写入STDOUT，可以通过管道传输到其他进程。有关此选项的更多信息在示例配置文件中有文档说明。

一个有用的起点示例脚本是用Python编写的，可以处理原始数据，可以在这里找到。

贡献

在开启拉取请求之前，请阅读CONTRIBUTING.md。

感谢：

• CelestialWalrus
• anko
• livibetter

在本项目早期开发中做出的重大贡献。

还要感谢dpayne找出如何获取pulseaudio默认接收器名称的方法。