readme-waves

Web App | npm

Generate animated music equalizer visualizations for GitHub profile READMEs.

Renders your music as a contribution-graph-style equalizer — frequency bands from left (bass) to right (treble), with GitHub's green color levels stacking from bottom to top based on intensity.

Output Modes

| Mode | Format | Audio | Auto-play in README | Best for | |------|--------|-------|---------------------|----------| | SVG | .svg | No | Yes (CSS animation) | Visual-only, lightweight | | Video | .mp4 | Yes | Requires manual embed | Full experience with sound |

Quick Start

CLI

Requires ffmpeg and yt-dlp (for YouTube mode).

# From local audio file
npx readme-waves song.mp3 -o waveform.svg

# MP4 video with audio
npx readme-waves song.mp3 --video -o waveform.mp4

# From YouTube URL
npx readme-waves "https://www.youtube.com/watch?v=xxxxx" -o waveform.svg

# YouTube → MP4
npx readme-waves "https://www.youtube.com/watch?v=xxxxx" --video -o waveform.mp4

Web App

Visit readme-wave.takalawang.dev — upload an audio file to generate SVG or MP4 directly in your browser. No server processing, everything runs client-side.

CLI Options

| Flag | Description | Default | |------|-------------|---------| | <input> | Audio file path or YouTube URL | (required) | | -o, --output | Output file path | waveform.svg | | --video | Generate MP4 video with audio | false | | --rows | Amplitude levels (height in squares) | 7 | | --cols | Frequency bands (number of columns) | 52 | | --frames | Animation frames (SVG mode) | 60 | | --fps | Video frame rate | 24 | | --duration | SVG animation loop (seconds) | 10 | | --theme | Color theme: dark, light | dark |

Embed in GitHub README

![Waveform](./assets/waveform.svg)

How It Works

1. Decodes audio via ffmpeg (CLI) or Web Audio API (browser)
2. Applies Short-Time Fourier Transform (STFT) with pure TypeScript FFT
3. Trims to the lower 30% of the frequency range (where music energy lives)
4. Per-band normalization with gamma correction for even dynamic range
5. Generates equalizer visualization:
   • SVG mode: per-cell CSS @keyframes animation
   • Video mode: raw pixel frames piped to ffmpeg (CLI) or ffmpeg.wasm (browser)

Color Themes

Dark (default) — GitHub dark mode contribution colors:

#161b22  #006d32  #26a641  #39d353

Light — GitHub light mode contribution colors:

#ebedf0  #40c463  #30a14e  #216e39

Local Development

pnpm install
pnpm dev          # Next.js dev server
pnpm build:cli    # Build CLI

Tech Stack

• Next.js — web app
• Web Audio API — browser audio decoding
• @ffmpeg/ffmpeg — browser video encoding
• commander — CLI
• yt-dlp — YouTube download (CLI)
• ffmpeg — audio/video processing (CLI)

License

MIT