musicvis-cli

musicvis.zsh is a zsh-based terminal music visualizer for macOS. It captures live system audio with Core Audio process taps, converts it into FFT band levels in a small Swift helper, and renders the spectrum in the terminal.

Requirements

• macOS with Xcode command line tools or full Xcode installed
• zsh
• System audio capture permission for the terminal app you launch it from

Install

Homebrew:

curl -fsSL -o /tmp/musicviscli.rb https://raw.githubusercontent.com/adamzafir/musicvis-cli/main/Formula/musicviscli.rb
brew install /tmp/musicviscli.rb

From source:

git clone https://github.com/adamzafir/musicvis-cli.git
cd musicvis-cli
./musicvis.zsh

Run

musicvis

Common commands:

musicvis
musicvis --configure
musicvis --mode galaxy --color ocean
musicvis --mode wave --color sunset
musicvis --mode scope --color mono --bands 48 --fps 24
musicvis --bands 48 --fps 24
musicvis --height 20
musicvis --chars ".,:;irsXA253hMHGS#9B&@"
musicvis --rebuild
musicvis --help

musicvis remembers the last mode/color you saved. Use musicvis --configure, then choose with the Up/Down arrow keys and press Enter. The configure flow also includes a reset-to-defaults option. While audio is playing, the visualizer automatically adapts to terminal resize changes. The footer uses spare width for live bass, mid, treble, and peak stats.

CLI options:

• --configure: interactive mode/color picker with save/reset
• --mode NAME: override the visual mode for the current run
• --color NAME: override the color palette for the current run
• --bands COUNT: set spectrum detail, default 32
• --fps FPS: set update rate, default 30
• --height ROWS: force the render height instead of using terminal size
• --chars STRING: set low-to-high density glyphs for the renderer
• --rebuild: force recompiling the Swift audio helper
• --help: print usage

Modes:

• bars: denser version of the classic spectrum columns
• mirror: reflected bars expanding away from the center line
• circle: circular pulse/ring visualizer driven by the same FFT bands
• wave: full-width rolling area waveform built from interpolated spectrum energy
• split: treble falls from the top while bass rises from the bottom
• scope: oscilloscope-style center trace shaped by band-to-band motion
• galaxy: bass drives a central core, mids spawn orbiters, highs twinkle as a starfield

Color palettes:

• gradient: broad rainbow ramp
• heat: dark red through yellow
• ocean: blue and cyan ramp
• neon: bright green/cyan glow
• sunset: magenta to amber ramp
• forest: green-heavy palette
• ice: cold blue-white palette
• mono: grayscale
• off: disable ANSI colors

Typical flows:

• musicvis: start immediately with your saved mode/color
• musicvis --configure: pick a mode and color with arrow keys, or reset to defaults
• musicvis --mode galaxy --color ocean: orbiting particles around a pulsing center
• musicvis --mode scope --color mono: override mode/palette just for the current run
• musicvis --chars ".,:;irsXA253hMHGS#9B&@": increase character density for more shading detail

How it works

• musicvis.zsh compiles src/SystemAudioBands.swift on first run into .build/bin/system-audio-bands.
• The Swift helper creates a Core Audio process tap and private aggregate device, reads live system-output buffers, computes log-spaced FFT bands, and prints one line of integer levels per frame.
• The zsh script reads those frames and draws one of several terminal visual modes with configurable density and color.

Permissions and constraints

• On the first capture run, macOS may prompt for system audio capture permission. If you deny it, the helper will fail to start until permission is granted for the terminal app in System Settings.
• The user-facing app is a zsh command, but the actual capture path relies on a compiled Swift helper because macOS does not expose this as a pure shell API.