red-pearl — Audio-Reactive Spectrum Visualizer

Pure-ffmpeg audio visualizer. No asset scraping. Takes an audio file and emits a dark, punk/VHS-graded music video driven entirely by audio-reactive filters (showcqt + showspectrum + showwaves) with heavy VHS post (chromatic aberration, film noise, moving scanlines, strobe flashes, vignette, hue drift, strong-contrast curves).

When to use

Use when the user asks for:

• a "vibe visualizer", "spectrum visualizer", "audio visualizer"
• a visual for a track that doesn't need sourced imagery
• a "red pearl" visualizer / "pearl" viz
• dark/punk/VHS looking visual driven by the audio itself

NOT to use: if the user wants GIF cuts, scraped Pinterest/Giphy content, anime fight cuts, etc. That's the separate visualizer skill (~/visualizer-skill/visualizer.py). The two are distinct.

Setup

One-time: none. Requires only ffmpeg (already on the Mac Studio).

The script lives at ~/red-pearl/red_pearl.py.

Usage

# Defaults: 16:9, red-pearl palette, medium intensity
python3 ~/red-pearl/red_pearl.py --audio ~/path/to/track.mp3

# Vertical for TikTok/Reels
python3 ~/red-pearl/red_pearl.py -a track.mp3 --aspect 9:16

# Different palette + high VHS intensity
python3 ~/red-pearl/red_pearl.py -a track.mp3 --palette void --intensity high

# Custom output path
python3 ~/red-pearl/red_pearl.py -a track.mp3 -o ~/Desktop/viz.mp4

Flags

Palette previews

• red-pearl — deep blacks, hot pink/red accents, white highlights. The default "grungy dark pearl" look.
• blood — saturated oxblood + orange, very red-heavy.
• void — purple/violet into white, cosmic.
• neon — cyan/magenta/yellow, arcade.
• toxic — radioactive green, hazmat.
• sunset — orange/pink/gold, warm.

Output

Default output lives in ~/Documents/Visualizer/ with a self-describing filename. Full duration of input audio. x264 / yuv420p / AAC 192k, MP4 with +faststart for streaming.

Sending to Telegram

Bot credentials in the user's memory (reference_telegram.md):

curl -s -X POST "https://api.telegram.org/bot<TOKEN>/sendVideo" \
  -F chat_id=<CHAT_ID> \
  -F supports_streaming=true \
  -F "caption=red-pearl // <track name>" \
  -F video=@<path>

If the file exceeds Telegram's 50 MB bot limit, transcode first:

ffmpeg -y -i in.mp4 -c:v libx264 -preset medium -b:v 1800k -maxrate 2000k \
  -bufsize 3200k -c:a aac -b:a 128k -pix_fmt yuv420p -movflags +faststart out.mp4

How it works (filter chain)

1. showcqt — main spectrum bars, 6-count, gamma-stretched, palette-colored
2. showspectrum — scrolling log-scale spectrogram, blended at 35% alpha over cqt
3. showwaves — cline-mode waveform band along the bottom (H - waveform_h - 20)
4. rgbashift — chromatic aberration (R/B channel offset, intensity-scaled)
5. noise — temporal + uniform film grain
6. vignette — dark corners
7. drawbox x2 — two time-sinusoidal moving scanlines (white + palette strobe color)
8. drawbox x2 — periodic strobe flashes (black at ~0.2Hz, palette color at ~0.14Hz)
9. curves strong_contrast — final crush
10. hue — slow hue modulation s = 1.3 + 0.4*sin(t*1.3)

All audio-reactive stages are fps=30; video framerate is 30.

Notes

• drawtext is NOT used (the system ffmpeg build lacks it). If you add text overlays later, generate PNG title cards with PIL and overlay them instead.
• zoompan with a t-variable expression breaks — ffmpeg zoompan uses on/in_time, not t. Stick to static zoom or drive with scale + sin(t*X) in separate filter.
• Drawbox sizes must be literal ints, not w=w/h=h expressions.