DanEQ

A btop-style terminal equalizer, effects rack and audio visualizer for Linux and macOS. It does not just draw pretty bars: it sits in the audio path, so the faders you move change what you hear, and daneq --selftest proves the filters match the curve on screen.

╭─┤Spectrum post-EQ├──────────────────────────────────┤braille  band 6/10: 1kHz +6.0dB├─╮
│ -10  braille spectrum, 2 bars per cell, peak-hold caps, gradient colors, dB scale       │
╰─────────────────────────────────────────────────────────────────────────────────────────╯
╭─┤Equalizer 10-band├──╮╭─┤Response├──────────────────────────────────────┤preamp +0.0dB├─╮
│ faders (keys + mouse) ││ exact filter curve with shaded boost/cut areas                  │
│                       │╭─┤Levels├──────────────────────────────────────────────┤dBFS├────╮
╰───────────────────────╯╰─────────────────────────────────────────────────────────────────╯

Contents

Docs site: https://fourzerosix.github.io/DanEQ/

1. What you get
2. Platform support
3. Quick start
4. Install - Linux, macOS, iPhone/iPad, ThinLinc, Docker, dependencies, uninstall
5. Usage examples
6. Keys, mouse and the Esc menu
7. Effects rack
8. Visualizations, bar styles, themes
9. Test signals and easter eggs
10. Public domain clips
11. Nerd mode
12. Files and settings
13. How it works
14. Command line reference
15. Troubleshooting
16. Development and testing
17. Publishing
18. FAQ and roadmap

What you get

• Equalizer: 4, 6, 8 or 10 bands (--bands), +/-12 dB per band, preamp, bypass for A/B, mute, 8 presets, auto headroom, RBJ biquad filters in real time. Export your curve as Equalizer APO / EasyEffects text.
• Effects rack: compressor, overdrive, bitcrusher, megaphone, phaser, flanger, chorus, tremolo, echo, reverb and stereo widener, each with braille rotary knobs.
• 11 views: spectrum (6 bar styles), waterfall, scope, vectorscope, radial, spinning vinyl record, reel-to-reel tape deck, fire, starfield, ripples, matrix rain. 20 color themes. 60 fps.
• Nerd mode: btop-style audio process, stream and device monitor.
• Esc menu like btop, resizable panels (keys and mouse drag), full mouse support.
• Test signals: 17 synthesized animals, cartoon sound effects, a bullhorn loudspeaker, binaural beats, dial-up modem, touch tones, morse, noise colors, and 12 public domain tunes including Amazing Grace.
• Real public domain recordings (Apollo 11, FDR, JFK) fetched on demand.
• No root, no kernel modules. PulseAudio and PipeWire on Linux; PortAudio plus a loopback driver on macOS.

Platform support

Everything that does not need live system audio (test signals, files, all visuals, effects, --no-output) works on any platform that runs Python 3.9+ with a UTF-8, 256-color terminal at least 80x24.

Quick start

git clone https://github.com/fourzerosix/DanEQ.git && cd DanEQ
scripts/install.sh                  # Linux or macOS; creates a private virtualenv and the `daneq` command
daneq --selftest                    # headless proof that the DSP is accurate
daneq --demo pink --no-output       # visual demo, no sound card needed
daneq                               # equalize everything playing on this machine

Install

Linux

One command (Debian/Ubuntu/Kubuntu, Fedora, Rocky/RHEL, Arch, openSUSE): scripts/install.sh. It installs the system tools, builds a virtualenv in ~/.local/share/daneq/venv, links ~/.local/bin/daneq and runs the self-test. Undo with scripts/install.sh --uninstall.

Manual, per distribution:

PipeWire systems already provide pactl/parec/pacat through pipewire-pulse; the package names above (pulseaudio-utils, libpulse) only supply the client tools.

python3 -m venv ~/.local/share/daneq/venv
~/.local/share/daneq/venv/bin/pip install --upgrade pip
~/.local/share/daneq/venv/bin/pip install ".[audio]"        # or: pip install daneq[audio]  once it is on PyPI
ln -s ~/.local/share/daneq/venv/bin/daneq ~/.local/bin/daneq

From other sources:

pipx install git+https://github.com/fourzerosix/DanEQ     # straight from GitHub
pipx install daneq                                          # from PyPI (after the first release)
docker run -it --rm fourzerosix/daneq                      # Docker Hub: built-in demo, no audio device needed
docker run -it --rm ghcr.io/fourzerosix/daneq --zoo --fx reverb --no-output     # same image from GHCR

Docker with real audio, passing the host's PulseAudio/PipeWire socket:

docker run -it --rm -v "$XDG_RUNTIME_DIR/pulse:/run/pulse" -e PULSE_SERVER=unix:/run/pulse/native \
  fourzerosix/daneq --demo

macOS

macOS has no PulseAudio and, by design, gives apps no way to tap the system mix. System-wide EQ therefore needs a free virtual loopback device. DanEQ uses BlackHole; the rest is automatic.

apps  ->  [BlackHole 2ch = system output]  ->  DanEQ (EQ + effects + visuals)  ->  your real speakers/headphones

1. Install (Terminal.app or iTerm2):

git clone https://github.com/fourzerosix/DanEQ.git && cd DanEQ
scripts/install.sh            # offers to install Homebrew Python, ffmpeg, BlackHole and switchaudio-osx

Or by hand: brew install python ffmpeg switchaudio-osx && brew install --cask blackhole-2ch then python3 -m venv ~/.local/share/daneq/venv && ~/.local/share/daneq/venv/bin/pip install ".[mac]". Homebrew Python is recommended: the Python that ships with the Xcode command line tools is old (3.9, pip 21) and its curses handles Unicode poorly.

2. Allow microphone access. Capturing BlackHole counts as recording, so the first run triggers a prompt; approve it, or enable your terminal under System Settings > Privacy & Security > Microphone.

3. Match sample rates (optional but best). Open Audio MIDI Setup and set BlackHole 2ch and your real output to the same rate, normally 48000 Hz.

4. Run it.

daneq --list-devices          # shows every device and marks virtual ones
daneq                         # captures BlackHole, plays to your system output
daneq --output "External"     # pick another real output by name fragment
daneq --input "BlackHole 2ch" --output "MacBook Pro Speakers"

With switchaudio-osx installed DanEQ switches the system output to BlackHole for you and restores it on exit. Without it, set System Settings > Sound > Output to BlackHole 2ch before starting and back afterwards.

Limits on macOS: BlackHole has no volume control, so the keyboard volume keys do nothing while it is the output (set your speaker volume first, or use per-app volume). Live system audio is new and untested by the author on a real Mac: run daneq --list-devices first and open an issue with its output if something is off. Files, test signals and all visuals do not need BlackHole at all: daneq --demo pink, daneq song.mp3.

iPhone and iPad

DanEQ cannot run natively on iOS or iPadOS: there is no system-wide audio tap for third-party apps, no curses terminal in the sandbox, and NumPy/SciPy are not available in the common on-device Python apps. What does work:

• SSH into a machine that runs DanEQ (Blink Shell, Termius, Prompt, or any iOS SSH client). Run daneq inside tmux on the remote Mac or Linux box; the interface, mouse and all visuals work over SSH. The audio being equalized is the remote machine's, not the phone's.
• ThinLinc or other remote desktop into a Linux box and use the terminal there (audio is forwarded by ThinLinc if enabled in the client).
• A native iOS version would be a separate Swift project (an AUv3 audio unit or an AVAudioEngine app that equalizes its own playback). The DSP here (RBJ biquads) ports directly; it is on the roadmap, not in this repo.

ThinLinc and other remote sessions

Inside the session, use a 256-color terminal and a UTF-8 locale:

export TERM=xterm-256color LANG=en_US.UTF-8
daneq --demo pink --no-output       # works even if the node has no audio path
daneq --demo                        # plays through the session's ThinLinc audio sink
daneq                               # equalizes everything playing in the session

Audio must be enabled in the ThinLinc client. If the session dies uncleanly, daneq --restore removes the virtual sink and resets the default output.

Dependencies at a glance

Uninstall

scripts/install.sh --uninstall, or pipx uninstall daneq. Settings stay in ~/.config/daneq; delete that folder to remove them. On macOS also brew uninstall --cask blackhole-2ch if you no longer want it.

Usage examples

# --- live system audio ---------------------------------------------------------------------------
daneq                                   # all apps through the EQ (Linux: virtual sink; macOS: BlackHole)
daneq --bands 4                         # 4 band layout (also 6, 8, 10)
daneq --preset Rock --theme synthwave   # start with a preset and a theme
daneq --fx reverb,echo --view vinyl     # effects on from the start, begin in the vinyl view
daneq --latency 15                      # lower latency (less buffering) for video
daneq --sink alsa_output.pci-0000_00_1f.3.analog-stereo      # pick the Linux output explicitly
daneq --restore                         # clean up after a crash (Linux)

# --- files ---------------------------------------------------------------------------------------
daneq song.flac                         # play a file through the EQ
daneq --loop loop.wav                   # loop it
daneq --no-output song.mp3              # visualize and EQ without playing (silent preview)

# --- measurement and EQ testing ------------------------------------------------------------------
daneq --selftest                        # prove accuracy: real tones vs the displayed response, all layouts
daneq --pink --no-output                # pink noise: boost a band and watch the spectrum bulge
daneq --sweep                           # 20 Hz to 20 kHz sweep: the moving peak follows your curve
daneq --export > my-curve.apo.txt       # save the curve as Equalizer APO / EasyEffects text
daneq --list-presets                    # Flat, Bass boost, Treble boost, Vocal, Loudness, Rock, ...

# --- fun ------------------------------------------------------------------------------------------
daneq --zoo --fx reverb                 # every animal, with reverb
daneq --lion --theme fire --view fire   # roar, rendered as flames
daneq --binaural --beat alpha --view vectorscope      # headphones: watch the phase drift
daneq --loudspeaker --fx megaphone,echo # bullhorn through a canyon
daneq --grace --view vinyl --theme gold # Amazing Grace on a spinning record
daneq --tetris --view reel-to-reel      # Korobeiniki on tape
daneq --clip moon --view scope          # Apollo 11, one small step
daneq --cartoon --style mirror          # slide whistles with a mirrored spectrum

# --- engineering ---------------------------------------------------------------------------------
daneq --nerd                            # start in nerd mode (audio processes, streams, devices)
daneq --list-devices                    # macOS / PortAudio: list audio devices
daneq --fps 30                          # lighter on slow remote sessions
daneq --no-mouse                        # if your terminal mangles mouse reporting

Keys, mouse and the Esc menu

Press Esc for a btop-style menu (view, bar style, theme, EQ preset, FX rack, nerd mode, auto headroom, bypass, save, export, help, about, quit). Arrow keys or j/k move, Enter or Right opens, Esc or Left goes back, the mouse works too. Press ? for an in-app key list.

Mouse: click or drag a fader, scroll the wheel over a band or knob, double click a fader to zero it, click FX tabs, drag the panel borders to resize.

Effects rack

Press f. Effects run in this order after the EQ: compressor, overdrive, bitcrusher, megaphone, phaser, flanger, chorus, tremolo, echo, reverb, stereo widener. Switch effects on with o, turn knobs with the arrows. Settings are saved with the rest of your config.

Notes: the phaser feedback is applied once per 32-sample chunk (an approximation); the overdrive is not oversampled, so extreme drive can alias.

Visualizations, bar styles, themes

Views (v / V or --view): spectrum, waterfall, scope, vectorscope, radial, vinyl, reel-to-reel, fire, starfield, ripples, matrix. The audio-reactive ones respond to bass, mid and treble separately.

Bar styles (g or --style): braille, line, mirror, dots, blocks, ascii.

Themes (c / C or --theme): classic, ice, fire, synthwave, mono, ocean, forest, sunset, vaporwave, matrix, gold, lava, aurora, candy, nord, dracula, gruvbox, cyberpunk, rainbow, thermal.

EQ presets: Flat, Bass boost, Treble boost, Vocal, Loudness, Rock, Electronic, Classical.

Layout: ( ) change the bottom panel height, { } change fader width, or drag the borders. The spectrum uses a multi-resolution FFT (long window for bass, short for treble); , and . change sensitivity, t toggles tilt.

Test signals and easter eggs

All of these are synthesized from scratch, so there are no licensing questions. They are cartoon-style approximations rather than recordings, but they have real spectral content, which is what makes them good for EQ and effects testing. daneq --list-demos prints the same list.

Animals

Comedy and nostalgia

Public domain tunes (chiptune)

Test and measurement

Binaural beats: the left and right ears get tones --beat Hz apart around --carrier. --beat takes a number or delta (2), theta (6), alpha (10), beta (20), gamma (40) or schumann (7.83). Use headphones; the beat exists only in your head. This is a test signal, not a medical device.

"You Are My Sunshine" is not included because it is still under copyright in the United States.

Public domain clips

Nothing is bundled. daneq --list-clips shows a small library that downloads on first use into ~/.cache/daneq/clips:

daneq --clip moon       # Apollo 11, one small step (NASA)
daneq --clip infamy     # FDR, "a date which will live in infamy"
daneq --clip fdr        # FDR, the full 8 Dec 1941 address
daneq --clip jfk        # JFK inaugural address
daneq --clip cuba       # JFK Cuban Missile Crisis address
daneq --clip https://example.org/some.ogg      # any URL
daneq --clip ~/Music/thing.flac                # any local file

These are works of the US government (public domain under 17 USC 105) hosted on Wikimedia Commons. Add your own named clips in ~/.config/daneq/clips.json:

{"mything": {"url": "https://.../file.ogg", "about": "what it is and why it is free to use"}}

Ogg and other compressed formats need ffmpeg, or pip install "daneq[audio]" where ffmpeg is unavailable.

Nerd mode

n or --nerd. Panels: DanEQ engine stats and a DSP load graph, devices (sinks, sources, ALSA hardware that is running), audio processes with CPU, memory and braille sparklines (servers such as pipewire/pulseaudio/wireplumber, clients that own streams, anything holding /dev/snd), and live PulseAudio/PipeWire streams with volume, format and latency. Up/Down select, o cycles the sort (cpu, mem, pid, name). On macOS it shows coreaudiod, audio tools and the PortAudio device list. Without pactl it still shows processes.

Files and settings

XDG_CONFIG_HOME and XDG_CACHE_HOME are honored.

How it works

Linux:   apps -> [daneq null sink] -> monitor -> parec -> numpy/scipy EQ + FX -> pacat -> your real output
macOS:   apps -> [BlackHole 2ch]   ------------> PortAudio in -> EQ + FX -> PortAudio out -> real output
files, demos:  decoder or generator -> EQ + FX -> output (or a silent timed sink with --no-output)
                                        |
                                        +-> analyzer tap -> spectrum / visuals / meters

On Linux DanEQ creates a virtual sink named daneq, makes it the default output, moves running streams onto it, equalizes its monitor and plays the result to the original sink. Everything is undone on exit, including on SIGTERM and SIGHUP. Latency is roughly twice --latency plus one 1024-frame block (about 80 ms by default).

Command line reference

usage: daneq [-h] [--demo [NAME]] [--beat HZ|NAME] [--carrier HZ]
             [--clip NAME|PATH|URL] [--list-clips] [--list-demos]
             [--backend {auto,pulse,portaudio}] [--input DEVICE]
             [--output DEVICE] [--list-devices] [--no-output] [--sink NAME]
             [--capture SOURCE] [--rate RATE] [--latency MS] [--loop]
             [--bands {4,6,8,10}]
             [--preset {Flat,Bass boost,Treble boost,Vocal,Loudness,Rock,Electronic,Classical}]
             [--theme {classic,ice,fire,synthwave,mono,ocean,forest,sunset,vaporwave,matrix,gold,lava,aurora,candy,nord,dracula,gruvbox,cyberpunk,rainbow,thermal}]
             [--view {spectrum,waterfall,scope,vectorscope,radial,vinyl,reel-to-reel,fire,starfield,ripples,matrix}]
             [--style {braille,line,mirror,dots,blocks,ascii}] [--fx LIST]
             [--fps N] [--nerd] [--no-mouse] [--list] [--export]
             [--list-presets] [--restore] [--selftest] [--version]
             [file]

DanEQ: a btop-style terminal equalizer, effects rack and audio visualizer.

positional arguments:
  file                  audio file to play through DanEQ (WAV, or anything
                        ffmpeg/soundfile reads)

options:
  -h, --help            show this help message and exit

test signals and easter eggs:
  --demo [NAME]         built-in signal (see --list-demos); default: music
  --beat HZ|NAME        binaural beat frequency or
                        delta/theta/alpha/beta/gamma/schumann (default 10)
  --carrier HZ          binaural carrier (default 220)
  --clip NAME|PATH|URL  play a clip from the clip library, a local file or a
                        URL
  --list-clips          list the clip library and exit
  --list-demos          list all built-in signals and exit

audio routing:
  --backend {auto,pulse,portaudio}
                        audio backend: pulse (Linux, default there) or
                        portaudio (macOS default)
  --input DEVICE        portaudio: capture device name or number (default:
                        BlackHole/loopback)
  --output DEVICE       portaudio: output device name or number (default:
                        system output)
  --list-devices        portaudio: list audio devices and exit
  --no-output           do not play audio, just process and visualize
  --sink NAME           output sink (default: current default sink)
  --capture SOURCE      capture from this source instead of the virtual sink
  --rate RATE           sample rate (default 48000)
  --latency MS          stream latency in ms (default 30)
  --loop                loop FILE

interface:
  --bands {4,6,8,10}    number of EQ bands (default 10)
  --preset {Flat,Bass boost,Treble boost,Vocal,Loudness,Rock,Electronic,Classical}
                        start with this EQ preset
  --theme {classic,ice,fire,synthwave,mono,ocean,forest,sunset,vaporwave,matrix,gold,lava,aurora,candy,nord,dracula,gruvbox,cyberpunk,rainbow,thermal}
                        color theme
  --view {spectrum,waterfall,scope,vectorscope,radial,vinyl,reel-to-reel,fire,starfield,ripples,matrix}
                        start in this view
  --style {braille,line,mirror,dots,blocks,ascii}
                        spectrum bar style
  --fx LIST             enable effects at start, e.g. reverb,echo,comp
  --fps N               target frame rate (default 60)
  --nerd                start in nerd mode (audio processes and streams)
  --no-mouse            disable mouse support

maintenance:
  --list                list output sinks and exit
  --export              print saved settings as Equalizer APO text and exit
  --list-presets        list EQ presets and exit
  --restore             remove a leftover virtual sink and fix the default
                        sink
  --selftest            verify the DSP against its analytic response and exit
  --version             show program's version number and exit

With no FILE, --demo or sound shortcut, DanEQ equalizes all system audio via a
virtual sink.

Troubleshooting

Development and testing

pip install -e ".[dev,audio]"
pytest -q                     # unit tests: DSP, effects, sounds, visuals, nerd parsers, backends, packaging
daneq --selftest              # accuracy check against the analytic response
daneq --demo pink --no-output # eyeball check

Layout: daneq/dsp.py (filters, analyzer), effects.py, sounds.py + synth.py (test signals), visuals.py, ui.py, nerd.py, audio.py (Pulse and PortAudio backends), clips.py, themes.py, cli.py. CI runs the tests on Linux and macOS. Packaging metadata lives in setup.cfg so that even old pip/setuptools (such as the ones Apple ships) install it correctly.

Publishing

Publishing a GitHub Release updates everything: PyPI, Docker Hub and GHCR (multi-arch), and the documentation site at https://fourzerosix.github.io/DanEQ/. See RELEASING.md for the one-time setup and the per-release steps.

FAQ and roadmap

Why not cava? cava only visualizes. DanEQ changes the sound, then shows you the result.

Can I use it as a permanent system EQ? Run it in a terminal multiplexer. A headless daemon mode is on the roadmap.

Roadmap ideas: headless daemon with systemd user unit; Equalizer APO import (AutoEq headphone profiles); named user presets saved from the menu; per-app routing; recording the processed output to WAV; MIDI/OSC control; Windows WASAPI loopback; a native iOS app; pitch shifting and convolution reverb.

License

GPL-3.0 (see LICENSE). Public domain tunes and recordings keep their own status as described above.

██████╗  █████╗ ███╗   ██╗███████╗ ██████╗          ________________________
██╔══██╗██╔══██╗████╗  ██║██╔════╝██╔═══██╗         | ██ ██ ██ ██ ██ ██ |2||
██║  ██║███████║██╔██╗ ██║█████╗  ██║   ██║         | ██ ██ ██ ██ ██ ██ |0||
██║  ██║██╔══██║██║╚██╗██║██╔══╝  ██║   ██║         | ██ ██ R.I.P ██ ██ |2||
██████╔╝██║  ██║██║ ╚████║███████╗╚██████╔╝         | ██ ██ D.J.E ██ ██ |6||
╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝ ╚═══██╗          | ██ ██ ██ ██ ██ ██ |J||
  |                |                  ╚═══╝         | ██ ██ ██ ██ ██ ██ |B||
╭─┤Spectrum post-EQ├────────────────────────────────┤band 6/10: 1kHz +6.0dB├─╮
│ -10  braille spectrum, 2 bars per cell, peak-hold caps, dB scale             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─┤Equalizer 10-band├──╮╭─┤Response├──────────────────────┤preamp +0.0dB├─╮
│ faders (mouse + keys) ││ exact filter curve, drawn in braille            │
│                       │╭─┤Levels├───────────────────────────────┤dBFS├────╮
╰───────────────────────╯╰────────────────────────────────────────────────────╯