Audio Effect

Copyright 2023 Ethan Christensen

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

bruhanimate.bruheffect.audio_effect._make_bolt(width: int, height: int) → list[tuple[int, int]]

Generate a branching lightning bolt path from a random top position downward.

bruhanimate.bruheffect.audio_effect._find_monitor_device()

Return a sounddevice input device index for a PulseAudio/PipeWire monitor, or None.

class bruhanimate.bruheffect.audio_effect.AudioEffect(buffer: Buffer, background: str, settings: AudioSettings = None)

Bases: BaseEffect

Visualizes system audio output as terminal animations.

Modes:

• "bars" — vertical EQ bars

• "mirror" — EQ bars mirrored from the vertical center outward

• "waveform" — oscilloscope: filled columns from center to sample amplitude

• "spectrum" — scrolling spectrogram; frequency on Y, time on X

• "radial" — circular pulse from center; each ring driven by a frequency band

• "rain" — audio-driven falling character rain; frequency energy sets density

• "tunnel" — rectangular frames that zoom toward the viewer; speed tracks energy

• "ripple" — beat-triggered elliptical rings that expand from center

• "vortex" — rotating Archimedean spiral arms; rotation speed tracks energy

• "wave" — multi-frequency sine interference; each band drives its own wave

• "starfield" — perspective star-zoom; stars accelerate with audio energy

• "fireworks" — particle bursts that explode and fall under gravity

• "interference" — two-source wave interference pattern; geometry shifts with audio

• "bounce" — balls with glowing trails that speed up with their frequency band

• "lightning" — branching electric bolts that strike on energy spikes

• "aurora" — flowing curtains of color that undulate with frequency bands

• "orbit" — sparse particles scattered at orbital radii; fills the screen with scattered dots

• "scope" — raw audio oscilloscope; shows the actual waveform sample-by-sample

• "grid" — screen-filling frequency grid; each cell glows with its band’s energy

• "helix" — scrolling double helix with rungs; pitch and rung density track audio

• "lissajous" — Lissajous figure whose frequency ratios are driven by bass and treble bands

• "sunburst" — rotating radial spokes from center; each spoke’s length driven by its band

• "mandala" — 8-fold symmetric petal patterns that bloom and rotate with audio

• "comet" — comets streak from screen edges with fading trails; speed tracks energy

• "weave" — interlaced horizontal and vertical sine waves that cross each other

Windows requires PyAudioWPatch for WASAPI loopback:

pip install bruhanimate[audio]

Linux requires sounddevice and a PulseAudio/PipeWire monitor source:

pip install bruhanimate[audio]

__init__(buffer: Buffer, background: str, settings: AudioSettings = None)

Initialize the audio effect.

Parameters:

• buffer (Buffer) – Effect buffer to push updates to.

• background (str) – Character or string to use for the background.

• settings (AudioSettings, optional) – Configuration for the audio effect.

set_mode(mode: str)

Switch visualization mode. Clears the buffer when leaving a stateful mode.

set_sensitivity(sensitivity: float)

Adjust the amplitude sensitivity multiplier.

set_smoothing(smoothing: float)

Set temporal smoothing (0 = none, close to 1 = very smooth).

set_color(color: bool)

Enable or disable colorized output.

set_bar_char(bar_char: str)

Set the character used to draw bars and fills.

set_compact(compact: bool)

Remove the gap column between bars when True.

_fft_bars(audio: ndarray) → ndarray

Return smoothed, normalised EQ bar heights (0–1).

static _height_color(ratio: float) → int

Green → yellow → red based on magnitude (0–1).

static _heat_color(ratio: float) → int

Blue → cyan → green → yellow → red heat palette (0–1).

render_frame(frame_number: int)

To be defined by each effect.

_render_waveform(audio: ndarray)

Scrolling RMS amplitude envelope: each column = one frame, scrolls left over time.

_render_spectrum(audio: ndarray)

Scrolling spectrogram: frequency on Y axis, time scrolls left.

_render_radial(audio: ndarray)

Circular pulse: each ring’s radius is driven by its frequency band’s energy.

_render_rain(audio: ndarray)

Audio-driven rain with occasional lightning strikes.

_render_tunnel(audio: ndarray)

Rectangular frames that spawn at the edges and zoom inward, driven by energy.

_render_ripple(audio: ndarray)

Elliptical rings that expand from the center; spawn rate scales with energy.

_render_vortex(audio: ndarray)

Three Archimedean spiral arms that rotate; speed and fill track audio energy.

_render_wave(audio: ndarray)

Multiple sine waves, each driven by its own frequency band, overlaid.

_render_starfield(audio: ndarray)

Stars zoom toward the viewer; speed proportional to audio energy.

_render_fireworks(audio: ndarray)

Particle bursts that explode outward and fall under gravity.

_render_interference(audio: ndarray)

Two-source wave interference; source positions and wave freq shift with audio.

_render_bounce(audio: ndarray)

Balls with glowing trails bounce around; each tracks its own frequency band.

_render_lightning(audio: ndarray)

Branching electric bolts strike downward on energy spikes.

_render_aurora(audio: ndarray)

Flowing vertical curtains of color; each band drives its own curtain’s height.

_render_orbit(audio: ndarray)

Orbiting particles with audio-reactive branching spikes; scales with screen dimensions.

_render_orbit_gradient(audio: ndarray)

Orbiting particles using a character density gradient with branching spikes for different bands.

_render_scope(audio: ndarray)

Raw oscilloscope: draws the actual audio samples across the screen width.

_render_grid(audio: ndarray)

Screen-filling frequency grid; each cell glows proportionally to its band’s energy.

_render_helix(audio: ndarray)

Scrolling double helix with rungs; pitch and rung spacing react to audio energy.

_render_lissajous(audio: ndarray)

Lissajous figure; bass drives the horizontal frequency ratio, treble drives vertical.

_render_sunburst(audio: ndarray)

Radial spokes from center; each spoke’s length is driven by its frequency band.

_render_mandala(audio: ndarray)

N-fold symmetric petal pattern; each layer’s bloom size driven by a frequency band.

_render_comet(audio: ndarray)

Comets streak across the screen from random edges; speed and spawn rate track energy.

_render_weave(audio: ndarray)

Interlaced horizontal and vertical sine waves; crossings glow based on energy.

stop()

Stop the background audio capture thread.