fourzerosix/daneq repository overview

⁠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 runni